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

예시:

/// 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 ?? 패턴 등)

4 KiB Raw Blame History