1. 从一次 Prompt 调试说起Claude Code 的提示词模块到底长什么样如果你正在用 Claude Code 做本地开发大概率遇到过这种情况同一个任务换个说法效果天差地别或者你想改改它的行为风格却不知道从哪下手。这背后的核心就是 Claude Code 的 Prompt 提示词模块。它不是一个简单的字符串而是一套分层拼装、带优先级覆盖、支持动态注入的工程化结构。理解这套结构你才能知道为什么 Claude Code 在复杂任务里比裸调 API 稳得多也才能在自己的项目里复刻类似的骨架。这篇文章聚焦 Claude Code 源码中 Prompt 模块的图解拆解同时结合 TaoToken 的统一 Key/API 通道给出settings.json与config.toml的可复制配置骨架并演示一次 Prompt 模块调用验证动作。适合已经上手 Claude Code、想深入理解提示词工程结构的开发者也适合想把 Claude Code 接入自己工具链、需要统一管理 API 通道的同学。全文按“结构拆解 → 接入配置 → 验证请求 → 排障”的顺序展开每一步都能跟着做。Claude Code 的 Prompt 模块大致分成六块Core System Prompt、Tool Prompts、Skill Prompts、Agent Prompts、Context Management Prompts、Memory Prompts。它们不是平铺的而是有明确的边界和优先级。下面逐层拆。2. Core System Prompt静态规则与动态分段的拼装逻辑Core System Prompt 是整个提示词体系的地基。它由两部分组成静态规则和动态分段dynamicSections。静态规则会被缓存动态分段每轮可能更新两者之间有一个 boundary 做划分。这种设计的好处是不变的部分不重复计算变的部分按需注入。静态规则最简形态类似这样if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) { return [ You are Claude Code, Anthropics official CLI for Claude.\n\nCWD: ${getCwd()}\nDate: ${getSessionStartDate()}, ] }动态分段则是一个数组每项通过systemPromptSection注册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这个命名它明确标记了“这个分段不缓存”因为 MCP 连接状态会在轮次间变化。这种显式标记比隐式约定更不容易踩坑。拼接时还有一个优先级策略树buildEffectiveSystemPrompt保证多模式、多角色、多来源 prompt 共存时覆盖关系清晰。优先级从高到低优先级来源行为P0Override SystemPrompt硬覆盖替换其他所有P1Coordinator Promptcoordinator 模式下替换默认P2Agent Prompt主线程为 agent 时替换默认proactive 模式下追加P3Custom System Prompt用户传--system-prompt时使用P4Default System Prompt最终兜底这个优先级树是理解 Claude Code 行为的关键。你如果发现自己的--system-prompt没生效先检查是不是被更高优先级的 agent 或 coordinator 覆盖了。3. Tool / Skill / Agent Prompts行为协议与渐进式加载Tool Prompts 的特点是“行为协议”这个工具是什么、什么时候用、什么时候不用、参数约束是什么。以 GrepTool 为例它的描述里会写“to find interface in Go Code”这类自然语言规则而不是在代码里做硬性补丁。Claude Code 选择相信大模型的语义理解能力把规则放在 Prompt 里而非代码里。BashTool 的描述则复杂得多更像一份高风险工具专用操作规程定义了 git 提交 PR 的详细流程、什么不能做、哪些步骤用 skill 替代。这种复杂度已经接近一个初版 Skill也解释了后来 Skill 机制出现的动机。Skill Prompts 解决的是 token 浪费问题。如果全用 MCP上下文窗口里会塞满 tool 定义和参数但模型每轮只选部分执行。Skill 采用渐进式加载先把 skill 作为 prompt 资产注册再由 SkillTool 在运行时展开成新的上下文消息。一个 skill 包含这些核心字段name: Claude API description: 这个技能用于帮助你使用 Claude API、Anthropic SDK 或 Agent SDK 构建应用... allowed-tools: - Read - WebFetch model: ... hooks: ... paths: ...prompt 生成规则是先找到## Reading Guide把 SKILL_PROMPT 分成两段前半段 basePrompt 保留中间的 reading guide 用运行时生成版替换。reading guide 本质是一个索引文件告诉模型遇到不同任务该读哪些 docs单轮文本分类 / 摘要 / 信息抽取 / 问答 → 看{lang}/claude-api/README.md聊天 UI 或实时流式响应展示 → 看{lang}/claude-api/README.md{lang}/claude-api/streaming.md长对话可能超过上下文窗口 → 看 README 中的 Compaction 部分lang由detectLanguage函数判断pyproject.toml/requirements.txt→ Pythonpackage.json/tsconfig.json→ TypeScriptgo.mod→ Gopom.xml→ Java。检测不出来就直接问用户。拼接时用doc path...标签区分文档来源避免后续重复查找。Agent Prompts 分两种给主线程看的告诉它如何使用 AgentTool和给具体 agent 做 system prompt 用的。后者有强角色边界和强流程编排抽象成可复用模块大概是你是一个 xxx 角色. ## 你的工作职责是 ## 强制边界 ## 你可以获取的信息 ## 执行过程 ## 错误处理 ## 工具使用指南 ## 输出的结果是什么这里有个重要原则prompt 是给大模型看的尽量用模型友好型的自然语言不要用 JSON、key-value 这类编码语言。4. TaoToken 前置统一 Key 与 API 通道的配置骨架理解了 Prompt 模块结构后下一步是把它接入本地环境。Claude Code 默认走 Anthropic 官方通道但如果你需要统一管理多个模型的 Key、或者想让 Claude Code 和别的工具共用一套 API 通道TaoToken 是一个可选方案。它的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。先拿 Key。打开 https://taotoken.net/api-keys 创建一个 API Key复制保存。注意这个 Key 只在创建时完整显示一次丢了就得重建。然后在 Claude Code 的配置里接入。Claude Code 支持通过环境变量或配置文件指定 API 通道。推荐用settings.json管理项目级配置用config.toml管理工具级配置。下面给出可复制的骨架。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不要带末尾斜杠否则部分客户端会拼出双斜杠路径导致 404。api_key建议用环境变量注入不要硬编码进版本库。配置完成后可以用一个最小请求验证通道是否通。下面这段 Node 脚本直接调 API 的 messages 端点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: 用一句话说明 Core System Prompt 的静态与动态分段区别。 }] }) }); const data await res.json(); console.log(data.content[0].text);如果返回正常文本说明 Key 和通道都没问题。如果报 401检查 Key 是否复制完整报 404检查 base_url 是否多了斜杠。5. 验证请求一次 Prompt 模块调用与结果解读配置就绪后做一次完整的 Prompt 模块调用验证。这里用 Claude Code 的 CLI 方式让它读取一个自定义 system prompt 文件并执行任务。先准备prompts/system.md你是一个源码解析助手。 ## 你的工作职责是 - 拆解 Claude Code 的 Prompt 模块结构 - 用表格对比各层 Prompt 的职责边界 ## 强制边界 - 不要编造源码中不存在的函数名 - 不确定的字段标注“待确认” ## 输出的结果是什么 - 必须包含层级名称、职责、优先级、示例片段然后运行claude --system-prompt ./prompts/system.md \ --model claude-sonnet-4-20250514 \ 请解析 Core System Prompt 的优先级策略树输出表格。预期结果是模型按你定义的格式输出表格包含 Override、Coordinator、Agent、Custom、Default 五层。如果输出格式不对说明 system prompt 没被正确加载检查文件路径和--system-prompt参数位置。再验证一次动态分段。在settings.json里加上language: zh-CN重新运行同一个任务观察输出语言是否切换。这一步能确认dynamicSections里的language分段是否生效。实测下来动态分段的注入顺序会影响模型对指令的遵循度。session_guidance放在memory前面时模型更倾向于先遵循会话级指令反过来则更容易被 memory 内容带偏。这个顺序在dynamicSections数组里调整即可。6. 本篇常见错排查报错一401 Unauthorized。最常见原因是 Key 没复制完整或者ANTHROPIC_API_KEY环境变量没生效。用echo $ANTHROPIC_API_KEY确认。如果用的是settings.json注意 Claude Code 读取的是env字段下的键不是顶层。报错二404 Not Found。检查ANTHROPIC_BASE_URL是否带了末尾斜杠。正确写法是https://taotoken.net/api不是https://taotoken.net/api/。另外确认请求路径是/v1/messages不是/messages。报错三system prompt 不生效。按优先级树排查是不是被 agent prompt 或 coordinator prompt 覆盖了用--system-prompt传的 custom prompt 优先级是 P3低于 agent 的 P2。如果当前会话开了 coordinator 模式你的 custom prompt 会被忽略。报错四动态分段没更新。DANGEROUS_uncachedSystemPromptSection标记的分段不缓存但其他分段会缓存。如果你改了memory分段的内容但没生效可能是缓存没失效。重启会话或清缓存目录。报错五Skill 展开后 token 暴涨。检查detectLanguage是否误判了项目语言导致加载了不相关的 docs。比如项目根目录同时有package.json和go.mod检测顺序会影响结果。可以在 skill 配置里显式指定paths来约束。报错六config.toml里的system_prompt_file路径找不到。相对路径是相对于config.toml所在目录不是当前工作目录。用绝对路径最稳。排障时如果怀疑是通道问题可以直接用模型对话页面发一条消息验证 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。如果那边正常、本地不正常问题就在本地配置。7. 接入文档与长期编码方案如果你要把 Claude Code 接入自己的 CI 或团队工具链建议先通读接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里有完整的端点列表、参数说明和错误码对照。对于需要长期跑编码任务或 Agent 的场景Coding Plan 比按量计费更划算也更容易做预算控制 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它适合那种每天都要跑几十次 Claude Code 调用的开发节奏。Key 管理入口在这里 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。建议给不同项目建不同的 Key方便排查和限额。最后说一个我踩过的坑Claude Code 的 Prompt 模块里静态规则和动态分段的 boundary 不是靠分隔符标记的而是靠缓存策略隐式划分的。你如果自己复刻这套结构最好显式加一个!-- STATIC_END --之类的标记否则后期维护时很难判断哪段该缓存、哪段该每轮更新。这个细节在源码里没有注释但实际调试时非常关键。