잊혀지지 않는 계획 단위 | Task 시스템

Overview

앞 레슨에서는 성공 기준을 테스트로 먼저 작성하고 Red Green Refactor 사이클로 1개 기능(필터링)을 끝냈습니다. 그런데 계획에 기능이 6개, 10개씩 들어가면 한 세션 안에 전부 담기 어렵습니다. context window가 가득 차면 Claude Code는 auto-compact로 오래된 대화를 요약하는데, 이 과정에서 계획의 구조 정보가 원본만큼 정확하게 남지 않을 수 있습니다.

이번 레슨에서는 계획 자체를 context 밖 파일에 저장하고 작업 순서를 명시하는 Task 시스템을 배웁니다.

학습 목표

• auto-compact 후에도 그대로 남는 정보와 정확도가 낮아지는 정보를 구분할 수 있습니다
• Task 시스템이 어떻게 계획을 context 밖에 보존하는지 설명할 수 있습니다
• blockedBy/blocks로 작업 간 의존성을 설정하고 실행 순서를 설명할 수 있습니다

시작하기 전 확인사항

• 실습 프로젝트의 시작 브랜치로 전환합니다 (git checkout ch05-04)

ch05-04 브랜치는 이 레슨의 시작점입니다.

한 회의에 담기지 않는 6개 안건

긴 회의를 떠올려 봅니다. 회의실에 앉아 안건 6개를 시작했습니다. 안건 1을 두 시간 동안 격렬하게 토론하고 결정을 내리고 나면, 안건 2의 자세한 배경이 머리에 흐릿해집니다. 안건 3까지 가면 처음 안건의 결정이 무엇이었는지 다시 회의록을 펼쳐 봐야 합니다. 사람의 머리는 한정된 공간이고, 한 가지에 집중하면 다른 게 흐려집니다.

AI의 한 세션도 같은 한계가 있습니다. Lesson 03에서는 필터링이라는 안건 1개를 한 세션에서 끝냈습니다. 이제 Todo 앱을 본격적으로 확장한다고 가정합니다.

## Todo 앱 확장 계획

### 기능 목록
1. 마감일 설정
2. 정렬 기능 (이름순, 생성일순)
3. 마감일순 정렬 (1, 2 완료 후)
4. 검색 기능
5. 카테고리 태그
6. 카테고리별 필터 (5 완료 후)

기능 6개, 각각에 성공 기준까지 붙이면 작업량이 상당합니다. 한 기능을 구현할 때마다 코드 읽기, 테스트 실행, 도구 응답이 context window에 쌓입니다. 기능을 거듭할수록 압박이 커지고, 결국 한도에 다다르는 시점이 옵니다.

context window가 가득 찼을 때 Claude Code는 어떻게 행동할까요?

auto-compact 후에 흐려지는 정보

context가 가득 차면 Claude Code는 auto-compact를 실행합니다. 오래된 대화를 요약하여 context에 자리를 만듭니다. 회의에 비유하면, 길어진 회의의 앞부분을 한두 줄로 줄여서 머릿속에 자리를 비웁니다.

auto-compact 후에도 AI가 정확하게 파악할 수 있는 것과 정확도가 떨어질 수 있는 것을 비교합니다.

그대로 남는 것

• 코드: 파일 시스템에 그대로 있으므로 읽으면 됩니다
• 커밋 기록: git log 로 무엇을 했는지 확인할 수 있습니다
• 대화 흐름: "마감일 설정 기능을 구현하고 테스트를 통과시켰다" 식의 요약이 남습니다

정확도가 떨어질 수 있는 것

• 6개 기능 중 어디까지 끝났고, 다음에 뭘 해야 하는지
• 마감일순 정렬을 하려면 마감일 설정과 정렬이 둘 다 먼저 끝나야 한다는 선후 관계
• 검색 기능의 성공 기준이 "'회의' 검색 시 '회의' 포함 항목만 표시"라는 구체적 내용

코드를 읽으면 "지금 뭐가 있는지"는 알 수 있습니다. 하지만 "앞으로 뭘 해야 하고, 어떤 순서로 해야 하는지"는 코드에도 요약에도 원본만큼 정확하게 남지 않을 수 있습니다. 회의록 없이 머리로만 진행한 회의에서 절반쯤 가면 "우리가 뭘 결정했더라"가 모호해지는 것과 같습니다.

이 문제를 해결하려면 계획 자체를 context 밖에 저장해야 합니다.

Task: 회의록처럼 context 밖에 적어두는 계획

회의를 다시 떠올려 봅니다. 안건 6개를 머리로 다 담지 않고 회의록에 적어두면 어떻게 될까요? 회의가 길어져 처음 안건이 흐려져도, 회의록을 펼치면 안건과 결정 사항이 그대로 적혀 있습니다.

Task는 계획을 구성하는 하나의 작업 단위로, 회의록 한 줄에 해당합니다. 여러 필드가 있는데, 그중 핵심은 제목(subject), 상세 설명(description), 상태(status), 의존성(blockedBy/blocks)입니다. 이 외에 id, 생성/수정 시각 등도 자동으로 기록됩니다. Task는 ~/.claude/tasks/ 폴더에 JSON 파일로 저장됩니다. 이 파일은 context window 밖에 있으므로 auto-compact의 영향을 받지 않습니다. context가 요약되어도 AI가 이 파일을 읽으면 진행 상황을 정확하게 파악합니다.

Task의 생명주기

각 Task의 상태는 네 가지 중 하나입니다.

• pending: 아직 시작하지 않은 작업
• in_progress: 현재 진행 중인 작업
• completed: 완료된 작업
• blocked: 의존하는 다른 Task가 끝나야 시작할 수 있는 작업

AI가 작업을 시작하면 in_progress 로 바꾸고, 끝나면 completed 로 표시합니다. 회의 진행자가 회의록 옆에 ✓ 표시를 하나씩 채워가는 것과 같습니다.

Task 생성 직접 요청

Claude가 자동으로 Task를 만들기도 하지만, 항상 그렇지는 않습니다. 확실한 방법은 프롬프트에서 직접 요청하는 것입니다.

• "각 기능을 Task로 등록해줘"
• "기능별로 Task를 나눠서 진행해줘"

Plan Mode에서 계획을 승인할 때 Task 등록을 함께 요청하면, 계획을 Task로 자연스럽게 등록할 수 있습니다.

blockedBy: 작업 순서 명시

회의 안건들 사이에는 종종 선후 관계가 있습니다. 마케팅 예산이 정해져야 캠페인 일정을 잡을 수 있고, 신제품 사양이 확정돼야 출시 일자를 정할 수 있습니다. 회의록에 "이 안건은 저 안건이 결정되어야 진행 가능"이라고 적어두면, 진행자가 순서를 헷갈리지 않습니다.

Task도 같습니다. 마감일 데이터가 없으면 마감일순 정렬을 만들 수 없고, 카테고리 태그가 없으면 카테고리별 필터를 만들 수 없습니다. blockedBy는 "이 작업은 다른 작업이 끝나야 시작할 수 있다"는 의존 관계를 명시합니다. 반대 방향인 blocks는 같은 관계를 반대편에서 표현한 것입니다. "이 작업이 끝나야 다른 작업을 시작할 수 있다"는 뜻입니다.

{
  "tasks": [
    { "id": "1", "subject": "마감일 설정", "status": "pending" },
    { "id": "2", "subject": "정렬 기능 (이름순, 생성일순)", "status": "pending" },
    { "id": "3", "subject": "마감일순 정렬", "status": "pending", "blockedBy": ["1", "2"] },
    { "id": "4", "subject": "검색 기능", "status": "pending" },
    { "id": "5", "subject": "카테고리 태그", "status": "pending" },
    { "id": "6", "subject": "카테고리별 필터", "status": "pending", "blockedBy": ["5"] }
  ]
}

이 구조에서 AI는 세 가지를 즉시 판단합니다.

• Task 1, 2, 4, 5는 blockedBy가 없으므로 바로 시작할 수 있습니다
• Task 3은 Task 1과 Task 2가 모두 완료되어야 시작할 수 있습니다
• Task 6은 Task 5가 완료되어야 시작할 수 있습니다

[데모] Plan Mode에서 Task로 이어지는 흐름

Todo 앱 확장 계획의 6개 기능을 Plan Mode로 계획하고, 승인 시 Task로 등록하여 auto-compact 후에도 계획이 그대로 유지되는 흐름을 체험합니다.

Step 1: Plan Mode 진입 + 요구사항 전달

Shift+Tab 으로 Plan Mode에 진입한 뒤 성공 기준이 포함된 요구사항을 전달합니다.

Todo 앱에 아래 기능을 추가하려고 해.
각 기능을 Task 로 등록하고, 순서대로 구현해줘.
성공 기준을 테스트로 먼저 작성한 뒤, 테스트가 통과하도록 구현해줘.

## 기능

1. 마감일 설정 - Todo 에 마감일 지정 (없이도 추가 가능)
2. 정렬 - 이름순, 생성일순 선택
3. 마감일순 정렬 - 마감일 가까운 순 (1, 2 완료 후)
4. 검색 - 제목으로 검색
5. 카테고리 태그 - 업무/개인/쇼핑 태그 지정
6. 카테고리별 필터 - 특정 카테고리만 보기 (5 완료 후)

## 성공 기준

### 마감일 설정
- 마감일 없는 Todo 추가 -> 정상 추가, 마감일 칸 비어 있음
- 마감일 있는 Todo 추가 -> 목록에 마감일 표시

### 정렬
- Todo 5개에서 '이름순' 선택 -> 가나다순 정렬
- Todo 5개에서 '생성일순' 선택 -> 최신순 정렬

### 마감일순 정렬
- '마감일순' 선택 -> 마감일 가까운 항목부터 표시
- 마감일 없는 항목 2개 + 있는 항목 3개 -> 없는 항목은 맨 뒤

### 검색
- '회의' 검색 -> '회의' 포함 항목만 표시
- 검색어 지우기 -> 전체 목록 복원

### 카테고리 태그
- '업무' 태그 지정 후 저장 -> 목록에 태그 표시

### 카테고리별 필터
- '업무' 필터 선택 -> 업무 태그 항목만 표시
- '전체' 선택 -> 필터 해제, 전체 목록 표시

## 범위 제한
- 필터링과 정렬 조합은 구현하지 않는다
- 마감일 알림 기능은 구현하지 않는다

Claude가 구현 계획을 제시합니다.

Step 2: 플랜 리뷰 + 승인 + Task 등록

Lesson 03에서 배운 체크리스트로 플랜을 확인합니다. 성공 기준이 모두 반영되었고 범위를 넘지 않았다면 터미널에서 플랜을 승인합니다.

프롬프트에 Task 등록 요청이 포함되어 있으므로 Claude가 계획을 Task로 등록하고 의존성을 설정합니다.

Tasks:
[1] [ ] 마감일 설정
[2] [ ] 정렬 기능 (이름순, 생성일순)
[3] [ ] 마감일순 정렬                    blockedBy: [1, 2]
[4] [ ] 검색 기능
[5] [ ] 카테고리 태그
[6] [ ] 카테고리별 필터                  blockedBy: [5]

Task 1, 2, 4, 5는 독립이므로 어느 것부터 해도 됩니다. Task 3은 1, 2가, Task 6은 5가 끝나야 시작할 수 있습니다. Plan Mode에서 세운 계획이 회의록(Task 시스템)으로 옮겨졌습니다.

Step 3: 첫 Task 실행과 다음 Task 자동 진행

Claude가 바로 Task 1(마감일 설정)을 시작합니다. 마감일 입력 UI를 추가하고, 성공 기준을 검증한 뒤 completed 로 표시합니다.

이어서 Claude가 Task 2(정렬 기능)를 시작합니다. Task 2가 완료되면 Task 3(마감일순 정렬)의 blockedBy [1, 2]가 모두 해소되어 Claude가 자동으로 Task 3을 시작합니다. Task 1만 끝나고 Task 2가 아직이라면, Claude는 Task 3을 건너뛰고 Task 2를 먼저 진행합니다. blockedBy가 설정되어 있으면 AI가 순서를 지킵니다.

핵심 포인트 정리

1. auto-compact 후 흐려지는 진행·의존성: 코드는 파일에, 대화 흐름은 요약에 남지만 의존성 그래프·진행 상태·작업별 상세 설명은 요약 과정에서 원본만큼 정확하게 남지 않을 수 있습니다.
2. Task = context 밖 JSON 파일: Task는 ~/.claude/tasks/ 의 JSON 파일로 저장되어 auto-compact의 영향을 받지 않습니다. AI가 이 파일을 읽으면 진행 상황을 정확하게 파악합니다.
3. blockedBy/blocks로 작업 순서 명시: 의존성이 있는 작업은 순서대로, 독립적인 작업은 바로 시작할 수 있습니다. 회의록에 "이 안건은 저게 결정되어야 진행 가능"이라고 적어두는 것과 같습니다.

FAQ

• Q: Task를 꼭 사용해야 하나요? 간단한 작업도요?

  • A: 1-2단계로 끝나는 단순한 작업에는 Task가 필요 없습니다. 여러 기능을 나눠서 진행하거나 context overflow가 예상되는 큰 작업에 Task가 유용합니다. Claude가 자동으로 Task를 만들기도 하지만, 확실한 방법은 프롬프트에서 "각 기능을 Task로 등록해줘"처럼 직접 요청하는 것입니다.

• Q: AI가 Task 순서를 무시하고 건너뛰면 어떻게 하나요?

  • A: blockedBy가 정확히 설정되어 있으면 AI는 선행 Task가 완료되지 않은 작업을 시작하지 않습니다. 의존성을 빠뜨리지 않고 적는 것이 중요합니다.

• Q: auto-compact 후에도 Plan의 맥락이 유지되나요?

  • A: Plan Mode에서 논의한 대화 맥락(왜 이 방식을 선택했는지 등)은 auto-compact 시 요약으로 압축되어 뉘앙스를 잃을 수 있습니다. 하지만 Plan의 결과물인 Task 목록(subject, description, 의존성)이 JSON 파일에 남아 있으므로, AI는 "무엇을 해야 하는지"를 정확하게 파악합니다. Task의 description이 구체적일수록 auto-compact 대비 복원력이 높아집니다.

이어서 배울 내용

Task 시스템으로 auto-compact 후에도 계획의 정확성을 유지하는 방법을 배웠습니다. 이로써 Plan Mode와 Task를 함께 쓰는 워크플로우를 완성했습니다. 다음 챕터부터는 CLAUDE.md에 쌓인 규칙을 경로별로 분리하는 것부터 시작해, Context 품질을 지키는 다양한 도구를 배웁니다.

• CLAUDE.md의 규칙을 주제별 파일로 분리하고 경로별로 적용하기 (Rules)
• 반복 프롬프트를 한 단어로 호출하는 Custom Commands