你每天在终端里敲同一串长指令，提示词比代码还多，这大概是从普通用户走向重度claude-code用户时最典型的一道坎。我也走过这条路，一开始靠复制粘贴上一轮的对话，后来发现上下文越滚越乱，干脆把常用的规则、流程、审查清单全部沉淀成模板文件，放进一个叫 claude-code-templates 的仓库里统一管理。这篇文章就是想把这套思路完整拆给你看：模板解决什么问题、文件怎么组织、针对需求/编码/审查/测试怎么设计四件套、多项目怎么同步、以及我在真实项目里踩过的坑和调优记录。
1. 模板到底在解决什么问题：先想清楚再动手
1.1 没有模板时，终端对话为什么会失控
我接触 Claude Code 初期最大的感觉是：它在单次对话里很强，但跨对话之后表现极不稳定。今天新建一个会话，模型记得项目结构，明天再开一个会话，它连你用的框架版本都要重新问一遍。这不是模型笨，而是缺少稳定的项目上下文注入机制。
没有模板的典型状态是这样的：打开终端，输入claude，然后开始现场打字，交代技术栈、目录约定、代码风格、测试命令、禁止事项。这些话每次都要重写，而且写得长了你心疼时间，写短了模型理解不到位。更麻烦的是，一旦遇到长任务，比如"帮我重构这个模块并补充单测"，你很难在一段话里把约束讲完，模型做两步就偏了。
另一个隐蔽问题是规则不一致。你给模型说"提交信息用 conventional commits"，它记住了；隔天新会话里你忘了提，它又按自己的理解提交。纪律性完全取决于你每次提示词的完整程度，这对人的要求太高了。
1.2 模板化之后，工作流被重塑成什么样
把模板体系搭起来之后，我的日常变成了这样：
- 进入项目目录，启动终端，Claude Code 自动读取
CLAUDE.md，项目规则已经在它脑子里了。 - 需要做代码审查时，我输入
/review，一个预设好的审查流程被激活，包含检查项、输出格式、禁止改动范围。 - 需要写测试时，输入
/test，模型按固定模板生成测试用例，并自动运行验证。 - 每个会话不需要从头解释"我是谁、我在哪个项目、我要什么"，所有上下文由模板层解决。
这套机制的底层逻辑是：把人的经验固化成文件，把文件的规则注入模型的上下文。你不用每次跟模型重新谈判，它天然知道边界在哪里。我这里说的模板不是简单的"提示词收藏夹"，而是一个有结构的、可以被版本管理的工程资产。
提示：如果你还没有接触过 CLAUDE.md 和自定义命令，后面第2节会从文件落点开始拆解，新手也能按图索骥。
2. claude-code-templates 的目录结构与文件职责
一个真正能落地的 claude-code-templates 仓库，不是把一堆 .md 扔进去就行，而是要让每个文件落在正确的位置、承担明确的职责。下面这四类文件是我的核心组成。
2.1 CLAUDE.md：项目级"宪法"，越早建立越好
CLAUDE.md是 Claude Code 在每个项目根目录自动读取的核心指令文件，相当于项目给 AI 立的规矩。它最厉害的地方在于加载是隐式的：你打开终端进入项目，模型的第一条上下文就包含它，不需要任何手动操作。
我维护的CLAUDE.md通常包含这些区块：
# 项目身份 - 项目名称：api-gateway - 技术栈：Go 1.22 + Gin + Redis + PostgreSQL - 包管理：go mod # 构建与测试 - 启动：docker compose up -d - 测试：make test - 静态检查：make lint # 编码规范 - 错误处理：所有 error 必须向上返回，禁止吞错 - 日志：使用结构化日志 zap，格式为 key=value - 命名：接口名以 Service 结尾，仓库层以 Repo 结尾 # 用户交互规则 - 在修改公共接口前先向我确认 - 数据库迁移文件不允许直接编辑，新增迁移必须新建文件 - 提交信息遵循 conventional commits这里有个非常关键的设计原则：只写"模型需要知道且容易搞错的内容"，不写废话。比如"请认真编码""保证代码质量"这类话没有任何信息量，模型无法据此行动。而"禁止吞错""迁移文件不允许直接编辑"是高约束规则，模型一旦违反会产生真实成本，必须写进去。
CLAUDE.md的优先级逻辑也值得一提：它会被当前会话的 prompt 整体注入，而用户在对话里临时说的话通常拥有更高的即时优先级。这意味着如果你想临时改规矩，直接在对话里说就行，不用每次改文件。
2.2 commands 目录：把高频操作变成斜杠命令
如果你把某件事做了三遍以上，就应该把它固化成命令。比如 code review、生成测试、写提交信息，这些动作的流程高度固定，非常适合模板化。
命令文件的落点在.claude/commands/，一个 Markdown 文件对应一条斜杠命令。文件名是命令名，比如review.md对应/review。
一个典型的 review 命令长这样：
--- description: 对当前分支改动执行完整代码审查，重点关注正确性、安全性与设计一致性 allowed-tools: Bash(git diff, git log), Read --- # 代码审查流程 你作为资深代码审查者，按以下步骤对当前分支相对 main 的改动进行审查： 1. 先执行 `git diff main...HEAD --stat` 快速了解改动范围 2. 对每个改动文件执行 `git diff main...HEAD -- <file>` 获取详细内容 3. 按以下维度输出审查结论： - 正确性：是否存在逻辑错误、边界未覆盖、并发问题 - 安全性：是否有注入、越权、敏感信息泄露 - 设计一致性：是否符合项目分层约定与命名规范 4. 对每个问题标注严重级别：blocker / major / minor / nit 5. 最后用表格汇总问题清单，并给出修改建议 ## 输出格式要求 - 每个问题必须有文件路径+行号+具体原因+建议修改方案 - 不直接修改代码，除非我明确要求文件开头的 frontmatter 负责声明元信息：description会在你不小心忘了命令名时被自动补全甚至匹配；allowed-tools限制这个命令可以调用的工具，减少权限失控风险。这里有个从实践中来的经验：命令文件的核心是流程编排与输出约束，而不是给模型画画。真正有效的审查命令，靠的是"先 stat 再逐文件 diff"这类可执行的步骤序列，模型跟着步骤走，质量远高于直接说"帮我 review 一下"。
2.3 agents 目录：给不同任务配专职人员
如果说 commands 是把动作固化成命令，那 agents 就是把角色固化成配置。Claude Code 支持定义子代理，每个代理有独立的系统提示词、工具权限和模型偏好，相当于在团队里给你配了几个可以随时调用的专职同事。
我常用的 agents 设计如下：
--- name: db-migration-reviewer description: 数据库变更专项审查人员，精通 SQL 与 schema 兼容性评估 tools: Read, Bash, Grep model: sonnet --- 你只负责审查数据库变更相关内容： - 判断 SQL 是否符合项目的迁移规范 - 检查索引设计与查询模式是否匹配 - 评估新增字段对现有服务的影响范围 - 输出风险等级，并明确说明是否允许在低峰期执行实际调用时用@db-migration-reviewer还能通过--model让它用高上限模型跑复杂推理。在设计原则上有两点提醒：一是 agents 的职责范围要窄而清晰，别让一个代理什么都干，否则相当于没有代理；二是工具权限要按需发放，比如让代理读文件可以，但别默认给它写权限。
2.4 settings.json 与 hooks：让规则在关键时刻强制执行
模板不只是提示词，还应该包含自动化的钩子。.claude/settings.json里可以配置 hooks，在特定事件发生时自动执行脚本。我最常用的两个 hook 场景：
{ "hooks": { "PreToolUse": [ { "matcher": "Bash(git push*)", "hooks": [ { "type": "command", "command": "bash scripts/check-branch.sh" } ] } ], "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "bash scripts/auto-format.sh" } ] } ] } }前者在模型执行git push前检查分支名是否合规，防止它往保护分支直接推送；后者在模型每次编辑文件后自动格式化，让风格保持一致。这套东西的价值在于：把"希望模型自觉遵守"升级为"系统层面强制执行"。模板体系到了这个层次，才算真正闭环。
3. 按开发流设计一套完整模板：从需求到上线的四件套
有了文件结构之后，下一步是填充内容。我不建议零散地写模板，而是按开发流中的关键环节设计一套"四件套"：需求澄清、代码生成、代码审查、测试补全。这套组合覆盖了我日常 80% 的编码任务。
3.1 需求澄清模板：把模糊想法逼成可执行规格
大多数开发问题不是写代码难，而是需求没说清。我给 Claude Code 配的/clarify命令，核心思路是通过固定追问顺序，把"做个用户管理功能"这种模糊描述，逼成一个可执行规格。
--- description: 将模糊需求澄清为包含边界与验收标准的规格说明 --- # 需求澄清任务 用户会提供一段需求描述。在开始任何代码编写之前，你必须依次获取以下信息： 1. 核心目标：这个功能要解决什么问题，用户可感知的变化是什么 2. 角色与权限：谁会使用这个功能，不同角色是否有差异 3. 数据与字段：核心实体有哪些字段，哪些必填，哪些只读 4. 交互流程：从入口到完成的主路径是什么，异常路径如何处理 5. 非功能约束：性能、安全、兼容性、埋点要求 6. 验收标准：什么样的表现算"做完"，给出 3 条以上可测试的标准 输出要求： - 使用"我们决定"句式，最终输出一份需求规格草案 - 对每一条规则标注【硬约束】或【软建议】，硬约束后续不允许被 AI 自行放宽 - 如果用户描述中某一部分缺失，直接列出问题清单，不要假设设计这个模板的动机很实际：模型天生倾向于"把缺的部分补全"，但软件开发里最贵的错误恰恰是"补错了"。让模型把推断和事实分开，把约束分级标注，后续开发阶段就不会出现"我以为你不在乎"的扯皮。
3.2 代码生成模板：带着约束开工
进入编码阶段，我用的不是一句"帮我实现登录功能"，而是让模型遵循一个代码生成模板：
--- description: 按照项目规范生成代码，实现前先给出方案 --- # 代码实现任务 用户会描述要实现的模块或功能。你的工作流程： 1. 方案设计：先用 150 字以内的篇幅描述实现方案，包括涉及的模块、接口、数据流 2. 等待确认：输出方案后停下来，等用户说"继续"再开始写代码 3. 代码实现约束： - 必须遵循 CLAUDE.md 中的编码规范 - 新增文件必须创建配套的单测文件（测试框架按项目约定） - 公共函数必须写 godoc/tsdoc 风格注释 - 不允许修改与该功能无关的文件 4. 完成标准：代码通过构建；测试全部通过；给出每个改动文件的摘要 ## 执行规则 - 如果发现需求与既有架构冲突，先停下说明冲突点，不得擅自选择 - 涉及数据库变更时，提醒用户走迁移流程这套代码生成模板的精髓在于"先方案后代码"和"改动范围隔离"。尤其改动范围隔离，是我吃过亏才加的规则——模型经常顺手帮你重构旁边的代码，表面上很贴心，实际上会让 code review 变成灾难。
3.3 代码审查模板：审查的对象是设计，不只是语法
第2节里我贴过一个简化版 review 命令，实际生产环境我用的版本会多一层设计审查维度：
| 审查维度 | 核心问题 | 发现问题的动作 |
|---|---|---|
| 正确性 | 逻辑是否覆盖所有分支 | 构造边界输入逐条验证 |
| 并发与状态 | 共享数据是否有锁或事务保护 | 检查 goroutine/async 调用链 |
| 依赖方向 | 模块是否依赖了不该依赖的层 | 画出包引用关系 |
| 兼容性 | API 变更是否破坏已有调用方 | 搜索所有调用点 |
| 安全与合规 | 输入校验、权限校验是否齐全 | 追踪外部输入流向 |
我在这类模板里特别加了"不要修改代码，只输出结论"的约束。原因是我发现审查类命令一旦允许改代码，模型很容易边审边改，最后你看到的 diff 一团乱麻，根本分不清哪些是原有问题、哪些是模型顺手动的。审查就是审查，修复另行提出。
3.4 测试补全模板：不是凑覆盖率，而是找关键路径
测试模板的定位不是"把覆盖率从 70% 补到 90%"，而是"优先补最值得补的路径"。我的/test-enhance命令会这样引导模型：
- 先读取被测模块，识别核心执行路径与异常分支
- 对每条路径标注：当前是否有测试覆盖；缺失覆盖的风险等级
- 按风险等级排序，优先实现高风险缺失用例
- 每个用例必须包含三部分：构造前置条件、执行动作、断言结果
- 测试运行失败时，先排查用例本身是否合理，不得为了通过测试而修改被测代码
这个模板与普通的"帮我写个测试"最大的差异是它引入了风险分级。因为 AI 写测试的成本很低，如果你不约束它，它会批量生成一堆低价值的快乐路径用例，把核心异常逻辑漏掉。限定"按风险排序补"之后，每一轮测试补充都花在刀刃上。
4. 多项目复用与版本管理：模板漂移是最大的敌人
claude-code-templates 作为一个仓库，它的第三层价值在于"一次沉淀、多处复用"。但只要你同时维护多个项目，就会遇到模板漂移问题：项目 A 的规则改了，项目 B 还停留在三个月前；或者一个通用命令在某个项目里被局部修改，时间一长没人记得改过什么。
4.1 把模板拆成共享层与项目层
我解决漂移的方法是显式分层。仓库根目录下分两层：
claude-code-templates/ ├── shared/ # 跨项目通用 │ ├── CLAUDE.md # 通用编码规范与协作原则 │ ├── commands/ │ │ ├── review.md │ │ ├── clarify.md │ │ └── test-enhance.md │ └── agents/ │ ├── db-reviewer.md │ └── security-reviewer.md └── projects/ ├── api-gateway/ # 每个项目一个目录 │ ├── CLAUDE.md # 项目专属规则 │ └── commands/ │ └── deploy.md # 项目专属命令 └── web-console/ ├── CLAUDE.md └── commands/ └── gen-page.md共享层放所有项目共用的规则与命令，项目层只放差异部分。同步机制上我目前用的是脚本方式：把shared/软链或者复制到每个项目的.claude/目录，profile 配置则由一个sync.sh统一处理。不推荐直接把整个模板仓库 clone 到项目里，那样项目目录会非常脏，而且版本容易乱。
4.2 让 changelog 成为模板仓库的一部分
模板是会进化的。比如我在 review 命令里新增了安全审查维度，这会改变所有项目的 review 行为，需要让团队知道。所以我在仓库里维护一个简单的CHANGELOG.md，记录每一轮模板改动：
## 2025-06-13 - review.md: 新增安全审查维度，要求对外部输入追踪来源 - test-enhance.md: 输出增加风险分级说明，优先补高风险用例 - projects/api-gateway/CLAUDE.md: 新增错误追踪 ID 规范 ## 2025-06-02 - agents/db-reviewer.md: 新增 `--model sonnet` 推荐配置 - shared/CLAUDE.md: 明确禁止自动修改公共接口这套改动的核心价值是让模板变更可审计。一个月后回头看，你能知道某个行为变化来自哪次模板调整，也能在项目出问题时快速定位是模板锅还是项目锅。
4.3 模板变更后要在真实项目里回归验证
我最开始犯过的错误是：改完模板直接推到仓库，等到下次跑命令才发现命令不生效、工具权限缺失、或者模型行为跟预期完全不符。后来我加了两条验证动作：一是在一个测试项目里跑一遍所有受影响的命令，确认流程通畅；二是记录每条命令最后一次验证通过的日期。这个验证动作看似消耗时间，实际能省掉大量的现场排查时间。
5. 高频踩坑与调优记录
模板体系不是搭好就完事，它本身也需要持续调优。这里记录几个真实高频踩坑点，都是我在项目和社区里反复见到的典型问题。
5.1 CLAUDE.md 越长越没用，信息密度才是关键
有个常见心态是"既然 CLAUDE.md 会被注入，那就把所有想得到的规则都塞进去"。结果就是文件长到几千行，模型表面记住了、实际遵循率极低，因为关键规则被海量低价值文本稀释了。
我的调优经验是：CLAUDE.md 里只保留三类内容——会导致返工的硬约束、高频操作的准确命令、容易踩坑的领域陷阱。常规编码风格交给代码格式化工具和 lint 处理，不要写进 CLAUDE.md；模棱两可的"建议"也不要写，因为模型对建议和执行要求的区分并不稳定，建议类内容很容易被无视。
注意：规则表达越接近"如果 X，则必须 Y"的句式，遵循率越高。模糊表达如"尽量保证代码质量""注意性能"在实操中几乎等于没说。
5.2 命令与内部规则打架，模型会优先执行命令里的显式步骤
我有一次把CLAUDE.md里写了"禁止自动修改公共接口"，但/refactor命令里又不小心写了"重构时可以调整所有必要调用点"。结果模型真的改了公共接口，因为命令文件里的指令离执行任务更近、更加具体。在模型眼里，离任务最近的显式指令通常具有最高的优先性。
解决方案是建立一致性检查：命令文件里每出现一个动作指令，都对照CLAUDE.md里的规则，看有没有冲突。在 claude-code-templates 仓库里，我把这步做进了 PR 模板里，要求所有命令类变更必须附带"与现有规则无冲突"的检查。
5.3 hooks 卡住任务：bash 脚本比想象中更容易失败
hooks 的执行是阻塞式的，脚本返回非零退出码，模型就不能继续。我配置自动格式化 hook 时踩过坑：脚本在 CI 环境正常，但在本地个别文件上因为 lint 版本差异直接退出 1，结果模型后续所有动作都被卡死。
调优建议：hooks 脚本必须做防御性设计，比如加set +e、在脚本内部自行处理异常并最终返回 0，让格式化失败不阻塞主流程。如果你希望严格模式，也建议分两个阶段：先让只读检查类 hook 严格阻塞，写操作类 hook 尽量软失败。
5.4 工具权限设置过宽，模型会替你把手伸进不该碰的地方
commands 里的allowed-tools和 agents 里的tools字段，是成本与安全的平衡点。刚开始我图方便，给所有命令都放开了全部工具，结果 review 命令居然自己执行了git commit。没造成事故，但足够吓人。
最终采用的权限原则是：默认读多写少，写操作按需申请。例如 review 命令给 Bash 但只允许git diff、git log等只读命令；代码生成命令允许Write和Edit，但不给 Bash 执行部署类脚本的权限。permission 设置越细，后期出意外越少。
5.5 模板不是一次性的，要随项目演进定期修剪
最后一条经验可能听起来反直觉：模板仓库不是越做越大，而是要定期"剪枝"。每两个月我会翻一遍所有模板文件，删掉已经不再用的命令、合并重复规则、更新过时技术栈说明。剪枝的依据很简单——如果一个命令在过去一个月里一次都没有被调用，它大概率已经没有存在价值了。保留一堆僵尸模板，跟没有模板一样糟糕。
我在实际操作中最直接的体会是：模板质量比模板数量重要得多，一个能确保行为一致的 review 命令，胜过二十个你永远想不起来调用的花哨工具。如果你刚开始搭建，不要追求一步到位，先从一个CLAUDE.md加一个/review命令起步，跑两周，感受模型行为的变化，再慢慢往里加东西。模板的价值是在迭代中体现的，不是写完就有的。
