클로드 코드 Tasks: 세션을 넘나드는 작업 관리

클로드 코드로 규모 있는 프로젝트를 진행하다 보면 한 세션에서 끝나지 않는 작업이 생기기 마련입니다. 인증 시스템을 추가하려면 DB 스키마부터 설계하고, API 엔드포인트를 만들고, 프론트엔드를 고치고, 테스트까지 작성해야 하죠. 문제는 이 과정에서 어디까지 했고 뭐가 남았는지 추적하기가 쉽지 않다는 겁니다. 🤔

예전에는 Claude Code가 내부적으로 Todo라는 간단한 체크리스트를 사용했는데요. 세션 메모리에만 존재해서 터미널을 닫거나 /clear를 하면 사라져 버렸습니다. 서브 에이전트도 메인 세션의 Todo를 볼 수 없었고요. 짧은 작업에는 문제가 없었지만 여러 세션에 걸친 프로젝트에서는 꽤나 답답했습니다.

이런 한계를 해결하기 위해 2026년 1월 Claude Code v2.1.16에서 Tasks가 도입되었습니다. 파일 시스템에 영구 저장되는 태스크를 만들고 작업 간 의존성까지 추적할 수 있는 본격적인 작업 관리 시스템인데요. 여러 세션이 같은 태스크 리스트를 공유하는 것도 가능합니다.

Todo에서 Tasks로

기존 Todo 시스템과 Tasks의 차이를 먼저 짚어보겠습니다.

핵심은 작업 상태가 세션 수명에 묶이지 않는다는 점입니다. 터미널이 꺼지든, 컨텍스트 윈도우가 리셋되든, 노트북을 덮고 내일 다시 열든 태스크는 그대로 남아 있습니다. 이 단순한 변화가 AI 코딩 에이전트의 활용 범위를 크게 넓혀주죠.

네 가지 핵심 도구

Tasks는 TaskCreate, TaskGet, TaskUpdate, TaskList 네 가지 도구로 구성되어 있습니다.

TaskCreate로 새 태스크를 만들면 고유 ID가 부여되고 pending 상태로 시작됩니다.

TaskCreate({
  subject: "JWT 인증 미들웨어 구현",
  description: "API 라우트에 JWT 검증과 리프레시 토큰 지원 추가"
})

TaskUpdate로는 상태를 바꾸거나 의존성을 걸 수 있습니다. 상태는 pending → in_progress → completed 순서를 따르고요.

// 작업 시작
TaskUpdate({ taskId: "1", status: "in_progress" })

// 완료 처리
TaskUpdate({ taskId: "1", status: "completed" })

// 의존성 설정 - 3번은 1번과 2번이 끝나야 시작 가능
TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })

TaskGet으로 특정 태스크의 상세 정보를 가져올 수 있고, TaskList는 전체 태스크 목록을 보여줍니다.

#1 [completed] DB 스키마 설계
#2 [in_progress] API 엔드포인트 구현 (owner: backend-agent)
#3 [pending] 프론트엔드 연동 [blocked by #2]
#4 [pending] 통합 테스트 작성 [blocked by #2, #3]

이 도구들은 직접 호출할 일은 거의 없습니다. “이 프로젝트를 태스크로 나눠줘”라고 자연어로 요청하면 Claude가 알아서 적절한 도구를 사용해 태스크를 생성하고 의존성을 설정합니다. 작업 중에 현재 태스크 상태를 확인하고 싶으면 Ctrl+T를 누르면 됩니다. 태스크 패널이 토글되면서 전체 목록과 진행 상황을 한눈에 볼 수 있죠.

의존성 추적

Tasks에서 가장 유용한 건 의존성 추적입니다. 태스크 간에 blockedBy 관계를 설정하면 방향성 비순환 그래프(DAG)가 만들어지는데요. 앞선 작업이 끝나지 않으면 뒤 작업이 시작되지 않도록 자동으로 관리됩니다.

실제 프로젝트 상황을 예로 들어보겠습니다. ElevenLabs 음성 API를 새로운 프로바이더로 추가하는 작업이 있다고 해보죠.

#1 [pending] ElevenLabs API 클라이언트 작성
#2 [pending] 스트리밍 인터페이스 구현          [blocked by #1]
#3 [pending] 설정 옵션 추가
#4 [pending] 프로바이더 팩토리 연동            [blocked by #1, #3]
#5 [pending] 통합 테스트                      [blocked by #2, #4]
#6 [pending] 문서 작성                        [blocked by #5]

여기서 1번과 3번은 서로 의존하지 않으니 동시에 진행할 수 있습니다. 1번이 끝나면 2번이 자동으로 풀리고, 1번과 3번이 모두 끝나야 4번이 시작됩니다. 이런 자동 언블로킹 덕분에 “아, 2번을 먼저 해야 했는데”하고 나중에 깨닫는 일이 없어지죠.

의존성 관리가 없던 시절에는 서브 에이전트를 여러 개 띄워놓으면 3번 작업이 1번보다 먼저 끝나버려서 충돌이 생기는 경우가 있었습니다. Tasks의 의존성 그래프가 이런 문제를 구조적으로 막아줍니다.

세션을 넘나드는 태스크 공유

기본적으로 태스크 리스트는 세션에 귀속됩니다. 세션 ID가 곧 태스크 리스트 식별자가 되기 때문에 세션을 닫거나 /clear를 하면 태스크 리스트도 사라지죠. 태스크 자체는 파일 시스템에 남아 있지만 새 세션에서는 새 리스트를 쓰게 됩니다.

여러 세션이 같은 태스크 리스트를 공유하려면 CLAUDE_CODE_TASK_LIST_ID 환경 변수를 설정해야 합니다.

CLAUDE_CODE_TASK_LIST_ID="my-project" claude

같은 ID를 지정한 모든 세션이 동일한 태스크 리스트를 바라보게 됩니다. 한 세션에서 태스크를 완료하면 다른 세션에서도 바로 반영되죠.

매번 환경 변수를 입력하기 번거롭다면 settings.json에 넣어두는 것도 방법입니다.

{
  "env": {
    "CLAUDE_CODE_TASK_LIST_ID": "my-project"
  }
}

이렇게 설정하면 해당 프로젝트에서 클로드 코드를 열 때마다 같은 태스크 리스트를 사용하게 됩니다.

참고로 태스크 파일 자체의 저장 경로(~/.claude/tasks/)는 현재 변경할 수 없습니다. Plans에는 plansDirectory 설정이 있지만 Tasks에는 아직 비슷한 옵션이 없어서 프로젝트 디렉토리에 태스크를 저장하거나 Git으로 공유하는 건 불가능합니다.

서브 에이전트와 함께 쓰기

Tasks가 빛을 발하는 순간은 서브 에이전트와 조합할 때입니다. 태스크를 만들고 서브 에이전트에게 병렬로 실행하라고 맡기면 의존성 그래프에 따라 자동으로 순서를 조율합니다.

앞의 ElevenLabs 예제로 돌아가 보겠습니다.

Wave 1 (병렬 실행):
├── Task #1: API 클라이언트 작성
└── Task #3: 설정 옵션 추가

Wave 2 (#1 완료 후):
├── Task #2: 스트리밍 인터페이스 구현
└── Task #4: 프로바이더 팩토리 연동 (#3도 완료된 경우)

Wave 3 (#2, #4 완료 후):
└── Task #5: 통합 테스트

Wave 4 (#5 완료 후):
└── Task #6: 문서 작성

서브 에이전트마다 독립된 컨텍스트 윈도우에서 작업하기 때문에 메인 세션의 컨텍스트가 오염되지 않습니다. 테스트 출력이며 탐색 결과며 온갖 중간 결과물이 서브 에이전트 쪽에만 남고 메인 세션에는 “태스크 #1 완료” 같은 상태 변경만 전달되죠.

작업 중에 서브 에이전트가 예상 못한 추가 작업을 발견할 수도 있습니다. 인증 구현 도중 토큰 만료 처리가 빠져 있다는 걸 알게 되면 서브 에이전트가 알아서 새 태스크를 추가합니다.

TaskCreate({
  subject: "만료된 토큰 갱신 로직 추가",
  description: "인증 구현 중 발견 - 리프레시 토큰 회전 로직 필요"
})

이렇게 태스크 리스트가 살아있는 문서처럼 작업 과정에서 계속 진화해 나갑니다.

에이전트 팀과의 시너지

에이전트 팀 기능을 활성화하면 Tasks와 궁합이 아주 잘 맞습니다. 에이전트 팀에서 태스크 리스트는 팀원들이 공유하는 작업 보드 역할을 하거든요.

팀 리드가 전체 작업을 태스크로 나누면 팀원들이 태스크를 하나씩 가져가서(claim) 처리합니다. 각 팀원이 독립 인스턴스로 동작하면서도 하나의 태스크 리스트를 보고 자율적으로 작업을 조율하는 구조죠. 마치 실제 개발팀이 Jira 보드를 보면서 일하는 것과 비슷합니다.

다만 에이전트 팀은 아직 실험적 기능이라는 점은 기억해두세요. 기본적으로 비활성화되어 있고 토큰 사용량이 상당히 늘어나기 때문에 병렬 처리가 확실히 가치 있는 작업에 한해 사용하는 게 좋습니다.

실전 활용 팁

Tasks를 쓰면서 느낀 팁을 몇 가지 공유합니다.

태스크 단위를 적절하게 잡는 게 중요합니다. “인증 시스템 전체 구축”처럼 너무 크면 진행 상황 파악이 어렵고, “JWT 라이브러리 import문 추가”처럼 너무 작으면 관리 오버헤드가 이득보다 커집니다. “JWT 토큰 생성 서비스 구현”이나 “토큰 검증 미들웨어 작성”처럼 함수 하나 혹은 파일 하나 수준의 결과물이 명확한 단위가 좋습니다.

태스크 제목도 신경 써야 합니다. “인증 관련 작업”보다 “JWT 리프레시 토큰 엔드포인트 구현”이 훨씬 낫죠. Claude가 태스크 제목을 보고 뭘 해야 하는지 판단하기 때문에 제목이 모호하면 결과도 모호해집니다.

그리고 간단한 작업에는 Tasks를 쓸 필요가 없습니다. 3단계도 안 되는 작업이나 한 세션에서 끝나는 일은 그냥 대화하면서 진행하는 게 더 빠르거든요. Tasks는 여러 세션에 걸치는 작업이나 의존성이 복잡한 프로젝트, 서브 에이전트에게 병렬로 맡기는 상황에서 빛납니다.

마치며

Tasks 덕분에 Claude Code가 단순히 코드를 생성하는 도구를 넘어 프로젝트를 관리하는 파트너처럼 쓸 수 있게 되었습니다. 작업을 나누고 의존성을 추적하면서 여러 에이전트가 협업하는 모습이 실제 개발팀 워크플로우와 꽤 비슷하죠.

처음 써본다면 현재 진행 중인 프로젝트에서 “이 작업을 태스크로 나눠줘”라고 한번 요청해보세요. Claude가 적절한 단위로 태스크를 생성하고 의존성을 설정하는 걸 보면 감이 올 겁니다. 거기서 서브 에이전트로 병렬 실행까지 시도해보면 Tasks가 왜 필요한지 바로 느껴질 겁니다.

클로드 코드의 다른 기능이 궁금하다면 클로드 코드 소개에서 전체적인 그림을 살펴보세요. 서브 에이전트에게 작업을 위임하는 방법은 서브 에이전트 가이드에서, 여러 인스턴스가 팀으로 협업하는 구조는 에이전트 팀 가이드에서 다루고 있습니다. 태스크를 만들기 전에 먼저 설계를 검토하고 싶다면 Plan 모드가 유용합니다. 에이전트 동작을 세밀하게 제어하고 싶다면 Hooks를, 프로젝트별 환경 설정이 필요하면 설정 가이드가 도움이 됩니다. 세션을 거듭하면서 Claude가 프로젝트를 학습하는 과정이 궁금하다면 자동 메모리도 참고해보세요.