# AI-Friendly Refactoring To-Do

AI(Claude 등)가 코드베이스를 더 잘 이해하고 수정할 수 있도록 하는
리팩토링 작업 목록. 우선순위 순으로 정렬.

---

## ✅ 완료

### 1. command_data.dart 도메인별 분리
- **작업**: 1300줄짜리 단일 파일을 9개 도메인 파일로 분리
- **결과**: AI가 특정 커맨드 수정 시 읽어야 할 코드량 대폭 감소
- **상세**: `refactoring/history_001.md` 참조

### 2. commands/util/ 폴더 정리 — 잘못 배치된 커맨드 이동
- **작업**: `util/`의 도메인 혼재 파일 5개 이동, 중복 파일 1개 삭제
- **결과**:
  - `util/slack.dart` → `notification/slack.dart`
  - `util/mattermost.dart` → `notification/mattermost.dart`
  - `util/publish_ios.dart` → `build/publish_ios.dart`
  - `util/zip.dart` → `file/zip.dart`
  - `util/smb_authorize.dart` → `infra/smb_authorize.dart`
  - `util/jira.dart` → 삭제 (`jira/jira.dart`와 중복, import 없음)
  - `command.dart` import 경로 5곳 수정

### 3. Self-registering Command 패턴
- **작업**: `command.dart`의 import 40개 + `_commandMap` 리터럴 78줄 제거, registry 패턴 도입
- **결과**:
  - `Command.register()` static 메서드 추가
  - 커맨드 파일 39개에 `registerXxx()` top-level 함수 추가
  - `commands/command_registry.dart` 신규 생성 — 모든 커맨드 등록 중앙화
  - `application.dart`의 `build()` 초반에 `registerAllCommands()` 호출
- **새 커맨드 추가 절차**:
  1. 커맨드 파일 작성 + 해당 파일의 `registerXxx()`에 1줄 추가
  2. `command.dart` enum에 1줄 추가 → `build_runner` 재실행
  3. `command_registry.dart`에 import + 함수 호출 추가 (신규 파일인 경우)

### 4. 태그 시스템 중앙화
- **작업**: 태그 파싱/치환 로직을 `command.dart`에서 분리
- **결과**:
  - `lib/oto/core/tag_system.dart` 신규 생성 — `TagSystem` 클래스에 전체 구현 이동
  - 태그 문법 레퍼런스 주석 포함 (`<!property.key>`, `<!state.cmdId>`, `<@property.key>`)
  - `command.dart`의 태그 메서드는 `TagSystem`으로의 얇은 위임(delegate)만 유지
  - 기존 `Command.replaceTagValue()` 등 외부 호출부는 수정 없이 그대로 동작

---

## 📋 할 일

### 5. Pipeline Executor에 YAML 예제 주석 추가
**우선순위: 중간 / 난이도: 낮음**

현재 `assets/yaml/example/` 폴더에 예제가 따로 있어 코드-예제 매핑이 안 된다.
각 PipelineExecutor 클래스 상단에 인라인 YAML 예제를 주석으로 추가하면
AI가 파이프라인 구조를 한 파일만 읽어도 파악할 수 있다.

대상 파일:
- `lib/oto/pipeline/pipeline_exe.dart`
- `lib/oto/pipeline/pipeline_if.dart`
- `lib/oto/pipeline/pipeline_foreach.dart`
- `lib/oto/pipeline/pipeline_while.dart`
- `lib/oto/pipeline/pipeline_switch.dart`
- `lib/oto/pipeline/pipeline_exe_handle.dart`
- `lib/oto/pipeline/pipeline_wait_until.dart`

예시:
```dart
/// Example YAML:
/// ```yaml
/// - if:
///     equal-string: "<!property.env>"
///     value: "prod"
///     on-true:
///       - exe: deployProd
///     on-false:
///       - exe: deployDev
/// ```
class PipelineIf extends PipelineExecutor { ... }
```

---

### 6. CLAUDE.md 작성 — 마지막에 작성
**우선순위: 높음 / 난이도: 낮음 / 시점: 모든 리팩토링 완료 후**

> ⚠️ 리팩토링이 진행되면 구조가 계속 바뀌므로 반드시 마지막에 작성한다.

프로젝트 루트에 `CLAUDE.md`를 두면 Claude가 대화 시작 시 자동으로 읽는다.
매 대화마다 프로젝트 구조를 다시 파악하는 비용을 없앨 수 있다.

포함할 내용:
- 프로젝트 개요 (Dart CLI, Jenkins 연동 빌드 자동화)
- 최종 디렉토리 구조 요약
- 새 커맨드 추가 방법 (단계별)
- 새 도메인 데이터 클래스 추가 방법 (`build_runner` 실행 포함)
- 태그 문법 레퍼런스 (`<!property.key>`, `<!state.cmdId>`, `<!common.field>`)
- 에러 핸들링 패턴 (`application.dart` catch 구조)
- 주의사항 (xcworkspace/xcodeproj `??` 패턴 등)