Claude Code Task System 실전 활용 가이드

게시 2026/01/25

By BLUEBUG

82 분읽는 시간

영속적 작업 관리로 AI 협업 개발을 혁신하다

Task 시스템이 필요한 이유
To-Do vs Task: 무엇이 달라졌나
Task의 핵심 개념 3가지
실제 Task 파일 구조 완전 분석
실전 사용법: 단계별 가이드
언제 Task를 사용하고, 언제 사용하지 말아야 하나
다중 세션 협업 마스터하기
실전 워크플로우 패턴
Task 파일 직접 다루기
문제 해결 및 팁
고급 활용 시나리오

Task 시스템이 필요한 이유

Claude Code 2.1.16/2.1.17 버전에서 도입된 Task 시스템은 단순한 기능 추가가 아닙니다. 이는 AI 기반 개발 도구가 “일회성 어시스턴트”에서 “장기 협업 파트너”로 진화하는 중요한 전환점입니다.

기존 To-Do 시스템의 치명적 한계

Claude Code의 이전 To-Do 시스템은 대부분의 개발자들이 무시했습니다. 그 이유는 명확했습니다:

메모리에만 존재하는 휘발성: 터미널을 닫는 순간 모든 할 일 목록이 증발했습니다. 커피 한 잔 마시고 돌아와서 새 세션을 시작하면, Claude는 이전에 무엇을 하고 있었는지 전혀 기억하지 못했습니다.

서브에이전트 간 단절: 메인 에이전트가 추적하던 작업 목록을 서브에이전트는 전혀 알 수 없었습니다. 각 에이전트는 완전히 독립적으로 작동하여, 중복 작업이나 충돌이 빈번했습니다.

단순 작업에는 불필요: 한두 개 파일만 수정하는 간단한 작업의 경우, Claude는 이미 무엇을 해야 하는지 알고 있었습니다. 체크리스트는 오히려 귀찮은 오버헤드였습니다.

Opus 4.5와 장기 자율 실행의 등장

상황이 바뀐 것은 Opus 4.5 모델의 등장과 함께입니다. Opus 4.5는 훨씬 더 긴 시간 동안 자율적으로 작업을 수행할 수 있게 되었고, 자체적으로 상태를 추적할 수 있는 능력을 갖추었습니다.

Anthropic은 실제 사용 데이터를 분석한 결과, 흥미로운 패턴을 발견했습니다:

단순 작업: 기존 TodoWrite 도구가 거의 사용되지 않았습니다. Claude는 이미 무엇을 해야 하는지 알고 있었고, 별도의 체크리스트 없이도 완벽하게 작업을 수행했습니다.
복잡한 프로젝트: 여러 세션에 걸쳐 진행되거나 다수의 서브에이전트가 참여하는 대규모 프로젝트에서는 To-Do가 완전히 무용지물이었습니다. 상태 추적이 불가능했고, 협업 조율이 되지 않았습니다.

Task 시스템은 바로 이 격차를 메우기 위해 설계되었습니다. 간단한 작업은 여전히 Task 없이 처리하되, 복잡하고 장기적인 프로젝트를 위해서는 영속적이고, 공유 가능하며, 의존성을 추적할 수 있는 강력한 도구를 제공하는 것입니다.

Task가 해결하는 실제 문제들

시나리오 1: 대규모 리팩토링

기존 방식으로 100개 파일을 리팩토링한다고 가정해봅시다. To-Do로는 진행 상황을 추적할 수 없었습니다. 50개를 완료한 시점에 세션이 종료되면, 어디까지 했는지 수동으로 확인해야 했습니다.

Task 시스템에서는:

  
# Claude가 자동으로 100개 작업 생성
# 각 작업의 완료 상태가 JSON 파일로 저장
# 세션을 재시작해도 "51번째 파일부터 계속하세요"라고 정확히 알려줌

시나리오 2: 팀 협업

여러 개발자가 같은 기능을 개발하는 경우, 각자 자신의 Claude Code 세션을 실행합니다. 기존에는 누가 무엇을 하고 있는지 알 방법이 없었습니다.

Task 시스템에서는:

  
# 모든 개발자가 같은 TASK_LIST_ID 사용
# 개발자 A가 "인증 API" 작업 시작
# 개발자 B는 실시간으로 "인증 API는 진행 중"이라고 확인
# 개발자 B는 겹치지 않는 "데이터베이스 스키마" 작업 선택

시나리오 3: 의존성이 복잡한 프로젝트

마이크로서비스 아키텍처로 전환하는 경우, 작업 간의 의존성이 복잡합니다. 데이터베이스 스키마가 완성되어야 API를 만들 수 있고, API가 준비되어야 프론트엔드를 구현할 수 있습니다.

Task 시스템은 이러한 의존성을 자동으로 추적하고, 선행 작업이 완료될 때까지 후속 작업을 차단합니다.

To-Do vs Task: 무엇이 달라졌나

기존 To-Do 시스템과 새로운 Task 시스템의 차이를 구체적으로 살펴보겠습니다.

1. 저장 방식: 메모리 vs 파일 시스템

기존 To-Do:

메모리 내 데이터 구조
├─ Session ID: abc123
│  └─ todos: ["할 일 1", "할 일 2", "할 일 3"]
│
└─ 세션 종료 시: 모든 데이터 소멸

To-Do는 Claude Code 프로세스의 메모리에만 존재했습니다. 이는 마치 메모장에 적은 메모를 컴퓨터를 끄면서 저장하지 않는 것과 같습니다.

새로운 Task:

~/.claude/tasks/
└── a97e3eb7-205e-4ad3-9d42-f59e6efa1025/
    ├── 1.json  (304 bytes)
    ├── 2.json  (322 bytes)
    ├── 3.json  (320 bytes)
    └── ...

Task는 실제 파일 시스템에 JSON 파일로 저장됩니다. Windows, Mac, Linux 모두에서 동일한 방식으로 작동합니다. 세션을 종료해도, 컴퓨터를 재시작해도, 심지어 일주일 후에 돌아와도 모든 작업 정보가 그대로 유지됩니다.

2. 구조: 평면 리스트 vs 의존성 그래프

기존 To-Do:

☐ 데이터베이스 설정
☐ API 엔드포인트 구현
☐ 프론트엔드 UI 작성
☐ 테스트 작성
☐ 문서 업데이트

모든 항목이 동등한 우선순위를 가진 단순 리스트였습니다. “API 엔드포인트 구현은 데이터베이스 설정이 완료된 후에만 가능하다”는 관계를 표현할 수 없었습니다.

새로운 Task:

#1 데이터베이스 설정
 └─► #2 API 엔드포인트 구현 (blocked by #1)
      ├─► #3 프론트엔드 UI 작성 (blocked by #2)
      └─► #4 테스트 작성 (blocked by #2)
           └─► #5 문서 업데이트 (blocked by #4)

각 작업은 blocks (이 작업이 완료되어야 시작할 수 있는 다른 작업들)와 blockedBy (이 작업을 시작하기 전에 완료되어야 하는 선행 작업들) 필드를 통해 명확한 의존성 관계를 표현합니다.

이는 실제 프로젝트의 작업 흐름을 정확히 반영합니다. Claude는 이 의존성 그래프를 보고 어떤 작업을 병렬로 진행할 수 있고, 어떤 작업은 대기해야 하는지 자동으로 판단합니다.

3. 협업: 격리 vs 공유

기존 To-Do:

터미널 1: Session A
  └─ To-Do: [작업 1, 작업 2]

터미널 2: Session B
  └─ To-Do: [작업 3, 작업 4]

↑ 두 세션은 서로를 전혀 인식하지 못함

각 세션은 완전히 독립적이었습니다. 한 터미널에서 작업을 완료해도, 다른 터미널의 Claude는 그 사실을 알 수 없었습니다.

새로운 Task:

터미널 1: Session A (TASK_LIST_ID=my-project)
터미널 2: Session B (TASK_LIST_ID=my-project)
터미널 3: Session C (TASK_LIST_ID=my-project)
    ↓
모두 동일한 ~/.claude/tasks/my-project/ 디렉토리 참조
    ↓
실시간 동기화: Session A가 작업 완료 → Session B, C 즉시 확인

같은 TASK_LIST_ID를 설정한 모든 세션은 동일한 작업 목록을 공유합니다. 하나의 세션에서 작업 상태가 변경되면, 다른 세션들도 파일 시스템을 통해 즉시 그 변경사항을 확인할 수 있습니다.

4. 상태 표현: 이진 vs 다중 상태

기존 To-Do:

☐ 작업 A (미완료)
☑ 작업 B (완료)

체크되었거나 체크되지 않았거나, 두 가지 상태만 존재했습니다.

새로운 Task:

  
{
  "status": "pending"      // 대기 중
  "status": "in_progress"  // 진행 중
  "status": "completed"    // 완료
}

실제로는 세 가지 주요 상태가 있으며, 의존성에 따라 “blocked” 상태도 자동으로 표현됩니다. 이는 작업의 실제 진행 상황을 훨씬 정확하게 반영합니다.

5. 메타데이터: 없음 vs 풍부한 정보

기존 To-Do:

단순 문자열: "사용자 인증 구현"

작업에 대한 추가 정보를 저장할 방법이 없었습니다.

새로운 Task:

  
{
  "id": "1",
  "subject": "사용자 인증 구현",
  "description": "JWT 기반 토큰 인증 시스템 구축, bcrypt로 비밀번호 해싱",
  "activeForm": "인증 시스템 구현 중",
  "status": "in_progress",
  "blocks": ["3", "4"],
  "blockedBy": ["1"]
}

각 작업은 제목, 상세 설명, 현재 진행 형태, 상태, 의존성 정보 등 풍부한 메타데이터를 포함합니다.

Task의 핵심 개념 3가지

Task 시스템을 효과적으로 사용하려면 세 가지 핵심 개념을 이해해야 합니다.

1. 영속성 (Persistence)

영속성이란? 프로그램이 종료되어도 데이터가 사라지지 않고 저장 장치에 보존되는 특성입니다.

Task 시스템의 영속성은 파일 시스템을 기반으로 합니다:

  
# Windows
C:\Users\YourName\.claude\tasks\

# Mac/Linux
~/.claude/tasks/

이 디렉토리는 사용자의 홈 디렉토리에 위치하며, Claude Code와 완전히 독립적입니다. 즉:

Claude Code를 업데이트해도 작업 데이터는 유지됩니다
Claude Code를 완전히 삭제하고 재설치해도 작업 데이터는 남아있습니다
여러 버전의 Claude Code를 번갈아 사용해도 같은 작업 데이터를 공유합니다

실제 활용 시나리오:

금요일 오후 5시:
  - 대규모 리팩토링 작업 시작
  - 100개 작업 중 30개 완료
  - 퇴근하면서 터미널 종료

월요일 오전 9시:
  - Claude Code 재시작
  - "지난주 작업 계속해줘"
  - Claude가 정확히 31번째 작업부터 재개

2. 의존성 추적 (Dependency Tracking)

의존성이란? 특정 작업이 다른 작업의 완료에 의존하는 관계입니다.

Task 시스템은 두 가지 방향의 의존성을 추적합니다:

blockedBy (선행 의존성): 이 작업을 시작하기 전에 완료되어야 하는 작업들 blocks (후행 의존성): 이 작업이 완료되어야 시작할 수 있는 작업들

실제 예시:

  
// Task 1: 데이터베이스 설정
{
  "id": "1",
  "subject": "데이터베이스 설정",
  "blockedBy": [],        // 선행 작업 없음 → 즉시 시작 가능
  "blocks": ["2"]         // Task 2는 이것이 완료될 때까지 대기
}

// Task 2: API 구현
{
  "id": "2",
  "subject": "API 엔드포인트 구현",
  "blockedBy": ["1"],     // Task 1이 완료될 때까지 대기
  "blocks": ["3", "4"]    // Task 3, 4는 이것이 완료될 때까지 대기
}

// Task 3: 프론트엔드
{
  "id": "3",
  "subject": "프론트엔드 UI",
  "blockedBy": ["2"],     // Task 2가 완료될 때까지 대기
  "blocks": []
}

// Task 4: 테스트
{
  "id": "4",
  "subject": "통합 테스트",
  "blockedBy": ["2"],     // Task 2가 완료될 때까지 대기
  "blocks": []
}

병렬 처리 가능성 식별:

위 예시에서 Task 3과 Task 4는 모두 Task 2에만 의존하고 서로에게는 의존하지 않습니다. 따라서 Task 2가 완료되면 Task 3과 Task 4를 동시에 병렬로 진행할 수 있습니다.

Claude는 이러한 병렬 처리 기회를 자동으로 식별하고, 다음과 같이 제안합니다:

● Task #2 완료됨!
● 다음 작업 가능: Task #3, Task #4
● 이 두 작업은 서로 독립적이므로 병렬 처리 권장

옵션 1: 두 개의 터미널에서 동시에 진행
  터미널 A: Task #3 처리
  터미널 B: Task #4 처리

옵션 2: 서브에이전트 활용
  메인: Task #3을 서브에이전트에 위임
  메인: Task #4 직접 처리

3. 다중 세션 협업 (Multi-Session Collaboration)

핵심 메커니즘: CLAUDE_CODE_TASK_LIST_ID 환경 변수

이 환경 변수는 작업 목록을 저장할 디렉토리의 이름을 지정합니다. 같은 값을 사용하는 모든 Claude Code 세션은 동일한 작업 목록을 공유합니다.

설정 방법:

  
# Mac/Linux
export CLAUDE_CODE_TASK_LIST_ID="my-project"
claude

# Windows PowerShell
$env:CLAUDE_CODE_TASK_LIST_ID="my-project"
claude

# Windows CMD
set CLAUDE_CODE_TASK_LIST_ID=my-project
claude

실시간 동기화 작동 방식:

시간 09:00 - 터미널 A
  → Task #1 시작
  → 1.json 파일에 status: "in_progress" 기록

시간 09:01 - 터미널 B
  → Ctrl+T 눌러 작업 목록 확인
  → 파일 시스템에서 1.json 읽기
  → "Task #1은 진행 중" 확인
  → Task #2 선택하여 시작

시간 09:30 - 터미널 A
  → Task #1 완료
  → 1.json 파일에 status: "completed" 기록
  → 2.json 파일의 blockedBy에서 "1" 제거

시간 09:31 - 터미널 B
  → 자동으로 파일 변경 감지
  → "Task #1이 완료되어 Task #2의 블록 해제됨" 알림 표시

협업 시나리오:

  
# 개발자 A의 터미널
export CLAUDE_CODE_TASK_LIST_ID="team-sprint-2026-w04"
cd ~/project/backend
claude
> "Task #5 (API 인증 구현) 처리해줘"

# 개발자 B의 터미널
export CLAUDE_CODE_TASK_LIST_ID="team-sprint-2026-w04"
cd ~/project/frontend
claude
> Ctrl+T로 목록 확인
> "Task #5는 개발자 A가 진행 중"
> "Task #6 (프론트엔드 로그인 폼) 시작해줘"

# 개발자 C의 터미널
export CLAUDE_CODE_TASK_LIST_ID="team-sprint-2026-w04"
cd ~/project/tests
claude
> "Task #7 (통합 테스트) 시작해줘"
> "아, Task #7은 Task #5, #6이 완료될 때까지 blocked 상태네"
> "대신 Task #8 (단위 테스트) 먼저 할게"

실제 Task 파일 구조 완전 분석

이론적인 설명을 넘어, 실제로 생성된 Task 파일의 구조를 상세히 분석해보겠습니다.

Task 디렉토리 구조

Claude Code에서 Task를 생성하면 다음과 같은 디렉토리 구조가 만들어집니다:

~/.claude/
└── tasks/
    └── a97e3eb7-205e-4ad3-9d42-f59e6efa1025/
        ├── 1.json   (304 bytes)
        ├── 2.json   (322 bytes)
        ├── 3.json   (320 bytes)
        ├── 4.json   (353 bytes)
        ├── 5.json   (409 bytes)
        ├── 6.json   (359 bytes)
        ├── 7.json   (354 bytes)
        └── 8.json   (370 bytes)

디렉토리 이름의 의미:

a97e3eb7-205e-4ad3-9d42-f59e6efa1025는 작업 목록의 고유 ID입니다
기본적으로 현재 프로젝트 디렉토리 경로를 해싱하여 자동 생성됩니다
CLAUDE_CODE_TASK_LIST_ID 환경 변수로 명시적으로 지정할 수도 있습니다

파일 이름 규칙:

각 작업은 {id}.json 형식의 파일명을 갖습니다
1.json은 Task #1, 2.json은 Task #2를 나타냅니다
파일 크기는 작업의 설명 길이에 따라 달라집니다 (보통 300-500 bytes)

JSON 파일 내부 구조

Joe Njenga의 실제 예시에서 나온 Task #1의 완전한 구조를 살펴보겠습니다:

  
{
  "id": "1",
  "subject": "Initialize project and install dependencies",
  "description": "Set up project structure, package.json, and install core dependencies (express, dotenv, cors, etc.)",
  "activeForm": "Initializing project",
  "status": "pending",
  "blocks": ["2"],
  "blockedBy": []
}

각 필드의 의미와 활용:

1. id (작업 식별자)

  
"id": "1"

타입: 문자열 (숫자처럼 보이지만 문자열로 저장됨)
용도: 작업의 고유 식별자, 의존성 참조에 사용
특징: 생성 순서대로 1부터 증가
불변성: 한번 할당되면 변경되지 않음

2. subject (작업 제목)

  
"subject": "Initialize project and install dependencies"

타입: 문자열
용도: 작업 목록에 표시될 간단한 제목
권장: 50자 이내의 명확한 동사 형태
예시:
- “Configure database connection”
- “Implement JWT authentication”
- “Write integration tests”

3. description (상세 설명)

  
"description": "Set up project structure, package.json, and install core dependencies (express, dotenv, cors, etc.)"

타입: 문자열
용도: 작업의 구체적인 내용과 요구사항
권장: 무엇을, 어떻게, 왜 해야 하는지 포함
활용: Claude가 작업을 정확히 이해하고 실행하는 데 사용

예시:

"Set up PostgreSQL database with user authentication tables.
 Include columns for: id, email, password_hash, created_at.
 Use UUID for id, bcrypt for password hashing."

4. activeForm (진행 중 표현)

  
"activeForm": "Initializing project"

타입: 문자열
용도: 작업이 진행 중일 때 표시될 동사 형태
특징: subject의 진행형 버전
예시:
- subject: “Configure database” → activeForm: “Configuring database”
- subject: “Write tests” → activeForm: “Writing tests”

5. status (작업 상태)

  
"status": "pending"

타입: 문자열 (열거형)
가능한 값:
- "pending": 아직 시작하지 않음
- "in_progress": 현재 진행 중
- "completed": 완료됨
자동 전환:
- pending → in_progress: Claude가 작업을 시작할 때
- in_progress → completed: Claude가 작업을 완료할 때

6. blocks (이 작업이 차단하는 작업들)

  
"blocks": ["2"]

타입: 문자열 배열
의미: Task #1이 완료되어야 Task #2를 시작할 수 있음
다중 값 예시:
1 "blocks": ["2", "3", "4"]
→ Task #1 완료 시 Task #2, #3, #4가 모두 시작 가능해짐
빈 배열: 다른 작업을 차단하지 않음

7. blockedBy (이 작업을 차단하는 작업들)

  
"blockedBy": []

타입: 문자열 배열
의미: 이 작업을 시작하기 전에 완료되어야 하는 작업들
빈 배열: 즉시 시작 가능
예시:
1 "blockedBy": ["1"]
→ Task #1이 완료될 때까지 대기
1 "blockedBy": ["3", "4"]
→ Task #3과 Task #4가 모두 완료될 때까지 대기

실제 8개 작업의 완전한 의존성 그래프

Joe Njenga의 REST API 인증 시스템 예시에서, 8개 작업의 전체 JSON 구조와 그들의 관계를 시각화하면 다음과 같습니다:

작업 의존성 트리:

#1 Initialize project
 │
 └─► #2 Configure database (blockedBy: ["1"])
      │
      └─► #3 Create User model (blockedBy: ["2"])
           │
           └─► #4 Auth utilities (blockedBy: ["3"])
                ├─► #5 Auth routes (blockedBy: ["4"])
                │    │
                │    └──────────────┐
                │                   ↓
                └─► #6 Auth middleware (blockedBy: ["4"])
                     │
                     └─► #7 Protected routes (blockedBy: ["6"])
                          │
                          └─► #8 Tests (blockedBy: ["5", "7"])

병렬 처리 기회:

Task #5와 #6은 모두 Task #4에만 의존하므로, Task #4 완료 후 동시에 진행 가능
Task #8은 Task #5와 #7 모두 완료될 때까지 대기

크리티컬 패스 (Critical Path):

가장 긴 의존성 체인:

#1 → #2 → #3 → #4 → #6 → #7 → #8

이 경로의 모든 작업이 순차적으로 완료되어야 전체 프로젝트가 완료됩니다.

Task 파일 직접 확인하기

Windows PowerShell:

  
# 작업 디렉토리 찾기
Get-ChildItem ~\.claude\tasks

# 출력:
# Directory: C:\Users\User\.claude\tasks
# Mode    LastWriteTime         Length Name
# ----    -------------         ------ ----
# d-----  1/23/2026  11:18 PM          a97e3eb7-205e-4ad3-9d42-f59e6efa1025

# 특정 작업 목록의 모든 작업 보기
Get-ChildItem ~\.claude\tasks\a97e3eb7-205e-4ad3-9d42-f59e6efa1025

# 출력:
# Mode    LastWriteTime         Length Name
# ----    -------------         ------ ----
# -a----  1/23/2026  11:18 PM     304   1.json
# -a----  1/23/2026  11:18 PM     322   2.json
# ...

# 특정 작업 내용 읽기
Get-Content ~\.claude\tasks\a97e3eb7-205e-4ad3-9d42-f59e6efa1025\1.json

# 모든 작업 내용 한번에 보기
Get-Content ~\.claude\tasks\a97e3eb7-205e-4ad3-9d42-f59e6efa1025\*.json

Mac/Linux:

  
# 작업 디렉토리 구조 보기
ls -la ~/.claude/tasks/

# 특정 작업 목록의 모든 작업 나열
ls -lh ~/.claude/tasks/a97e3eb7-205e-4ad3-9d42-f59e6efa1025/

# 특정 작업 내용 읽기 (예쁘게 포맷팅)
cat ~/.claude/tasks/a97e3eb7-205e-4ad3-9d42-f59e6efa1025/1.json | jq '.'

# 모든 작업의 제목과 상태만 간단히 확인
for file in ~/.claude/tasks/a97e3eb7-205e-4ad3-9d42-f59e6efa1025/*.json; do
  echo "$(basename $file): $(jq -r '.subject + " (" + .status + ")"' $file)"
done

# 출력 예시:
# 1.json: Initialize project and install dependencies (completed)
# 2.json: Configure database connection (in_progress)
# 3.json: Create User model and schema (pending)

실전 사용법: 단계별 가이드

실제로 Task 시스템을 사용하는 과정을 처음부터 끝까지 따라가보겠습니다.

단계 1: Claude Code 버전 확인

Task 시스템은 Claude Code 2.1.16 이상에서 사용 가능합니다. 반드시 최신 버전으로 업데이트하세요.

  
# 버전 확인
claude --version

# 출력 예시:
# Claude Code version 2.1.17

# 2.1.16 미만이면 업데이트
npm update -g @anthropic-ai/claude-code

단계 2: 프로젝트에서 Claude Code 시작

  
# 프로젝트 디렉토리로 이동
cd ~/projects/my-rest-api

# Claude Code 실행
claude

단계 3: Task 생성 요청

가장 간단한 방법은 Claude에게 직접 작업 분해를 요청하는 것입니다.

예시 프롬프트:

Break down building a REST API with user authentication into tasks with dependencies

또는 한글로:

JWT 토큰 기반 사용자 인증 시스템 구축을 의존성을 포함한 작업들로 나눠줘

단계 4: Claude의 작업 생성 과정 관찰

Claude는 다음과 같은 순서로 작업을 생성합니다:

❯ JWT 토큰 기반 사용자 인증 시스템 구축을 의존성을 포함한 작업들로 나눠줘

● 논리적인 작업들로 의존성과 함께 분해하겠습니다.
✔ Task #1 생성됨: 프로젝트 초기화 및 의존성 설치
✔ Task #2 생성됨: 데이터베이스 연결 설정
✔ Task #3 생성됨: User 모델 및 스키마 생성
✔ Task #4 생성됨: 비밀번호 해싱 및 JWT 유틸리티 구현
✔ Task #5 생성됨: 인증 라우트 구축 (register/login/logout)
✔ Task #6 생성됨: 인증 미들웨어 생성
✔ Task #7 생성됨: 보호된 사용자 라우트 추가
✔ Task #8 생성됨: 인증 플로우 테스트 작성

● 이제 의존성을 설정하겠습니다.
✔ Task #2 업데이트됨: blockedBy 설정
✔ Task #3 업데이트됨: blockedBy 설정
✔ Task #4 업데이트됨: blockedBy 설정
✔ Task #5 업데이트됨: blockedBy 설정
✔ Task #6 업데이트됨: blockedBy 설정
✔ Task #7 업데이트됨: blockedBy 설정
✔ Task #8 업데이트됨: blockedBy 설정

8개 작업 (0개 완료, 8개 진행 가능)

단계 5: 작업 목록 확인

Ctrl+T를 누르면 작업 목록이 표시됩니다:

Tasks (0 done, 8 open) · ctrl+t to hide tasks

◻ #1 프로젝트 초기화 및 의존성 설치
◻ #2 데이터베이스 연결 설정 › blocked by #1
◻ #3 User 모델 및 스키마 생성 › blocked by #2
◻ #4 비밀번호 해싱 및 JWT 유틸리티 구현 › blocked by #3
◻ #5 인증 라우트 구축 › blocked by #4
◻ #6 인증 미들웨어 생성 › blocked by #4
◻ #7 보호된 사용자 라우트 추가 › blocked by #6
◻ #8 인증 플로우 테스트 작성 › blocked by #5, #7

단계 6: 의존성 그래프 시각화

Claude가 자동으로 ASCII 아트로 의존성 트리를 그려줍니다:

작업 의존성 구조:

  #1 프로젝트 초기화
   └─► #2 데이터베이스 설정
        └─► #3 User 모델 생성
             └─► #4 인증 유틸리티 (bcrypt/JWT)
                  ├─► #5 인증 라우트 (register/login/logout)
                  │    └────────────────────┐
                  └─► #6 인증 미들웨어      │
                       └─► #7 보호된 라우트 │
                            └─► #8 테스트 ◄─┘

주요 의존성 노트:
- Task #5와 #6은 병렬 실행 가능 (둘 다 #4에만 의존)
- Task #8 (테스트)은 인증 라우트와 보호된 라우트 모두 완료 대기
- 크리티컬 패스: 1 → 2 → 3 → 4 → 6 → 7 → 8

Task #1부터 시작할까요?

단계 7: 작업 실행

옵션 A: Claude에게 작업 실행 요청

> Task #1 처리해줘

옵션 B: 자동 실행 요청

> Ready to start with task #1? (Claude의 질문에 대한 답변)
> Yes, let's start

옵션 C: 순차적으로 모든 작업 실행

> Task #1부터 #8까지 순서대로 처리해줘

단계 8: 진행 상황 모니터링

작업이 진행되는 동안 언제든 Ctrl+T를 눌러 현재 상태를 확인할 수 있습니다:

Tasks (3 done, 5 open)

☑ #1 프로젝트 초기화 및 의존성 설치
☑ #2 데이터베이스 연결 설정
☑ #3 User 모델 및 스키마 생성
▶ #4 비밀번호 해싱 및 JWT 유틸리티 구현 (in progress)
◻ #5 인증 라우트 구축 › blocked by #4
◻ #6 인증 미들웨어 생성 › blocked by #4
◻ #7 보호된 사용자 라우트 추가 › blocked by #6
◻ #8 인증 플로우 테스트 작성 › blocked by #5, #7

아이콘 의미:

☑ 완료됨 (completed)
▶ 진행 중 (in_progress)
◻ 대기 중 (pending)
› blocked by: 차단 상태

단계 9: 세션 종료 및 재개

세션 종료:

exit
# 또는 Ctrl+C

다음 날 재개:

cd ~/projects/my-rest-api
claude

> 어제 작업 계속해줘

Claude는 자동으로 파일 시스템에서 작업 목록을 읽어와 정확히 중단된 지점부터 재개합니다.

단계 10: 완료 확인

모든 작업이 완료되면:

Tasks (8 done, 0 open)

☑ #1 프로젝트 초기화 및 의존성 설치
☑ #2 데이터베이스 연결 설정
☑ #3 User 모델 및 스키마 생성
☑ #4 비밀번호 해싱 및 JWT 유틸리티 구현
☑ #5 인증 라우트 구축
☑ #6 인증 미들웨어 생성
☑ #7 보호된 사용자 라우트 추가
☑ #8 인증 플로우 테스트 작성

🎉 모든 작업이 완료되었습니다!

언제 Task를 사용하고, 언제 사용하지 말아야 하나

Task 시스템은 강력하지만, 모든 상황에 적합한 것은 아닙니다. Joe Njenga의 경험을 바탕으로 명확한 가이드라인을 제시합니다.

Task를 사용하지 말아야 할 때

1. 빠른 버그 수정

나쁜 예:
> "이 버튼 클릭 안 되는 버그 수정해줘"
> Claude: "작업으로 분해할까요?"
> ❌ 불필요한 오버헤드

좋은 예:
> "이 버튼 클릭 안 되는 버그 수정해줘"
> Claude: [즉시 코드 수정]
> ✓ 바로 처리

왜? 단일 파일의 간단한 수정은 Claude가 이미 무엇을 해야 하는지 알고 있습니다. Task로 분해하는 것은 시간 낭비입니다.

2. 단일 파일 리팩토링

나쁜 예:
> "utils.ts 파일을 함수형으로 리팩토링해줘"
> Claude: "4개 작업으로 나눌까요?"
> ❌ 과도한 세분화

좋은 예:
> "utils.ts 파일을 함수형으로 리팩토링해줘"
> Claude: [전체 파일 리팩토링]
> ✓ 한 번에 처리

왜? 단일 파일 내의 작업은 컨텍스트가 완전히 명확하므로 Task로 분해할 필요가 없습니다.

3. 간단한 질문이나 설명

나쁜 예:
> "React의 useEffect 훅 설명해줘"
> Claude: "설명 작업을 만들까요?"
> ❌ 의미 없음

좋은 예:
> "React의 useEffect 훅 설명해줘"
> Claude: [즉시 설명]
> ✓ 직접 답변

왜? 정보 제공이나 설명은 상태 추적이 필요 없습니다.

4. Claude가 한 번에 처리할 수 있는 모든 것

판단 기준:
- 파일 3개 이하?
- 10분 이내 완료 가능?
- 명확한 단일 목표?
→ Task 없이 처리

Task를 사용해야 할 때

1. 다중 파일 기능 개발

✓ 좋은 예:
> "사용자 인증 시스템 전체 구축해줘
   - 백엔드 API
   - 프론트엔드 UI
   - 데이터베이스 스키마
   - 테스트"

→ 10-15개 파일 관련
→ 여러 컴포넌트 걸침
→ Task로 분해 권장

왜? 각 부분(백엔드, 프론트엔드, DB, 테스트)은 독립적으로 작업 가능하며, 명확한 의존성이 있습니다.

2. 대규모 리팩토링

✓ 좋은 예:
> "전체 코드베이스를 JavaScript에서 TypeScript로 변환해줘
   - 100개 파일
   - 타입 정의 생성
   - 설정 파일 업데이트
   - 빌드 프로세스 수정"

→ Task로 분해하여 진행 추적
→ 세션 간 이어서 작업
→ 병렬 처리 가능

왜? 장시간 작업이며, 중간에 중단/재개가 필요하고, 진행 상황을 명확히 추적해야 합니다.

3. 다중 세션 프로젝트

✓ 좋은 예:
금요일:
  > "마이크로서비스 아키텍처로 전환 계획 수립"
  > 20개 작업 생성
  > Task #1-#5 완료
  > 퇴근

월요일:
  > "지난주 작업 계속"
  > Task #6부터 재개

왜? Task 파일에 모든 진행 상황이 저장되어 정확한 재개가 가능합니다.

4. 서브에이전트 조율이 필요한 작업

✓ 좋은 예:
메인 에이전트:
  > "백엔드 API는 서브에이전트에게 맡기고
     나는 프론트엔드 작업할게"

서브에이전트 A:
  → Task #1-#5 (백엔드) 처리

메인:
  → Task #6-#10 (프론트엔드) 처리

→ 병렬 처리로 시간 절약

왜? 각 에이전트가 독립적으로 작업하면서도 전체 진행 상황을 공유할 수 있습니다.

5. 나중에 돌아올 작업

✓ 좋은 예:
오전:
  > "새로운 기능 개발 작업 목록 만들어줘"
  > 15개 작업 생성
  > "일단 저장만 하고 오후에 시작할게"

오후:
  > "오전에 만든 작업 목록 시작하자"
  > Claude: "15개 작업 로드 완료, Task #1부터 시작합니다"

왜? 작업 계획과 실행을 분리할 수 있고, 언제든 재개 가능합니다.

의사결정 플로우차트

질문에 답해보세요:

1. 이 작업이 파일 5개 이상 관련되나요?
   ├─ 예 → Task 사용 고려
   └─ 아니오 → 2번으로

2. 이 작업이 30분 이상 걸릴 것 같나요?
   ├─ 예 → Task 사용 고려
   └─ 아니오 → 3번으로

3. 중간에 중단하고 나중에 재개할 가능성이 있나요?
   ├─ 예 → Task 사용 고려
   └─ 아니오 → 4번으로

4. 여러 사람이나 여러 세션에서 협업하나요?
   ├─ 예 → Task 사용 필수
   └─ 아니오 → 5번으로

5. 명확한 작업 의존성이 있나요? (A 완료 후 B 시작)
   ├─ 예 → Task 사용 고려
   └─ 아니오 → Task 없이 진행

최종 판단:
- "고려" 항목이 2개 이상: Task 사용 권장
- "필수" 항목 하나라도: 반드시 Task 사용
- 모두 "아니오": Task 없이 간단히 처리

다중 세션 협업 마스터하기

Task 시스템의 가장 강력한 기능은 여러 Claude Code 세션이 동일한 작업 목록을 공유하며 협업할 수 있다는 점입니다.

기본 설정: TASK_LIST_ID 사용

핵심 원칙: 같은 CLAUDE_CODE_TASK_LIST_ID 값을 사용하는 모든 세션은 동일한 작업 목록을 공유합니다.

시나리오: 단일 개발자, 여러 터미널

  
# 터미널 1 (메인 작업)
export CLAUDE_CODE_TASK_LIST_ID="my-auth-project"
cd ~/projects/auth-system
claude

# 터미널 2 (테스트 작업)
export CLAUDE_CODE_TASK_LIST_ID="my-auth-project"
cd ~/projects/auth-system
claude

# 터미널 3 (문서 작업)
export CLAUDE_CODE_TASK_LIST_ID="my-auth-project"
cd ~/projects/auth-system
claude

결과: 세 터미널 모두 ~/.claude/tasks/my-auth-project/ 디렉토리의 동일한 JSON 파일들을 읽고 씁니다.

환경 변수 설정 방법 (OS별)

Mac/Linux (Bash/Zsh):

  
# 현재 세션만:
export CLAUDE_CODE_TASK_LIST_ID="project-name"

# 프로젝트 디렉토리에 들어갈 때 자동 설정 (direnv 사용):
# .envrc 파일 생성
echo 'export CLAUDE_CODE_TASK_LIST_ID="project-name"' > .envrc
direnv allow

# 모든 터미널에서 영구적으로 (권장하지 않음):
echo 'export CLAUDE_CODE_TASK_LIST_ID="default-project"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell:

  
# 현재 세션만:
$env:CLAUDE_CODE_TASK_LIST_ID="project-name"

# 영구 설정 (사용자 레벨):
[System.Environment]::SetEnvironmentVariable(
  "CLAUDE_CODE_TASK_LIST_ID",
  "project-name",
  "User"
)

# 프로젝트별 자동 설정 (PowerShell 프로필):
# $PROFILE 파일 편집
if (Test-Path ".\project-marker.txt") {
  $env:CLAUDE_CODE_TASK_LIST_ID="project-name"
}

Windows CMD:

REM 현재 세션만:
set CLAUDE_CODE_TASK_LIST_ID=project-name

REM 영구 설정:
setx CLAUDE_CODE_TASK_LIST_ID "project-name"

실시간 협업 워크플로우

예시: REST API 개발을 3개 세션으로 병렬 처리

단계 1: 메인 세션에서 작업 계획 수립

  
# 터미널 1 (메인 기획)
export CLAUDE_CODE_TASK_LIST_ID="rest-api-sprint"
claude

> "REST API 백엔드를 다음과 같이 나눠줘:
   - 데이터베이스 설정
   - 사용자 인증 API
   - 게시물 CRUD API
   - 댓글 시스템
   - 테스트 및 문서화
   각 단계별로 의존성 포함해서 작업 생성해줘"

Claude의 응답:

✔ Task #1 생성: 데이터베이스 스키마 설계
✔ Task #2 생성: DB 연결 및 마이그레이션
✔ Task #3 생성: 사용자 모델 및 인증 API
✔ Task #4 생성: JWT 미들웨어 구현
✔ Task #5 생성: 게시물 모델 및 CRUD API
✔ Task #6 생성: 댓글 모델 및 API
✔ Task #7 생성: API 통합 테스트
✔ Task #8 생성: API 문서 작성 (Swagger)

의존성 설정:
- Task #2 depends on #1
- Task #3 depends on #2
- Task #4 depends on #3
- Task #5 depends on #2 (병렬 가능!)
- Task #6 depends on #5
- Task #7 depends on #4, #6
- Task #8 depends on #7

단계 2: 병렬 작업 분배

  
# 터미널 2 (개발자 A 또는 서브에이전트)
export CLAUDE_CODE_TASK_LIST_ID="rest-api-sprint"
claude

> Ctrl+T로 작업 목록 확인
> "Task #3 (사용자 인증 API) 처리해줘"

# 터미널 3 (개발자 B 또는 또 다른 서브에이전트)
export CLAUDE_CODE_TASK_LIST_ID="rest-api-sprint"
claude

> Ctrl+T로 작업 목록 확인
> "Task #5 (게시물 CRUD API) 처리해줘"
> ⚠️ 주의: Task #5는 Task #2에 의존하므로 #2 완료 후 시작됨

# 터미널 1 (메인)
> "Task #1, #2 먼저 완료할게"
> [#1, #2 완료]
> → 터미널 2와 3이 자동으로 인식하고 각자 작업 시작

단계 3: 실시간 상태 동기화

[09:00] 터미널 1
  → Task #1 시작
  → 1.json에 status: "in_progress" 기록

[09:02] 터미널 2
  → Ctrl+T 눌러 확인
  → "Task #1 진행 중" 표시
  → Task #3은 아직 blocked (Task #2 대기)

[09:15] 터미널 1
  → Task #1 완료
  → 1.json에 status: "completed" 기록
  → Task #2 시작

[09:16] 터미널 2, 3
  → 자동으로 파일 변경 감지
  → "Task #1 완료됨" 업데이트

[09:45] 터미널 1
  → Task #2 완료
  → 2.json에 status: "completed" 기록

[09:46] 터미널 2
  → Task #3의 blocked 상태 자동 해제
  → "Task #3 시작 가능" 알림
  → Task #3 자동 시작

[09:46] 터미널 3
  → Task #5의 blocked 상태 자동 해제
  → "Task #5 시작 가능" 알림
  → Task #5 자동 시작

→ Task #3과 #5가 병렬로 동시 진행!

CLI 모드에서의 Task 협업

대화형 세션뿐만 아니라 CLI 명령어로도 Task를 활용할 수 있습니다.

자동화 스크립트 예시:

  
#!/bin/bash

# 공유 Task List ID 설정
export CLAUDE_CODE_TASK_LIST_ID="automated-pipeline"

# Task 생성
claude -p "마이크로서비스 배포 파이프라인을 10개 작업으로 나눠줘"

# 각 작업을 순차적으로 처리
for i in {1..10}; do
  echo "Processing Task #$i..."
  claude -p "Task #$i 처리해줘"
  
  # 에러 발생 시 중단
  if [ $? -ne 0 ]; then
    echo "Task #$i failed, stopping pipeline"
    exit 1
  fi
done

echo "All tasks completed!"

병렬 처리 스크립트:

  
#!/bin/bash

export CLAUDE_CODE_TASK_LIST_ID="parallel-build"

# Task 생성
claude -p "100개 컴포넌트를 10개 그룹으로 나눠서 작업 생성해줘"

# 5개 병렬 프로세스로 처리
for i in {1..5}; do
  (
    # 각 프로세스가 2개 작업씩 처리
    start=$((i * 2 - 1))
    end=$((i * 2))
    
    for task_id in $(seq $start $end); do
      claude -p "Task #$task_id 처리해줘"
    done
  ) &
done

# 모든 병렬 프로세스 완료 대기
wait

echo "All parallel tasks completed!"

팀 협업 베스트 프랙티스

1. 명명 규칙 통일

  
# 권장: 프로젝트명-스프린트-날짜
CLAUDE_CODE_TASK_LIST_ID="myapp-sprint-2026-01"

# 권장: 기능별 그룹화
CLAUDE_CODE_TASK_LIST_ID="myapp-auth-feature"

# 비권장: 너무 일반적
CLAUDE_CODE_TASK_LIST_ID="tasks"  # 다른 프로젝트와 충돌 가능

2. Task 소유권 명시

JSON 파일을 직접 편집하여 담당자 정보 추가:

  
{
  "id": "5",
  "subject": "API 인증 구현",
  "description": "JWT 토큰 발급 및 검증 로직",
  "status": "in_progress",
  "assignee": "developer-a",  // 커스텀 필드 추가
  "started_at": "2026-01-25T09:00:00Z"
}

3. 정기적인 동기화 확인

  
# 팀원 모두 주기적으로 실행
claude

> Ctrl+T
> "현재 진행 중인 작업과 완료된 작업 요약해줘"

4. 충돌 방지 규칙

원칙: 한 번에 하나의 세션만 하나의 Task 처리

나쁜 예:
  터미널 A → Task #3 처리 중
  터미널 B → Task #3 처리 시작 (충돌!)

좋은 예:
  터미널 A → Task #3 처리 중
  터미널 B → Ctrl+T로 확인 → Task #4 선택

5. 작업 완료 알림 설정 (고급)

  
# .claude/hooks/on-task-complete.sh
#!/bin/bash

TASK_ID=$1
TASK_SUBJECT=$2

# Slack 알림
curl -X POST $SLACK_WEBHOOK_URL \
  -H 'Content-Type: application/json' \
  -d "{
    \"text\": \"✅ Task #$TASK_ID completed: $TASK_SUBJECT\",
    \"username\": \"Claude Task Bot\"
  }"

실전 워크플로우 패턴

실제 개발 현장에서 검증된 Task 활용 패턴을 소개합니다.

패턴 1: 요구사항 기반 작업 분해

시작점: 제품 요구사항 문서 (PRD)

claude

> "다음 PRD를 읽고 구현 작업으로 분해해줘:
   
   [PRD 내용 붙여넣기 또는 파일 경로]
   
   requirements.md 파일을 읽어봐"

Claude의 처리 과정:

1. PRD 분석 중...
   ✓ 핵심 기능: 사용자 인증, 대시보드, 알림 시스템
   ✓ 기술 스택: React, Node.js, PostgreSQL
   ✓ 제약사항: 2주 내 MVP 완성

2. 작업 트리 생성 중...
   ✓ 총 24개 작업 식별
   ✓ 3개 병렬 트랙으로 구성 (백엔드/프론트/인프라)

3. 의존성 매핑 중...
   ✓ 크리티컬 패스: 12일 예상
   ✓ 병렬 처리 시: 8일로 단축 가능

4. Task 생성 완료!
   24 tasks created with dependencies

패턴 2: 점진적 구현 (Incremental Implementation)

전략: 작업을 작은 단위로 나누어 점진적으로 검증하며 진행

> "사용자 인증 시스템을 다음 단계로 나눠줘:
   Phase 1: 기본 로그인 (이메일/비밀번호)
   Phase 2: 소셜 로그인 추가 (Google, GitHub)
   Phase 3: 2FA 구현
   Phase 4: 세션 관리 개선
   
   각 Phase가 완전히 작동하는 상태여야 다음 Phase 시작"

생성되는 작업 구조:

Phase 1 (Tasks #1-#5):
  #1 기본 로그인 백엔드
  #2 로그인 UI
  #3 세션 토큰 관리
  #4 로그아웃 기능
  #5 Phase 1 통합 테스트 ← 필수 게이트

Phase 2 (Tasks #6-#10):
  #6 OAuth 설정 (blockedBy: #5)
  #7 Google 로그인 통합
  #8 GitHub 로그인 통합
  #9 소셜 계정 연동 UI
  #10 Phase 2 통합 테스트 ← 필수 게이트

...

장점: 각 Phase 완료 시점에 배포 가능한 기능 제공

패턴 3: 탐색적 리팩토링

시나리오: 레거시 코드베이스 개선

> "이 레거시 코드베이스를 분석하고 리팩토링 계획 세워줘:
먼저 현재 구조 파악
문제점 식별
리팩토링 작업 우선순위화
안전한 단계별 계획 수립"

Claude의 접근 방식:

1단계: 분석 작업 생성
  Task #1: 코드베이스 구조 매핑
  Task #2: 의존성 그래프 생성
  Task #3: 코드 품질 메트릭 수집
  Task #4: 기술 부채 식별 및 우선순위화

2단계: 리팩토링 계획 (Task #4 완료 후)
  Task #5: 고위험 영역 격리
  Task #6: 테스트 커버리지 확보
  Task #7: 핵심 모듈부터 리팩토링
  ...

3단계: 점진적 실행
  각 Task마다 안전성 검증 후 진행

패턴 4: 병렬 기능 개발

시나리오: 독립적인 여러 기능 동시 개발

> "다음 3개 기능을 병렬로 개발할 수 있게 작업 나눠줘:
   A. 사용자 프로필 편집
   B. 파일 업로드 시스템
   C. 알림 센터
   
   각 기능은 완전히 독립적이고, 공유 인프라만 먼저 준비"

생성되는 구조:

공유 인프라 (Tasks #1-#3):
  #1 API 기본 구조
  #2 데이터베이스 기본 스키마
  #3 인증 미들웨어

기능 A: 프로필 편집 (Tasks #4-#7, blockedBy: #1-#3):
  #4 프로필 모델
  #5 프로필 API
  #6 프로필 UI
  #7 프로필 테스트

기능 B: 파일 업로드 (Tasks #8-#11, blockedBy: #1-#3):
  #8 파일 스토리지 설정
  #9 업로드 API
  #10 업로드 UI
  #11 파일 테스트

기능 C: 알림 센터 (Tasks #12-#15, blockedBy: #1-#3):
  #12 알림 모델
  #13 알림 API
  #14 알림 UI
  #15 알림 테스트

병렬 실행:

  
# 터미널 1: 공유 인프라
> "Task #1-#3 처리해줘"

# 인프라 완료 후 각 기능별로 분배
# 터미널 2: 기능 A
> "Task #4-#7 처리해줘"

# 터미널 3: 기능 B
> "Task #8-#11 처리해줘"

# 터미널 4: 기능 C
> "Task #12-#15 처리해줘"

패턴 5: 테스트 주도 개발 (TDD)

전략: 각 기능마다 테스트 작업을 먼저 생성

> "사용자 인증 기능을 TDD 방식으로 개발하고 싶어.
   각 기능마다 테스트를 먼저 작성하는 작업을 만들어줘"

생성되는 패턴:

#1 사용자 등록 테스트 작성
#2 사용자 등록 구현 (blockedBy: #1)
#3 사용자 등록 테스트 통과 확인 (blockedBy: #2)

#4 로그인 테스트 작성 (blockedBy: #3)
#5 로그인 구현 (blockedBy: #4)
#6 로그인 테스트 통과 확인 (blockedBy: #5)

#7 비밀번호 재설정 테스트 작성 (blockedBy: #6)
#8 비밀번호 재설정 구현 (blockedBy: #7)
#9 비밀번호 재설정 테스트 통과 확인 (blockedBy: #8)

장점: 각 단계에서 “실패하는 테스트 → 구현 → 테스트 통과” 사이클 강제

패턴 6: 의존성 최소화를 위한 작업 분할

전략: 병렬 처리를 극대화하기 위해 의존성 최소화

> "이 작업들을 가능한 한 많은 부분이 병렬로 진행될 수 있도록 재구성해줘"

Before (순차적):

#1 전체 백엔드
 └─► #2 전체 프론트엔드
      └─► #3 전체 테스트

After (병렬화):

#1 공유 타입 정의
 ├─► #2 백엔드: 데이터 레이어
 ├─► #3 백엔드: 비즈니스 로직
 ├─► #4 프론트: UI 컴포넌트
 └─► #5 프론트: 상태 관리

#2, #3, #4, #5 완료 후:
 └─► #6 통합
      └─► #7 테스트

결과: 4개 작업이 동시 진행 가능, 전체 시간 대폭 단축

Task 파일 직접 다루기

때로는 Claude를 통하지 않고 Task 파일을 직접 조작해야 할 때가 있습니다.

Task 파일 수동 편집

사용 사례:

Task에 커스텀 메타데이터 추가
우선순위 수동 변경
담당자 정보 추가
예상 소요 시간 기록

예시: 우선순위 및 담당자 추가

  
# Mac/Linux
nano ~/.claude/tasks/my-project/5.json

# Windows
notepad C:\Users\YourName\.claude\tasks\my-project\5.json

기존 내용:

  
{
  "id": "5",
  "subject": "API 인증 구현",
  "description": "JWT 토큰 발급 및 검증",
  "activeForm": "API 인증 구현 중",
  "status": "pending",
  "blocks": ["6", "7"],
  "blockedBy": ["4"]
}

수정 후:

  
{
  "id": "5",
  "subject": "API 인증 구현",
  "description": "JWT 토큰 발급 및 검증",
  "activeForm": "API 인증 구현 중",
  "status": "pending",
  "blocks": ["6", "7"],
  "blockedBy": ["4"],
  "priority": "high",
  "assignee": "john-doe",
  "estimated_hours": 8,
  "tags": ["backend", "security", "auth"]
}

주의사항:

JSON 문법이 정확해야 합니다 (쉼표, 따옴표 확인)
Claude는 표준 필드만 인식하지만, 커스텀 필드는 무시하므로 안전합니다
파일 저장 후 Claude Code 세션들이 자동으로 변경사항을 감지합니다

스크립트로 Task 관리

Python 스크립트 예시:

  
#!/usr/bin/env python3
import json
import os
from pathlib import Path
from datetime import datetime

# Task 디렉토리 경로
TASK_DIR = Path.home() / ".claude" / "tasks" / "my-project"

def list_tasks():
    """모든 Task 목록 출력"""
    tasks = []
    for task_file in sorted(TASK_DIR.glob("*.json")):
        with open(task_file) as f:
            task = json.load(f)
            tasks.append(task)
    
    print(f"Total tasks: {len(tasks)}")
    print(f"Completed: {sum(1 for t in tasks if t['status'] == 'completed')}")
    print(f"In progress: {sum(1 for t in tasks if t['status'] == 'in_progress')}")
    print(f"Pending: {sum(1 for t in tasks if t['status'] == 'pending')}")
    print("\nTasks:")
    
    for task in tasks:
        status_icon = {
            'completed': '✓',
            'in_progress': '▶',
            'pending': '◻'
        }.get(task['status'], '?')
        
        print(f"{status_icon} #{task['id']}: {task['subject']}")
        if task.get('blockedBy'):
            print(f"   └─ blocked by: {', '.join(task['blockedBy'])}")

def mark_completed(task_id):
    """특정 Task를 완료로 표시"""
    task_file = TASK_DIR / f"{task_id}.json"
    
    with open(task_file) as f:
        task = json.load(f)
    
    task['status'] = 'completed'
    task['completed_at'] = datetime.now().isoformat()
    
    with open(task_file, 'w') as f:
        json.dump(task, f, indent=2)
    
    print(f"Task #{task_id} marked as completed")
    
    # blockedBy에서 이 task를 제거
    update_dependencies(task_id)

def update_dependencies(completed_task_id):
    """완료된 Task를 참조하는 다른 Task들의 blockedBy 업데이트"""
    for task_file in TASK_DIR.glob("*.json"):
        with open(task_file) as f:
            task = json.load(f)
        
        if completed_task_id in task.get('blockedBy', []):
            task['blockedBy'].remove(completed_task_id)
            
            with open(task_file, 'w') as f:
                json.dump(task, f, indent=2)
            
            print(f"  └─ Unblocked task #{task['id']}")

if __name__ == "__main__":
    import sys
    
    if len(sys.argv) < 2:
        list_tasks()
    elif sys.argv[1] == "complete":
        if len(sys.argv) < 3:
            print("Usage: task-manager.py complete <task_id>")
        else:
            mark_completed(sys.argv[2])
    else:
        list_tasks()

사용법:

  
# 모든 Task 확인
python task-manager.py

# Task #5 완료 표시
python task-manager.py complete 5

Task 데이터 백업 및 복원

백업:

  
# Mac/Linux
tar -czf claude-tasks-backup-$(date +%Y%m%d).tar.gz ~/.claude/tasks/

# Windows PowerShell
Compress-Archive -Path ~\.claude\tasks\* `
  -DestinationPath "claude-tasks-backup-$(Get-Date -Format 'yyyyMMdd').zip"

복원:

  
# Mac/Linux
tar -xzf claude-tasks-backup-20260125.tar.gz -C ~/

# Windows PowerShell
Expand-Archive -Path claude-tasks-backup-20260125.zip -DestinationPath ~\.claude\

Task를 다른 형식으로 변환

JSON → Markdown 변환 스크립트:

  
#!/usr/bin/env python3
import json
from pathlib import Path

TASK_DIR = Path.home() / ".claude" / "tasks" / "my-project"
OUTPUT_FILE = "tasks-report.md"

def json_to_markdown():
    tasks = []
    for task_file in sorted(TASK_DIR.glob("*.json")):
        with open(task_file) as f:
            tasks.append(json.load(f))
    
    with open(OUTPUT_FILE, 'w') as f:
        f.write("# Project Tasks Report\n\n")
        f.write(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}\n\n")
        
        # 상태별 요약
        f.write("## Summary\n\n")
        f.write(f"- Total: {len(tasks)}\n")
        f.write(f"- Completed: {sum(1 for t in tasks if t['status'] == 'completed')}\n")
        f.write(f"- In Progress: {sum(1 for t in tasks if t['status'] == 'in_progress')}\n")
        f.write(f"- Pending: {sum(1 for t in tasks if t['status'] == 'pending')}\n\n")
        
        # 작업 목록
        f.write("## Tasks\n\n")
        for task in tasks:
            status = task['status'].replace('_', ' ').title()
            f.write(f"### Task #{task['id']}: {task['subject']}\n\n")
            f.write(f"**Status:** {status}\n\n")
            f.write(f"**Description:** {task['description']}\n\n")
            
            if task.get('blockedBy'):
                f.write(f"**Blocked by:** Tasks {', '.join(task['blockedBy'])}\n\n")
            
            if task.get('blocks'):
                f.write(f"**Blocks:** Tasks {', '.join(task['blocks'])}\n\n")
            
            f.write("---\n\n")
    
    print(f"Markdown report generated: {OUTPUT_FILE}")

if __name__ == "__main__":
    from datetime import datetime
    json_to_markdown()

문제 해결 및 팁

일반적인 문제들

문제 1: Task 목록이 표시되지 않음

  
# 진단 단계:

# 1. Task 시스템이 활성화되어 있는지 확인
echo $CLAUDE_CODE_ENABLE_TASKS
# (비어있거나 'true'여야 함, 'false'면 비활성화 상태)

# 2. Task 파일이 실제로 존재하는지 확인
ls -la ~/.claude/tasks/   # Mac/Linux
dir ~\.claude\tasks\      # Windows

# 3. TASK_LIST_ID 확인
echo $CLAUDE_CODE_TASK_LIST_ID
# (설정했다면 해당 값 표시, 아니면 비어있음)

# 4. Claude Code 버전 확인
claude --version
# (2.1.16 이상이어야 함)

해결책:

  
# 옵션 1: Task 시스템 명시적 활성화
export CLAUDE_CODE_ENABLE_TASKS=true

# 옵션 2: Claude Code 재시작
claude --reset

# 옵션 3: 캐시 정리
rm -rf ~/.claude/cache/

문제 2: 세션 간 동기화가 안 됨

  
# 원인: 다른 TASK_LIST_ID 사용 중

# 진단:
# 터미널 1
echo $CLAUDE_CODE_TASK_LIST_ID
# 출력: project-a

# 터미널 2
echo $CLAUDE_CODE_TASK_LIST_ID
# 출력: project-b  ← 다름!

# 해결: 모든 터미널에서 동일한 ID 사용
# 모든 터미널에서:
export CLAUDE_CODE_TASK_LIST_ID="shared-project"

문제 3: Task 파일이 손상됨

  
# 증상: Claude가 Task를 읽지 못함
# 에러 메시지: "Failed to parse task file"

# 진단: JSON 문법 검증
cat ~/.claude/tasks/my-project/5.json | jq '.'
# 에러 발생하면 JSON 문법 오류

# 해결책 1: 백업에서 복원
cp ~/.claude/tasks-backup/my-project/5.json ~/.claude/tasks/my-project/

# 해결책 2: 수동 수정
# JSON 검증 도구 사용: https://jsonlint.com/

문제 4: Task가 너무 많아서 느림

  
# 완료된 Task 아카이빙

# 1. 아카이브 디렉토리 생성
mkdir -p ~/.claude/tasks/my-project/archive

# 2. 완료된 Task만 이동
for file in ~/.claude/tasks/my-project/*.json; do
  if jq -e '.status == "completed"' "$file" > /dev/null; then
    mv "$file" ~/.claude/tasks/my-project/archive/
  fi
done

# 3. 현재 진행 중인 Task만 남음
ls ~/.claude/tasks/my-project/*.json

고급 팁

팁 1: Task 템플릿 만들기

  
# ~/.claude/task-template.json
{
  "id": "PLACEHOLDER",
  "subject": "PLACEHOLDER",
  "description": "PLACEHOLDER",
  "activeForm": "PLACEHOLDER",
  "status": "pending",
  "blocks": [],
  "blockedBy": [],
  "priority": "medium",
  "tags": [],
  "created_at": "PLACEHOLDER",
  "estimated_hours": 0
}

# 새 Task 생성 스크립트
create_task.sh:
#!/bin/bash
TASK_ID=$1
SUBJECT=$2
DESCRIPTION=$3

TEMPLATE=$(cat ~/.claude/task-template.json)
TASK_FILE=~/.claude/tasks/my-project/${TASK_ID}.json

echo "$TEMPLATE" | \
  jq --arg id "$TASK_ID" \
     --arg subject "$SUBJECT" \
     --arg desc "$DESCRIPTION" \
     --arg time "$(date -Iseconds)" \
     '.id = $id | .subject = $subject | .description = $desc | .created_at = $time' \
  > "$TASK_FILE"

echo "Task #$TASK_ID created"

팁 2: Task 진행률 시각화

  
# progress.sh
#!/bin/bash

TASK_DIR=~/.claude/tasks/my-project

TOTAL=$(ls $TASK_DIR/*.json 2>/dev/null | wc -l)
COMPLETED=$(grep -l '"status": "completed"' $TASK_DIR/*.json 2>/dev/null | wc -l)
IN_PROGRESS=$(grep -l '"status": "in_progress"' $TASK_DIR/*.json 2>/dev/null | wc -l)
PENDING=$(grep -l '"status": "pending"' $TASK_DIR/*.json 2>/dev/null | wc -l)

PERCENT=$((COMPLETED * 100 / TOTAL))

echo "Progress: $COMPLETED/$TOTAL ($PERCENT%)"
echo -ne "["
for i in $(seq 1 20); do
  if [ $((i * 5)) -le $PERCENT ]; then
    echo -ne "="
  else
    echo -ne " "
  fi
done
echo "] $PERCENT%"

echo ""
echo "Completed:   $COMPLETED"
echo "In Progress: $IN_PROGRESS"
echo "Pending:     $PENDING"

팁 3: Task 자동 생성 훅

  
# .git/hooks/post-commit
#!/bin/bash

# 커밋 메시지에서 Task 참조 추출
COMMIT_MSG=$(git log -1 --pretty=%B)

if echo "$COMMIT_MSG" | grep -q "Task #[0-9]\+"; then
  TASK_ID=$(echo "$COMMIT_MSG" | grep -oP "Task #\K[0-9]+")
  TASK_FILE=~/.claude/tasks/$(basename $(pwd))/${TASK_ID}.json
  
  if [ -f "$TASK_FILE" ]; then
    # Task에 커밋 정보 추가
    jq --arg commit "$(git rev-parse HEAD)" \
       --arg msg "$COMMIT_MSG" \
       '.commits += [{"hash": $commit, "message": $msg}]' \
       "$TASK_FILE" > tmp.$$ && mv tmp.$$ "$TASK_FILE"
    
    echo "Updated Task #$TASK_ID with commit info"
  fi
fi

고급 활용 시나리오

시나리오 1: 대규모 마이그레이션 프로젝트

배경: 1000개 파일을 Python 2에서 Python 3으로 마이그레이션

claude

> "1000개 Python 파일을 Python 3으로 마이그레이션하는 프로젝트를 계획해줘.
   파일들을 10개 그룹으로 나누고, 각 그룹을 독립적인 Task로 만들어줘.
   각 그룹은 100개 파일씩 담당."

Claude의 응답:

✔ Task #1-#10 생성: 각각 100개 파일 마이그레이션
✔ Task #11 생성: 통합 테스트
✔ Task #12 생성: 호환성 검증

각 Task는 독립적으로 실행 가능하므로 10개 병렬 세션 권장

병렬 실행:

  
# 10개 터미널 실행 (또는 tmux 사용)
for i in {1..10}; do
  export CLAUDE_CODE_TASK_LIST_ID="python3-migration"
  claude -p "Task #$i 처리해줘" &
done

wait  # 모든 작업 완료 대기

예상 시간:

순차 처리: ~10시간
병렬 처리 (10 세션): ~1시간

시나리오 2: AI 기반 코드 리뷰 워크플로우

  
# Git hook: pre-push
#!/bin/bash

export CLAUDE_CODE_TASK_LIST_ID="code-review-$(git rev-parse --short HEAD)"

claude << EOF
현재 커밋의 모든 변경사항을 리뷰하고 다음 Task들을 생성해줘:
- 각 파일별로 코드 품질 검토 Task
- 보안 이슈 확인 Task
- 성능 최적화 기회 식별 Task
- 테스트 커버리지 확인 Task

모든 Task 완료 후 종합 리포트 생성
EOF

# Task 완료 대기
while [ $(ls ~/.claude/tasks/code-review-*/completed | wc -l) -lt $(ls ~/.claude/tasks/code-review-*/*.json | wc -l) ]; do
  sleep 5
done

echo "코드 리뷰 완료, push 진행..."

시나리오 3: 지속적 문서화

  
# .claude/skills/auto-document.md

프로젝트 변경사항을 자동으로 문서화:

1. git diff로 변경된 파일 확인
2. 각 변경사항에 대해:
   - 무엇이 변경되었는지
   - 왜 변경되었는지
   - 어떤 영향이 있는지
3. CHANGELOG.md 업데이트 Task 생성
4. API 문서 업데이트 Task 생성 (API 변경 시)
5. README 업데이트 Task 생성 (사용법 변경 시)

결론 및 핵심 요약

Claude Code의 Task 시스템은 AI 기반 개발 도구를 “일회성 어시스턴트”에서 “장기 협업 파트너”로 진화시켰습니다.

핵심 장점 재확인

영속성: 세션이 종료되어도 모든 작업 정보가 파일 시스템에 보존되어 언제든 재개 가능
의존성 추적: 복잡한 프로젝트의 작업 간 관계를 시스템적으로 관리하여 병목 현상 자동 식별
다중 세션 협업: 여러 개발자나 여러 에이전트가 실시간으로 동일한 작업 목록을 공유하며 협업
파일 기반 설계: JSON 파일로 저장되어 버전 관리, 백업, 외부 도구 통합이 용이
자동 상태 관리: Claude가 작업 시작/완료 시 자동으로 상태 업데이트 및 의존성 해제

실전 적용 체크리스트

Task 사용 전 확인사항:

Claude Code 버전 2.1.16 이상 설치됨
작업이 5개 이상의 파일 또는 30분 이상 소요될 것으로 예상됨
명확한 작업 의존성이 존재함
중간에 중단 후 재개할 가능성이 있음
여러 세션/개발자가 협업할 필요가 있음

Task 생성 시 베스트 프랙티스:

각 작업의 제목이 명확하고 구체적임
상세 설명에 무엇을, 어떻게, 왜가 포함됨
의존성이 정확하게 설정됨
병렬 처리 가능한 작업들이 식별됨
전체 프로젝트의 크리티컬 패스를 파악함

협업 시 권장사항:

팀 전체가 동일한 TASK_LIST_ID 사용
작업 소유권을 명확히 지정
정기적으로 진행 상황 동기화
완료된 작업은 주기적으로 아카이빙

다음 단계

Task 시스템을 마스터했다면, 다음 단계로 나아갈 수 있습니다:

Skills 시스템 학습: 반복적인 Task 패턴을 재사용 가능한 스킬로 정의
Hooks 활용: Task 생성/완료 시 자동 실행되는 스크립트 작성
MCP 통합: 외부 도구(Jira, Linear 등)와 Task 동기화
CI/CD 파이프라인: Task 기반 자동화 빌드/배포 구축

Claude Code Task 시스템은 단순한 체크리스트가 아닌, AI 시대의 프로젝트 관리 인프라입니다. 이를 효과적으로 활용하여 개발 생산성을 획기적으로 향상시키시기 바랍니다.

작성 일자: 2026-01-25

AI, Claude Code

AI claude-code task-management Claude.write

영속적 작업 관리로 AI 협업 개발을 혁신하다

목차

Task 시스템이 필요한 이유

기존 To-Do 시스템의 치명적 한계

Opus 4.5와 장기 자율 실행의 등장

Task가 해결하는 실제 문제들

To-Do vs Task: 무엇이 달라졌나

1. 저장 방식: 메모리 vs 파일 시스템

2. 구조: 평면 리스트 vs 의존성 그래프

3. 협업: 격리 vs 공유

4. 상태 표현: 이진 vs 다중 상태

5. 메타데이터: 없음 vs 풍부한 정보

Task의 핵심 개념 3가지

1. 영속성 (Persistence)

2. 의존성 추적 (Dependency Tracking)

3. 다중 세션 협업 (Multi-Session Collaboration)

실제 Task 파일 구조 완전 분석

Task 디렉토리 구조

JSON 파일 내부 구조

실제 8개 작업의 완전한 의존성 그래프

Task 파일 직접 확인하기

실전 사용법: 단계별 가이드

단계 1: Claude Code 버전 확인

단계 2: 프로젝트에서 Claude Code 시작

단계 3: Task 생성 요청

단계 4: Claude의 작업 생성 과정 관찰

단계 5: 작업 목록 확인

단계 6: 의존성 그래프 시각화

단계 7: 작업 실행

단계 8: 진행 상황 모니터링

단계 9: 세션 종료 및 재개

단계 10: 완료 확인

언제 Task를 사용하고, 언제 사용하지 말아야 하나

Task를 사용하지 말아야 할 때

Task를 사용해야 할 때

의사결정 플로우차트

다중 세션 협업 마스터하기

기본 설정: TASK_LIST_ID 사용

환경 변수 설정 방법 (OS별)

실시간 협업 워크플로우

CLI 모드에서의 Task 협업

팀 협업 베스트 프랙티스

실전 워크플로우 패턴

패턴 1: 요구사항 기반 작업 분해

패턴 2: 점진적 구현 (Incremental Implementation)

패턴 3: 탐색적 리팩토링

패턴 4: 병렬 기능 개발

패턴 5: 테스트 주도 개발 (TDD)

패턴 6: 의존성 최소화를 위한 작업 분할

Task 파일 직접 다루기

Task 파일 수동 편집

스크립트로 Task 관리

Task 데이터 백업 및 복원

Task를 다른 형식으로 변환

문제 해결 및 팁

일반적인 문제들

고급 팁

고급 활용 시나리오

시나리오 1: 대규모 마이그레이션 프로젝트

시나리오 2: AI 기반 코드 리뷰 워크플로우

시나리오 3: 지속적 문서화

결론 및 핵심 요약

핵심 장점 재확인

실전 적용 체크리스트

다음 단계

인기 태그