最近我一直在折腾一个叫 claude-code-templates 的仓库起因很实在我们小组五个人都用 Claude Code 写代码、跑测试、做 review但同样一个任务五个人喂出来的 Agent 行为完全不一样。有人让它改个测试它顺手把生产代码也重构了有人让它写 commit message它滔滔不绝写了一篇“工作总结”。问题不在模型而在我们每个人塞给它的上下文太随心所欲。后来我把 CLAUDE.md、slash command、subagent 定义、hooks 和权限配置当成一套正经的“模板工程”来维护把散落各处的配置收敛成了一个独立仓库再按项目复制、组装、更新。实测下来Agent 的“发挥不稳定”问题缓解了一大半。这篇文章就是完整记录Claude Code 的模板体系由哪些部分组成、CLAUDE.md 怎么写才真正管用、高频任务怎么固化成 slash command以及我们从翻车现场里总结出来的排查经验。适合正在把编码 Agent 引入日常开发、又受够了“每次都得重新调教”的团队参考。1. 先从整体看模板体系到底由哪几块拼成先说一个容易混淆的点Claude Code 的“模板”跟我们以前说的“项目脚手架模板”不是一回事。脚手架模板解决的是“项目结构怎么初始化”而编码 Agent 的模板解决的是“这个 Agent 的长期上下文怎么初始化”。换句话说前者生成代码后者塑造行为。我在搭建 claude-code-templates 仓库时第一件事就是把“塑造行为”这个目标拆成五块CLAUDE.md、slash command、subagent、hooks、settings。这五块各有分工缺了任何一块模板体系都会有漏洞。比如只做 CLAUDE.md 不做 slash command高频任务的执行方式还是靠人肉复制粘贴只做 command 不做 subagent复杂的代码审查就缺少一个专职视角而 hooks 和 settings 更像是“保险丝”用来拦一些 Agent 容易越界的动作。把这五层理解清楚后面的模板设计才不会跑偏。1.1 从“写提示词”到“搭模板”的思维切换很多人的习惯是把提示词写在一个 Markdown 文件里让 Agent “参考执行”。这能解决单次对话的问题但解决不了多次、多项目、多成员的一致性问题。人写的提示词是开放式的今天写到第三点明天可能忘了第二点张三写得细李四写得粗最终 Agent 的行为风格完全不可预期。我当时做 claude-code-templates 的核心动机就是把“一次性提示词”升级为“可持续维护的模板”。模板的本质是约束约束 Agent 读什么、不读什么、先做什么、后做什么、做到什么程度算完成。约束越多Agent 的自由发挥空间越少但产出的可预期性会显著提高。这个 trade-off 我会在后面反复提到因为所有模板设计中的纠结本质上都是在“约束”和“灵活”之间找平衡。所以第一步不是急着写文件而是先想清楚我们希望 Agent 在什么场景下表现出什么样的稳定行为这个问题的答案直接决定了模板仓库里每一份文件的定位。1.2 五大模板载体各自负责什么在 Claude Code 里模板载体的分工大概可以整理成下面这张表。这里基于的是我实际使用并验证过的配置方式不同版本在细节上可能有差异但整体框架是稳定的。模板层主载体解决什么问题典型存放位置长期记忆CLAUDE.md项目背景、命令、约束、常见坑仓库根目录、子目录、~/.claude/任务宏Slash command高频任务的固定执行流程.claude/commands/*.md专职角色Subagent需要独立视角的子任务.claude/agents/*.md确定性护栏Hooks在关键节点强制检查或采集上下文.claude/settings.json权限边界Settings限制 Agent 能调用哪些工具.claude/settings.jsonCLAUDE.md 是“项目记忆”。它的特点是每次会话都会参与上下文构建适合放那些长期有效、且与具体代码强相关的信息比如构建命令、测试方式、目录约定、历史踩坑。它不适合放长篇大论的项目愿景也不适合放频繁变化的内容。我在初版模板里写过一段关于“产品未来规划”的文字结果 Agent 不但没受益反而经常在代码里自作主张地预留接口非常头疼。Slash command 是“工作流留声机”。它把一段完整的任务流程固化成 markdown 文件比如“审查当前分支改动”“生成测试计划”“复现这个 bug”。使用者在对话框里输入 /review、/plan 这类命令就能触发一套标准流程不需要每次重新组织语言。这是模板仓库里使用频率最高的部分。Subagent 是“专职同事”。Claude Code 的 subagent 机制允许为特定任务定义独立的角色提示词并在需要时由主 Agent 调用。比如我可以定义一个 code-reviewer subagent让它从代码异味的角度提意见而不是像主 Agent 那样“边写边审”。这层模板适合放那些需要角色切换才能做好的任务。Hooks 和 settings 则是“规则围栏”。Hooks 可以在工具调用前后执行确定性逻辑比如“不允许 Agent 修改数据库迁移文件”“在每次执行测试前先把当前分支名写入日志”。Settings 可以配置哪些工具默认禁用、哪些目录需要额外确认。这是模板体系里最容易被忽略的部分但恰恰是生产环境最依赖的护栏。我的经验是模板负责让 Agent “做得对”hooks 负责让 Agent “不能做错”。2. CLAUDE.md 模板设计让 Agent 把规则当回事CLAUDE.md 是整个模板仓库的地基。地基不牢上面都是空中楼阁。我在 claude-code-templates 项目里踩过最深的坑就是写了很多自以为很有道理的项目规约但 Agent 根本不按规则走。这里要说一个容易被忽略的机制语言模型不像人一样会“领会精神”它是在按概率选择 token。一条规则写得再正确如果太长、太抽象、太靠后在上下文里的权重就会很低。真正能被执行下去的 CLAUDE.md应该是“高位置的、具体的、可验证的”。2.1 一份能长期生效的 CLAUDE.md 骨架长什么样我把自己在多个项目里迭代过的一版 CLAUDE.md 骨架放出来它不是唯一的答案但结构上很实用# 项目支付对账服务 ## 项目定位两句话 用于每日对账的异步任务服务消费订单消息生成差异报告。 ## 命令写给 Agent 的命令手册 - 本地构建: make build - 单元测试: make test - 集成测试: go test ./integration/... - 静态检查: golangci-lint run - 数据库迁移: make migrate ## 技术栈 - Go 1.22 / Postgres 15 / Redis 7 / Temporal ## 核心目录约定 - internal/order 只允许依赖 internal/contracts禁止反向依赖 - cmd/worker 是唯一入口业务逻辑不允许写在 main.go ## 常见坑历史教训 - 调试日志统一用 slog不要用 fmt.Println - 数据库迁移文件一旦提交禁止修改历史版本只能新增新的变更 - 订单金额一律以分为单位存储浮点数只用于展示层 ## 完成标准Definition of Done 1. 实现代码并补齐单元测试覆盖率不低于 90% 2. 执行 make test golangci-lint run必须全部通过 3. 在最终回复里贴出测试输出的关键片段方便 review 确认这个骨架有几个关键设计。首先是“命令”放在最靠前的位置因为 Agent 日常干活的第一步几乎都是“我要执行什么命令”。如果它连测试命令都要靠猜后面的一切都会跑偏。其次是“常见坑”写得特别具体每条都对应一个真实发生过的失误。模型对“不要用什么”这类负面约束的记忆效果远比想象中弱所以每写一条负面约束最好附上替代做法例如“不要用 fmt.Println 调日志用 slog”。然后是“完成标准”。这是整个 CLAUDE.md 里价值最高的一段。它把 Agent 的“任务终点”从模糊的“做得差不多”变成了可执行的“跑测试 贴输出”。我在模板里刻意强调“在最终回复里贴出测试输出的关键片段”是因为 Agent 说自己“测试通过”并不可信但它贴出的命令输出可以作为证据。这种写法本质上是给 Agent 加了一道自我检查的手续。2.2 让 Agent “听劝”的三个写法技巧第一规则要“命令化”不要“价值观化”。很多人写 CLAUDE.md 时喜欢说“请保证代码质量”“注意性能问题”。这种话对模型来说几乎等于没说。正确的写法是给出动作例如“在审查代码时如果发现 N1 查询必须标记为 Block 等级”。命令化的规则具备可执行性价值观化的规则只提供心理安慰。第二长文档用引用拆开不要让 CLAUDE.md 变成一本书。Claude Code 支持在 CLAUDE.md 里通过引用语法导入其他文档比如docs/architecture.md。我建议把大段的架构说明放到独立文件里CLAUDE.md 只保留一句“架构约束见 docs/architecture.md”。这既是给 Agent 减负也是给自己减负架构文档单独更新不影响 CLAUDE.md 的稳定结构。但要注意引用的文件同样会占用上下文空间能只引一段就不要引一篇。第三模板里应该包含“先侦察后动手”的起步动作。我见过很多 Agent 一上来就改代码结果改错了文件。后来我在 CLAUDE.md 的“完成标准”之前加了一条“起步动作”任务开始时先运行git status和git log --oneline -5再说明这次变更预计影响的模块最后才开始写代码。这个动作会让 Agent 先对齐“当前在哪、改了什么”再进入操作环节极大地减少了改错文件的风险。另外如果你项目里定义了 subagent也可以在 CLAUDE.md 里留一小段说明它们的职责边界。但更完整的定义应该放在 .claude/agents/ 目录里。subagent 模板和 CLAUDE.md 的分工并不冲突CLAUDE.md 管全局背景subagent 管专项角色。3. Slash Command 模板实操高频率任务固化成宏如果说 CLAUDE.md 是项目的“长期记忆”那 slash command 就是团队的“标准作业程序”。我真正感受到 claude-code-templates 仓库的回报是在把高频任务固化成 slash command 之后。在这之前每个成员每次执行 code review 或者写 commit message 时措辞和流程都不一样固化成命令模板后四个人输入的 /review 触发的是同一套工作流输出结构也趋于一致。3.1 命令模板的存放与变量规则Slash command 的模板放在项目的.claude/commands/目录下每个 Markdown 文件对应一个命令。文件名就是命令名例如review.md对应/review。也可以放在团队共享的模板仓库里由同步脚本复制到各个项目。命令模板里有两个我常用的变量$ARGUMENTS和$INPUT前者是用户输入的命令参数后者用于接收粘贴进来的大文本比如一段报错日志。这个区分很重要因为如果有人把整段日志直接粘贴给一个命令模板收到后会变得不可控所以我倾向于让命令先问“要处理的目标是什么”再决定读哪个文件。下面是一个我实际在用的 /review 命令模板简化版可以很直观地看出命令模板的结构。它的设计目标很明确把 code review 的步骤从“想到什么说什么”变成“按步骤检查 按格式汇报”。# 对当前分支的变更进行代码审查 用户提供的参数$ARGUMENTS用于指定审查重点例如并发安全、数据库索引。 执行步骤如下 1. 运行 git diff --stat 查看变更涉及的文件列出你认为风险最高的三个文件。 2. 运行 git diff 获取具体变更按文件逐一审查。 3. 审查维度必须覆盖 - 逻辑正确性是否存在边界条件遗漏 - 并发与事务是否涉及共享状态或事务边界 - 可维护性命名、函数长度、重复代码 4. 每个维度输出结论通过 / 警告 / 阻塞。 5. 最后用列表输出变更摘要、风险点、改进建议、是否建议合并。这个模板看起来不复杂但它把“审查一份代码”从开放式任务变成了封闭式流程。步骤 3 的多维检查避免了 Agent 只盯着逻辑错误而忽略可维护性的毛病步骤 5 的结构化输出则让团队在群里 review 结果时一眼能抓到重点。模板非常忌讳一句“请帮我 review 一下代码”就完事那等于把决定权全部交给模型。3.2 三个适合做成命令模板的高频场景第一个是/plan。需求方丢过来一个需求Agent 先不要动手写代码而是先输出实施计划涉及哪些模块、改动顺序、测试方案、预估风险。这个命令模板的价值在于把“思考前置”避免 Agent 兴冲冲改了 20 个文件后发现方向错了。模板里我会硬性要求第一步必须输出“一句话需求理解”如果理解偏差后面所有步骤都可以停下来。第二个是/repro。遇到线上 bug用户把错误信息粘进来Agent 负责定位问题并输出一个可执行的复现流程。模板里要明确要求 Agent 不要“猜原因”而是先找日志、找入口、找最近的代码变更再给出复现路径。这个模板是我们排查线上问题时的主力它能把“我觉得可能是……”变成“执行以下三步必然复现”。第三个是/commit。生成符合规范的 commit message。模板里会要求 Agent 读取git diff --staged然后按“类型 主题 正文描述关联需求”的格式输出。团队如果对 commit 规范有统一要求这个模板能省掉大量 review 时的沟通成本。最开始我担心这类模板会不会太“死板”但实践下来规范化的 commit 反而是团队收益最明显的一处。还有一类命令行模板值得做/init让 Agent 检查当前项目是否具备 CLAUDE.md、是否有配套的 subagent如果没有则根据现有代码生成一份。这个命令适合在接手一个旧项目时使用相当于用模板化方式快速补齐 Agent 需要的项目背景。官方模板仓库里也有类似思路你可以直接把这一类 init 模板作为模板仓库的入口文件。4. 搭建一个可复制的模板仓库目录设计、组装与演练前面几节讲的是“单文件怎么写”这一节说“一整个仓库怎么组织”。claude-code-templates 的价值不在于某一份 CLAUDE.md 写得有多好而在于把各项目的共性抽离出来让模板能被反复复制和更新。4.1 模板仓库的目录结构设计我目前使用的目录结构大概是这样的claude-code-templates/ ├── CLAUDE.md # 模板仓库本身的说明 ├── common/ │ ├── claude.md # 通用项目规范 │ ├── commands/ │ │ ├── plan.md │ │ ├── review.md │ │ ├── commit.md │ │ └── repro.md │ └── agents/ │ ├── code-reviewer.md │ └── debugger.md ├── stacks/ │ ├── go-service/ │ │ ├── claude.md │ │ └── commands/ │ │ └── db-migrate.md │ ├── node-service/ │ │ ├── claude.md │ │ └── commands/ │ └── python-worker/ │ ├── claude.md │ └── commands/ └── scripts/ └── apply.sh # 安装脚本把模板组装到目标项目common 目录放所有项目通用的规则stacks 目录放按技术栈或服务类型区分的规则commands 和 agents 再按通用/专用拆开。这里有个容易被忽视的原则不要把某个项目的“个性”过早地抽到 common 里。比如“支付金额用分存储”这条规则只对支付类服务有意义如果把它放进 common其他项目的 Agent 会被无关规则干扰。模版抽取的时机应该是在至少两三个项目出现同一需求之后而不是一开始就追求“大而全”。4.2 模板的组装、校验与持续迭代有了目录结构接下来是怎么把这些模板“安装”到目标项目。我一开始是手动复制但很快就发现手动复制会导致各项目版本漂移改了一处模板其他项目跟不上。后来我写了一个很简单的 apply 脚本核心逻辑就是按配置文件把模板文件复制到目标项目并支持覆盖前先 diff#!/usr/bin/env bash # 用法: ./scripts/apply.sh 目标项目路径 [stacks/go-service] set -euo pipefail target$1 stack${2:-common} if [ ! -d $target ]; then echo 目标目录不存在: $target exit 1 fi for file in common/commands/*.md common/claude.md; do dest$target/.claude/$(basename $file) if [ -f $dest ]; then diff $file $dest /dev/null 21 || echo 差异文件: $dest fi cp $file $dest done # 按技术栈追加 stack 级规范 cp stacks/$stack/claude.md $target/CLAUDE.md.stack # 合并 stack 规范到项目 CLAUDE.md若不存在 if [ ! -f $target/CLAUDE.md ]; then cat stacks/$stack/claude.md $target/CLAUDE.md else # 把 stack 级内容追加到根 CLAUDE.md 的引用区 cp $target/CLAUDE.md $target/CLAUDE.md.bak cat $target/CLAUDE.md.bak stacks/$stack/claude.md $target/CLAUDE.md fi echo 模板已同步请人工确认 diff: $target/CLAUDE.md这个脚本很简陋但核心思想值得借鉴所有模板的中心是 claude-code-templates 仓库目标项目只是一份派生品。更新模板后重新运行脚本就能让所有项目的 CLAUDE.md 和 commands 保持一致如果目标项目里有本地化修改diff 会先提示冲突避免无脑覆盖。组装之后还要演练。这是我前期做得不够、后期补回来的一项工作模板写得好不好只能靠“跑一遍”验证。我会在测试分支上给 Agent 一个真实小任务比如“在internal/order里新增一个导出函数并补充测试”然后盯着命令日志观察它是否按照 CLAUDE.md 里的命令操作、是否最终贴出了测试输出。如果 Agent 跳过了步骤说明模板约束力度不够需要把它变成显式的“必须做”清单。模板不是写完就算完至少每个季度要随项目演进过一遍否则它又会变成一堆没人看的文档。5. 常见问题和排查实录模板这个东西刚搭建的时候感觉“哪里都要管”实际跑一阵子后问题会集中出现在几个固定位置。这里我把踩过的坑整理成五个场景再加上一张速查表方便大家对照排查。5.1 五类最常见翻车现场场景一CLAUDE.md 写太长Agent 跟没看见一样。这不是模型不行而是上下文被稀释了。我的解决办法是压缩 CLAUDE.md 到 80 行以内把细节文档用引用拆出去同时把最重要的三条规则放在文件最前面不要让 Agent 在找命令的路上耗费注意力。场景二slash command 明明定义了但 Agent 回复“找不到这个命令”。常见原因是命令文件放错了层级或者文件名大小写不一致。Claude Code 对命令文件的命名有约定建议统一用 kebab-case命令名就是文件名不要把文件名和命令文案混淆。另一个原因是模板仓库同步脚本没有覆盖到目标项目导致本地根本没有对应文件。场景三Agent 做了步骤 1、3、5就是不按顺序来。命令模板被跳步通常说明步骤之间的依赖关系表达得不够清楚。我后来在模板里加了“上一步输出未确认前禁止进入下一步”这类显式闸门跳步问题明显减少。模型不像人有强顺序感模板里必须把“必须按顺序”写成规则而不是潜台词。场景四hooks 把工具使用权限收得太紧Agent 任务一多就四处碰壁。我早期在 settings 里一次性加了一堆“禁止使用”的规则结果 Agent 连读取某个配置文件的权限都没有任务直接卡死。后来改成“默认允许敏感目录和危险命令单独禁用”并在正式生效前先切到非阻塞模式观察几轮确认没有误伤了才逐步收紧。场景五团队里每个人的行为还是不一样。原因通常出在用户级配置上每个人的~/.claude/CLAUDE.md或个人偏好覆盖了项目模板。解决方法是把“必须使用项目级模板”写进团队规范并把关键命令/review、/plan设计成项目命令而不是个人命令让团队成员统一入口。5.2 排查思路速查表症状常见原因处理动作Agent 无视 CLAUDE.md 中的规则文档过长、规则抽象、位置靠后精简到 80 行内命令化表达关键规则提前命令模板被跳步步骤依赖不明确增加“确认上一步输出后才继续”的闸门Agent 执行了未授权操作权限边界未收紧在 settings.json 中细化 allow/deny加入 hooks 校验多项目模板不一致手动复制导致版本漂移统一使用 apply 脚本以模板仓库为单一来源复现问题的命令无效模板只是提示词缺少确定性步骤在命令模板里强制要求测试命令并贴出输出最后再说一件事模板仓库本身要纳入版本管理每次改动都要写清原因。这不是形式主义而是因为模板会影响 Agent 的行为如果某次改动让 Agent 开始变得激进你需要能快速定位是哪条规则引起的。我在仓库的 commit message 里会写“在 /review 模板增加数据库索引检查维度”这类描述回滚时非常省力。安全方面也要留意不要在命令模板里存放任何敏感信息例如数据库密码、内部凭证模板是要同步给全团队的敏感内容必须走环境变量或凭证管理。根据我个人的落地经验模板仓库最大的回报不在搭建当天而在两三个星期之后当团队成员几乎不再为“如何让 Agent 理解我的项目”而重复解释时这套投入就回本了。往后的每次规则调整也只是在仓库里改一行字、再跑一次同步脚本的事。如果你也正被 Agent 的“发挥不稳定”困扰不妨从一份精简的 CLAUDE.md 和一个 /review 命令模板开始跑顺一个项目再慢慢扩成自己的模板仓库。