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ù)刻類(lèi)似的骨架。這篇文章聚焦 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)類(lè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ì)寫(xiě)“to find interface in Go Code”這類(lèi)自然語(yǔ)言規(guī)則而不是在代碼里做硬性補(bǔ)丁。Claude Code 選擇相信大模型的語(yǔ)義理解能力把規(guī)則放在 Prompt 里而非代碼里。BashTool 的描述則復(fù)雜得多更像一份高風(fēng)險(xiǎn)工具專(zhuā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單輪文本分類(lèi) / 摘要 / 信息抽取 / 問(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 這類(lèi)編碼語(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í)名稱(chēng)、職責(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是否帶了末尾斜杠。正確寫(xiě)法是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 --之類(lèi)的標(biāo)記否則后期維護(hù)時(shí)很難判斷哪段該緩存、哪段該每輪更新。這個(gè)細(xì)節(jié)在源碼里沒(méi)有注釋但實(shí)際調(diào)試時(shí)非常關(guān)鍵。