1. 为什么你的 Claude Code 提示词总是「用完即弃」很多人用 Claude Code 的方式是在对话框里临时敲一段要求帮我写个函数、帮我改个 bug、帮我加个测试。单次任务确实能跑通但过两天换个项目、换台机器之前那套「先规划、再写测试、最后审查」的流程就全丢了。团队里每个人各写各的提示词代码风格、提交规范、安全底线全靠口头约定新人进来只能靠翻聊天记录猜。Claude Code 的 Rules 体系就是来解决这个问题的。它把零散提示词沉淀成仓库里可版本管理的文件~/.claude/rules/放规则~/.claude/agents/放子代理~/.claude/settings.json放 hooks 触发点。规则是「知识」agents 是「分工」hooks 是「自动化执行」。三者组合起来才是一套可复用的团队规范而不是一段随时会丢的 prompt。这套配置适合谁适合已经把 Claude Code 当日常开发工具、想让团队协作有一致标准的开发者也适合个人开发者想把自己的编码习惯固化下来避免每次开新会话都要重新交代一遍。下面我按「目录结构 → agents 分工 → hooks 触发 → 规则生效验证 → 排错」的顺序给一套可以直接复制的配置案例。核心检索词就是 Claude Code Rules 配置全文围绕 agents 与 hooks 怎么落地展开。需要说明的是Claude Code 本身通过 Anthropic 官方接口调用国内直连有时不稳定。我实测下来用兼容 Anthropic 协议的接入方式会更省心后面第二节会给出具体配置把 Base URL 指向兼容端点即可规则文件本身不受影响。2. TaoToken 前置把 Claude Code 的请求端点配好在写 Rules 之前得先保证 Claude Code 能稳定发出请求。Claude Code 读取的是 Anthropic 风格的接口所以我们要配置的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个环境变量。TaoToken 提供了兼容 Anthropic 协议的端点把 Base URL 指过去Key 换成自己的令牌即可。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个令牌复制出来。注意这个 Key 只在创建时完整显示一次丢了就得重建。拿到之后不要写死在代码里放到 shell 的环境变量或者 Claude Code 的 settings 里。配置方式有两种。第一种是写进 shell 配置文件适合全局生效# 写入 ~/.zshrc 或 ~/.bashrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的令牌改完执行source ~/.zshrc让它生效。第二种是写进 Claude Code 的 settings适合按项目隔离。Claude Code 会读取~/.claude/settings.json我们可以在里面加一个env字段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的令牌 } }这里有个坑要提醒ANTHROPIC_BASE_URL结尾不要带/v1Claude Code 会自己拼接路径。如果你写成https://taotoken.net/api/v1请求就会变成/v1/v1/messages直接 404。我踩过一次排查了半天才发现是多了个后缀。配好之后先别急着写规则跑一个最小验证在终端执行claude进入交互随便问一句「你好」能正常返回就说明端点通了。如果报 401多半是 Key 复制时带了空格或者令牌被禁用如果报连接超时检查 Base URL 是否写错。这一步通了后面的 Rules 才有意义因为规则文件是本地读取的但 agents 执行、hooks 触发都要走模型请求。关于模型选择Claude Code 默认会用配置里的模型。如果你在 settings 里指定了model字段确保它和端点支持的模型 ID 一致。TaoToken 的模型列表可以在 https://taotoken.net/models 查看选一个支持长上下文的因为 Rules 文件会占用不少 token。3. 可复制配置rules 目录、agents 分工与 hooks 触发这一节是全文的核心给一套可以直接抄的目录结构和配置文件。先看整体布局~/.claude/ ├── settings.json # hooks 与环境变量 ├── rules/ │ ├── git-workflow.md # 提交与 PR 规范 │ ├── coding-style.md # 编码风格 │ ├── security.md # 安全检查清单 │ └── testing.md # 测试要求 └── agents/ ├── planner.md # 规划代理 ├── code-reviewer.md # 审查代理 └── tdd-guide.md # TDD 代理rules 目录下的每个 md 文件就是一条规则。Claude Code 在会话开始时会读取这些文件把它们作为系统上下文注入。写规则的原则是具体、可执行、带反例。比如coding-style.md不要只写「保持代码整洁」而要写清楚「函数不超过 50 行、文件不超过 800 行、禁止直接修改对象属性用展开运算符返回新对象」。agents 目录下每个文件定义一个子代理格式是带 frontmatter 的 markdown--- name: code-reviewer description: 代码审查代理在写完代码后立即调用 tools: Read, Grep, Glob model: sonnet --- 你是一名严格的代码审查员。审查时按以下顺序检查 1. 是否有硬编码密钥 2. 是否有未处理的错误分支 3. 函数是否超过 50 行 4. 是否有 console.log 残留 输出格式按严重程度分级critical / high / medium每条给出文件行号和修复建议。tools字段限制这个代理能用哪些工具审查类代理只需要读不需要写所以给Read, Grep, Glob就够了。model字段可以指定模型审查这种需要推理的任务用 sonnet 比较合适。hooks 写在settings.json里按触发时机分三类PreToolUse工具执行前、PostToolUse工具执行后、Stop会话结束。下面是一个可用的配置片段{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npx prettier --write \$CLAUDE_FILE_PATH\ 2/dev/null || true } ] } ], Stop: [ { hooks: [ { type: command, command: grep -rn console.log ./src 2/dev/null | head -20 || true } ] } ] } }这段配置做了两件事每次编辑或写入文件后自动用 Prettier 格式化会话结束时扫描 src 目录下的 console.log 并打印出来。matcher是工具名匹配Edit|Write表示这两个工具触发。$CLAUDE_FILE_PATH是 Claude Code 注入的环境变量指向被修改的文件。注意 hooks 命令里的|| true这是防止命令返回非零退出码导致整个 hook 失败。Prettier 对某些文件类型会报错加了这个兜底就不会中断流程。如果你用的是 Cline 或 CC Switch 这类工具配置逻辑类似但字段名可能不同。以 CC Switch 为例它管理的是多套配置的切换核心三件套还是 Base URL、Key、Model ID{ provider: anthropic, baseUrl: https://taotoken.net/api, apiKey: sk-你的令牌, model: claude-sonnet-4-5 }Codex 用户如果走auth.json结构也差不多把OPENAI_BASE_URL换成对应端点即可。不管用哪个客户端记住三件套缺一不可端点、令牌、模型 ID。少一个就会报 401 或 model not found。4. 验证请求改一个文件看 hooks 和 agents 是否按预期执行配置写完不算完得验证它真的生效。我设计了一个最小验证流程你可以跟着做一遍。第一步验证 rules 被读取。在项目根目录启动 Claude Code输入「请按我的编码风格写一个用户注册函数」。如果 rules 生效它应该会遵守coding-style.md里的约定比如用不可变模式、函数不超过 50 行。如果它写出了一个 200 行的巨型函数说明 rules 没被加载。这时候检查~/.claude/rules/路径是否正确文件名是否是.md结尾。第二步验证 hooks 触发。随便改一个.ts文件故意把格式写乱比如const user{name:test,age:18}保存后观察终端。如果 PostToolUse hook 生效你应该能看到 Prettier 自动把它格式化成const user { name: test, age: 18 }没生效的话检查settings.json的 JSON 语法是否正确可以用cat ~/.claude/settings.json | python -m json.tool验证。另外确认npx prettier在 PATH 里能直接调用有些环境需要写全路径。第三步验证 agents 被调用。在会话里输入「帮我审查一下刚才改的代码」。如果code-revieweragent 配置正确Claude Code 会调用它输出按 critical/high/medium 分级的审查结果。如果它只是普通地回了一段话说明 agent 没被识别。检查~/.claude/agents/下的文件 frontmatter 格式name和description是必填的缺了就不会注册。第四步验证 Stop hook。在src/下故意留一个console.log(debug)然后结束会话输入/exit或 CtrlC。如果 Stop hook 生效退出前会打印出这个 console.log 的位置。这一步能帮你养成提交前清理调试代码的习惯。整个验证流程走下来大概五分钟。如果四步都通过说明你的 Rules 体系已经跑起来了。接下来就是往 rules 里持续补充团队规范往 agents 里加新的分工。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中最容易撞上的几类报错我按实际遇到的频率排个序给出排查路径。401 Unauthorized。这是最常见的。原因通常有三个Key 复制时带了首尾空格令牌被禁用或过期Base URL 和 Key 不匹配比如把 A 平台的 Key 配到了 B 平台的端点。排查方法先echo $ANTHROPIC_AUTH_TOKEN看有没有多余字符再去 https://taotoken.net/api-keys 确认令牌状态。如果用的是 settings.json 里的 env注意 JSON 里不能有注释也不能用单引号。local proxy failed。这个报错说明 Claude Code 尝试走本地代理但连不上。检查你的 shell 里有没有残留的HTTP_PROXY或HTTPS_PROXY环境变量有的话先unset掉。另外确认ANTHROPIC_BASE_URL是完整的https://开头不要写成http://或者漏了协议头。reading choices 相关报错。这类错误通常出现在响应解析阶段说明返回的 JSON 结构不符合预期。常见原因是 Base URL 多写了/v1导致请求打到了错误的路径返回了 HTML 而不是 JSON。把ANTHROPIC_BASE_URL改成https://taotoken.net/api再试。如果还不行用 curl 直接测一下端点curl -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的令牌 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-5,max_tokens:100,messages:[{role:user,content:hi}]}能返回正常 JSON 就说明端点没问题问题在客户端配置。OAuth 相关报错。Claude Code 某些版本会尝试 OAuth 登录流程如果你用的是 API Key 模式需要在 settings 里明确禁用 OAuth。检查有没有forceLoginMethod之类的字段把它设成apiKey。另外确认没有同时配置 OAuth token 和 API Key两者冲突会导致认证失败。hooks 不触发。如果 hooks 完全没反应先确认settings.json的路径是~/.claude/settings.json而不是项目目录下的。Claude Code 读的是用户级配置。其次检查matcher的工具名是否拼写正确Edit和Write是区分大小写的。最后看 hook 命令本身能不能在终端手动跑通跑不通就先修命令。agents 不生效。检查 frontmatter 的---是不是在文件第一行前面不能有空行。name字段要和你在会话里调用的名字一致。如果 agent 文件放在项目目录的.claude/agents/下注意项目级配置会覆盖用户级确认没有同名文件冲突。6. 把规则沉淀成团队资产从个人配置到协作规范Rules 体系真正的价值不在于单次任务跑得多顺而在于它把「怎么做」这件事从人脑里搬到了仓库里。新人 clone 下来~/.claude/rules/一放立刻就能按团队标准写代码老成员改了规范提交一个 md 文件的 diff所有人下次会话自动生效。这比写一份 Wiki 然后没人看要实在得多。我建议的演进路径是先个人用把最常重复交代的三五条规则写进 rules跑顺了再抽成团队仓库用 git submodule 或者直接复制的方式分发最后把 agents 和 hooks 也纳入版本管理让「规划 → 写测试 → 审查 → 提交」这条链路完全自动化。到这一步Claude Code 就不只是一个补全工具而是团队工程规范的一个执行层。如果你还没配好端点先去 https://taotoken.net/api-keys 拿一个令牌按第二节的配置写进 settings.json。规则文件的具体写法可以参考 https://taotoken.net/doc 里的接入说明里面有更完整的字段解释。想先试试模型对话效果可以直接打开 https://taotoken.net/chat 体验一下。长期做编码和 Agent 任务的建议了解一下 Coding Plan配额和并发更适合高频使用场景。配置这件事跑通一次后面就是复制粘贴的事了。 
长河君 · 2026/10/9 11:52:33 · 阅读 1.2k Claude Code | Rules 最佳配置案例（中文）：用 agents 与 hooks 搭建可复用规则体系
1. 为什么你的 Claude Code 提示词总是「用完即弃」很多人用 Claude Code 的方式是在对话框里临时敲一段要求帮我写个函数、帮我改个 bug、帮我加个测试。单次任务确实能跑通但过两天换个项目、换台机器之前那套「先规划、再写测试、最后审查」的流程就全丢了。团队里每个人各写各的提示词代码风格、提交规范、安全底线全靠口头约定新人进来只能靠翻聊天记录猜。Claude Code 的 Rules 体系就是来解决这个问题的。它把零散提示词沉淀成仓库里可版本管理的文件~/.claude/rules/放规则~/.claude/agents/放子代理~/.claude/settings.json放 hooks 触发点。规则是「知识」agents 是「分工」hooks 是「自动化执行」。三者组合起来才是一套可复用的团队规范而不是一段随时会丢的 prompt。这套配置适合谁适合已经把 Claude Code 当日常开发工具、想让团队协作有一致标准的开发者也适合个人开发者想把自己的编码习惯固化下来避免每次开新会话都要重新交代一遍。下面我按「目录结构 → agents 分工 → hooks 触发 → 规则生效验证 → 排错」的顺序给一套可以直接复制的配置案例。核心检索词就是 Claude Code Rules 配置全文围绕 agents 与 hooks 怎么落地展开。需要说明的是Claude Code 本身通过 Anthropic 官方接口调用国内直连有时不稳定。我实测下来用兼容 Anthropic 协议的接入方式会更省心后面第二节会给出具体配置把 Base URL 指向兼容端点即可规则文件本身不受影响。2. TaoToken 前置把 Claude Code 的请求端点配好在写 Rules 之前得先保证 Claude Code 能稳定发出请求。Claude Code 读取的是 Anthropic 风格的接口所以我们要配置的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个环境变量。TaoToken 提供了兼容 Anthropic 协议的端点把 Base URL 指过去Key 换成自己的令牌即可。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个令牌复制出来。注意这个 Key 只在创建时完整显示一次丢了就得重建。拿到之后不要写死在代码里放到 shell 的环境变量或者 Claude Code 的 settings 里。配置方式有两种。第一种是写进 shell 配置文件适合全局生效# 写入 ~/.zshrc 或 ~/.bashrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的令牌改完执行source ~/.zshrc让它生效。第二种是写进 Claude Code 的 settings适合按项目隔离。Claude Code 会读取~/.claude/settings.json我们可以在里面加一个env字段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的令牌 } }这里有个坑要提醒ANTHROPIC_BASE_URL结尾不要带/v1Claude Code 会自己拼接路径。如果你写成https://taotoken.net/api/v1请求就会变成/v1/v1/messages直接 404。我踩过一次排查了半天才发现是多了个后缀。配好之后先别急着写规则跑一个最小验证在终端执行claude进入交互随便问一句「你好」能正常返回就说明端点通了。如果报 401多半是 Key 复制时带了空格或者令牌被禁用如果报连接超时检查 Base URL 是否写错。这一步通了后面的 Rules 才有意义因为规则文件是本地读取的但 agents 执行、hooks 触发都要走模型请求。关于模型选择Claude Code 默认会用配置里的模型。如果你在 settings 里指定了model字段确保它和端点支持的模型 ID 一致。TaoToken 的模型列表可以在 https://taotoken.net/models 查看选一个支持长上下文的因为 Rules 文件会占用不少 token。3. 可复制配置rules 目录、agents 分工与 hooks 触发这一节是全文的核心给一套可以直接抄的目录结构和配置文件。先看整体布局~/.claude/ ├── settings.json # hooks 与环境变量 ├── rules/ │ ├── git-workflow.md # 提交与 PR 规范 │ ├── coding-style.md # 编码风格 │ ├── security.md # 安全检查清单 │ └── testing.md # 测试要求 └── agents/ ├── planner.md # 规划代理 ├── code-reviewer.md # 审查代理 └── tdd-guide.md # TDD 代理rules 目录下的每个 md 文件就是一条规则。Claude Code 在会话开始时会读取这些文件把它们作为系统上下文注入。写规则的原则是具体、可执行、带反例。比如coding-style.md不要只写「保持代码整洁」而要写清楚「函数不超过 50 行、文件不超过 800 行、禁止直接修改对象属性用展开运算符返回新对象」。agents 目录下每个文件定义一个子代理格式是带 frontmatter 的 markdown--- name: code-reviewer description: 代码审查代理在写完代码后立即调用 tools: Read, Grep, Glob model: sonnet --- 你是一名严格的代码审查员。审查时按以下顺序检查 1. 是否有硬编码密钥 2. 是否有未处理的错误分支 3. 函数是否超过 50 行 4. 是否有 console.log 残留 输出格式按严重程度分级critical / high / medium每条给出文件行号和修复建议。tools字段限制这个代理能用哪些工具审查类代理只需要读不需要写所以给Read, Grep, Glob就够了。model字段可以指定模型审查这种需要推理的任务用 sonnet 比较合适。hooks 写在settings.json里按触发时机分三类PreToolUse工具执行前、PostToolUse工具执行后、Stop会话结束。下面是一个可用的配置片段{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npx prettier --write \$CLAUDE_FILE_PATH\ 2/dev/null || true } ] } ], Stop: [ { hooks: [ { type: command, command: grep -rn console.log ./src 2/dev/null | head -20 || true } ] } ] } }这段配置做了两件事每次编辑或写入文件后自动用 Prettier 格式化会话结束时扫描 src 目录下的 console.log 并打印出来。matcher是工具名匹配Edit|Write表示这两个工具触发。$CLAUDE_FILE_PATH是 Claude Code 注入的环境变量指向被修改的文件。注意 hooks 命令里的|| true这是防止命令返回非零退出码导致整个 hook 失败。Prettier 对某些文件类型会报错加了这个兜底就不会中断流程。如果你用的是 Cline 或 CC Switch 这类工具配置逻辑类似但字段名可能不同。以 CC Switch 为例它管理的是多套配置的切换核心三件套还是 Base URL、Key、Model ID{ provider: anthropic, baseUrl: https://taotoken.net/api, apiKey: sk-你的令牌, model: claude-sonnet-4-5 }Codex 用户如果走auth.json结构也差不多把OPENAI_BASE_URL换成对应端点即可。不管用哪个客户端记住三件套缺一不可端点、令牌、模型 ID。少一个就会报 401 或 model not found。4. 验证请求改一个文件看 hooks 和 agents 是否按预期执行配置写完不算完得验证它真的生效。我设计了一个最小验证流程你可以跟着做一遍。第一步验证 rules 被读取。在项目根目录启动 Claude Code输入「请按我的编码风格写一个用户注册函数」。如果 rules 生效它应该会遵守coding-style.md里的约定比如用不可变模式、函数不超过 50 行。如果它写出了一个 200 行的巨型函数说明 rules 没被加载。这时候检查~/.claude/rules/路径是否正确文件名是否是.md结尾。第二步验证 hooks 触发。随便改一个.ts文件故意把格式写乱比如const user{name:test,age:18}保存后观察终端。如果 PostToolUse hook 生效你应该能看到 Prettier 自动把它格式化成const user { name: test, age: 18 }没生效的话检查settings.json的 JSON 语法是否正确可以用cat ~/.claude/settings.json | python -m json.tool验证。另外确认npx prettier在 PATH 里能直接调用有些环境需要写全路径。第三步验证 agents 被调用。在会话里输入「帮我审查一下刚才改的代码」。如果code-revieweragent 配置正确Claude Code 会调用它输出按 critical/high/medium 分级的审查结果。如果它只是普通地回了一段话说明 agent 没被识别。检查~/.claude/agents/下的文件 frontmatter 格式name和description是必填的缺了就不会注册。第四步验证 Stop hook。在src/下故意留一个console.log(debug)然后结束会话输入/exit或 CtrlC。如果 Stop hook 生效退出前会打印出这个 console.log 的位置。这一步能帮你养成提交前清理调试代码的习惯。整个验证流程走下来大概五分钟。如果四步都通过说明你的 Rules 体系已经跑起来了。接下来就是往 rules 里持续补充团队规范往 agents 里加新的分工。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中最容易撞上的几类报错我按实际遇到的频率排个序给出排查路径。401 Unauthorized。这是最常见的。原因通常有三个Key 复制时带了首尾空格令牌被禁用或过期Base URL 和 Key 不匹配比如把 A 平台的 Key 配到了 B 平台的端点。排查方法先echo $ANTHROPIC_AUTH_TOKEN看有没有多余字符再去 https://taotoken.net/api-keys 确认令牌状态。如果用的是 settings.json 里的 env注意 JSON 里不能有注释也不能用单引号。local proxy failed。这个报错说明 Claude Code 尝试走本地代理但连不上。检查你的 shell 里有没有残留的HTTP_PROXY或HTTPS_PROXY环境变量有的话先unset掉。另外确认ANTHROPIC_BASE_URL是完整的https://开头不要写成http://或者漏了协议头。reading choices 相关报错。这类错误通常出现在响应解析阶段说明返回的 JSON 结构不符合预期。常见原因是 Base URL 多写了/v1导致请求打到了错误的路径返回了 HTML 而不是 JSON。把ANTHROPIC_BASE_URL改成https://taotoken.net/api再试。如果还不行用 curl 直接测一下端点curl -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的令牌 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-5,max_tokens:100,messages:[{role:user,content:hi}]}能返回正常 JSON 就说明端点没问题问题在客户端配置。OAuth 相关报错。Claude Code 某些版本会尝试 OAuth 登录流程如果你用的是 API Key 模式需要在 settings 里明确禁用 OAuth。检查有没有forceLoginMethod之类的字段把它设成apiKey。另外确认没有同时配置 OAuth token 和 API Key两者冲突会导致认证失败。hooks 不触发。如果 hooks 完全没反应先确认settings.json的路径是~/.claude/settings.json而不是项目目录下的。Claude Code 读的是用户级配置。其次检查matcher的工具名是否拼写正确Edit和Write是区分大小写的。最后看 hook 命令本身能不能在终端手动跑通跑不通就先修命令。agents 不生效。检查 frontmatter 的---是不是在文件第一行前面不能有空行。name字段要和你在会话里调用的名字一致。如果 agent 文件放在项目目录的.claude/agents/下注意项目级配置会覆盖用户级确认没有同名文件冲突。6. 把规则沉淀成团队资产从个人配置到协作规范Rules 体系真正的价值不在于单次任务跑得多顺而在于它把「怎么做」这件事从人脑里搬到了仓库里。新人 clone 下来~/.claude/rules/一放立刻就能按团队标准写代码老成员改了规范提交一个 md 文件的 diff所有人下次会话自动生效。这比写一份 Wiki 然后没人看要实在得多。我建议的演进路径是先个人用把最常重复交代的三五条规则写进 rules跑顺了再抽成团队仓库用 git submodule 或者直接复制的方式分发最后把 agents 和 hooks 也纳入版本管理让「规划 → 写测试 → 审查 → 提交」这条链路完全自动化。到这一步Claude Code 就不只是一个补全工具而是团队工程规范的一个执行层。如果你还没配好端点先去 https://taotoken.net/api-keys 拿一个令牌按第二节的配置写进 settings.json。规则文件的具体写法可以参考 https://taotoken.net/doc 里的接入说明里面有更完整的字段解释。想先试试模型对话效果可以直接打开 https://taotoken.net/chat 体验一下。长期做编码和 Agent 任务的建议了解一下 Coding Plan配额和并发更适合高频使用场景。配置这件事跑通一次后面就是复制粘贴的事了。