Anthropic 官方 Claude System Prompt 工程指南：从 CLAUDE.md 到 settings.json 的落地配置

1. 为什么你的 CLAUDE.md 写了却像没写很多人第一次接触 Anthropic 官方 System Prompt 工程指南都会有一种道理我都懂但落到项目里就散架的感觉。官方文档讲的是原则XML 结构化、显式约束、少样本示例、扩展思考、上下文位置策略。可当你打开自己的项目面对的是一个真实的 Claude Code 会话、一个.claude/settings.json、一个根目录的CLAUDE.md问题就变成了这些原则到底写在哪一行、哪个字段、哪个标签里我见过最常见的三种翻车现场。第一种是CLAUDE.md写成了一篇散文开头是本项目致力于打造业界领先的……Claude 读完根本不知道你要它遵守什么。第二种是settings.json里塞了一堆权限白名单但模型 ID 写错、Base URL 没配请求直接 401。第三种最隐蔽提示词写对了但关键约束埋在文件中间Claude 在长上下文里把它忘了——这不是玄学是官方明确讲过的位置偏见。这篇内容聚焦一件事把 Anthropic 官方 System Prompt 工程指南翻译成 Claude 工具链里可以直接复制、可以维护、可以验证的工程配置。核心载体是两个文件——CLAUDE.md负责组织系统提示词.claude/settings.json负责骨架配置。我会给出完整模板、可复制的 JSON 片段、验证提示词是否真的生效的检查动作以及几个真实报错的排查路径。适合谁看正在用 Claude Code 做团队协作的工程师、需要把提示词从个人技巧变成团队资产的技术负责人、以及被settings.json配置卡住过的人。读完你应该能做到新建一个项目十分钟内搭出一套可用的提示词工程配置并且知道怎么确认它生效了。先说一个反直觉的结论官方指南里影响力最大的技巧不是写得长而是分得清。XML 标签之所以被官方标为五星是因为它给 Claude 提供了明确的语义边界。你的CLAUDE.md如果只是把信息堆在一起Claude 就得自己猜哪段是背景、哪段是规则、哪段是禁止项。猜错的概率比你想象的高。2. TaoToken 前置把 Claude 工具链接进统一入口在动手写配置之前得先把请求往哪发这件事定下来。Claude Code、Cline、Codex 这类工具都支持自定义 Base URL 和 API Key这意味着你可以把它们统一接到一个兼容 Anthropic 协议的入口上而不是每个工具单独维护一套凭证。我这边用的是 TaoToken 作为统一入口。它的 API 地址是https://taotoken.net/api兼容 Anthropic 的 Messages 接口格式所以 Claude Code 这类原生走 Anthropic 协议的工具可以直接对接。官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册和拿 Key 都在控制台完成。具体要准备三样东西这三样在后面的配置里会反复出现我把它叫三件套第一是 Base URL。Claude Code 走 Anthropic 协议时填https://taotoken.net/api。注意不要带多余的路径后缀工具会自己拼接/v1/messages。第二是 API Key。在控制台的 API Keys 页面创建格式通常是一串以特定前缀开头的字符串。这个 Key 只显示一次创建后立刻复制保存。如果你用的是 Claude Code它会读环境变量ANTHROPIC_API_KEY如果用settings.json可以写在env字段里。第三是 Model ID。这是最容易出错的地方。Anthropic 的模型 ID 有固定格式比如claude-sonnet-4-20250514这种带日期后缀的写法。你不能随便写claude-4或者sonnet工具会直接报模型不存在。具体有哪些可用模型在控制台的模型列表里能看到复制准确的 ID。拿 Key 的入口在这里API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite里面有各工具的对接说明。这里要提醒一句不要把 Key 硬编码进CLAUDE.md或者提交到 Git。CLAUDE.md是会被 Claude 读取的上下文文件写进去等于把凭证暴露给每一次会话。正确做法是放在settings.json的env字段或者用系统环境变量并且把settings.json加进.gitignore如果是本地个人配置。准备好这三件套之后就可以进入配置环节了。下面先给CLAUDE.md的模板再给settings.json的骨架最后讲怎么验证。3. 可复制配置CLAUDE.md 模板与 settings.json 骨架这一节是全文的核心给的都是可以直接复制粘贴的东西。我按官方十组件框架的思路来组织CLAUDE.md但做了工程化裁剪——不是每个项目都需要十个标签但角色、上下文、指令、约束、输出格式这五个是底线。先看CLAUDE.md模板。放在项目根目录Claude Code 进入目录时会自动读取# CLAUDE.md - 项目名称 role_and_persona 你是一个资深后端工程师专注于 Python FastAPI 服务开发。 工作风格先理解现有代码再动手小步提交改动前说明方案。 专长范围API 设计、数据库建模、异步任务、性能优化。 /role_and_persona context 这是一个面向企业内部的数据同步服务负责在多个业务系统之间 同步用户和订单数据。日均处理量约 50 万条记录。 当前阶段从单体向微服务拆分。 /context instructions 1. 修改代码前先阅读相关文件理解现有实现 2. 新增 API 端点必须包含类型注解和 Pydantic 模型 3. 数据库操作必须使用参数化查询 4. 提交前运行 make test 和 make lint /instructions constraints - 禁止使用任何未在 requirements.txt 中声明的第三方库 - 禁止在代码中硬编码密钥、连接串、Token - 禁止直接执行用户输入的字符串作为代码 - 涉及数据删除的操作必须先向用户确认 /constraints output_format 代码修改类任务按以下结构回复 【理解】简述你对现有代码的理解 【方案】说明修改思路 【改动】列出修改的文件和关键变更 【验证】说明如何验证改动正确 /output_format common_commands | 命令 | 用途 | |------|------| | make test | 运行单元测试 | | make lint | 运行 ruff mypy | | make migrate | 执行数据库迁移 | /common_commands这个模板的关键点在于每个标签只放一类信息。constraints里全是禁止项instructions里全是动作项不混。官方指南里反复强调的显式约束落地就是这个constraints块——把不要做什么写清楚而不是指望 Claude 猜。再看.claude/settings.json。这个文件放在项目根目录的.claude/目录下负责工具链的骨架配置{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Bash(make test:*), Bash(make lint:*), Read, Write, Edit ], deny: [ Bash(rm -rf:*), Bash(git push --force:*) ] } }这里的三件套对应关系是ANTHROPIC_BASE_URL填https://taotoken.net/apiANTHROPIC_API_KEY填你创建的 KeyANTHROPIC_MODEL填准确的 Model ID。permissions块是 Claude Code 的权限控制allow里放允许自动执行的操作deny里放明确禁止的。把rm -rf和git push --force放进deny是防止 Agent 在自主循环里做出不可逆操作。如果你用的是 Cline 或者带 MCP 的客户端配置思路一样只是字段名不同。Cline 的 MCP 配置通常在cline_mcp_settings.json里Base URL、Key、Model ID 三件套一个都不能少。Codex 的话看auth.json结构类似。有个细节要注意settings.json里的env字段会覆盖系统环境变量。如果你在多个项目间切换每个项目的settings.json可以指向不同的 Model ID比如简单任务用 Haiku复杂推理用 Sonnet。这就是官方按任务选模型原则的工程化落地。配置写完之后别急着跑。先确认文件位置对不对CLAUDE.md在项目根目录settings.json在.claude/子目录。位置错了Claude 读不到等于白写。4. 验证请求确认提示词真的生效了配置写完不等于生效。这一节讲怎么验证分三层验证连接通不通、验证提示词被读取了、验证约束真的起作用了。第一层验证连接。最直接的方式是发一个最小请求。如果你装了 Claude Code CLI在项目目录下执行claude -p 回复 OK 两个字母不要有其他内容如果配置正确你会看到OK。如果报 401说明 Key 有问题如果报local proxy failed或者连接超时说明 Base URL 不对如果报模型不存在说明 Model ID 写错了。这三个报错后面会单独讲。第二层验证CLAUDE.md被读取。这个稍微绕一点因为 Claude 不会主动告诉你我读了 CLAUDE.md。技巧是在CLAUDE.md里放一个独特的、不可能被猜到的标记然后问 Claude 这个标记是什么。比如在context里加一句本项目的内部代号是 PROJECT_PHOENIX_2026。然后执行claude -p 本项目的内部代号是什么只回答代号本身如果返回PROJECT_PHOENIX_2026说明CLAUDE.md确实被加载进了上下文。如果 Claude 说我不知道或者开始编说明文件没被读到检查路径和文件名大小写。第三层验证约束生效。这是最关键的一层。挑一条constraints里的禁止项构造一个会触发它的请求看 Claude 是否拒绝。比如约束里写了禁止使用未声明的第三方库你可以问claude -p 帮我写一个用 requests 库发 HTTP 请求的函数如果requests不在你的requirements.txt里正确的行为是 Claude 提醒你这违反了项目约束或者改用标准库urllib。如果它直接给你import requests的代码说明约束没生效——要么CLAUDE.md没被读要么约束写得太模糊。再验证一条输出格式约束。output_format里定义了代码修改类任务的四段式回复你可以让它改一个小文件看回复结构是不是【理解】【方案】【改动】【验证】。如果它直接甩代码说明格式约束没被遵守。这三层验证做完你基本能确定配置是活的。我建议把这三个验证动作写进项目的Makefile或者 CI 脚本里每次改完CLAUDE.md跑一遍防止改坏了不知道。还有一个进阶验证用claude --debug或者类似参数看请求日志确认system字段里确实带了你的提示词。不同工具的参数名不一样Claude Code 可以用--verbose看详细输出。这一步能帮你区分提示词没发出去和发出去了但模型没遵守。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中会撞到几个高频报错这一节逐个拆。每个报错我都给出触发场景、根因和修复动作。401 Unauthorized。这是最常见的。触发场景请求发出去了但服务端拒绝。根因通常是三个之一Key 写错、Key 过期、Key 没带上。检查顺序先确认settings.json里ANTHROPIC_API_KEY的值是不是完整复制了有没有多余空格再去控制台确认这个 Key 还在有效期内最后确认环境变量有没有被覆盖——有时候系统里有个旧的ANTHROPIC_API_KEY优先级比settings.json高。修复动作重新创建一个 Key直接粘贴不要手打。local proxy failed。这个报错通常出现在 Claude Code 启动阶段。根因是工具尝试连接 Base URL 但连不上。检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/多了斜杠或者https://taotoken.net少了/api。正确的写法是https://taotoken.net/api不带尾部斜杠。另外确认你的网络能正常访问这个地址可以用curl -I https://taotoken.net/api测一下连通性。Error reading choices / reading choices 相关报错。这个报错说明请求发出去了但返回的响应格式不符合工具预期。常见于 Base URL 指向了一个不兼容 Anthropic 协议的端点。修复动作确认你用的是 Anthropic 兼容入口而不是 OpenAI 格式的入口。TaoToken 的https://taotoken.net/api是 Anthropic 兼容的如果你误填了其他路径就会出这个错。另外检查 Model ID 是否是 Anthropic 格式OpenAI 格式的模型名会触发解析失败。OAuth 相关报错。Claude Code 某些版本会走 OAuth 流程如果你用的是 API Key 模式可能会看到 OAuth token 相关的错误。根因是工具在两种认证模式之间混淆了。修复动作确认settings.json里没有残留的 OAuth 配置字段比如oauth_token之类。如果工具支持--api-key参数显式指定走 Key 模式。有些版本需要设置ANTHROPIC_AUTH_MODEapi_key来强制走 Key。除了这四个还有一个隐蔽的坑CLAUDE.md里的 XML 标签没闭合。比如你写了constraints但忘了/constraintsClaude 会把后面的所有内容都当成约束的一部分导致指令和格式定义全部失效。这个不会报错但行为会很怪。检查方法用编辑器的标签匹配功能过一遍或者写个简单的脚本统计开闭标签数量。再补一个settings.json的 JSON 语法错误。多一个逗号、少一个引号工具启动时可能不报错但配置静默失效。用python -m json.tool .claude/settings.json验证一下语法能省很多排查时间。6. 把官方实践变成团队资产写到这里配置、验证、排障都覆盖了。最后说一个工程化的点怎么让这套东西在团队里可维护。CLAUDE.md和settings.json应该进版本控制但 Key 不能进。做法是把settings.json拆成两份一份settings.json提交到仓库只放 Base URL、Model ID、权限配置另一份settings.local.json放 Key加进.gitignore。Claude Code 会合并这两份配置本地文件优先级更高。提示词的迭代也要有记录。每次改CLAUDE.md在 commit message 里写清楚改了什么、为什么改、验证结果如何。这样当某个约束突然不生效时你能快速定位是哪次改动引入的。如果你需要长期跑 Agent 类任务比如让 Claude 自主完成多步重构可以考虑用 Coding Plan 这类按量方案避免单次会话的额度限制影响长任务。入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite。验证模型行为、对比不同 Model ID 的输出差异可以用模型对话页面快速试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite。回到最开始那个问题为什么你的CLAUDE.md写了却像没写大概率不是 Claude 不听话而是信息没有分清楚、约束没有写明白、验证没有做到位。官方指南给的是原则工程落地靠的是把原则拆进具体的文件和字段里。你现在可以打开自己的项目按第 3 节的模板改一版然后用第 4 节的三个验证动作跑一遍。跑通了这套配置就是你的了。