1. 从重复劳动说起为什么我们需要模板我真正意识到模板的必要性是在第三个连续项目上。那段时间我同时维护着两个 Python 服务和一个前端仓库每次切换项目都要对着 Claude Code 重新交代一遍项目背景、技术栈、代码风格、测试要求还要把改完记得跑一遍 lint这种话念叨好几遍。有一次我忘了在 A 项目里强调不要动数据库迁移文件结果 Claude 顺手把 migration 目录里的文件改了差点把测试环境搞挂。后来我把这几次对话翻出来复盘发现真正的问题不是我叮嘱得不够多而是上下文根本没有被固化。每一次新的会话Claude 对我手上的项目都是一个第一次见面的陌生人而我不但没给它一份简历还指望着它能自动理解我的心意。就是从那时候起我开始认真研究 claude-code-templates把反复交代的内容整理成模板、沉淀成文件让每个新会话一开始就建立在对项目足够了解的基础上。这篇文章就把我这一路摸出来的经验完整整理出来。从模板的类型、目录设计、实操写法到踩过的坑和调试方法再到团队协作的版本管理都放在里面。不管你是刚接触 Claude Code 的新手还是已经用它写过不少代码的人这套方法论应该都能帮你把重复劳动砍掉一大半。我会尽量避开空泛的最佳实践说教直接给你能抄的写法。2. 模板的核心载体先搞清楚东西要放在哪里2.1 四种载体分工完全不同Claude Code 的模板体系不是只有一种文件。我刚开始研究的时候也以为只要能写个指令文件就行后来才发现一个项目的模板系统至少包含四个层次CLAUDE.md、Slash Command、Agent Skills 以及 Hooks。这四个载体各有各的用途把它们混在一起用或者把本该放在 A 地方的内容硬塞进 B 地方才是模板感觉没起作用的最常见原因。载体作用范围触发时机适合放什么CLAUDE.md整个项目每次会话启动时自动加载项目背景、技术栈约定、工作流偏好、质量门槛Slash Command按需调用用户输入斜杠命令时触发固定场景任务比如代码评审、提交信息生成Agent Skills按需加载被任务描述匹配到时触发需要专门步骤的复杂技能比如重构、迁移、测试生成Hooks自动执行绑定在事件上如文件写入、命令执行后强制校验、自动格式化、防止误操作CLAUDE.md 相当于项目的入职文档Claude 每次开工前都要先读一遍把里面写的约定当成默认行为准则。Slash Command 则像是工具栏里的快捷按钮你按下去它才执行。Agent Skills 更聪明一些它带了一段描述文字Claude 会根据当前任务自己判断要不要调用。Hooks 则完全不需要对话触发属于规约强制执行器。我见过很多人在 CLAUDE.md 里堆了整整一屏的详细任务指令希望 Claude 一启动就按照某个完整工作流执行。这个想法是反的——CLAUDE.md 的价值在于建立稳定的背景规则而不是塞进去一个三十分钟才能跑完的流程。真正的长流程任务应该放到 Slash Command 或 Skills 里按需触发既不会把上下文预算吃掉也不会在一开始就分散模型的注意力。2.2 模板的粒度与复用边界设计模板的时候还有一个关键决策要做模板到底该做得大而全还是小而专我的经验是模板的粒度决定了它的复用率。最开始我一股脑写了一个超大的全栈项目开发模板里面涵盖了初始化、开发、测试、部署、评审五六个环节。上线后我发现它实际被完整使用的次数是零因为大部分时候我只是想让 Claude 帮我改一个函数、写一个单元测试根本不需要把整个生命周期流程走一遍。后来我把这个大模板拆成了十几个小模板每个只负责一件事提交信息生成、代码评审、测试生成、Bug 修复辅助、数据库迁移检查、依赖更新分析,每一个都能独立使用。小模板还有一个额外好处当几个任务组合出现时我可以在一次会话里按顺序触发多个模板而不是被一个大模板卡住节奏。关于复用边界我的建议是遵循任务边界清晰原则。如果一个场景能被一个动词清楚描述出来——审查、迁移、重构、生成提交信息——它就适合独立成模板。如果一个场景需要翻来覆去解释边界和例外条件那大概率是正确的模板还没被设计出来或者这个任务本身不够稳定还不值得固化成模板。3. 从零搭建模板库目录设计与文件规范3.1 项目级指令文件 CLAUDE.md 的结构设计CLAUDE.md 是模板体系的地基。我强烈建议所有项目都放一个哪怕你暂时还没有其他模板。它的结构设计直接决定了 Claude 对项目的理解深度我给出一个经过多次迭代后稳定使用的骨架# 项目:用户中心服务 ## 项目简介 基于 FastAPI 的用户注册、登录、权限管理服务。 面向小程序端提供 JSON API数据存储在 PostgreSQL。 ## 技术栈与关键依赖 - Python 3.11 FastAPI SQLAlchemy 2.0 - Alembic 做数据库迁移 - Pydantic v2 做请求校验和序列化 - 测试框架: pytest httpx ## 常用命令 - 启动开发服务器: uvicorn app.main:app --reload - 运行测试: pytest tests/ -x -q - 代码格式化: ruff format . - 静态检查: ruff check . ## 编码规范与约定 - 所有 API 返回结构统一为 { code: 0, data: ..., message: ok } - 数据库模型文件位于 app/models/禁止手工改 migration 文件 - 新增接口必须附带 pytest 测试覆盖正常和异常两条路径 - 日志使用 structlog禁止在业务代码里 print ## 工作流偏好 - 修改代码后必须先跑相关单测再交给我 - 提交信息按 Conventional Commits 规范写(type: subject) - 涉及数据库变更时先展示需要执行的迁移命令再执行这个文件的每一段都有明确用途项目简介让 Claude 在回答问题时不至于跑偏技术栈告诉它该用哪种姿势写代码常用命令避免它瞎猜启动方式编码规范是灵魂所在很多细节问题比如 API 返回结构都是靠这个约束住的工作流偏好则决定了 Claude 的办事节奏这一点被很多人忽略。一个常见疑问是 CLAUDE.md 会不会太长影响效果。我的实测结论是100-200 行是一个比较舒适的范围。再长的话Claude 虽然也能读但重要性权重会被稀释。如果真有超过 200 行的内容优先考虑拆到 Skills 里按需加载而不是全塞进 CLAUDE.md。3.2 自定义命令模板 Slash Command 的写法Slash Command 是模板库中使用频率最高、见效最快的一层。它的本质是一个带固定名字的提示词模板放在项目的.claude/commands/目录下文件名就是命令名。比如我创建一个.claude/commands/review.md之后在会话里输入/reviewClaude 就会按照这个文件里的指令执行。--- description: 对当前分支的改动做一次完整代码评审 argument-hint: [可选: 指定评审重点] --- 请对当前分支相对主分支的改动进行代码评审: 1. 先执行 git diff main...HEAD --stat 等命令了解改动范围和规模。 2. 重点检查以下几类问题: - 是否存在数据一致性风险、并发写入隐患 - 资源(连接、文件句柄、临时文件)是否正确释放 - 敏感信息是否可能被打印或记录到日志 - 是否缺少必要的错误处理和边界校验 3. 按照 严重问题 / 建议优化 / 可忽略 三级给出评审结论 4. 每条建议务必给出具体文件路径和行号,并附上简化后的代码示例 5. 最后输出一个总体评价,如果存在严重问题请明确说不建议合并 如果用户提供了评审重点,优先聚焦在该范围内。这个文件的写法有一个核心要点给 Claude 一个稳定的执行流程外加明确的输出格式。很多人写命令模板只写了请帮我做一次评审这一句话结果是 Claude 的自由发挥空间太大每次输出风格都不一样。我在模板里明确指定了先执行哪些命令、关注哪些问题维度、按什么分级输出这样得到的评审结果几乎每次都能稳定在可用的水平。frontmatter 里的 description 字段也很关键。Claude Code 会扫描目录下所有命令模板需要根据 description 内容来判断这个命令的用途从而在对话里智能匹配。description 写得含糊比如一个处理一下Claude 不知道它到底是格式化代码还是重构架构调用准确率就会下降。我的习惯是写成对当前分支改动进行代码评审并输出分级结论这种带明确对象和动作的描述。3.3 Skills 与 Hooks 的补充价值Slash Command 适合手动触发的场景Skills 则更进一步它允许 Claude自动识别任务并主动加载对应技能。Skill 的目录结构通常是这样.skills/ refactor-module/ SKILL.md details.mdSKILL.md 的开头是一段带 frontmatter 的描述用于让 Claude 判断这个技能是否应该被使用。写作方式跟 Slash Command 有区别因为 Skills 被触发时用户可能没有显式输入斜杠命令所以要靠 description 把适用场景写清楚。比如 description 可以写当用户要求把某个模块的职责拆开、把功能迁移到新模块时使用适用于大型重构任务。我当时做的一个比较成功的 Skill 是python-dependency-bump。它专门处理依赖升级的场景检查当前依赖版本变化、分析破坏性变更、运行测试、生成变更说明。因为这个任务涉及步骤较多而且每个步骤之间还有依赖关系放 Skills 里比放 Slash Command 更合适——Claude 可以在执行中途根据实际情况调整后续步骤。Hooks 是最后一个需要了解的机制。它做的事情是强制——比如在文件写入之后自动跑格式化或者在每条命令执行后检查输出里有没有敏感信息。我常用的是在 git commit 之前设置一个 hook自动执行一遍测试。不是所有团队都需要 Hooks但对质量要求高的项目来说这种不需要对话、自动执行的约束非常省心。4. 实操过程做一套可复用的代码润色模板4.1 先定义输入和输出再写提示词代码评审模板只是第一个例子。真正让我体会到模板威力的是另一套我频繁使用的模板代码润色——把一段不太完善的实现改成符合项目标准的样子。这个模板的操作过程可以用来展示一套完整模板从设计到落地要经过哪些步骤。第一步先定义清楚输入和输出。我的输入约定是一段代码 可选的背景说明输出约定是修改后的代码 改动说明 针对改动的测试建议。没有这个前置定义模板就会变成一个空泛的帮忙改改代码。第二步才是写提示词模板。我的写法是这样--- description: 对指定代码片段做一致性润色使其符合项目规范与既有实现风格 argument-hint: [可选: 代码文件路径或片段; 背景说明] --- 请对用户提供的代码片段或指定文件进行润色要求: 1. 严格忠于现有逻辑不允许改变接口签名和外部行为 2. 对照项目 CLAUDE.md 中的技术栈与编码规范逐条自查 3. 使用项目依赖中已有的工具库不要引入新的依赖 4. 命名遵循项目既有风格不强行改为其他风格 5. 输出以下三部分内容: - 修改后的完整代码(仅给出有改动的位置及其上下文) - 改动点逐条说明包括改动原因 - 针对改动的测试建议至少一条 如果背景信息不足先向用户提出具体问题再开始润色。模板写好之后我把它放到.claude/commands/polish.md。注意我用的文件名和 description 里的措辞都对齐了——文件名负责被记住description 负责被理解。这两者在实践中都很重要缺一个整个模板的可用性都会掉一截。4.2 微调与上下文绑定的两个细节第一个细节是范围控制。润色模板很容易被 Claude 理解成自由发挥优化的机会进而把好好的代码改成它自认为更优雅的实现。我在模板里特意加了不允许改变接口签名和外部行为以及只在必要的范围内修改这两句话实测效果显著。很多模板不是没写清楚要做什么而是没写清楚不要做什么。我在打磨模板时会把过去遇到过的越界行为逐条写进负面清单里。随着用的时间越来越久这个清单越来越完整模板的可靠性也一直在提升。第二个细节是动态获取上下文的能力。Claude Code 跟普通聊天机器人最大的区别之一就是它能在终端里执行命令、读取真实文件。写模板时完全可以利用这一点让 Claude 在开始干活之前自己去拉取必要信息。比如我在代码评审模板里让它先跑 git diff 再评审在润色模板里让它先读项目里的 CLAUDE.md 再动手效果都很不错。哪怕模板里没有明确指示Claude 也有能力自己去做这些事但写清楚了它的执行会更稳定不会漏掉关键步骤。4.3 测试模板的方法与评价标准模板写完后不能直接上生产环境必须有一个验证环节。我的标准流程是这样至少用三个不同形态的任务去触发同一个模板观察输出差异。重点关注模板里标出的关键约束比如不允许修改接口签名是否在所有场景下都被遵守。检查输出格式是否稳定如果两次输出结构差异很大说明模板里的输出格式约束还不够明确。记录一次失败场景根据失败原因回头修改模板直到三次测试全部通过。在验证润色模板时我准备了一个简单函数、一个 aiohttp 异步请求处理、一个混着旧风格和新写法的模块。三个任务跑下来前两个通过率很高第三个暴露了一个问题模板里没说明遇到一个文件里新旧风格混杂的情况应该怎么处理结果 Claude 只顾着把新代码改成旧风格导致整个文件显得更混乱。我随后在模板里加了一条规则优先保持文件内既有主流风格若一个文件内风格不统一先询问用户希望采用哪种风格。这条规则一加第三个场景也稳定了。模板的评价标准说到底就三条稳定、边界清晰、输出可执行。稳定性指的是同一类问题反复触发结果不会有太大偏差边界清晰指的是模板知道什么改什么不该改不会越权操作可执行指的是它的输出能直接落地不需要再花时间返工。5. 模板设计中的常见坑与排查心得5.1 模板被忽略或跑偏的四种原因模板写好之后不一定每次都按预期运作我在这上面也栽过不少跟头。总结下来模板失效的原因大致有四类而且这四类问题各有各的解法。第一类是最常见的模板描述太宽泛。你让它整理代码它可能觉得只调换一下函数顺序就算整理完了和你想的重构文件结构差着十万八千里。解决办法是忍痛把任务描述写细把整理改成具体的动作比如把错误处理逻辑统一收口到独立的 helper 函数。描述越具体跑偏概率越低。第二类是上下文冲突。当 CLAUDE.md 里的约定和模板里的指令方向不一致时Claude 会无所适从然后倾向于选择它先读到的那个约定通常是 CLAUDE.md。有一次我的项目 CLAUDE.md 里写着所有改动都要跑单测而某个模板里没提测试结果模板任务输出时自觉地跑了一堆测试白白浪费了几分钟。解决办法是模板内部也写明测试要求或者模板明确说这个任务不需要额外跑测试。第三类是模板内部要求过多导致模型选择性遗忘。一个模板里如果写了超过十条纪律模型在后半段可能会出现纪律失效的情况靠前的规则遵守得好靠后的规则被忽略。把纪律压缩到5条以内或者把更重要的规则放在靠前的位置是最有效的两条路径。第四类是上下文长度问题。模板文件本身写得长还没有大问题最大的问题是模板触发时把它引用的其他文件内容也一并塞了进去比如模板让 Claude 读取项目里几个大文件结果上下文窗口被塞满输出的质量急剧下降。这种情况下模板里应该有意识地控制读取文件的范围和深度比如只读取关键部分。5.2 排查模板问题的一套实用流程当模板的输出开始不对劲时我有一个很稳定的排查流程跟调代码的逻辑一样先看输入再看上下文最后才怀疑模板本身。第一步是确认模板是否真的被加载了。用/commands列出可用命令检查目录权限和文件后缀名——.md结尾是必须的我之前见过把命令文件保存成.txt的情况结果完全不生效。第二步是检查上下文里是否有和模板冲突的内容。把会话中被加载的所有指令文件快速扫一遍尤其是 CLAUDE.md。我踩过的最隐蔽的坑是旧版本项目的 CLAUDE.md 里有一条不再适用的规则它和模板的新约定互斥导致模板逻辑本身没错但执行结果怪异。第三步是看模板里的提示词是否产生歧义。我会试着把模板第一人称改成站在一个第一次读这份文件的操作者视角看它要做什么是否一目了然。如果我自己读一遍都觉得模棱两可那 Claude 读起来失准也就能理解了。有时候一个模板明明写了但没生效不是 Claude 的错是模板写得太像给朋友发的一条微信而不是一份可执行的操作手册。最后一种情况如果问题跟特定文件内容强相关我会缩小范围把模板 一个最小复现片段单独拎出来调试。比如给模板喂一段只有一个简单函数的测试代码看它会不会沿着正确的路径跑。这本质上是最小化复现的思路在调模板的时候一样管用。6. 进阶玩法搭建属于你的模板流水线6.1 模板的组合与嵌套使用单个模板解决单个任务这只是一个起点。真正让模板体系发挥威力的是把模板串成一个流水线。举一个我实际用过的例子功能开发完成后的标准化收尾流程。我在项目里建了一个finish-feature命令模板它会依次做这些事检查改动是否满足 CLAUDE.md 里的编码规范、把涉及的文件精确列出并逐层评审、生成提交信息、提醒我跑完整测试。这个模板本身不含具体的审查步骤而是通过触发其他模板来完成各个子任务——评审交给/review模块提交信息交给/commit模块。这种组合方式让不同模板各司其职也避免了大模板出现规则冲突时无从下手的问题。组合模板有一个设计原则要记住子模板被组合调用时父模板要显式声明以子模板的输出为准否则子模板内部定义的输出格式可能被子模板的部分规则覆盖掉一部分导致最终格式混乱。我在finish-feature模板里明确写了这样一句review 子模板的输出直接原样采用无需额外格式转换。加了这个声明之后流水线的输出稳定性提升了很多。6.2 用 Git 管理模板库的进化过程模板是活的资产它会随着项目经验的积累而持续变化。把模板库纳入 Git 管理是我在踩过几次改坏了想回退却回不去的坑之后坚定的做法。我在企业项目仓库里单独建了一个templates/目录用独立的 Git 仓库管理不跟业务代码混在一起。这样模板可以独立于项目迭代多个项目之间也可以共享同一套模板。模板仓库的 CI 配置也值得做。我设了两道简单检查第一道检查所有.md文件的 frontmatter 格式是否合法description 字段是否缺失、文件后缀是否正确第二道检查是对描述的唯一性做校验防止两个命令模板的 description 太相似导致调用时反复触发错误匹配。这两道检查都是纯文本级别的实现成本很低但能挡掉不少低级问题。版本管理模板的更进阶做法是给模板加状态标记。我在文件头部用注释标出模板的成熟度draft、stable、deprecated三种状态。draft代表刚写的还需要多跑几次验证stable代表已经连续稳定使用一段时间deprecated则意味着即将被移除或者被其他模板替代。这个标记能帮我在做季度复盘时快速判断哪些模板该删、哪些模板影响力最大。6.3 多项目复用模板时需要注意的两个问题模板设计出来是为了复用的但不同项目之间的差异会在复用过程中暴露出来。第一个问题是技术栈差异。我在一个 Python 项目里写了一个很顺手的依赖升级模板里面大量用到poetry命令。后来把这个模板直接搬到用uv管理依赖的项目里跑出来的命令全是错的。再后来我在模板里增加了一个前置步骤先读取项目的包管理工具配置再执行对应的命令。这样一来同一个模板就能适配两种环境。第二个问题更隐蔽项目之间约定的差异。A 项目的提交信息规范是 Conventional CommitsB 项目完全不在乎格式。如果贸然把 A 项目的提交信息模板搬到 B 项目Claude 就会拼命按照规范格式去写而 B 项目的团队看着这些信息反而觉得莫名其妙。解决方法是把项目特定的约定写进各个项目的 CLAUDE.md而不是写进模板里。模板只保留如何生成提交信息的通用流程具体格式则从 CLAUDE.md 里读取。这样同一份模板在不同项目里会自动适用不同的约定。这个思路可以说是模板设计里最核心的一条原则区分通用的能力和项目的偏好。通用能力固化成模板项目偏好放在 CLAUDE.md两层配合才能实现跨项目的高效复用。7. 我对模板设计的一些个人体会研究了这么久的 Claude Code 模板我自己的心态也在变化。最开始我以为模板是把所有提醒都写进去写得越全越好。后来我发现真正的关键其实在于设计边界。边界定义得越清晰模板的发挥就越稳定。它就像是一个实习生的工作手册——手册里写清楚什么事可以做、做到什么程度、以什么标准交付、有什么事绝对不能做这个实习生反而更容易上手干出活来。如果手册只有一个大方向那只能靠碰运气了。另一个体会是模板需要持续维护。我每两到三周会翻一次模板库把这段时间里Claude 做得出乎意料的地方记录到模板的负面清单里。用这种方式模板会随着你的实操经验一起进化越用越顺手。最后分享一个小技巧给模板写评价标准。好的模板不但告诉 Claude 该做什么还告诉它做到什么程度算合格。比如代码评审模板里写明每条建议必须带文件路径和行号就是一个简单有效的评价标准。标准定得清楚Claude 自己就有了判断工作完成好坏的依据输出的质量自然更稳。这个技巧我几乎用在了所有模板里实测是性价比最高的一处修改。