前言

在AI應(yīng)用中，若將系統(tǒng)提示詞（System Prompt）比作智能體的“腦”，那么工具（Tools）就是它的“手”。二者相輔相成，共同構(gòu)成AI Agent的核心運行機制——思維指導(dǎo)行動，行動反哺思維，使智能體既能理解任務(wù)，又能真正完成任務(wù)。上一篇文章中我們重點解析了ClaudeCode的系統(tǒng)提示詞，本文中通過分析其工具設(shè)計，分享如何進(jìn)行合理而高效的工具體系構(gòu)建。

ClaudeCode內(nèi)置Tools

Task: 啟動一個新的代理來自主處理復(fù)雜的、多步驟的任務(wù)
Bash: 在持久 shell 會話中執(zhí)行給定的 bash 命令，允許設(shè)置超時，確保正確的處理和安全措施
BashOutput:獲取Bash的輸出內(nèi)容
KillBash:關(guān)閉Bash
Glob: 本地文件匹配工具
Grep: 本地文件搜索工具
LS: 列出給定路徑中的文件和目錄
ExitPlanMode:退出計劃模式
Read:讀取本地文件
Edit:編輯本地文件（在文件中執(zhí)行精確的字符串替換）
MultiEdit:基于Edit的 在一次操作中對單個文件進(jìn)行多次編輯的工具
Write:寫入本地文件
NotebookEdit:編輯Jupyter notebook文件
WebFetch:從指定網(wǎng)頁獲取內(nèi)容
TodoWrite:創(chuàng)建、管理任務(wù)列表，跟蹤任務(wù)進(jìn)度，組織復(fù)雜任務(wù)
WebSearch:從網(wǎng)絡(luò)上搜索結(jié)果

以下是ClaudeCode的架構(gòu)圖：

claudecode分層多agent架構(gòu)圖.png

在上述的這些工具中，最為重要的工具是就Task和TodoWrite，Task作為入口其重要性不言而喻，其啟動新的agent（SubAgent）處理復(fù)雜、多步驟的任務(wù)，可以說Task的表現(xiàn)直接影響到是否能給出令人滿意的結(jié)果；TodoWrite的重要性實際上在我們上一篇文章 《ClaudeCode為什么這么強大？通過解析其系統(tǒng)提示詞一探究竟》中就已經(jīng)體現(xiàn)出來了，ClaudeCode系統(tǒng)提示詞中明確指使使用 TodoWrite 管理任務(wù)、規(guī)劃任務(wù)及跟蹤任務(wù)狀態(tài)，并鼓勵積極、頻繁的使用 TodoWrite。

例如當(dāng)我要求ClaudeCode為我 分析項目結(jié)構(gòu)找出潛在的bug，使用 ctrl + o展示Thinking的詳細(xì)過程。

任務(wù)分析.png

Explore.png

可以看出流程是：首先調(diào)用了Task工具并啟動了新的SubAgent（Expore）完成任務(wù)，由于這是一個復(fù)雜任務(wù)，所以使用TodoWrite進(jìn)行任務(wù)步驟拆解并跟蹤子任務(wù)狀態(tài)。

1、Task詳解

json定義描述如下：

{
    "name": "Task",
    "description": "Launch a new agent to handle complex, multi-step tasks autonomously...",
    "input_schema": {
        "type": "object",
        "properties": {
            "description": {
                "type": "string",
                "description": "任務(wù)的簡短描述（3-5個詞）"
            },
            "prompt": {
                "type": "string",
                "description": "agent要執(zhí)行的任務(wù)（詳細(xì)內(nèi)容）"
            },
            "subagent_type": {
                "type": "string",
                "description": "用于此任務(wù)的指定agent"
            }
        },
        "required": [
            "description",
            "prompt",
            "subagent_type"
        ],
        "additionalProperties": false,
        "$schema": "[http://json-schema.org/draft-07/schema#](http://json-schema.org/draft-07/schema#)"
    }
}

一共需要三個參數(shù)且都是必須參數(shù)，我們帶入上面的使用示例解釋這三個參數(shù)分別是什么:

• description：分析項目結(jié)構(gòu)找出潛在的bug
• prompt：
  探索這個項目的整體結(jié)構(gòu)。請分析：
  1. 項目的主要目錄和文件組織
  2. 主要的Python模塊和它們的職責(zé)
  3. 項目的核心功能是什么
  4. 使用了哪些主要的技術(shù)棧和依賴
  5. 配置文件和入口點
• subagent_type： Explore

對Task的詳細(xì)描述如下：

啟動一個新的自動處理復(fù)雜的、多步驟的任務(wù)。

可用的Agent類型及其可以訪問的工具：
- 通用型：用于研究復(fù)雜問題、搜索代碼和執(zhí)行多步驟任務(wù)的通用型代理。當(dāng)你搜索關(guān)鍵字或文件，并且不確定在最初幾次嘗試中找到正確的匹配時，請使用此代理執(zhí)行搜索。
- statusline-setup：使用這個代理配置用戶的Claude Code狀態(tài)行設(shè)置。（工具：Read， Edit） 
- output-style-setup：使用此代理創(chuàng)建Claude Code輸出樣式。（工具：Read、Write、Edit、Glob、LS、Grep）

在使用Task工具時，必須指定subagent_type參數(shù)來選擇要使用的Agent類型。


什么時候不使用Agent：
- 如果你想讀一個特定的文件路徑,使用Read或Glob工具更快的獲取更多的匹配結(jié)果，而不是代理工具
- 如果你正在尋找一個特定的類例如：“class Foo”,使用Glob工具更快地找到匹配結(jié)果
- 如果你在一個指定文件或2-3個文件中搜索代碼，使用Read工具而不是代理工具
- 其他所有與agent描述不相關(guān)的任務(wù)

使用說明：
1. 盡可能同時啟動多個代理，以實現(xiàn)性能最大化；要做到這一點，在一句話中使用多個工具（而不是多句話多個工具）
2. agent處理完成后會返回一條消息。agent返回的結(jié)果對用戶是不可見的。為了向用戶顯示結(jié)果，您應(yīng)該向用戶發(fā)送一條對結(jié)果簡要說明的消息。
3. 每個代理調(diào)用都是無狀態(tài)的。你將無法向代理發(fā)送額外的消息，代理也無法在其給出最終結(jié)果前與你通訊。因此，提示詞中應(yīng)該包含代理自主執(zhí)行的非常詳細(xì)的任務(wù)描述，并且你應(yīng)該準(zhǔn)確地指定代理應(yīng)該在其最終且唯一的消息中返回給你的信息。
4. 代理的輸出通常應(yīng)該是可信的。
5. 因為代理不知道用戶的意圖，所以你需要清楚地告訴代理你是希望它寫代碼還是只是做研究（搜索、文件讀取、網(wǎng)頁搜索等），
6. 如果代理描述提到應(yīng)該主動使用它，你應(yīng)該運用你的判斷力盡最大努力使用它，而不需要用戶要求使用它（才去使用它）。


示例：

代理的描述示例
<example_agent_descriptions>
"code-reviewer": 在編寫完一段重要的代碼后使用這個代理
"greeting-responder":當(dāng)使用友好的笑話回應(yīng)用戶的問候時，使用此代理
</example_agent_description>

<example>
user: 請編寫一個函數(shù)，檢查一個數(shù)是否為質(zhì)數(shù)
assistant: 當(dāng)然，讓我寫一個函數(shù)來檢驗一個數(shù)是否為質(zhì)數(shù)
assistant: 首先讓我用寫工具寫一個函數(shù)來檢查一個數(shù)是否是素數(shù)
assistant: 我將使用Write工具編寫以下代碼:
<code>
function isPrime(n) {
  if (n <= 1) return false
  for (let i = 2; i * i <= n; i++) {
    if (n % i === 0) return false
  }
  return true
}
</code>
<commentary>
由于編寫了一段重要的代碼并且完成了任務(wù)，現(xiàn)在可以使用code-reviewer來審查代碼
</commentary>
assistant: 現(xiàn)在讓我使用code-reviewer代理來審查代碼
assistant: 使用Task工具與code-reviewer代理一起啟動
</example>

<example>
user: 你好
<commentary>
由于用戶在打招呼，所以使用greeting-responder代理以友好的笑話進(jìn)行響應(yīng)
</commentary>
assistant: 使用Task工具啟動greeting-responder代理
</example>

從Task的描述總結(jié)出以下幾個關(guān)鍵點：

• Task不直接處理任務(wù)，而是通過創(chuàng)建子agent的方式完成任務(wù)，Task提供子agent所需要的信息并接收處理結(jié)果
• 明確可使用的agent和工具，明確什么情況下適合使用agent而什么情況下更適合使用工具
• 詳細(xì)的使用說明，最大限度的提升處理結(jié)果
• 給出具體示例

2、TodoWrite詳解

json定義描述如下：

{
    "name": "TodoWrite",
    "description": "Use this tool to create and manage a structured task list for your current coding session. This helps you track progress...",
    "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"
                            ]
                        },
                        "id": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "content",
                        "status",
                        "id"
                    ],
                    "additionalProperties": false
                },
                "description": "The updated todo list"
            }
        },
        "required": [
            "todos"
        ],
        "additionalProperties": false,
        "$schema": "[http://json-schema.org/draft-07/schema#](http://json-schema.org/draft-07/schema#)"
    }
}

需要注意的是所需參數(shù)只有todos且其類型為數(shù)組，數(shù)據(jù)的元素是一個具有content、status和id的對象，content為子任務(wù)內(nèi)容，status子任務(wù)狀態(tài)，任務(wù)狀態(tài)一共有 pending、in_progress和completed三種類型，id是子任務(wù)的id，可以認(rèn)為就是子任務(wù)的執(zhí)行順序。
帶入上面的使用示例以json格式表示就是：

[
  {
    "id": 1,
    "content": "項目的主要目錄和文件組織",
    "status": "completed"
  },
  {
    "id": 2,
    "content": "主要的Python模塊和它們的職責(zé)",
    "status": "in_progress"
  },
  {
    "id": 3,
    "content": "項目的核心功能是什么",
    "status": "pending"
  },
  {
    "id": 4,
    "content": "使用了哪些主要的技術(shù)棧和依賴",
    "status": "pending"
  },
  {
    "id": 5,
    "content": " 配置文件和入口點",
    "status": "pending"
  }
]

對TodoWrite的詳細(xì)描述如下：

使用此工具可為當(dāng)前編碼會話創(chuàng)建和管理結(jié)構(gòu)化任務(wù)列表。這可以幫助你跟蹤進(jìn)度，組織復(fù)雜的任務(wù)，并向用戶展示處理問題的詳盡程度。
它還可以幫助用戶了解任務(wù)的進(jìn)度和請求的總體進(jìn)度。

## 什么時候使用
在以下場景中主動使用此工具：

1. 復(fù)雜的多步驟任務(wù)——當(dāng)一個任務(wù)需要3個或更多不同的步驟或動作時
2. 影響重大且復(fù)雜的任務(wù)——需要仔細(xì)規(guī)劃或多次操作的任務(wù)
3. 用戶明確要求使用待辦事項列表——當(dāng)用戶直接要求你使用待辦事項列表時
4. 用戶提供多個任務(wù)——當(dāng)用戶提供要做的事情的列表時（編號或逗號分隔)
5. 收到新指令后-立即獲取用戶需求作為待辦事項
6. 當(dāng)你開始處理一項任務(wù)時——在開始工作之前把它標(biāo)記為“進(jìn)行中”。理想情況下，你應(yīng)該一次只做一件待辦事項
7. 完成任務(wù)后-將其標(biāo)記為已完成，并添加在執(zhí)行過程中發(fā)現(xiàn)的任何新的后續(xù)任務(wù)

### 什么時候不使用
在以下情況下跳過使用此工具：
1. 只有一個簡單的、直接的任務(wù)
2. 這個任務(wù)過于瑣碎（微不足道），跟蹤它對整體管理并沒有實質(zhì)幫助。
3. 這項任務(wù)只需不到3個簡單的步驟就可以完成
4. 任務(wù)是純粹的對話或詢問

請注意，如果只有一個微不足道的任務(wù)要做，不應(yīng)使用此工具。在這種情況下你應(yīng)該直接完成任務(wù)。

## 有關(guān)什么時候使用Todo list的示例

<example>
User: 我想在應(yīng)用程序設(shè)置增加暗模式。確保運行測試并在完成后進(jìn)行構(gòu)建！
Assistant:我將幫助添加一個暗模式到您的應(yīng)用程序設(shè)置。讓我創(chuàng)建一個待辦事項列表來跟蹤這個實現(xiàn)。
*使用以下項創(chuàng)建待辦事項列表:*
1. 在設(shè)置頁面中創(chuàng)建暗模式切換組件
2. 添加暗模式狀態(tài)管理
3. 為暗模式實現(xiàn)CSS-in-JS樣式
4. 更新現(xiàn)有組件以支持主題切換
5. 運行測試和生成過程，處理發(fā)生的任何故障或錯誤
*開始處理第一個任務(wù)*

<reasoning>
使用待辦列表的原因如下:
1. 添加暗模式是一個多步驟的功能，需要UI、狀態(tài)管理和樣式更改
2. 用戶明確要求之后運行測試和構(gòu)建
3. 助手通過添加“確保測試和構(gòu)建成功”作為最終任務(wù)來推斷測試和構(gòu)建需要通過
</reasoning>
</example>

<example>
User: 將項目中的函數(shù)getCwd重命名為getCurrentWorkingDirectory
Assistant: 讓我先搜索一下代碼庫，找出所有出現(xiàn)的‘getCwd’
*使用grep或搜索工具在代碼庫中定位getCwd的所有實例*
Assistant: 我在8個不同的文件中發(fā)現(xiàn)了15個“getCwd”實例。讓我創(chuàng)建一個待辦事項列表來跟蹤這些更改。
*為每個需要更新的文件創(chuàng)建帶有特定項目的待辦事項列表*

<reasoning>
使用待辦列表的原因如下:
1. 首先，助手進(jìn)行搜索，了解任務(wù)范圍
2. 當(dāng)在不同的文件中發(fā)現(xiàn)多次出現(xiàn)時，可以確定這是一個包含多個步驟的復(fù)雜任務(wù)
3. 待辦事項列表有助于確保系統(tǒng)地跟蹤和更新每個實例
4. 這種方法可以防止遺漏任何事件，并保持代碼的一致性
</reasoning>
</example>


<example>
User: 我需要為我的電子商務(wù)網(wǎng)站實現(xiàn)這些功能：用戶注冊、產(chǎn)品目錄、購物車和結(jié)帳流程。
Assistant: 我將幫助實現(xiàn)這些特性。首先，讓我們將所有功能添加到待辦事項列表中。
*創(chuàng)建一個待辦事項列表，根據(jù)項目架構(gòu)將每個特性分解為特定的任務(wù)*
Assistant: 讓我們從用戶注冊開始。這將涉及創(chuàng)建與現(xiàn)有身份驗證系統(tǒng)集成的數(shù)據(jù)庫模型、API端點和前端表單。

<reasoning>
使用待辦列表的原因如下:
1. 用戶在逗號分隔的列表中提供了多個復(fù)雜的特性實現(xiàn)
2. 待辦事項列表有助于將這些大型功能組織到可管理的任務(wù)中
3. 這種方法允許跟蹤整個實現(xiàn)的進(jìn)度
</reasoning>
</example>

<example>
User: 你能幫我優(yōu)化我的React應(yīng)用嗎？它的渲染速度很慢，并且有性能問題。
Assistant: 我將幫助優(yōu)化您的React應(yīng)用程序。首先，讓我檢查一下您的代碼庫，以確定潛在的性能瓶頸。
*查看組件結(jié)構(gòu)、呈現(xiàn)模式、狀態(tài)管理和數(shù)據(jù)獲取*
Assistant: 在分析了代碼庫之后，我發(fā)現(xiàn)了幾個性能問題。讓我創(chuàng)建一個待辦事項列表來跟蹤我們的優(yōu)化工作。
*創(chuàng)建待辦事項列表的項目如下：1)在ProductList中實現(xiàn)昂貴計算的記憶，2)在儀表板中添加長列表的虛擬化，3)優(yōu)化Gallery組件中的圖像加載，4)修復(fù)ShoppingCart中的狀態(tài)更新循環(huán)，5)審查包大小并實現(xiàn)代碼分割*
讓我們從實現(xiàn)ProductList組件中昂貴計算的記憶開始。
<reasoning>
使用待辦列表的原因如下:
1. 首先，助手檢查代碼庫以確定特定的性能問題
2. 基于此分析，確定了多個優(yōu)化可能
3. 性能優(yōu)化是一項非常重要的任務(wù)，需要多個步驟
4. 待辦事項列表有助于系統(tǒng)地跟蹤不同組件之間的改進(jìn)
5. 這種系統(tǒng)的方法確保所有性能瓶頸都得到解決
</reasoning>
</example>

## 什么時候使用

<example>
User: 使用python如何打印出'Hello World'
Assistant: 在 Python 中，你可以用下面這段簡單的代碼打印 "Hello World"：

python
print("Hello World")


當(dāng)你執(zhí)行這段代碼時，它會在控制臺輸出文本 "Hello World"。</assistant>

<reasoning>
助手沒有使用待辦事項列表（todo list），因為這是一個單一且非常簡單的任務(wù)，只需要一步就能完成。對于這樣直觀的請求，沒有必要去跟蹤多個任務(wù)或步驟。
</reasoning>
</example>

<example>
User:git status命令有什么用
Assistant: `git status` 命令會顯示當(dāng)前工作目錄和暫存區(qū)的狀態(tài)。它會列出哪些更改已經(jīng)被暫存、哪些更改尚未暫存，以及哪些文件還沒有被 Git 追蹤。在提交之前，這個命令是了解當(dāng)前倉庫狀態(tài)的基礎(chǔ)工具。

<reasoning>
助手沒有使用待辦事項列表，因為這是一個純信息類請求，并不涉及實際的編碼任務(wù)。用戶只是想要一個解釋，而不是讓助手執(zhí)行多個步驟或任務(wù)。
</reasoning>
</example>

<example>
User: 能給calculateTotal函數(shù)添加一個注釋來解釋它的作用嗎？
Assistant: 當(dāng)然，讓我給calculateTotal函數(shù)添加一條注釋來解釋它的作用。
* 使用 Edit 工具為 calculateTotal 函數(shù)添加了一條說明其功能的注釋 *

<reasoning>
助手沒有使用待辦事項列表，因為這是一個單一、簡單的任務(wù)，并且只局限在代碼的一個位置。添加注釋不需要跟蹤多個步驟，也不需要系統(tǒng)化的任務(wù)組織。
</reasoning>
</example>

<example>
User: 為我運行npm install并告訴我發(fā)生了什么
Assistant: 我將為你運行npm install命令

*執(zhí)行：npm install*

命令已成功執(zhí)行。以下是輸出內(nèi)容：
[Output of npm install command]

所有依賴項都已經(jīng)按照你的 package.json 文件安裝完成。

<reasoning>
助手沒有使用待辦事項列表，因為這只是單條命令的執(zhí)行并立刻得到結(jié)果。這里不存在需要跟蹤或組織的多步驟流程，所以對于這個簡單任務(wù)，待辦事項列表是沒有必要的。
</reasoning>
</example>

## 任務(wù)狀態(tài)、任務(wù)管理

1. **任務(wù)狀態(tài)**: 使用以下狀態(tài)來跟蹤任務(wù)進(jìn)度：

    * pending：任務(wù)尚未開始
    * in_progress：任務(wù)正在進(jìn)行中（同一時間只能有一個任務(wù)處于該狀態(tài)）
    * completed：任務(wù)已成功完成

2. **任務(wù)管理**:

    * 在實際工作過程中實時更新任務(wù)狀態(tài)
    * 任務(wù)完成后立刻標(biāo)記為 completed（不要把多個完成一起批量更新）
    * 任意時刻只允許有一個任務(wù)處于 in_progress 狀態(tài)
    * 在開始新任務(wù)之前，必須先完成當(dāng)前任務(wù)
    * 對于不再相關(guān)的任務(wù)，應(yīng)直接從列表中移除

3. **任務(wù)完成要求**:

    * 只有在“完全”完成任務(wù)時，才能將其標(biāo)記為 completed
    * 如果遇到錯誤、阻塞或無法完成任務(wù)，應(yīng)保持任務(wù)狀態(tài)為 in_progress
    * 當(dāng)被阻塞時，創(chuàng)建一個新的任務(wù)，用來描述需要解決的問題
    * 在以下情況中絕不能將任務(wù)標(biāo)記為 completed：

        * 測試未通過
        * 實現(xiàn)不完整
        * 存在尚未解決的錯誤
        * 無法找到所需的文件或依賴

4. **任務(wù)分解**:

    * 創(chuàng)建具體且可執(zhí)行的任務(wù)項
    * 將復(fù)雜任務(wù)拆分為更小、更易管理的步驟
    * 使用清晰、描述性強的任務(wù)名稱

如果有疑問，請使用此工具。積極主動地進(jìn)行任務(wù)管理表明了你的專注，并確保你成功地完成所有要求。

TodoWrite的描述作用如下：

• TodoWrite將復(fù)雜任務(wù)拆分成多步驟的子任務(wù)
• 明確什么情況使用而什么情況不使用
• 任務(wù)管理、任務(wù)追蹤、任務(wù)分解、任務(wù)完成要求
• 對每種場景、每個階段都給出了詳細(xì)的示例

總結(jié)

可以看出與系統(tǒng)提示詞不同的是，對工具的描述是更為簡短且覆蓋范圍更小的，我們只需要明確這個工具是做什么的，什么時候使用這個工具而什么時候不使用這個工具，并在最后給出充足的示例展示。從這一點上來說，設(shè)計一個合理的工具比設(shè)計一個合格的系統(tǒng)提示詞要容易得多。

篇幅有限不可能在一篇文章中對ClaudeCode所有的tools進(jìn)行全面解析，Task和TodoWrite作為其眾多工具中最為復(fù)雜、最為關(guān)鍵的工具，對兩者解析已經(jīng)能夠一定程度上反應(yīng)ClaudeCode工具的設(shè)計哲學(xué)，Task和TodoWrite的設(shè)計原則與設(shè)計邏輯給我們開發(fā)agent tools提供了良好的示范，希望通過這篇文章能讓大家有所收獲。