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 패턴

우선순위: 최고 / 난이도: 높음

2번 작업(util/ 정리)과 연계. commands/ 구조 개편의 마무리 단계. 현재 새 커맨드 추가 시 두 곳을 수정해야 한다:

도메인 데이터 파일 — 데이터 클래스 추가
commands/command.dart — 130+ case factory switch에 추가

각 Command 클래스가 자신을 등록하는 패턴으로 변경하면 새 커맨드 추가 시 해당 파일 하나만 수정하면 된다.

작업 내용:

Command 클래스에 registerFactory() static 메서드 추가
각 커맨드 파일에 static void register() 메서드 추가
application.dart 또는 별도 registry 파일에서 모든 커맨드 등록
기존 switch factory 제거

⚠️ 변경 범위가 크므로 2번 완료 후 진행 권장

4. 태그 시스템 중앙화

우선순위: 중간 / 난이도: 낮음

현재 태그 처리 로직(<!property.key> 등)이 commands/command.dart 내부에 흩어져 있다. 별도 파일로 분리하면 AI가 "어떤 태그를 쓸 수 있나?" 질문에 코드 한 곳만 읽어도 답할 수 있다.

작업 내용:

lib/oto/core/tag_system.dart 파일 생성
태그 파싱/치환 로직을 command.dart에서 이동
태그 종류 명세를 주석으로 정리 (property, state, common 등)
command.dart는 tag_system.dart를 import해서 사용

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.2 KiB Raw Blame History