1. 为什么你的 CLAUDE.md 写了却像没写很多人第一次接触 Claude Code 工程化都会经历一个相似的阶段兴冲冲在项目根目录建了个CLAUDE.md把团队规范、技术栈、目录结构一股脑塞进去然后发现 Claude 该犯的错还是犯该乱改的文件还是乱改。于是得出结论——这玩意儿没用。问题往往不在 Claude Code而在那份CLAUDE.md本身。它本质上是一份写给模型看的 system prompt而不是写给人类看的 README。人类看文档会脑补上下文模型不会。你写代码要规范它不知道你指的是命名规范、缩进规范还是提交信息规范你写测试要全面它不知道覆盖率阈值是 60% 还是 90%。我试过把一份 300 行的CLAUDE.md砍到 80 行只保留角色定义、硬约束、输出格式和 WHY结果 Claude 在同一个仓库里的表现反而稳定了很多。这件事让我意识到Prompt Engineering 不是过时了而是被吸收进了更大的工程框架里。在 Claude Code 里Prompt 是 Harness 的一部分Harness 是 Prompt 的运行环境。你写的每一行CLAUDE.md、每一个 SubAgent 的 system prompt、每一条 Skill 的 description都是在给这个运行环境设定边界。这篇文章聚焦三件事怎么写出真正能被模型执行的CLAUDE.md怎么用 SubAgent 做职责分工怎么用 Skill 做能力复用以及怎么把 endpoint 和auth.json切到 TaoToken 之后用同一把 Key 验证多模型调用是否真的生效。适合已经在用 Claude Code、但觉得配置能跑却跑不好的团队。2. TaoToken 前置把 endpoint 与 auth.json 接进来在动 Prompt 之前先把运行环境接好。Claude Code 默认走 Anthropic 官方 endpoint但团队协作场景下你往往需要统一入口、统一计费、统一模型切换。TaoToken 提供的就是这样一个兼容层它暴露 Anthropic 风格的 API你只需要改 Base URL 和 Key就能让 Claude Code 把请求打到 TaoToken 上。先拿到 Key。访问https://taotoken.net/api-keys创建一个项目级的 Key。建议按环境分 Key比如claude-code-dev、claude-code-ci这样出问题时能快速定位是哪个环境在刷量。拿到 Key 之后Claude Code 的配置分两块一块是 endpoint一块是认证。endpoint 通过环境变量控制认证通过auth.json控制。先看环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥注意ANTHROPIC_BASE_URL后面不要带/v1Claude Code 会自己拼路径。如果你写成https://taotoken.net/api/v1请求会变成/api/v1/v1/messages直接 404。然后是auth.json。Claude Code 在部分版本里会读取~/.claude/auth.json做认证兜底格式如下{ anthropic: { apiKey: sk-你的TaoToken密钥, baseURL: https://taotoken.net/api } }如果你用的是 Codex 风格的配置auth.json结构会略有不同但核心三件套不变Base URL、Key、Model ID。这三者必须同时正确缺一个就会出现 401 或者模型找不到。Model ID 这块要特别注意。Claude Code 默认会请求claude-sonnet-4-5这类模型名TaoToken 侧需要支持同名映射。你可以在https://taotoken.net/models确认当前可用的模型列表。如果团队想混用多个模型比如日常用 Sonnet、评审用 Opus可以在CLAUDE.md里通过 SubAgent 的model字段指定而不是全局改环境变量。配置完成后先别急着写 Prompt跑一条最小验证请求确认链路是通的。这一步很多人跳过结果后面 Prompt 调半天最后发现是 Key 没生效。3. 可复制配置CLAUDE.md、SubAgent 与 Skill 三件套这一节给可直接复制的片段。先看CLAUDE.md模板。核心原则是角色定义 硬约束 输出格式 WHY。不要写成百科要写成契约。# 项目约定 ## 角色 你是本仓库的资深后端工程师熟悉 Python 3.11、FastAPI、PostgreSQL。 你的职责是修改代码、补测试、更新文档而不是重构架构。 ## 硬约束 - 只允许修改 src/ 和 tests/ 下的文件禁止改动 migrations/ 和 infra/。 - 禁止执行 rm -rf、git push、git reset --hard。 - 修改任何函数签名前必须先搜索所有调用点并在回复中列出。 - 不确定的依赖版本先读 requirements.txt不要猜。 ## 输出格式 每次修改后按以下结构汇报 ### 变更文件 - path:line — 改了什么 — 为什么 ### 验证命令 - 具体命令 预期结果 ### 风险 - 可能受影响的模块 ## WHY - 禁止改 migrations/迁移文件已上线改动会导致生产库结构漂移。 - 禁止 git pushCI 有独立发布流程手动 push 会绕过审批。 - 要求列调用点历史上出现过改签名漏改调用导致线上 500。这份模板的关键在于 WHY 段。模型遇到规则没覆盖的情况时只有知道原因才能自己推理。没有 WHY它只能乱猜。接下来是 SubAgent。SubAgent 的价值是职责隔离一个负责写一个负责审避免自夸偏差。在.claude/agents/下建文件比如code-reviewer.md--- name: code-reviewer description: Review code changes for quality and security before commit. Use when user asks for review or before merging. tools: Read, Grep, Glob model: claude-opus-4-5 --- 你是资深 Python 代码评审员有 10 年以上金融系统后端经验。 # 硬约束 - 只读文件禁止使用 Edit 和 Write。 - Bash 仅允许git diff、git log、pytest --co、ruff check。 - 不要对未读过的代码做假设。 # 报告格式 ## Code Review: branch ### Critical (must fix before merge) - file:line — issue — suggested fix ### Warning (should fix) - file:line — issue — suggested fix ### Nit (optional) - file:line — suggestion注意model字段。评审用更强的模型生成用更快的模型这是 Producer-Reviewer 模式的典型用法。同一把 TaoToken Key 可以同时调这两个模型不需要额外配置。最后是 Skill。Skill 的description是 LLM 推理的索引键写何时触发而不是做什么。在.claude/skills/下建changelog.md--- name: changelog description: Update CHANGELOG.md from git commits. Use when user says 更新 changelog or release notes, or before creating a release tag. --- # 步骤 1. 运行 git log --oneline last-tag..HEAD 获取提交。 2. 按 feat/fix/docs 分类。 3. 追加到 CHANGELOG.md 顶部保持 Keep a Changelog 格式。 4. 不要修改历史条目。对比一下反例description: A changelog generator。Claude 看完不知道用户什么时候需要它自然不会触发。差别就在触发条件写没写清楚。4. 验证请求同一把 Key 跑通多模型调用配置写完必须验证。验证分两层一层是链路通不通一层是模型切不切得动。先验证链路。用 curl 直接打 TaoToken 的 messages 接口curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }预期返回里能看到content: [{type: text, text: OK}]。如果返回 401说明 Key 没生效如果返回 404说明 Base URL 拼错了如果返回model not found说明 Model ID 不对。链路通了之后验证多模型。把上面的model换成claude-opus-4-5再跑一次确认同一把 Key 能调不同模型。这一步很关键因为 SubAgent 里指定了model: claude-opus-4-5如果 TaoToken 侧没开这个模型SubAgent 会静默失败或者回退到默认模型你就白配了。再验证 Claude Code 本身。在项目里跑claude -p 读一下 CLAUDE.md告诉我硬约束里禁止改哪个目录预期它回答migrations/和infra/。如果它答不出来说明CLAUDE.md没被加载检查文件是不是在项目根目录、文件名大小写是否正确。最后验证 SubAgent 和 Skill 是否被识别claude -p 列出当前可用的 subagent 和 skill预期能看到code-reviewer和changelog。如果看不到检查.claude/agents/和.claude/skills/的路径以及 frontmatter 的---是否闭合。实测下来最容易出问题的是auth.json和环境变量冲突。如果两处都配了 Key 但值不一样Claude Code 的行为取决于版本可能优先读环境变量也可能优先读auth.json。建议只保留一处环境变量用于 CIauth.json用于本地。5. 本篇常见错排查401、local proxy failed 与 OAuth配置过程中会撞到几类典型报错逐个拆。401 Unauthorized。最常见的原因是 Key 没被读到。先确认echo $ANTHROPIC_API_KEY有输出再确认auth.json里的 Key 没有多余空格。如果用的是 TaoToken 的 Key注意它和 Anthropic 官方 Key 格式不同不要混用。还有一种情况是 Key 被禁用或额度耗尽去https://taotoken.net/console看用量。local proxy failed。这个报错通常出现在你本地起了代理层但代理层没起来或者端口不对。Claude Code 本身不要求本地代理如果你没主动配代理检查是不是环境里残留了HTTP_PROXY或HTTPS_PROXY。清掉这两个变量再试unset HTTP_PROXY HTTPS_PROXY ALL_PROXYreading choices 报错。这个报错说明返回体不是预期的 JSON 结构通常是 endpoint 拼错导致打到了 HTML 页面。检查ANTHROPIC_BASE_URL是不是https://taotoken.net/api末尾不要带斜杠也不要带/v1。OAuth 相关报错。Claude Code 某些版本会尝试 OAuth 登录流程如果你用的是 API Key 模式需要在配置里显式关闭 OAuth。检查~/.claude/config.json里有没有authType: oauth有的话改成apiKey。如果报错里出现invalid_grant或token expired基本就是 OAuth 残留清掉~/.claude/下的 token 缓存文件即可。SubAgent 不触发。如果 Claude 该调code-reviewer却没调先看description里有没有写触发条件。description: Review code太短模型不知道什么时候用。改成Review code changes before commit. Use when user asks for review or before merging.触发率会明显提升。Skill 重复触发。如果changelogskill 在无关场景被调用说明description写得太宽。加上明确的触发词比如Use when user says 更新 changelog而不是Use when user mentions changelog。模型回退。如果 SubAgent 指定了claude-opus-4-5但实际用的是 Sonnet去 TaoToken 控制台确认该模型是否在你的套餐里。不在的话要么升级套餐要么把 SubAgent 的model改成可用模型。6. 把 Prompt 当成工程资产来维护回到最开始的问题为什么CLAUDE.md写了像没写因为大多数人把它当成一次性文档而不是工程资产。工程资产的特点是有版本、有评审、有测试、有回滚。具体做法上我建议把CLAUDE.md、.claude/agents/、.claude/skills/全部纳入 Git 管理改动走 PR。每次改完跑一遍验证请求确认硬约束仍然生效。团队里指定一个人负责 Prompt 的维护避免同一信息在三处重复改一处忘一处。判断一条 Prompt 写得好不好用四个维度自测清晰度模型看完知道下一步做什么吗具体度模型知道用什么工具、什么参数吗边界度模型知道什么不能做吗可验证度你能检查模型是否遵守了吗。四个都过才算合格。最后提醒一点Prompt 是地基不是全部。地基之上还有 Context Engineering 和 Harness Engineering。但地基不牢楼盖不高。当你发现 Claude Code不听话的时候先别急着换模型回头看看你的 Prompt 能不能过得了那四个维度的自测。 
长河君 · 2026/10/12 19:54:54 · 阅读 1.2k Claude Code工程化实践加课4：Prompt Engineering 底层内功与 CLAUDE.md 配置到 TaoToken
1. 为什么你的 CLAUDE.md 写了却像没写很多人第一次接触 Claude Code 工程化都会经历一个相似的阶段兴冲冲在项目根目录建了个CLAUDE.md把团队规范、技术栈、目录结构一股脑塞进去然后发现 Claude 该犯的错还是犯该乱改的文件还是乱改。于是得出结论——这玩意儿没用。问题往往不在 Claude Code而在那份CLAUDE.md本身。它本质上是一份写给模型看的 system prompt而不是写给人类看的 README。人类看文档会脑补上下文模型不会。你写代码要规范它不知道你指的是命名规范、缩进规范还是提交信息规范你写测试要全面它不知道覆盖率阈值是 60% 还是 90%。我试过把一份 300 行的CLAUDE.md砍到 80 行只保留角色定义、硬约束、输出格式和 WHY结果 Claude 在同一个仓库里的表现反而稳定了很多。这件事让我意识到Prompt Engineering 不是过时了而是被吸收进了更大的工程框架里。在 Claude Code 里Prompt 是 Harness 的一部分Harness 是 Prompt 的运行环境。你写的每一行CLAUDE.md、每一个 SubAgent 的 system prompt、每一条 Skill 的 description都是在给这个运行环境设定边界。这篇文章聚焦三件事怎么写出真正能被模型执行的CLAUDE.md怎么用 SubAgent 做职责分工怎么用 Skill 做能力复用以及怎么把 endpoint 和auth.json切到 TaoToken 之后用同一把 Key 验证多模型调用是否真的生效。适合已经在用 Claude Code、但觉得配置能跑却跑不好的团队。2. TaoToken 前置把 endpoint 与 auth.json 接进来在动 Prompt 之前先把运行环境接好。Claude Code 默认走 Anthropic 官方 endpoint但团队协作场景下你往往需要统一入口、统一计费、统一模型切换。TaoToken 提供的就是这样一个兼容层它暴露 Anthropic 风格的 API你只需要改 Base URL 和 Key就能让 Claude Code 把请求打到 TaoToken 上。先拿到 Key。访问https://taotoken.net/api-keys创建一个项目级的 Key。建议按环境分 Key比如claude-code-dev、claude-code-ci这样出问题时能快速定位是哪个环境在刷量。拿到 Key 之后Claude Code 的配置分两块一块是 endpoint一块是认证。endpoint 通过环境变量控制认证通过auth.json控制。先看环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥注意ANTHROPIC_BASE_URL后面不要带/v1Claude Code 会自己拼路径。如果你写成https://taotoken.net/api/v1请求会变成/api/v1/v1/messages直接 404。然后是auth.json。Claude Code 在部分版本里会读取~/.claude/auth.json做认证兜底格式如下{ anthropic: { apiKey: sk-你的TaoToken密钥, baseURL: https://taotoken.net/api } }如果你用的是 Codex 风格的配置auth.json结构会略有不同但核心三件套不变Base URL、Key、Model ID。这三者必须同时正确缺一个就会出现 401 或者模型找不到。Model ID 这块要特别注意。Claude Code 默认会请求claude-sonnet-4-5这类模型名TaoToken 侧需要支持同名映射。你可以在https://taotoken.net/models确认当前可用的模型列表。如果团队想混用多个模型比如日常用 Sonnet、评审用 Opus可以在CLAUDE.md里通过 SubAgent 的model字段指定而不是全局改环境变量。配置完成后先别急着写 Prompt跑一条最小验证请求确认链路是通的。这一步很多人跳过结果后面 Prompt 调半天最后发现是 Key 没生效。3. 可复制配置CLAUDE.md、SubAgent 与 Skill 三件套这一节给可直接复制的片段。先看CLAUDE.md模板。核心原则是角色定义 硬约束 输出格式 WHY。不要写成百科要写成契约。# 项目约定 ## 角色 你是本仓库的资深后端工程师熟悉 Python 3.11、FastAPI、PostgreSQL。 你的职责是修改代码、补测试、更新文档而不是重构架构。 ## 硬约束 - 只允许修改 src/ 和 tests/ 下的文件禁止改动 migrations/ 和 infra/。 - 禁止执行 rm -rf、git push、git reset --hard。 - 修改任何函数签名前必须先搜索所有调用点并在回复中列出。 - 不确定的依赖版本先读 requirements.txt不要猜。 ## 输出格式 每次修改后按以下结构汇报 ### 变更文件 - path:line — 改了什么 — 为什么 ### 验证命令 - 具体命令 预期结果 ### 风险 - 可能受影响的模块 ## WHY - 禁止改 migrations/迁移文件已上线改动会导致生产库结构漂移。 - 禁止 git pushCI 有独立发布流程手动 push 会绕过审批。 - 要求列调用点历史上出现过改签名漏改调用导致线上 500。这份模板的关键在于 WHY 段。模型遇到规则没覆盖的情况时只有知道原因才能自己推理。没有 WHY它只能乱猜。接下来是 SubAgent。SubAgent 的价值是职责隔离一个负责写一个负责审避免自夸偏差。在.claude/agents/下建文件比如code-reviewer.md--- name: code-reviewer description: Review code changes for quality and security before commit. Use when user asks for review or before merging. tools: Read, Grep, Glob model: claude-opus-4-5 --- 你是资深 Python 代码评审员有 10 年以上金融系统后端经验。 # 硬约束 - 只读文件禁止使用 Edit 和 Write。 - Bash 仅允许git diff、git log、pytest --co、ruff check。 - 不要对未读过的代码做假设。 # 报告格式 ## Code Review: branch ### Critical (must fix before merge) - file:line — issue — suggested fix ### Warning (should fix) - file:line — issue — suggested fix ### Nit (optional) - file:line — suggestion注意model字段。评审用更强的模型生成用更快的模型这是 Producer-Reviewer 模式的典型用法。同一把 TaoToken Key 可以同时调这两个模型不需要额外配置。最后是 Skill。Skill 的description是 LLM 推理的索引键写何时触发而不是做什么。在.claude/skills/下建changelog.md--- name: changelog description: Update CHANGELOG.md from git commits. Use when user says 更新 changelog or release notes, or before creating a release tag. --- # 步骤 1. 运行 git log --oneline last-tag..HEAD 获取提交。 2. 按 feat/fix/docs 分类。 3. 追加到 CHANGELOG.md 顶部保持 Keep a Changelog 格式。 4. 不要修改历史条目。对比一下反例description: A changelog generator。Claude 看完不知道用户什么时候需要它自然不会触发。差别就在触发条件写没写清楚。4. 验证请求同一把 Key 跑通多模型调用配置写完必须验证。验证分两层一层是链路通不通一层是模型切不切得动。先验证链路。用 curl 直接打 TaoToken 的 messages 接口curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }预期返回里能看到content: [{type: text, text: OK}]。如果返回 401说明 Key 没生效如果返回 404说明 Base URL 拼错了如果返回model not found说明 Model ID 不对。链路通了之后验证多模型。把上面的model换成claude-opus-4-5再跑一次确认同一把 Key 能调不同模型。这一步很关键因为 SubAgent 里指定了model: claude-opus-4-5如果 TaoToken 侧没开这个模型SubAgent 会静默失败或者回退到默认模型你就白配了。再验证 Claude Code 本身。在项目里跑claude -p 读一下 CLAUDE.md告诉我硬约束里禁止改哪个目录预期它回答migrations/和infra/。如果它答不出来说明CLAUDE.md没被加载检查文件是不是在项目根目录、文件名大小写是否正确。最后验证 SubAgent 和 Skill 是否被识别claude -p 列出当前可用的 subagent 和 skill预期能看到code-reviewer和changelog。如果看不到检查.claude/agents/和.claude/skills/的路径以及 frontmatter 的---是否闭合。实测下来最容易出问题的是auth.json和环境变量冲突。如果两处都配了 Key 但值不一样Claude Code 的行为取决于版本可能优先读环境变量也可能优先读auth.json。建议只保留一处环境变量用于 CIauth.json用于本地。5. 本篇常见错排查401、local proxy failed 与 OAuth配置过程中会撞到几类典型报错逐个拆。401 Unauthorized。最常见的原因是 Key 没被读到。先确认echo $ANTHROPIC_API_KEY有输出再确认auth.json里的 Key 没有多余空格。如果用的是 TaoToken 的 Key注意它和 Anthropic 官方 Key 格式不同不要混用。还有一种情况是 Key 被禁用或额度耗尽去https://taotoken.net/console看用量。local proxy failed。这个报错通常出现在你本地起了代理层但代理层没起来或者端口不对。Claude Code 本身不要求本地代理如果你没主动配代理检查是不是环境里残留了HTTP_PROXY或HTTPS_PROXY。清掉这两个变量再试unset HTTP_PROXY HTTPS_PROXY ALL_PROXYreading choices 报错。这个报错说明返回体不是预期的 JSON 结构通常是 endpoint 拼错导致打到了 HTML 页面。检查ANTHROPIC_BASE_URL是不是https://taotoken.net/api末尾不要带斜杠也不要带/v1。OAuth 相关报错。Claude Code 某些版本会尝试 OAuth 登录流程如果你用的是 API Key 模式需要在配置里显式关闭 OAuth。检查~/.claude/config.json里有没有authType: oauth有的话改成apiKey。如果报错里出现invalid_grant或token expired基本就是 OAuth 残留清掉~/.claude/下的 token 缓存文件即可。SubAgent 不触发。如果 Claude 该调code-reviewer却没调先看description里有没有写触发条件。description: Review code太短模型不知道什么时候用。改成Review code changes before commit. Use when user asks for review or before merging.触发率会明显提升。Skill 重复触发。如果changelogskill 在无关场景被调用说明description写得太宽。加上明确的触发词比如Use when user says 更新 changelog而不是Use when user mentions changelog。模型回退。如果 SubAgent 指定了claude-opus-4-5但实际用的是 Sonnet去 TaoToken 控制台确认该模型是否在你的套餐里。不在的话要么升级套餐要么把 SubAgent 的model改成可用模型。6. 把 Prompt 当成工程资产来维护回到最开始的问题为什么CLAUDE.md写了像没写因为大多数人把它当成一次性文档而不是工程资产。工程资产的特点是有版本、有评审、有测试、有回滚。具体做法上我建议把CLAUDE.md、.claude/agents/、.claude/skills/全部纳入 Git 管理改动走 PR。每次改完跑一遍验证请求确认硬约束仍然生效。团队里指定一个人负责 Prompt 的维护避免同一信息在三处重复改一处忘一处。判断一条 Prompt 写得好不好用四个维度自测清晰度模型看完知道下一步做什么吗具体度模型知道用什么工具、什么参数吗边界度模型知道什么不能做吗可验证度你能检查模型是否遵守了吗。四个都过才算合格。最后提醒一点Prompt 是地基不是全部。地基之上还有 Context Engineering 和 Harness Engineering。但地基不牢楼盖不高。当你发现 Claude Code不听话的时候先别急着换模型回头看看你的 Prompt 能不能过得了那四个维度的自测。