메인 콘텐츠로 건너뛰기
할일 추적은 작업을 관리하고 사용자에게 진행 상황을 표시하는 구조화된 방법을 제공합니다. Claude Agent SDK에는 복잡한 워크플로우를 구성하고 사용자에게 작업 진행 상황을 알리는 데 도움이 되는 기본 제공 할일 기능이 포함되어 있습니다.
TypeScript Agent SDK 0.3.142 및 Claude Code v2.1.142부터 세션은 TodoWrite 대신 구조화된 Task 도구인 TaskCreate, TaskUpdate, TaskGet, TaskList를 사용합니다. 모니터링 코드 변경 방법은 Task 도구로 마이그레이션을 참조하십시오. 이 페이지의 예제는 아직 마이그레이션하지 않은 세션에 대해 TodoWrite를 계속 표시하기 위해 CLAUDE_CODE_ENABLE_TASKS=0을 설정합니다.

​
할일 생명주기

할일은 예측 가능한 생명주기를 따릅니다:
  1. 생성됨 - 작업이 식별될 때 pending으로 생성됨
  2. 활성화됨 - 작업이 시작될 때 in_progress로 활성화됨
  3. 완료됨 - 작업이 성공적으로 완료될 때
  4. 제거됨 - 그룹의 모든 작업이 완료될 때

​
할일이 사용되는 경우

SDK는 다음의 경우에 자동으로 할일을 생성합니다:
  • 복잡한 다단계 작업 - 3개 이상의 서로 다른 작업이 필요한 경우
  • 사용자 제공 작업 목록 - 여러 항목이 언급될 때
  • 중요한 작업 - 진행 상황 추적이 도움이 되는 경우
  • 명시적 요청 - 사용자가 할일 구성을 요청할 때

​
예제

​
할일 변경 모니터링

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Optimize my React app performance and track progress with todos",
  // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses
  // Task tools instead and these tool_use blocks never appear.
  options: { maxTurns: 15, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }
})) {
  // Todo updates are reflected in the message stream
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "tool_use" && block.name === "TodoWrite") {
        const todos = block.input.todos;

        console.log("Todo Status Update:");
        todos.forEach((todo, index) => {
          const status =
            todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";
          console.log(`${index + 1}. ${status} ${todo.content}`);
        });
      }
    }
  }
}

​
실시간 진행 상황 표시

import { query } from "@anthropic-ai/claude-agent-sdk";

class TodoTracker {
  private todos: any[] = [];

  displayProgress() {
    if (this.todos.length === 0) return;

    const completed = this.todos.filter((t) => t.status === "completed").length;
    const inProgress = this.todos.filter((t) => t.status === "in_progress").length;
    const total = this.todos.length;

    console.log(`\nProgress: ${completed}/${total} completed`);
    console.log(`Currently working on: ${inProgress} task(s)\n`);

    this.todos.forEach((todo, index) => {
      const icon =
        todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";
      const text = todo.status === "in_progress" ? todo.activeForm : todo.content;
      console.log(`${index + 1}. ${icon} ${text}`);
    });
  }

  async trackQuery(prompt: string) {
    for await (const message of query({
      prompt,
      // Re-enable TodoWrite, which this tracker watches for.
      options: { maxTurns: 20, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }
    })) {
      if (message.type === "assistant") {
        for (const block of message.message.content) {
          if (block.type === "tool_use" && block.name === "TodoWrite") {
            this.todos = block.input.todos;
            this.displayProgress();
          }
        }
      }
    }
  }
}

// Usage
const tracker = new TodoTracker();
await tracker.trackQuery("Build a complete authentication system with todos");

​
Task 도구로 마이그레이션

Task 도구는 단일 TodoWrite 호출을 각 새 항목에 대한 TaskCreate와 각 상태 변경에 대한 TaskUpdate로 분할하며, TaskList와 TaskGet은 모델이 현재 목록을 다시 읽을 수 있도록 사용 가능합니다. 모니터링 코드는 여전히 어시스턴트 스트림의 tool_use 블록을 검사하지만, 모든 호출에서 전체 목록을 바꾸는 대신 작업 ID로 키가 지정된 맵을 유지합니다. Task 도구는 TypeScript Agent SDK 0.3.142 및 Claude Code v2.1.142부터 기본값이므로 options.env 변경이 필요하지 않습니다.
TodoWrite 사용Task 도구 사용
한 번의 도구 호출로 전체 todos 배열을 다시 작성TaskCreate는 한 항목을 추가하고, TaskUpdate는 taskId로 한 항목을 패치
block.name === "TodoWrite" 일치block.name === "TaskCreate" 또는 "TaskUpdate" 일치
항목 형태: { content, status, activeForm }TaskCreate 입력: { subject, description, activeForm?, metadata? }. TaskUpdate 입력: { taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }. status는 "pending", "in_progress", 또는 "completed"이며, 삭제하려면 status: "deleted"를 설정
block.input.todos를 직접 렌더링호출 전체에서 항목을 누적하거나, TaskList 도구 결과에서 스냅샷을 읽음
할당된 작업 ID는 TaskCreate 입력에 없습니다. 일치하는 tool_result에서 { task: { id, subject } }로 반환되므로, 맵을 키로 지정하기 위해 결과 블록에서 캡처합니다. 다음 예제는 할일 변경 모니터링 루프에 대한 최소한의 변경을 보여줍니다. 전체 목록을 렌더링하려면 스트림에서 TaskList 도구 결과를 감시하거나 TaskCreate 결과와 TaskUpdate 입력을 맵으로 누적합니다: 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Optimize my React app performance",
})) {
  if (message.type !== "assistant") continue;
  for (const block of message.message.content) {
    if (block.type !== "tool_use") continue;
    if (block.name === "TaskCreate") {
      const input = block.input as { subject: string };
      console.log(`+ ${input.subject}`);
    } else if (block.name === "TaskUpdate") {
      const input = block.input as { taskId: string; status?: string };
      if (input.status) console.log(`  ${input.taskId} -> ${input.status}`);
    }
  }
}

​
관련 문서