Claude Code Tool 设计

name: TodoWrite
description: >- Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user. It also helps the user understand the progress of the task and overall progress of their requests.

名称：TodoWrite
描述：>- 使用此工具为当前编码会话创建和管理结构化任务列表。它可以帮助你跟踪进度、组织复杂任务，并向用户展示工作的周全程度。它还能帮助用户了解任务的执行进度，以及其请求的整体完成情况。

When to Use This Tool
Use this tool proactively in these scenarios:

Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
User explicitly requests todo list - When the user directly asks you to use the todo list
User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
After receiving new instructions - Immediately capture user requirements as todos
When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time
After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation

何时使用此工具


在以下场景中，应主动使用此工具：

复杂的多步骤任务——当一个任务需要 3 个或更多不同的步骤或操作时
不简单且复杂的任务——需要仔细规划或执行多项操作的任务
用户明确要求待办列表——当用户直接要求你使用待办列表时
用户提供多个任务——当用户给出一组需要完成的事项时（以编号或逗号分隔）
收到新指令后——立即将用户需求记录为待办事项
开始处理任务时——在开始工作之前将其标记为 in_progress。理想情况下，同一时间只能有一个待办事项处于 in_progress 状态
完成任务后——将其标记为 completed，并添加实现过程中发现的任何后续任务

When NOT to Use This Tool


Skip using this tool when:

There is only a single, straightforward task
The task is trivial and tracking it provides no organizational benefit
The task can be completed in less than 3 trivial steps
The task is purely conversational or informational

NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.

何时不应使用此工具

在以下情况下跳过此工具：

只有一个简单直接的任务
任务微不足道，跟踪它不能带来任何组织上的益处
任务可以在不到 3 个简单步骤内完成
任务纯粹是对话或信息咨询

请注意，如果只有一个简单任务要做，就不应使用此工具。在这种情况下，直接完成任务会更合适。

Examples of When to Use the Todo List

<example>
User: I want to add a dark mode toggle to the application settings. Make sure you run the tests and build when you’re done!
Assistant: I’ll help add a dark mode toggle to your application settings. Let me create a todo list to track this implementation.
Creates todo list with the following items:

Create dark mode toggle component in Settings page
Add dark mode state management (context/store)
Implement CSS-in-JS styles for dark theme
Update existing components to support theme switching
Run tests and build process, addressing any failures or errors that occur
Begins working on the first task

<reasoning>
The assistant used the todo list because:

Adding dark mode is a multi-step feature requiring UI, state management, and styling changes
The user explicitly requested tests and build be run afterward
The assistant inferred that tests and build need to pass by adding “Ensure tests and build succeed” as the final task
</reasoning>
</example>

应使用待办列表的示例


<example>
用户：我想在应用程序设置中添加一个深色模式开关。完成后请确保运行测试和构建！
助手：我会帮你在应用程序设置中添加深色模式开关。让我创建一个待办列表来跟踪这项实现工作。
创建包含以下事项的待办列表：

在 Settings 页面创建深色模式开关组件
添加深色模式状态管理（context/store）
为深色主题实现 CSS-in-JS 样式
更新现有组件以支持主题切换
运行测试和构建流程，并处理出现的任何失败或错误
开始处理第一个任务

<reasoning>
助手使用待办列表的原因：

添加深色模式是一项多步骤功能，需要更改 UI、状态管理和样式
用户明确要求之后运行测试和构建
助手推断测试和构建必须通过，因此将“确保测试和构建成功”添加为最后一个任务
</reasoning>
</example>

<example>


User: Help me rename the function getCwd to getCurrentWorkingDirectory across my project
Assistant: Let me first search through your codebase to find all occurrences of ‘getCwd’.
Uses grep or search tools to locate all instances of getCwd in the codebase
Assistant: I’ve found 15 instances of ‘getCwd’ across 8 different files. Let me create a todo list to track these changes.
Creates todo list with specific items for each file that needs updating
<reasoning>
The assistant used the todo list because:

First, the assistant searched to understand the scope of the task
Upon finding multiple occurrences across different files, it determined this was a complex task with multiple steps
The todo list helps ensure every instance is tracked and updated systematically
This approach prevents missing any occurrences and maintains code consistency
</reasoning>
</example>

<example>


用户：请帮我在整个项目中将函数 getCwd 重命名为 getCurrentWorkingDirectory。
助手：让我先搜索代码库，找出所有出现 ‘getCwd’ 的位置。
使用 grep 或搜索工具定位代码库中 getCwd 的所有实例
助手：我在 8 个不同文件中找到了 15 个 ‘getCwd’ 实例。让我创建一个待办列表来跟踪这些更改。
创建待办列表，为每个需要更新的文件列出具体事项
<reasoning>
助手使用待办列表的原因：

助手首先通过搜索了解任务范围
在不同文件中发现多处实例后，判定这是一个包含多个步骤的复杂任务
待办列表有助于确保每个实例都得到系统化的跟踪和更新
这种方法可以避免遗漏任何实例，并保持代码一致性
</reasoning>
</example>

<example>


User: I need to implement these features for my e-commerce site: user registration, product catalog, shopping cart, and checkout flow.
Assistant: I’ll help implement these features. First, let’s add all the features to the todo list.
Creates a todo list breaking down each feature into specific tasks based on the project architecture
Assistant: Let’s start with user registration. This will involve creating database models, API endpoints, and frontend forms that integrate with your existing authentication system.
<reasoning>
The assistant used the todo list because:

The user provided multiple complex features to implement in a comma separated list
The todo list helps organize these large features into manageable tasks
This approach allows for tracking progress across the entire implementation
</reasoning>
</example>

<example>


用户：我需要为电商网站实现这些功能：用户注册、商品目录、购物车和结账流程。
助手：我会帮你实现这些功能。首先，让我们把所有功能添加到待办列表中。
根据项目架构创建待办列表，将每项功能拆分成具体任务
助手：让我们从用户注册开始。这将涉及创建数据库模型、API 端点，以及与现有身份验证系统集成的前端表单。
<reasoning>
助手使用待办列表的原因：

用户以逗号分隔的列表提供了多个需要实现的复杂功能
待办列表有助于将这些大型功能组织成易于管理的任务
这种方法可以跟踪整个实现过程中的进度
</reasoning>
</example>

<example>


User: Can you help optimize my React application? It’s rendering slowly and has performance issues.
</user>
Assistant: I’ll help optimize your React application. First, let me examine your codebase to identify potential performance bottlenecks.
Reviews component structure, render patterns, state management, and data fetching
Assistant: After analyzing your codebase, I’ve identified several performance issues. Let me create a todo list to track our optimization efforts.
Creates todo list with items like: 1) Implement memoization for expensive calculations in ProductList, 2) Add virtualization for long lists in Dashboard, 3) Optimize image loading in Gallery component, 4) Fix state update loops in ShoppingCart, 5) Review bundle size and implement code splitting
Let’s start by implementing memoization for the expensive calculations in your ProductList component.
</assistant>
<reasoning>
The assistant used the todo list because:

First, the assistant examined the codebase to identify specific performance issues
Based on this analysis, it identified multiple optimization opportunities
Performance optimization is a non-trivial task requiring multiple steps
The todo list helps methodically track improvements across different components
This systematic approach ensures all performance bottlenecks are addressed
</reasoning>
</example>

<example>


用户：你能帮我优化 React 应用吗？它渲染缓慢，并且存在性能问题。
</user>
助手：我会帮你优化 React 应用。首先，让我检查代码库，找出潜在的性能瓶颈。
检查组件结构、渲染模式、状态管理和数据获取
助手：分析代码库后，我发现了几个性能问题。让我创建一个待办列表来跟踪优化工作。
创建待办列表，其中包括：1）为 ProductList 中开销较大的计算实现记忆化，2）为 Dashboard 中的长列表添加虚拟化，3）优化 Gallery 组件中的图片加载，4）修复 ShoppingCart 中的状态更新循环，5）检查包体积并实现代码拆分
让我们先为 ProductList 组件中开销较大的计算实现记忆化。
</assistant>
<reasoning>
助手使用待办列表的原因：

助手首先检查代码库，以识别具体的性能问题
根据分析结果，发现了多个优化机会
性能优化是一项需要多个步骤的复杂任务
待办列表有助于有条理地跟踪不同组件的改进
这种系统化方法可确保所有性能瓶颈都得到处理
</reasoning>
</example>

Examples of When NOT to Use the Todo List


<example>
User: How do I print ‘Hello World’ in Python?
Assistant: In Python, you can print “Hello World” with this simple code:
python
print(“Hello World”)
This will output the text “Hello World” to the console when executed.
</assistant>
<reasoning>
The assistant did not use the todo list because this is a single, trivial task that can be completed in one step. There’s no need to track multiple tasks or steps for such a straightforward request.
</reasoning>
</example>

不应使用待办列表的示例

<example>
用户：如何用 Python 打印 ‘Hello World’？
助手：在 Python 中，可以使用以下简单代码打印 “Hello World”：
python
print(“Hello World”)
执行后，控制台将输出文本 “Hello World”。
</assistant>
<reasoning>
助手没有使用待办列表，因为这是一个可以一步完成的单一简单任务。对于这样直接的请求，无需跟踪多个任务或步骤。
</reasoning>
</example>

<example>
User: What does the git status command do?
Assistant: The git status command shows the current state of your working directory and staging area. It displays which changes have been staged, which haven’t, and which files aren’t being tracked by Git. This is a fundamental command for understanding the current state of your repository before making commits.

<reasoning>
The assistant did not use the todo list because this is an informational request with no actual coding task to complete. The user is simply asking for an explanation, not for the assistant to perform multiple steps or tasks.
</reasoning>
</example>

<example>
用户：git status 命令有什么作用？
助手：git status 命令显示工作目录和暂存区的当前状态。它会显示哪些更改已暂存、哪些尚未暂存，以及哪些文件未被 Git 跟踪。这是在提交之前了解仓库当前状态的一条基础命令。

<reasoning>
助手没有使用待办列表，因为这是一个信息咨询请求，没有需要完成的实际编码任务。用户只是要求解释，并非要求助手执行多个步骤或任务。
</reasoning>
</example>

<example>
User: Can you add a comment to the calculateTotal function to explain what it does?
Assistant: Sure, let me add a comment to the calculateTotal function to explain what it does.
 Uses the Edit tool to add a comment to the calculateTotal function 

<reasoning>
The assistant did not use the todo list because this is a single, straightforward task confined to one location in the code. Adding a comment doesn’t require tracking multiple steps or systematic organization.
</reasoning>
</example>

<example>
用户：你能给 calculateTotal 函数添加一条注释，解释它的作用吗？
助手：当然，让我给 calculateTotal 函数添加一条注释来解释它的作用。
 使用 Edit 工具给 calculateTotal 函数添加注释 

<reasoning>
助手没有使用待办列表，因为这是一个仅涉及代码中单一位置的简单任务。添加注释不需要跟踪多个步骤，也不需要进行系统化组织。
</reasoning>
</example>

<example>
User: Run npm install for me and tell me what happens.
Assistant: I’ll run the npm install command for you.

Executes: npm install
The command completed successfully. Here’s the output:
[Output of npm install command]
All dependencies have been installed according to your package.json file.
<reasoning>
The assistant did not use the todo list because this is a single command execution with immediate results. There are no multiple steps to track or organize, making the todo list unnecessary for this straightforward task.
</reasoning>
</example>

<example>
用户：帮我运行 npm install，并告诉我结果。
助手：我会为你运行 npm install 命令。

执行：npm install
命令已成功完成。输出如下：
[npm install 命令的输出]
已根据 package.json 文件安装所有依赖项。
<reasoning>
助手没有使用待办列表，因为这只是执行一条能立即得到结果的命令。没有多个需要跟踪或组织的步骤，因此这个简单任务不需要待办列表。
</reasoning>
</example>

Task States and Management



Task States: Use these states to track progress:

pending: Task not yet started
in_progress: Currently working on (limit to ONE task at a time)
completed: Task finished successfully



Task Management:

Update task status in real-time as you work
Mark tasks complete IMMEDIATELY after finishing (don’t batch completions)
Only have ONE task in_progress at any time
Complete current tasks before starting new ones
Remove tasks that are no longer relevant from the list entirely

任务状态与管理




任务状态：使用以下状态跟踪进度：

pending：任务尚未开始
in_progress：当前正在处理（同一时间仅限一个任务）
completed：任务已成功完成



任务管理：

工作时实时更新任务状态
完成后立即将任务标记为完成（不要批量更新完成状态）
任何时候都只能有一个任务处于 in_progress 状态
先完成当前任务，再开始新任务
从列表中彻底移除不再相关的任务

3. Task Completion Requirements:
- ONLY mark a task as completed when you have FULLY accomplished it
- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
- When blocked, create a new task describing what needs to be resolved
- Never mark a task as completed if:
  - Tests are failing
  - Implementation is partial
  - You encountered unresolved errors
  - You couldn't find necessary files or dependencies


Task Breakdown:

Create specific, actionable items
Break complex tasks into smaller, manageable steps
Use clear, descriptive task names



When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.

3. 任务完成要求：


只有在任务已全部完成时，才能将其标记为 completed
如果遇到错误、阻碍或无法完成，请将任务保持为 in_progress 状态
遇到阻碍时，创建一个新任务来说明需要解决的问题
在以下情况下，绝不能将任务标记为 completed：

测试失败
实现尚不完整
遇到未解决的错误
无法找到所需的文件或依赖项




任务拆分：

创建具体且可执行的事项
将复杂任务拆分成更小、更易于管理的步骤
使用清晰且具有描述性的任务名称



如有疑问，请使用此工具。主动管理任务能体现细致周到，并确保你成功完成所有要求。

input_schema:
type: object
properties:
todos:
type: array
items:
type: object
properties:
content:
type: string
minLength: 1
status:
type: string
enum:
- pending
- in_progress
- completed
priority:
type: string
enum:
- high
- medium
- low
id:
type: string
required:
- content
- status
- priority
- id
additionalProperties: false
description: The updated todo list
required:
- todos
additionalProperties: false
$schema: http://json-schema.org/draft-07/schema#

input_schema（输入模式）：
type: object（对象）
properties（属性）：
todos（待办事项）：
type: array（数组）
items（数组项）：
type: object（对象）
properties（属性）：
content（内容）：
type: string（字符串）
minLength: 1（最小长度为 1）
status（状态）：
type: string（字符串）
enum（枚举）：
- pending（待处理）
- in_progress（进行中）
- completed（已完成）
priority（优先级）：
type: string（字符串）
enum（枚举）：
- high（高）
- medium（中）
- low（低）
id（标识符）：
type: string（字符串）
required（必填项）：
- content（内容）
- status（状态）
- priority（优先级）
- id（标识符）
additionalProperties: false（不允许额外属性）
description: The updated todo list（更新后的待办列表）
required（必填项）：
- todos（待办事项）
additionalProperties: false（不允许额外属性）
$schema: http://json-schema.org/draft-07/schema#