拿了“claude-code-templates”这个标题我想说的不是那种套壳的“prompt技巧列表”而是真正能把终端里的协作行为固化成模板的工程方法。先说结论claude-code 本身是一个在终端里和你一起写代码的助手但裸跑它的时候每次都要解释一遍项目背景、代码规范、测试要求、输出格式效率很低。templates 的作用就是把这类“每次都要重复交代的事”变成一套标准动作让助手按你的套路来干活。它适合单人多项目的人也适合想把团队开发规范真正落到执行层的技术负责人。1. 为什么需要模板把“反复交代”变成“默认动作”我第一次用 claude-code 的时候觉得它很聪明但也有点“难带”。同一个任务上午让它改 bug它会先看测试再动手下午让它改 bug它可能上来就开干完全不带测试。问题不是模型不行是我没有给它一套稳定的工作方式。templates 要解决的就是这个“工作方式不稳定”的问题。1.1 模板的本质是行为预设不是文档很多人把模板当成“一段写好的提示词”这种理解太窄了。在 claude-code 里模板更像是一份“入职手册”它不止告诉助手“你要做什么”还告诉它“你在这个项目里应该怎么思考、怎么动手、做到什么程度算完成”。举个例子。你可以在全局配置里写## 代码风格 - TypeScript 严格模式禁用 any - 组件使用函数式写法不使用 class 组件 - 提交信息统一格式: type(scope): subject这段内容不是给开发者看的是给 claude-code 每次启动时自动加载的“背景记忆”。它会让助手在写代码、提建议、生成提交信息时默认往这个方向靠。这就是模板的第一个价值把隐性的团队规范变成每次会话都会生效的显性上下文。1.2 模板能省下的是“沟通成本”和“返工成本”我在一个多项目环境里工作过一段时间每天要在三四个仓库之间切换。每个仓库的技术栈、目录结构、测试习惯都不一样。如果没有模板我每次都要敲一大段描述比如“这是 Python 项目用 poetry 管理依赖测试放在 tests/ 下改完必须跑一条指定命令”。这种话偶尔说一次没问题天天说就很崩溃。用了模板之后这些信息被固化到项目配置里。我只需要说“帮我改一下登录接口的 bug”助手会自动带着对应的规范去理解任务。省下来的不是几秒钟的输入时间而是避免了一系列因上下文缺失导致的返工它不会乱建文件不会用错依赖管理工具不会提交一个不符合规范的 commit。1.3 模板的价值上限取决于流程的标准化程度这里想泼一盆冷水如果你的开发流程本身是混乱的模板救不了你。它做的只是“固化”不是“创造”。我见过有人把一堆自相矛盾的规则塞进模板里结果 claude-code 执行起来左右互搏。所以搭建模板之前先花时间梳理自己的流程你希望它怎么开始任务先看代码还是先看文档产出物是什么格式什么情况下应该停下问人这些想清楚了模板才有意义。这也是我把“流程盘点”放在整个搭建过程第一步的原因。2. 拆解 claude-code 的模板体系四个层级各有分工claude-code 的模板不是单一文件它是一整套分层的配置体系。刚接触的人很容易只改一个文件然后抱怨“怎么不生效”其实是因为层级用错了。2.1 全局配置CLAUDE.md 和用户级设置它会在几处自动读取 Markdown 格式的说明文件最常见的是CLAUDE.md。你可以放在用户主目录下比如~/.claude/CLAUDE.md也可以放在项目根目录比如./CLAUDE.md。全局配置适合放“所有项目通用的偏好”。比如你习惯让助手先生成测试用例再写实现或者你要求它在每一步里使用中文注释。全局配置不用频繁改它是最底层的行为底色。我个人会在全局配置里放这些内容通用编程语言偏好比如默认使用严格类型、禁止魔法数字命令执行的注意事项比如长任务必须加超时控制回答风格比如解释问题时先给结论再给推导2.2 项目级配置决定“在这个仓库里怎么干活”项目根目录下的CLAUDE.md优先级更高它的作用是描述这个仓库特有的规则。我喜欢把它理解成“仓库的 README 伴侣”README 给人看CLAUDE.md给助手看。项目级配置里我会写# 项目说明 这是一个 FastAPI 服务目录结构如下 - app/ 下按模块组织代码 - tests/ 使用 pytest数据库操作一律 mock # 任务流程 1. 修改代码前先定位相关模块 2. 修改后运行 poetry run pytest 3. 通过后再给出 diff 摘要这套配置让 claude-code 进入仓库时自动带上“上下文”不用我每次重复。如果你是一个仓库里的常驻开发项目级配置的收益是最大的我强烈建议先从这里入手。2.3 命令模板斜杠命令的定制化能力除了配置说明它还支持自定义斜杠命令。你可以把一些高频操作整理成.md文件放在.claude/commands/目录下文件名就是命令名。比如我建了一个.claude/commands/review.md然后在 claude-code 会话里输入/review它就会执行我预设的代码审查流程。这里的关键理解是斜杠命令不是“执行预先写好的文本”而是“加载一段动态的指令让助手执行”。它可以在开头引用当前上下文、调用脚本、甚至读取用户输入。命令模板的设计自由度很高我后面会专门讲。2.4 子代理与技能更精细的分工单位再往下还有 subagents 和 skills 这一类更细粒度的机制。简单理解你可以定义一些“专才”子代理比如“测试编写专家”“性能分析专家”它们有各自的角色说明、可用工具和行为约束。主进程接任务后可以按需把这些子代理拉进来干活。这套机制本质上也是模板只是粒度更小、职责更单一。对于大型项目用子代理能显著减少“做什么都混在一起”的上下文混乱。我在重构老项目的时候就会专门定义一个“迁移专家”子代理让它只负责分析旧代码、输出迁移计划不碰其他杂事。3. 从零搭建一套模板库实操过程与参数设计理论上限说完了落到地上怎么搞我按自己搭过几套模板库的经验拆成五个步骤。这套方法不依赖具体项目任何技术栈都能用。3.1 盘点高频动作找出真正值得模板化的操作写模板最大的忌讳是“为了写而写”。先翻一翻你最近两周在终端里指挥 claude-code 做的事哪些重复次数超过三次我复盘下来最高频的是写 commit message、跑测试并修复、做代码审查、生成模块改动说明、排查报错。建议做一个简单的清单把任务分为三类高频固定型每周至少三次动作完全一致值得做命令模板低频但复杂型不常发生但操作链条长、容易漏步骤适合做子代理或流程模板一次性任务不需要模板临时说就行拿这个标准筛一遍最后沉淀下来的模板数量不会很多。我自己的库到现在也就十几个命令但每个都真的在用。3.2 设计模板结构目标、输入、约束、输出缺一不可一份好的命令模板至少要包含四块目标定义、输入参数、执行约束、输出格式。我见过很多不生效的模板问题就出在“只有目标”或“只有约束”。我在写模板时常用的骨架是这样的# PR Review ## 目标 以资深代码审查者的视角审查当前分支的改动发现逻辑错误、安全隐患和代码风格问题。 ## 输入 - 分支名: {{branch}} - 关注重点: {{focus}} ## 执行约束 1. 先 git diff origin/main...HEAD 拿到改动 2. 逐文件审查不跳跃、不凭记忆 3. 每个问题都要给出文件路径和行号暗示 4. 不提出与本次改动范围无关的建议 ## 输出格式 - 概况段改动规模、涉及模块 - 问题列表按严重程度排序 - 建议优先级必改、建议改、可选这里的“目标”给方向“输入”给参数“执行约束”管行为“输出格式”管成果缺一块都会让执行结果飘忽。3.3 理解变量与上下文传递让模板从静态变动态如果你只写死文字模板很快会僵化因为每次任务的具体目标不同。claude-code 的斜杠命令支持把用户输入的内容注入模板格式是$ARGUMENTS。比如我写了一个explain.md# 解释代码 请解释以下问题或代码段$ARGUMENTS 说明时按三层来 1. 这段代码的作用 2. 关键逻辑为什么要这么写 3. 潜在的问题点和改进方向调用时只要输入/explain 这个缓存为什么过期时间这么短助手就会把$ARGUMENTS里的内容当作具体目标来执行。这样模板是通用的但是每次执行是定制化的。另一个实用的技巧是利用命令行参数。在命令模板文件里可以配置allowed-tools、model等参数也可以引用$CLAUDE_PROJECT_DIR这类环境变量。我在写模板时会先确认项目根目录是否存在再决定从哪里读代码避免它在错误的路径下工作。3.4 实操案例一个可落地的“修复测试”命令模板我拿实际在用的模板举个例子它不是玩具是解决真实痛点的。我经常遇到“测试挂了要我看看”的任务于是建了.claude/commands/fixtest.md# 修复测试 ## 流程 1. 运行 $ARGUMENTS 指定的测试命令或自动探测项目测试命令 2. 阅读失败输出定位失败用例找到对应源码 3. 先分析失败原因不要直接改代码 4. 给出诊断说明确认修复方案后实施 5. 修复后重新运行测试直到通过 ## 约束 - 如果失败原因不明要求用户提供更多信息禁止瞎猜修复 - 最小化改动不顺手重构 - 修复完成后输出一份简明报告根因、改动文件、测试结果这个模板看起来简单但效果非常好。它把“看到失败就乱改”的行为控制住了。以前我指挥 claude-code 改测试它经常改了一个断言又挂另一个因为没有先做根因分析。模板强制它先诊断再动手返工率明显下降。3.5 模板的内部一致性检查写完模板别急着用先自己检查一遍。我喜欢用三个问题来自查如果把这个模板交给一个完全不熟悉项目的新人他能按步骤执行吗模板里有没有同时要求两件互相冲突的事输出格式是否明确到“看一眼就知道有没有完成”我吃过亏有一版模板要求“先看代码再提意见”后面又写着“快速给出总结”结果执行的时候它为了求快跳过了代码阅读。自那以后我会刻意删掉模板里所有模糊的修饰词只留明确的行为指令。4. 模板库的管理与团队共享目录结构、版本与命名规范个人用模板怎么舒服怎么来。但一旦涉及团队共享或者要长期维护就得引入工程化手段。这一节讲我如何组织模板库让它不变成一堆散落各处的 md 文件。4.1 目录组织全局还是项目倾向分明我的习惯是两层分法属于个人偏好的放~/.claude/属于仓库规则的放项目根目录.claude/。命令模板统一放.claude/commands/文件名即命令名。目录结构类似这样~/.claude/ ├── CLAUDE.md # 个人通用偏好 └── commands/ # 个人高频命令 ├── explain.md └── commit.md 项目根目录/ ├── CLAUDE.md # 仓库专属规则 └── .claude/ ├── commands/ │ └── review.md └── agents/ └── migration-expert.md这个结构的核心逻辑是越靠近项目的规则越容易被具体任务覆盖越全局的规则越稳定、越少改。我见过有人把所有规则全塞进项目级配置结果换一个仓库就完全水土不服。4.2 把模板库纳入版本管理我要强调一个很多人忽略的点模板是你工程资产的一部分必须进 git。我会给整个~/.claude单独建一个 dotfiles 仓库项目级模板则直接提交到各自的代码仓库里。这样改动可追溯出了问题还能回滚。项目级模板我建议和代码同步提交。比如这周团队决定以后新代码必须带测试我就会把这条规则写进CLAUDE.md和代码一起走 MR 流程。这样做有一个额外好处历史代码对应的模板版本是当时的规范不会因为后来规则变更导致无法复盘。4.3 命名规范与团队协作约定模板命名直接影响使用体验。斜杠命令是输入到终端里的必须好记。我遵循的规范是动词开头、不超过两个词、能表达完整动作。举例/fix修测试/review审查变更/commit生成提交信息/explain解释代码团队协作时我还会要求命令模板里的输出格式统一。不能一个人输出表格、另一个人输出大段文字。格式不统一会让大家觉得工具“不稳定”最后弃用。另外模板更新要经过评审。我们团队约定任何涉及公共命令模板的改动都要在 PR 描述里写清楚“旧行为是什么、新行为是什么、为什么改”。否则很容易出现有人改了模板别人还按旧习惯用结果行为突变、一脸懵。4.4 同步机制让团队模板保持最新团队里如果用同一套模板同步是一个容易被忽视的坑。我是这样解决的公共命令模板放在一个独立的配置仓库里团队成员通过拉取更新来同步。同时搭配一个简单的自检命令启动时检查本地模板和远端模板的版本号不一致就提示。这种做法不复杂但能把“我模板怎么和你不一样”的沟通成本降下去。如果你只是个人使用只需要保证 dotfiles 仓库有备份换机器时拉下来就行。5. 常见问题与排查技巧实录我用了 claude-code 模板一段时间踩过不少坑。这里挑几个最有代表性的问题附上排查思路和最终解法希望能帮你少走弯路。5.1 模板太长导致上下文膨胀刚开始写模板总觉得写得越全越好。结果一段 3000 字的模板加载进去每次对话都要占大量 token反而让助手在无关信息里淹没了重点。排查方法是用 claude-code 的上下文视角功能比如/context看当前会话加载了哪些内容。如果模板占了三分之一篇幅就该精简了。我后来遵循一个原则模板里只留“会影响行为差异”的信息背景知识能不放就不放。5.2 模板指令互相冲突典型症状模板写了“先写测试再写实现”但另一个文件里写着“提高开发速度优先完成功能”。当冲突出现时助手的行为就变得随机时好时坏。我处理冲突的方法是分层定优先命令模板 项目级 CLAUDE.md 全局配置 默认行为。然后在模板里明确注明“如果与高层配置冲突以本模板为准”。这也是我前面强调内部一致性检查的原因。5.3 变量注入失败命令不按预期执行$ARGUMENTS这个变量偶尔会因为格式问题注入失败。比如调用/explain --detail 这段代码如果模板里没有定义如何解析--detail整个字符串会被当成一个参数传进去导致行为偏差。排查方式是先用一个极简模板做测试只输出$ARGUMENTS的原始内容看看它到底收到了什么。确认格式后再逐步加复杂逻辑。另外我建议模板开头就对参数做校验如果发现空参数直接提示用法而不是默默执行。5.4 助手“假装做完了”模板里缺少完成定义这个问题不只在模板场景下出现但模板可以缓解它。我发现如果模板没有定义“什么叫完成”助手可能会在测试没跑、警告没清的情况下就说“修复完成”。解决办法是在模板尾部加一段强制自我检查## 完成标准 - 相关测试已运行且通过贴出关键输出 - 无新增的愚蠢告警 - 改动影响范围已说明 - 如果存在未完成项明确列出不隐藏这个“明确列出未完成项”的约束很有效它堵住了“假装完成”的口子。5.5 无法复现问题时的调试手段模板种类太多有时候出了问题不好定位。我的调试顺序很固定先看模板文件是否被正确加载再看变量是否按预期注入最后看执行日志。用--debug模式跑一次能捕捉到助手收到什么指令、做了什么决策。大多数“模板失效”最后都定位到三个原因文件路径不对、文件名拼错、变量格式有误。症状可能原因排查方向命令找不到文件没放在 commands 目录检查路径和文件名命令执行但行为不像预设模板未被加载检查是否有高层配置覆盖变量内容不对参数格式或解析问题先回显$ARGUMENTS规则冲突、行为随机多层模板打架调整优先级并写明冲突策略这张表我打印出来贴在手边出现问题时照着排查效率高很多。6. 模板的进阶玩法把行为契约接入工作流如果你已经能把基础模板玩明白可以再往前一步把模板当作“行为契约”接进更大的工作流里。这里分享两个我实际用得很顺的方向。6.1 让模板成为 CI 之外的“本地守门员”我做的很多改动不会每次都推上去跑 CI。与其依赖远端流水线不如在本地就让 claude-code 按模板执行一轮检查。比如我的pre-push.md模板会做检查 diff 里是否有调试打印、是否新增了未使用的导入、提交信息是否符合规范。这些规则原本依赖人来盯现在变成模板内的固定检查项。接入方法是把模板和 git hook 结合起来push 前触发一个脚本脚本调用 claude-code 在非交互模式下跑一遍检查失败就阻止提交。这种方式让规范变成了工具的一部分而不是贴在 README 里的空话。6.2 从模板到“技能包”跨环境复用如果你在多个团队、多个项目里反复使用同类模板可以考虑把它们打包成“技能包”而不是在每个仓库复制一遍。比如“前端改版流程”包含设计审查、组件拆分、样式规范、验收清单这些内容可以做成一份独立模板在需要时通过一条命令导入项目。我目前的做法是把通用流程模板放在一个独立仓库里按场景分目录项目需要时用一条安装命令把对应场景的模板软链到项目.claude/commands/下。这样既保留项目独立性又避免重复维护多份拷贝。6.3 保留“人工复核”的底线最后说一条我认为很重要的经验模板再完善也要保留人工复核环节。claude-code 模板能做的是提高一致性和效率它替代不了人对产品方向和技术方案的判断。我的习惯是任何由模板自动生成的改动我会过一遍 diff重点看有没有“看似合理但方向跑偏”的地方。这不是不信任工具而是对结果的负责。把模板当成一个能力很强的初级工程师它会按流程干活但最终把关的人还是你。我在实际使用中最大的体会是模板的意义不在于“少敲几个字”而在于让工具的行为可预期、可控制、可演进。你投入时间去梳理流程、写模板、调参数换回来的是每次会话都稳定靠谱的产出。如果你还没开始找一个最高频的任务按照这篇里的结构写一份模板用上一周你会明显感觉到差别。