Claude Code Tasks로 복잡한 프로젝트 효율적으로 진행하기

Claude Code로 복잡한 프로젝트를 작업하다 보면, 하나의 세션에 모든 작업을 몰아넣을 때가 있습니다. 이 방식으로 계속 일하면, 작업이 누적될수록 컨텍스트가 포화해 작업 후반부로 갈수록 세션 동작이 불안정해지고요. 세션을 종료하면 재개 시 AI에게 작업 흐름을 처음부터 다시 설명해야 해 번거롭습니다.

Claude Code의 Tasks는 이러한 한계를 구조적으로 해결하는 기능인데요. 작업을 태스크 단위로 분할해 각 세션의 컨텍스트 부담을 줄이고, 태스크 간 의존성을 정의하며, 여러 터미널에서 병렬로 실행해도 상태가 자동으로 동기화되는 게 특징이죠. 모든 작업 상태는 디스크에 저장돼, 세션을 종료해도 다음 날 같은 지점에서 이어서 진행할 수 있습니다.

이 글에서는 Tasks의 등장 배경과 기존 Todos와의 차이, 상태 라이프사이클, 실전 사용법을 단계별로 살펴보겠습니다.

Tasks 등장 배경

먼저 Tasks의 등장 과정을 기존 기능의 한계, 커뮤니티의 우회 시도, Anthropic의 공식 대응을 중심으로 알아보겠습니다.

Todos의 한계

Claude Code에는 기존에 ‘Todos’라는 체크리스트 기능이 있었습니다. 이 기능은 복잡한 작업을 단계별로 나눠 추적하는 용도로 사용했는데요. 간단한 작업을 정리하는 데 유용했지만, 실제 개발 환경에서는 다음과 같은 구조적인 한계가 있었습니다.

1. 세션 종속 구조

Todos는 현재 대화 세션 내부에서만 동작하는 체크리스트였습니다. --continue나 --resume 옵션으로 같은 세션을 이어가면 Todos에 접근할 수 있었지만, 컨텍스트 압축이 발생하면 소멸했습니다. 새로운 세션이나 다른 터미널 환경에서는 기존 Todos를 불러올 방법이 없었습니다.

2. 병렬 실행·의존성 미지원

Todos는 작업 간 의존성 정의나 병렬 실행을 지원하지 않았습니다. 독립적으로 실행할 수 있는 작업이라도 사용자가 순서대로 하나씩 처리해야 했죠. 결과적으로 전체 작업 시간이 길어지고, 리소스를 효율적으로 활용하지 못했습니다.

커뮤니티의 선제적 해결책

사용자 커뮤니티는 이 한계를 먼저 해소하려고 시도했습니다. 소프트웨어 엔지니어 Geoffrey Huntley는 ‘Ralph Wiggum’이라는 기법을 고안해 문제를 우회했죠.

핵심 동작 방식은 다음과 같습니다.

1. Claude에게 작업과 완료 조건(completion promise)을 지정합니다.
2. Claude가 완료 조건을 충족하지 않은 채 종료하려 하면, stop hook이 이를 가로채고 동일한 프롬프트를 재주입합니다.
3. 완료 조건이 충족될 때까지 이 과정을 반복합니다.

일부 사용자는 plan.md 같은 외부 파일에 작업 목록을 저장해, 세션 내부에 갇힌 Todos를 ‘파일 기반 상태 관리 방식’으로 확장하기도 했습니다.

하지만 이 방식은 당시 Anthropic 제품 내장 기능이 아니었습니다. stop hook과 완료 조건을 직접 설정해야 했고, 초보자에게는 복잡한 우회 방법에 불과했죠. 근본적인 문제 개선으로 보기는 어려웠습니다.

Anthropic의 공식 흡수

Anthropic은 v2.1.16에서 Tasks를 정식 출시하며 근본적인 문제 해결에 나섰습니다. 커뮤니티가 외부 파일과 stop hook으로 수동 구현하던 방식을 제품 내장 기능으로 통합했죠.

기존 Todos는 TodoWrite 하나로 체크리스트를 관리했는데요. Tasks는 역할에 따라 네 가지 도구로 분리해 차별화됐습니다.

도구	한 줄 설명	Jira 비유
TaskCreate	새 태스크 생성 (제목, 설명, 초기 상태 설정)	티켓 생성
TaskGet	특정 태스크 상세 조회 (의존성 포함)	티켓 상세 보기
TaskUpdate	상태 변경, 의존성 추가, 설명 수정, 삭제	티켓 업데이트
TaskList	전체 태스크 목록과 상태 조회	보드 전체 보기

이제 사용자는 직접 도구를 호출할 필요가 없습니다. “태스크로 분할해줘”라고 말하면 Claude가 내부적으로 위 도구들을 자동으로 사용합니다.

기존 Todos와 비교해 구체적으로 무엇이 달라졌는지 살펴보겠습니다.

1. 작업 기록 방식

Todos는 세션 메모리에만 존재했습니다. 세션이 종료되거나 컨텍스트가 압축되면 작업 기록이 사라졌습니다.

Tasks는 태스크를 ~/.claude/tasks/ 경로에 자동 저장합니다. 사용자가 별도의 파일을 관리할 필요 없이, 세션과 무관하게 작업 기록이 유지됩니다.

2. 완료 탐지 방식

Todos도 pending, in_progress, completed 상태를 지원했지만, 태스크 간 의존성을 정의하거나 이를 기반으로 다음 작업을 판단하는 구조는 아니었습니다.

Tasks는 각 태스크의 pending → in_progress → completed 상태를 디스크에 저장하며, Claude는 이 상태와 의존성 관계를 기준으로 다음 작업을 자동으로 결정합니다. 구조화된 상태 전이(state transition) 기반 실행 모델입니다.

3. 멀티 세션 지원

Todos는 현재 세션에 종속되어, 다른 터미널이나 세션에서 동일한 작업 목록에 접근할 수 없었습니다.

Tasks에서는 CLAUDE_CODE_TASK_LIST_ID 값을 동일하게 설정하면 여러 세션이 자동으로 같은 태스크 목록을 공유합니다.

위 내용을 표로 정리하면 다음과 같습니다.

기능	기존 Todos	Tasks
저장 방식	세션 내부에서만 유지	~/.claude/tasks/{이름}/ 경로에 영구 저장
의존성 관리	지원하지 않음	addBlockedBy로 태스크 간 선후 관계 정의
멀티 세션	세션에 종속	CLAUDE_CODE_TASK_LIST_ID로 여러 세션 동시 접근
상태 관리	pending, in_progress, completed (세션 메모리 한정)	pending → in_progress → completed (디스크 저장 + 의존성 기반 실행 판단)
컨텍스트 압축 대응	소멸 (메모리 기반)	유지 (디스크 기반 저장)

상태 라이프사이클

Tasks는 각 태스크를 명확한 상태(state)로 관리합니다.

pending  →  in_progress  →  completed
 (대기)      (진행 중)          (완료)

각 상태의 의미

• pending: 아직 실행되지 않은 대기 상태
• in_progress: 현재 실행 중인 상태
• completed: 실행이 완료된 상태

태스크가 in_progress로 변경되면 다른 세션에서도 ‘해당 작업이 진행 중임’을 확인할 수 있습니다.

completed 상태가 되면, 해당 태스크에 의존하던 다음 태스크가 자동으로 실행 가능 상태로 전환됩니다. 이는 단순 체크리스트와 달리 ‘의존성 기반 실행 흐름 제어’를 지원한다는 의미입니다.

Tasks 특징

Tasks의 설계 구조와 이를 토대로 얻을 수 있는 실질적 이점을 살펴보겠습니다.

파일 구조

Tasks는 ~/.claude/tasks 경로 하위에 생성됩니다. 이는 단순 메모리 상태가 아니며, 파일 시스템 기반 상태 저장소입니다.

~/.claude/tasks/blog-guestbook/
├── .lock          ← 동시 접근 시 충돌 방지용
├── 1.json         ← 태스크 #1
├── 2.json         ← 태스크 #2
├── 3.json         ← 태스크 #3
├── 4.json         ← 태스크 #4
└── 5.json         ← 태스크 #5

실제 태스크 파일 예시 (3.json)

{
  "id": "3",
  "subject": "API 라우트 - GET/POST /api/guestbook",
  "description": "src/app/api/guestbook/route.ts 생성. GET: 방명록 목록 반환 (created_at DESC 정렬). POST: 새 방명록 작성 (nickname, message 필수). POST 시 금칙어 필터 적용 → 위반 시 400 에러 반환.",
  "activeForm": "방명록 API 라우트 구현 중",
  "status": "pending",
  "blocks": ["4", "5"],
  "blockedBy": ["1", "2"]
}

각 필드의 의미:

필드	설명	이 태스크에서 의미
id	태스크 고유 번호	3번 태스크
subject	태스크 목록에 표시되는 제목	API 라우트 구현
description	태스크의 상세 설명	어떤 파일에 어떤 기능을 구현할지
activeForm	in_progress 상태에서 표시되는 문구	"방명록 API 라우트 구현 중"
status	현재 상태 (pending, in_progress, completed)	아직 시작 전
blocks	이 태스크가 완료되어야 시작 가능한 태스크 목록	#4(UI), #5(테스트)
blockedBy	이 태스크를 시작하기 위해 선행되어야 하는 태스크 목록	#1(DB), #2(금칙어 필터)

blockedBy로 선행 태스크를 설정하면, 반대쪽 태스크의 blocks에 자동으로 추가됩니다.

즉, 의존성은 단방향 참조가 아니라 양방향 관계로 유지됩니다. 이 구조 덕분에 Claude는 태스크 그래프 전체를 기반으로 다음 작업을 판단할 수 있고, 안정성을 보장합니다.

영속성

Tasks는 모든 작업이 완료될 때까지 동일한 ID로 언제든지 다시 접근할 수 있습니다. 작업을 한 번에 끝내기 어려운 환경이라면, 이 영속성의 장점을 활용하면 됩니다. 세션을 종료해도 작업 상태는 디스크에 유지됩니다.

멀티세션 충돌 방지

모든 태스크를 완료하면 각 태스크의 JSON 파일은 삭제됩니다. 대신 마지막으로 사용된 태스크 번호가 .highwatermark 파일에 기록됩니다.

모든 태스크 완료 후 JSON 파일이 삭제되고, .highwatermark에 마지막 태스크 번호(5)가 기록된 모습

예를 들어,

• 1~5번 태스크를 모두 완료했습니다.
• 새로운 계획으로 태스크를 추가 생성합니다.
• 이때 새 태스크는 6번부터 시작합니다.

만약 다시 1번부터 생성된다면, 이전에 실행했던 세션에서 "1번 task 진행해 줘"라고 요청했을 때 과거 태스크인지 새로운 태스크인지 구분할 수 없습니다. .highwatermark는 세션 간 컨텍스트 충돌을 방지하는 안전장치 역할을 합니다.

병렬 실행

여러 터미널에서 동일한 CLAUDE_CODE_TASK_LIST_ID로 세션을 실행하면, 모든 세션이 같은 태스크 목록을 공유합니다. 각 세션은 디스크에 저장된 상태를 참조하므로, 한 세션에서 태스크를 완료하면 다른 세션에도 즉시 반영됩니다.

의존성이 설정된 태스크는 선행 태스크가 완료되기 전까지 시스템이 자동으로 실행을 차단합니다. 이미 완료된 태스크를 다른 세션에서 다시 실행하려 해도 중복 실행은 방지됩니다. 따라서 사람이 작업 순서나 중복 여부를 관리할 필요가 없습니다.

Tasks를 사용하면 이러한 방식으로 독립적인 태스크를 여러 세션에서 동시에 처리할 수 있어, 전체 작업 시간이 단축됩니다.

컨텍스트 분리

Tasks에서는 태스크 단위로 세션을 분리해 각 세션이 처리해야 할 정보량이 줄어듭니다. 하나의 세션에 모든 작업을 몰아넣을 때 발생하는 컨텍스트 포화 문제가 구조적으로 완화되죠.

또 각 세션이 자신의 태스크 범위에만 집중하므로, 불필요한 정보가 섞여 의사결정이 흐려지는 컨텍스트 오염 가능성도 줄어듭니다. 이는 소프트웨어 설계의 관심사 분리(Separation of Concerns) 원칙을 실행 구조에 적용한 것입니다.

Sub-agent와의 차이

Claude Code에서 Sub-agent는 실행이 끝나면 소멸합니다. 코드 결과물은 남지만, 작업 상태나 진행 맥락은 유지되지 않습니다.

그러나 Tasks는 작업 상태 자체를 디스크에 저장합니다. “어디까지 완료했고, 무엇이 남았는가”라는 정보가 그대로 유지됩니다.

비유하면,

• Sub-agent는 일회성 계약직에 가깝습니다.
• Tasks는 인수인계 문서가 체계적으로 관리되는 팀 운영 모델에 가깝습니다.

Tasks 실전 사용법

Tasks를 생성하고, 병렬 실행과 컨텍스트 분리를 활용하는 방법을 시나리오로 살펴보겠습니다.

Tasks 생성

Tasks는 Claude Code v2.1.16에 도입되었으며, v2.1.19부터 기본값으로 완전히 전환됐습니다. 별도의 슬래시 명령어를 입력할 필요가 없습니다.

사용자는 “태스크를 분할하고 의존성을 설정해 줘"라고 자연어로 요청하면 됩니다. 그러면 Claude가 내부적으로 TaskCreate 도구를 호출해 태스크를 생성합니다.

의존성 설정을 함께 요청하세요

태스크를 생성할 때는 의존성(blocked by) 설정까지 함께 요청하는 것이 좋습니다. 의존성을 명시하지 않으면 병렬 실행 중 충돌이나 순서 오류가 발생할 수 있기 때문입니다. 특히 여러 세션에서 동시에 작업할 때, 의존성 정의가 매우 중요합니다.

Tasks 미사용 vs 사용 비교

• Tasks 미사용(단순 작업 진행): 작업은 현재 세션 안에서만 관리됩니다. 작업 순서는 사용자가 직접 기억하거나 관리해야 합니다.

  
  Tasks를 사용하지 않고 단순 작업을 요청한 프롬프트 예시
  
  
  
  Tasks 없이 단일 세션에서 생성된 작업 계획
  
  

• Tasks 사용: 작업이 디스크에 저장되어, 여러 세션을 열어서 Task별로 진행이 가능합니다.

  
  태스크 분할과 의존성 설정을 함께 요청하는 프롬프트 예시
  
  
  
  의존성이 설정된 5개 태스크가 생성된 결과
  
  

Tasks ID 지정

여러 터미널에서 병렬로 작업하거나, 이후 동일한 태스크 목록에 다시 접근하려면 CLAUDE_CODE_TASK_LIST_ID 환경변수를 설정해야 합니다.

ID를 지정하지 않고 실행

claude

CLAUDE_CODE_TASK_LIST_ID를 설정하지 않은 상태에서 태스크 분할을 요청하면, Claude는 임의의 고유 ID를 자동 생성합니다. 자동 생성된 ID는 예측하기 어렵기 때문에, 이후 동일한 태스크 목록에 다시 접근하기가 번거롭습니다. 지속적인 프로젝트 작업에는 적합하지 않은 방식입니다.

ID를 지정하지 않았을 때 자동 생성된 태스크 디렉터리

ID를 지정하고 실행

CLAUDE_CODE_TASK_LIST_ID=blog-guestbook claude

CLAUDE_CODE_TASK_LIST_ID를 지정하면, 해당 이름으로 태스크 목록이 생성됩니다.

ID를 blog-guestbook으로 지정했을 때 생성된 태스크 디렉터리

병렬 작업 시나리오

Tasks의 가장 강력한 특징은 멀티세션 병렬 실행과 자동 상태 동기화입니다. 다음 시나리오로 확인해 보겠습니다.

사전 준비

먼저 계획만 생성한 뒤 Claude를 종료합니다.

태스크 계획만 생성하고 세션을 종료하기 위한 프롬프트 입력

시연

1. 동일한 Task ID로 다시 실행합니다.

   CLAUDE_CODE_TASK_LIST_ID=blog-guestbook claude

2. 추가로 두 개의 터미널을 열어, 총 세 개의 Claude 세션을 실행합니다. 편의상 각 터미널을 1번, 2번, 3번으로 구분하겠습니다.

   
   동일한 CLAUDE_CODE_TASK_LIST_ID로 실행된 세 개의 터미널
   
   

3. 각 터미널에서 Ctrl + T를 누르면 태스크 목록이 표시됩니다.

   
   Ctrl + T로 표시된 태스크 목록
   
   
   • 회색: 의존성 때문에 아직 실행 불가
   • 흰색: 즉시 실행 가능

4. 의존성이 있는 태스크는 시스템이 자동으로 차단합니다. 예를 들어, 3번 태스크를 먼저 요청해도 실행되지 않습니다. 작업 순서가 구조적으로 보호됩니다.

   
   3번 태스크를 요청했지만, 선행 태스크(#1, #2)가 미완료 상태라 실행이 차단된 모습
   
   

5. 이제 1번과 2번 터미널에서 동시에 다음과 같이 요청합니다. "1번 태스크 진행해 줘”

6. 2번 터미널이 먼저 작업을 완료하면서, 상태가 completed로 변경됩니다.

   
   2번 터미널에서 1번 태스크(DB 스키마)가 완료되고, 태스크 목록이 자동으로 업데이트된 모습
   
   

7. 이미 완료된 태스크를 1번 터미널이 다시 실행하려고 하면, 시스템은 이를 탐지하고 작업을 수행하지 않습니다.

   
   1번 터미널이 동일한 태스크를 실행하려 했지만, 이미 완료된 상태를 탐지하고 중복 실행을 건너뛴 모습
   
   

8. 3번 터미널은 아무 작업도 요청하지 않았지만, 태스크 목록은 자동으로 업데이트됩니다. 이는 모든 세션이 동일한 디스크 기반 상태 저장소를 공유하기 때문입니다.

   
   3번 터미널에서 아무 작업도 요청하지 않았지만, 1번 태스크가 completed로 자동 반영된 모습
   
   

컨텍스트 관리 시나리오

앞서 설명한 컨텍스트 분리가 실제로 어떻게 작동하는지 확인해 보겠습니다.

사전 준비

현재 4번 태스크(방명록 UI 구현)를 진행할 차례라고 가정하겠습니다.

1. 새로운 세션에서 Claude를 실행합니다.

   CLAUDE_CODE_TASK_LIST_ID=blog-guestbook claude

2. 기존 태스크 목록이 로드됩니다. "4번 task 진행해 줘”라고 요청합니다.

   
   이전 세션에서 완료된 3개 태스크가 반영된 상태로 태스크 목록이 로드된 모습
   
   

시연

1. 아래와 같은 결과를 얻었습니다.

   
   4번 태스크(방명록 UI 구현) 완료 후 생성된 방명록 페이지
   
   

2. 현재 터미널을 유지한 상태에서, 새로운 터미널을 열고 동일한 명령으로 Claude를 실행합니다.

   CLAUDE_CODE_TASK_LIST_ID=blog-guestbook claude

3. 이제 남은 마지막 태스크를 별도 세션에서 진행할 수 있습니다. 각 세션은 동일한 태스크 목록을 공유하지만, 실제 작업 컨텍스트는 독립적으로 유지됩니다.

4. 동시에 UI를 수정하려면 4번 태스크를 진행하던 터미널로 돌아갑니다. 해당 세션은 이미 UI 관련 코드와 대화 흐름을 충분히 포함하므로, 추가 설명 없이 다음과 같이 요청합니다. "디자인 컬러를 pink로 변경해 줘”

   
   왼쪽: 4번 세션에서 UI 컬러를 pink로 변경하는 작업 / 오른쪽: 별도 세션에서 5번 태스크(테스트)를 동시에 진행하는 모습
   
   

5. 간편하게 UI 색상이 변경되었네요!

   
   컬러 변경 요청 후 pink 테마가 적용된 방명록 페이지
   
   

이처럼 4번 태스크를 진행하던 세션에서 추가 설명 없이 "디자인 컬러를 pink로 변경해 줘"라고만 요청해도 정확히 동작합니다. 세션이 이미 해당 태스크의 맥락을 유지하고 있기 때문입니다.

실행 방식별 결과 비교

다음 표는 동일한 5단계 작업을 기준으로, 실행 방식에 따른 차이를 정리한 것입니다.

소요 시간은 동일한 난이도 작업을 기준으로 한 체감 비교이며, 환경에 따라 달라질 수 있습니다.

	기존 Todos (단일 세션)	Tasks (단일 세션)	Tasks (병렬 3세션)	Sub-agent
소요 시간	~75분	~75분	~25분	~25분
중간 개입	가능	가능	✅ 세션별 개별 개입 가능	❌ 실행 중 개입 불가
4단계 이후 품질 유지	❌ 컨텍스트 누적으로 저하	유지	유지	유지
세션 종료 후 재개	❌ 재시작 불가	✅ 이어서 가능	✅ 이어서 가능	❌ 결과만 남음
컨텍스트 사용량	~90% (위험 구간)	~60%	각 ~25%	각 ~25%
실시간 방향 변경	가능	가능	가능	❌ 불가
관리 노력	낮음	낮음	중간 (ID 관리 필요)	낮음

Tasks 활용 시나리오

1. 작업이 하루에 끝나지 않을 때

"오늘은 DB랑 API까지만 하고, 내일 UI 이어서 할게."

Tasks는 영속성을 제공합니다. 세션을 닫아도 상태가 디스크에 남아 다음 날 동일한 CLAUDE_CODE_TASK_LIST_ID로 바로 이어서 작업할 수 있습니다.

2. 독립적인 작업이 여러 개일 때

"DB, API, UI를 동시에 만들어야 해."

의존성이 없다면 세션을 나눠 병렬 실행이 가능합니다. 각 세션은 자신의 태스크에만 집중하므로 컨텍스트 낭비가 줄어들고, 전체 작업 시간도 단축됩니다.

3. 작업 순서가 중요할 때

"API가 완성되기 전에 UI를 만들면 안 돼."

blockedBy로 의존성을 설정하면, 선행 작업이 끝나기 전에는 다음 작업이 실행되지 않습니다. 사람이 순서를 관리할 필요가 없습니다.

4. 중간에 방향이 바뀔 때

"리뷰 보고 바꿀 수도 있어."

Tasks는 실행 중에도 대화로 방향을 수정할 수 있습니다. 자동화와 통제권을 동시에 유지합니다.

5. 대규모 작업을 수행할 때 (컨텍스트 한계 우려)

"파일이 많고 단계도 많아."

하나의 세션에 몰아넣으면 컨텍스트가 포화됩니다. Tasks로 분리하면 각 세션이 자신의 범위만 처리하므로 품질이 안정됩니다.

맺음말

Tasks의 핵심은 세 가지입니다.

1. 병렬로 일할 수 있다는 것
2. 시간을 나눠 쓸 수 있다는 것
3. 컨텍스트를 자동으로 관리해 준다는 것

작업을 태스크 단위로 나누면, 현재 리소스에 맞게 가능한 것부터 동시에 진행할 수 있습니다. 오늘 일부만 끝내도, 내일 같은 ID로 이어서 작업하면 됩니다.

각 세션은 자신의 태스크에만 집중하므로 컨텍스트는 자연스럽게 분리되고 과부하도 줄어듭니다. 거대한 대화를 유지하기 위해 신경 쓸 필요가 없습니다.

Tasks는 Claude를 더 안정적이고 체계적으로 활용하게 만드는 시스템입니다.

참고 자료

• “Claude Code Task Management: Anthropic's Native Answer to Ralph Wiggum”, Claude Fast, https://claudefa.st/blog/guide/development/task-management

지금 이 기술이 더 궁금하세요? 인포그랩의 DevOps 전문가가 알려드립니다.