1. 從一次 Prompt 調(diào)試說(shuō)起Claude Code 的提示詞模塊到底長(zhǎng)什么樣如果你正在用 Claude Code 做本地開(kāi)發(fā)大概率遇到過(guò)這種情況同一個(gè)任務(wù)換個(gè)說(shuō)法效果天差地別或者你想改改它的行為風(fēng)格卻不知道從哪下手。這背后的核心就是 Claude Code 的 Prompt 提示詞模塊。它不是一個(gè)簡(jiǎn)單的字符串而是一套分層拼裝、帶優(yōu)先級(jí)覆蓋、支持動(dòng)態(tài)注入的工程化結(jié)構(gòu)。理解這套結(jié)構(gòu)你才能知道為什么 Claude Code 在復(fù)雜任務(wù)里比裸調(diào) API 穩(wěn)得多也才能在自己的項(xiàng)目里復(fù)刻類似的骨架。這篇文章聚焦 Claude Code 源碼中 Prompt 模塊的圖解拆解同時(shí)結(jié)合 TaoToken 的統(tǒng)一 Key/API 通道給出settings.json與config.toml的可復(fù)制配置骨架并演示一次 Prompt 模塊調(diào)用驗(yàn)證動(dòng)作。適合已經(jīng)上手 Claude Code、想深入理解提示詞工程結(jié)構(gòu)的開(kāi)發(fā)者也適合想把 Claude Code 接入自己工具鏈、需要統(tǒng)一管理 API 通道的同學(xué)。全文按“結(jié)構(gòu)拆解 → 接入配置 → 驗(yàn)證請(qǐng)求 → 排障”的順序展開(kāi)每一步都能跟著做。Claude Code 的 Prompt 模塊大致分成六塊Core System Prompt、Tool Prompts、Skill Prompts、Agent Prompts、Context Management Prompts、Memory Prompts。它們不是平鋪的而是有明確的邊界和優(yōu)先級(jí)。下面逐層拆。2. Core System Prompt靜態(tài)規(guī)則與動(dòng)態(tài)分段的拼裝邏輯Core System Prompt 是整個(gè)提示詞體系的地基。它由兩部分組成靜態(tài)規(guī)則和動(dòng)態(tài)分段dynamicSections。靜態(tài)規(guī)則會(huì)被緩存動(dòng)態(tài)分段每輪可能更新兩者之間有一個(gè) boundary 做劃分。這種設(shè)計(jì)的好處是不變的部分不重復(fù)計(jì)算變的部分按需注入。靜態(tài)規(guī)則最簡(jiǎn)形態(tài)類似這樣if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) { return [ You are Claude Code, Anthropics official CLI for Claude.\n\nCWD: ${getCwd()}\nDate: ${getSessionStartDate()}, ] }動(dòng)態(tài)分段則是一個(gè)數(shù)組每項(xiàng)通過(guò)systemPromptSection注冊(cè)const dynamicSections [ systemPromptSection(session_guidance, () getSessionSpecificGuidanceSection(enabledTools, skillToolCommands)), systemPromptSection(memory, () loadMemoryPrompt()), systemPromptSection(language, () getLanguageSection(settings.language)), systemPromptSection(output_style, () getOutputStyleSection(outputStyleConfig)), DANGEROUS_uncachedSystemPromptSection( mcp_instructions, () isMcpInstructionsDeltaEnabled() ? null : getMcpInstructionsSection(mcpClients), MCP servers connect/disconnect between turns ), systemPromptSection(summarize_tool_results, () SUMMARIZE_TOOL_RESULTS_SECTION), ]注意DANGEROUS_uncachedSystemPromptSection這個(gè)命名它明確標(biāo)記了“這個(gè)分段不緩存”因?yàn)?MCP 連接狀態(tài)會(huì)在輪次間變化。這種顯式標(biāo)記比隱式約定更不容易踩坑。拼接時(shí)還有一個(gè)優(yōu)先級(jí)策略樹(shù)buildEffectiveSystemPrompt保證多模式、多角色、多來(lái)源 prompt 共存時(shí)覆蓋關(guān)系清晰。優(yōu)先級(jí)從高到低優(yōu)先級(jí)來(lái)源行為P0Override SystemPrompt硬覆蓋替換其他所有P1Coordinator Promptcoordinator 模式下替換默認(rèn)P2Agent Prompt主線程為 agent 時(shí)替換默認(rèn)proactive 模式下追加P3Custom System Prompt用戶傳--system-prompt時(shí)使用P4Default System Prompt最終兜底這個(gè)優(yōu)先級(jí)樹(shù)是理解 Claude Code 行為的關(guān)鍵。你如果發(fā)現(xiàn)自己的--system-prompt沒(méi)生效先檢查是不是被更高優(yōu)先級(jí)的 agent 或 coordinator 覆蓋了。3. Tool / Skill / Agent Prompts行為協(xié)議與漸進(jìn)式加載Tool Prompts 的特點(diǎn)是“行為協(xié)議”這個(gè)工具是什么、什么時(shí)候用、什么時(shí)候不用、參數(shù)約束是什么。以 GrepTool 為例它的描述里會(huì)寫“to find interface in Go Code”這類自然語(yǔ)言規(guī)則而不是在代碼里做硬性補(bǔ)丁。Claude Code 選擇相信大模型的語(yǔ)義理解能力把規(guī)則放在 Prompt 里而非代碼里。BashTool 的描述則復(fù)雜得多更像一份高風(fēng)險(xiǎn)工具專用操作規(guī)程定義了 git 提交 PR 的詳細(xì)流程、什么不能做、哪些步驟用 skill 替代。這種復(fù)雜度已經(jīng)接近一個(gè)初版 Skill也解釋了后來(lái) Skill 機(jī)制出現(xiàn)的動(dòng)機(jī)。Skill Prompts 解決的是 token 浪費(fèi)問(wèn)題。如果全用 MCP上下文窗口里會(huì)塞滿 tool 定義和參數(shù)但模型每輪只選部分執(zhí)行。Skill 采用漸進(jìn)式加載先把 skill 作為 prompt 資產(chǎn)注冊(cè)再由 SkillTool 在運(yùn)行時(shí)展開(kāi)成新的上下文消息。一個(gè) skill 包含這些核心字段name: Claude API description: 這個(gè)技能用于幫助你使用 Claude API、Anthropic SDK 或 Agent SDK 構(gòu)建應(yīng)用... allowed-tools: - Read - WebFetch model: ... hooks: ... paths: ...prompt 生成規(guī)則是先找到## Reading Guide把 SKILL_PROMPT 分成兩段前半段 basePrompt 保留中間的 reading guide 用運(yùn)行時(shí)生成版替換。reading guide 本質(zhì)是一個(gè)索引文件告訴模型遇到不同任務(wù)該讀哪些 docs單輪文本分類 / 摘要 / 信息抽取 / 問(wèn)答 → 看{lang}/claude-api/README.md聊天 UI 或?qū)崟r(shí)流式響應(yīng)展示 → 看{lang}/claude-api/README.md{lang}/claude-api/streaming.md長(zhǎng)對(duì)話可能超過(guò)上下文窗口 → 看 README 中的 Compaction 部分lang由detectLanguage函數(shù)判斷pyproject.toml/requirements.txt→ Pythonpackage.json/tsconfig.json→ TypeScriptgo.mod→ Gopom.xml→ Java。檢測(cè)不出來(lái)就直接問(wèn)用戶。拼接時(shí)用doc path...標(biāo)簽區(qū)分文檔來(lái)源避免后續(xù)重復(fù)查找。Agent Prompts 分兩種給主線程看的告訴它如何使用 AgentTool和給具體 agent 做 system prompt 用的。后者有強(qiáng)角色邊界和強(qiáng)流程編排抽象成可復(fù)用模塊大概是你是一個(gè) xxx 角色. ## 你的工作職責(zé)是 ## 強(qiáng)制邊界 ## 你可以獲取的信息 ## 執(zhí)行過(guò)程 ## 錯(cuò)誤處理 ## 工具使用指南 ## 輸出的結(jié)果是什么這里有個(gè)重要原則prompt 是給大模型看的盡量用模型友好型的自然語(yǔ)言不要用 JSON、key-value 這類編碼語(yǔ)言。4. TaoToken 前置統(tǒng)一 Key 與 API 通道的配置骨架理解了 Prompt 模塊結(jié)構(gòu)后下一步是把它接入本地環(huán)境。Claude Code 默認(rèn)走 Anthropic 官方通道但如果你需要統(tǒng)一管理多個(gè)模型的 Key、或者想讓 Claude Code 和別的工具共用一套 API 通道TaoToken 是一個(gè)可選方案。它的官網(wǎng)是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。先拿 Key。打開(kāi) https://taotoken.net/api-keys 創(chuàng)建一個(gè) API Key復(fù)制保存。注意這個(gè) Key 只在創(chuàng)建時(shí)完整顯示一次丟了就得重建。然后在 Claude Code 的配置里接入。Claude Code 支持通過(guò)環(huán)境變量或配置文件指定 API 通道。推薦用settings.json管理項(xiàng)目級(jí)配置用config.toml管理工具級(jí)配置。下面給出可復(fù)制的骨架。settings.json骨架{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-taotoken-key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [Read, Grep, Glob], deny: [Bash(rm -rf:*)] } }config.toml骨架[api] base_url https://taotoken.net/api api_key sk-your-taotoken-key timeout 60 [model] default claude-sonnet-4-20250514 max_tokens 8192 [prompt] system_prompt_file ./prompts/system.md dynamic_sections [session_guidance, memory, language]注意ANTHROPIC_BASE_URL不要帶末尾斜杠否則部分客戶端會(huì)拼出雙斜杠路徑導(dǎo)致 404。api_key建議用環(huán)境變量注入不要硬編碼進(jìn)版本庫(kù)。配置完成后可以用一個(gè)最小請(qǐng)求驗(yàn)證通道是否通。下面這段 Node 腳本直接調(diào) API 的 messages 端點(diǎn)const res await fetch(https://taotoken.net/api/v1/messages, { method: POST, headers: { Content-Type: application/json, x-api-key: process.env.ANTHROPIC_API_KEY, anthropic-version: 2023-06-01 }, body: JSON.stringify({ model: claude-sonnet-4-20250514, max_tokens: 256, system: You are a prompt module inspector., messages: [{ role: user, content: 用一句話說(shuō)明 Core System Prompt 的靜態(tài)與動(dòng)態(tài)分段區(qū)別。 }] }) }); const data await res.json(); console.log(data.content[0].text);如果返回正常文本說(shuō)明 Key 和通道都沒(méi)問(wèn)題。如果報(bào) 401檢查 Key 是否復(fù)制完整報(bào) 404檢查 base_url 是否多了斜杠。5. 驗(yàn)證請(qǐng)求一次 Prompt 模塊調(diào)用與結(jié)果解讀配置就緒后做一次完整的 Prompt 模塊調(diào)用驗(yàn)證。這里用 Claude Code 的 CLI 方式讓它讀取一個(gè)自定義 system prompt 文件并執(zhí)行任務(wù)。先準(zhǔn)備prompts/system.md你是一個(gè)源碼解析助手。 ## 你的工作職責(zé)是 - 拆解 Claude Code 的 Prompt 模塊結(jié)構(gòu) - 用表格對(duì)比各層 Prompt 的職責(zé)邊界 ## 強(qiáng)制邊界 - 不要編造源碼中不存在的函數(shù)名 - 不確定的字段標(biāo)注“待確認(rèn)” ## 輸出的結(jié)果是什么 - 必須包含層級(jí)名稱、職責(zé)、優(yōu)先級(jí)、示例片段然后運(yùn)行claude --system-prompt ./prompts/system.md \ --model claude-sonnet-4-20250514 \ 請(qǐng)解析 Core System Prompt 的優(yōu)先級(jí)策略樹(shù)輸出表格。預(yù)期結(jié)果是模型按你定義的格式輸出表格包含 Override、Coordinator、Agent、Custom、Default 五層。如果輸出格式不對(duì)說(shuō)明 system prompt 沒(méi)被正確加載檢查文件路徑和--system-prompt參數(shù)位置。再驗(yàn)證一次動(dòng)態(tài)分段。在settings.json里加上language: zh-CN重新運(yùn)行同一個(gè)任務(wù)觀察輸出語(yǔ)言是否切換。這一步能確認(rèn)dynamicSections里的language分段是否生效。實(shí)測(cè)下來(lái)動(dòng)態(tài)分段的注入順序會(huì)影響模型對(duì)指令的遵循度。session_guidance放在memory前面時(shí)模型更傾向于先遵循會(huì)話級(jí)指令反過(guò)來(lái)則更容易被 memory 內(nèi)容帶偏。這個(gè)順序在dynamicSections數(shù)組里調(diào)整即可。6. 本篇常見(jiàn)錯(cuò)排查報(bào)錯(cuò)一401 Unauthorized。最常見(jiàn)原因是 Key 沒(méi)復(fù)制完整或者ANTHROPIC_API_KEY環(huán)境變量沒(méi)生效。用echo $ANTHROPIC_API_KEY確認(rèn)。如果用的是settings.json注意 Claude Code 讀取的是env字段下的鍵不是頂層。報(bào)錯(cuò)二404 Not Found。檢查ANTHROPIC_BASE_URL是否帶了末尾斜杠。正確寫法是https://taotoken.net/api不是https://taotoken.net/api/。另外確認(rèn)請(qǐng)求路徑是/v1/messages不是/messages。報(bào)錯(cuò)三system prompt 不生效。按優(yōu)先級(jí)樹(shù)排查是不是被 agent prompt 或 coordinator prompt 覆蓋了用--system-prompt傳的 custom prompt 優(yōu)先級(jí)是 P3低于 agent 的 P2。如果當(dāng)前會(huì)話開(kāi)了 coordinator 模式你的 custom prompt 會(huì)被忽略。報(bào)錯(cuò)四動(dòng)態(tài)分段沒(méi)更新。DANGEROUS_uncachedSystemPromptSection標(biāo)記的分段不緩存但其他分段會(huì)緩存。如果你改了memory分段的內(nèi)容但沒(méi)生效可能是緩存沒(méi)失效。重啟會(huì)話或清緩存目錄。報(bào)錯(cuò)五Skill 展開(kāi)后 token 暴漲。檢查detectLanguage是否誤判了項(xiàng)目語(yǔ)言導(dǎo)致加載了不相關(guān)的 docs。比如項(xiàng)目根目錄同時(shí)有package.json和go.mod檢測(cè)順序會(huì)影響結(jié)果?？梢栽?skill 配置里顯式指定paths來(lái)約束。報(bào)錯(cuò)六config.toml里的system_prompt_file路徑找不到。相對(duì)路徑是相對(duì)于config.toml所在目錄不是當(dāng)前工作目錄。用絕對(duì)路徑最穩(wěn)。排障時(shí)如果懷疑是通道問(wèn)題可以直接用模型對(duì)話頁(yè)面發(fā)一條消息驗(yàn)證 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。如果那邊正常、本地不正常問(wèn)題就在本地配置。7. 接入文檔與長(zhǎng)期編碼方案如果你要把 Claude Code 接入自己的 CI 或團(tuán)隊(duì)工具鏈建議先通讀接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文檔里有完整的端點(diǎn)列表、參數(shù)說(shuō)明和錯(cuò)誤碼對(duì)照。對(duì)于需要長(zhǎng)期跑編碼任務(wù)或 Agent 的場(chǎng)景Coding Plan 比按量計(jì)費(fèi)更劃算也更容易做預(yù)算控制 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它適合那種每天都要跑幾十次 Claude Code 調(diào)用的開(kāi)發(fā)節(jié)奏。Key 管理入口在這里 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。建議給不同項(xiàng)目建不同的 Key方便排查和限額。最后說(shuō)一個(gè)我踩過(guò)的坑Claude Code 的 Prompt 模塊里靜態(tài)規(guī)則和動(dòng)態(tài)分段的 boundary 不是靠分隔符標(biāo)記的而是靠緩存策略隱式劃分的。你如果自己復(fù)刻這套結(jié)構(gòu)最好顯式加一個(gè)!-- STATIC_END --之類的標(biāo)記否則后期維護(hù)時(shí)很難判斷哪段該緩存、哪段該每輪更新。這個(gè)細(xì)節(jié)在源碼里沒(méi)有注釋但實(shí)際調(diào)試時(shí)非常關(guān)鍵。