콘텐츠로 이동

ADR-0004: TODO Phase Model

We will manage long-term execution plans in .claude/TODO.md using a phase-based model with auto-progress tracking.

Status

Accepted

  • Decided at — 2026-04-15
  • Decided by — pabloism0x

Context

코딩 에이전트가 복잡한 작업을 수행할 때 체계적 진행 관리가 필요하다. Claude Code의 built-in TaskCreate/TaskUpdate는 세션 내 단기 task 관리에 적합하지만 세션 간 지속되지 않는다. 팀 수준에서 공유 가능하고, git에 커밋 가능하며, 세션을 넘어 지속되는 실행 계획이 필요하다.

Decision

.claude/TODO.md에 Phase 기반 실행 계획을 관리한다.

TODO.md 스키마

# TODO — [프로젝트명]

## Phase 1: [제목]
> 목표: [달성할 것]

- [x] 완료된 task
- [ ] 미완료 task

## Phase 2: [제목]
> 목표: [달성할 것]

- [ ] task

설계 제약

  1. 의존성 순 정렬 — Phase는 의존성이 낮은 순으로 강제 정렬
  2. 순차 진행 — Phase N 완료 → Phase N+1 시작
  3. 자동 갱신 — PostToolUse(Write|Edit) hook, FileChanged(TODO.md) hook
  4. Markdown 호환 — GitHub Flavored Markdown checkbox (- [x], - [ ])

Built-in Task와의 관계

도구 범위 지속성
Built-in TaskCreate/TaskUpdate 세션 내 단기 분할 세션 종료 시 소멸
TODO.md 프로젝트 레벨 장기 계획 git 커밋으로 영구

둘은 보완 관계 — TODO.md의 한 task를 구현할 때 built-in task로 세부 분할 가능.

Consequences

Positive

  • Markdown이므로 git diff/PR 리뷰에 자연스럽게 통합
  • 세션 간 지속
  • 팀원 간 공유 가능 (git commit)
  • 사람이 읽기 쉬운 형식
  • statusline에 진행률 표시 가능

Negative

  • 자동 갱신의 정확도가 hook 로직에 의존
  • Phase 간 의존성 강제 정렬 로직 구현 필요
  • built-in task 시스템과 이중 관리 가능성

Neutral

  • TODO.md는 표준 markdown이므로 어떤 에디터에서든 직접 편집 가능

Alternatives considered

Alternative 1: Built-in TaskCreate만 사용

Pros - 별도 구현 불필요 - Claude Code 네이티브

Cons - 세션 간 지속 안 됨 - git 커밋/팀 공유 불가

Why rejected — 프로젝트 레벨의 장기 계획에는 적합하지 않다.

Alternative 2: 외부 프로젝트 관리 도구 연동 (Linear, Jira)

Pros - 기존 팀 도구와 통합

Cons - MCP 서버 의존 - 복잡도 증가 - 오프라인/로컬 동작 불가

Why rejected — 단순성과 git 기반 워크플로우를 우선한다. 추후 연동은 가능.

Alternative 3: JSON 기반 task 파일

Pros - 프로그래매틱 처리 용이 - 스키마 검증 가능

Cons - 사람이 읽기 어려움 - git diff가 비직관적 - PR 리뷰에서 변경 내용 파악 어려움

Why rejected — "사람이 읽기 쉬운 것"이 팀 공유에서 더 중요하다.

Compliance

  • /todo:plan skill이 생성하는 TODO.md가 스키마를 준수하는지 테스트
  • Phase 순서가 의존성 역순인지 계획 수립 시 검증

Revisit triggers

  • hook 기반 자동 갱신의 오탐/미탐이 빈번할 때
  • 팀이 외부 프로젝트 관리 도구로 완전히 전환할 때
  • Phase 모델이 복잡한 프로젝트에서 한계를 보일 때

References

  • ADR-0001 — Auto-Load First (자동 갱신도 같은 원칙)
  • ADR-0002 — Main-Bundle Structure (todo는 primitives core)