如果你现在还在把claude-code当成一个高级聊天框一条消息一个回车地去喂问题那我建议你先停下来花十分钟把这篇看完。我过去两个多月的实际感受是不管用哪个命令行 AI 编程工具真正拉开效率差距的从来不是某一条提示词写得有多花哨而是你有没有一套属于自己的templates。这里说的 templates不是网上那种30 个万能 prompt 合集而是长在你项目里的、可复用、可演进的一套提示词骨架。我最早用 claude-code 的时候什么都是现场想让它看一段报错让它重构一个函数让它做代码 review。听起来很灵活实际用下来全是重复劳动。同一个仓库我每天要重新交代一遍技术栈、目录结构、编码规范同一个类型的任务我每次都要用不同的措辞描述输出自然忽好忽坏。后来我把 claude-code 升级到支持自定义命令的版本又去翻了不少团队的公开配置最终搭出了一套稳定运行的模板体系。这篇文章不打算讲太多理论核心是把我的目录结构、模板文件、设计思路、踩坑记录全部摊开。内容偏实战适合正在用 claude-code 写实际项目、又觉得每次对话都不够连续的人。读完你至少能搭出第一版自己的模板库并且知道怎么让它随项目长大。1. 先说说我为什么要给 Claude Code 配一套自己的 templates很多人的第一反应是claude-code 本来就有上下文记忆我把背景说一次它不就记住了吗理论上是这样但实际体验完全不是那么回事。下面这几个痛点我猜大多数人都不陌生。1.1 散装提示词的三个具体痛点第一个痛点是上下文断裂。有一次我上午让 claude-code 分析一个模块的耦合关系下午接着让它改这个模块的测试它完全忘了上午的结论又把代码从头读了一遍。要么我把上午的分析结果重新发一遍要么让它重新扫描一堆文件一来一回十分钟就没了。这还算是轻的更常见的是同一个项目背景下每开一个新会话都要重复交代这个项目是 Python 写的、用 FastAPI、数据库是 Postgres、代码在app/和tests/下。说多了自己都烦。第二个痛点是提示词质量不稳定。我试过在精神好的时候写一段很精确的 prompt输出相当漂亮也试过赶进度时只丢一句帮我看看这个报错结果它天马行空地给了七八种猜测没有一种对症。人不是机器状态波动难免但提示词工程恰恰是不能靠临场发挥的。既然我白天写代码都知道要抽公共函数为什么写 prompt 反而每次都从零手写第三个痛点是跨项目经验无法沉淀。在 A 项目里好不容易总结出一套如何让模型做代码审查的靠谱指令换到 B 项目全忘了又得重新调。等到某一天我突然想干脆把这些反复使用的指令固化成文件让 claude-code 直接读取于是就有了我自己的 templates 体系。整套东西不复杂但确实解决了前面三个问题的绝大部分。1.2 模板的本质不是让模型变笨而是给它一个稳定的工作台有人担心模板写多了会限制 claude-code 的灵活性。我的观点刚好相反。模板把你希望模型怎么思考这件事固定下来模型反而可以在一个更清晰的框架里发挥。这就像你给一个高级工程师一份 issue 描述模板他不会因为模板就变蠢反而能把精力放在真正需要判断力的地方。当然模板不能是一堆细到行的指令。比较合理的定位是模板规定思考路径、输出结构、检查清单而具体代码怎么改、用哪个方案仍然要留给模型基于上下文判断。后面我给的每个模板文件都会把这两件事分开处理。1.3 我期望自己的模板库达到什么效果我对这套模板的验收标准只有三条新开一个会话时我能用一条命令唤起完整任务流程不需要重复交代背景同一类任务连续跑三次输出结构基本一致质量波动控制在可接受范围模板能随项目一起维护团队其他人拉下来也能用而不是只存在于我某个终端的临时输入里。这三条分别对应自动化、稳定性、可共享。也是后面所有设计决策的出发点。2. 模板库的最小可行架构两个目录加一份约定一开始不要设计得太宏大。什么模板分类器、多级目录、动态加载都不需要。先跑通最小闭环再慢慢加东西。我的第一版模板库只有两个目录加一份约定。2.1 目录结构长什么样我现在的标准结构是这样的~/.claude/ └── CLAUDE.md 项目根目录/ └── .claude/ ├── CLAUDE.md └── commands/ ├── review.md ├── debug.md ├── research.md ├── refactor.md └── commit.md~/.claude/CLAUDE.md是全局指令适合放通用偏好比如优先使用 Python 标准库代码注释要简洁回答问题前先列出假设。项目根目录下的.claude/CLAUDE.md放项目专属背景比如技术栈、目录说明、构建命令、测试命令。commands/目录下每个.md文件代表一个自定义命令。在 claude-code 里如果你在支持自定义命令的版本中输入/review它就会读取.claude/commands/review.md的内容把它和你的输入一起作为提示词。这个机制非常关键模板不是复制粘贴而是变成一个可以随时调用的函数。2.2 全局模板和项目模板的分工很多人会把所有内容一股脑塞进全局模板。我吃过这个亏。全局模板一旦太长每个会话都会带上一大段背景模型容易失去重点。我的原则是位置适合放什么不适合放什么全局~/.claude/CLAUDE.md跨项目的个人偏好、通用工作流、禁用事项具体项目的目录结构、依赖版本、专有名词项目.claude/CLAUDE.md项目背景、技术栈、构建测试方式、架构约束个人偏好、和项目无关的通用规则项目.claude/commands/一次性的任务型指令如 review、refactor长期不变的背景信息刚开始我把所有项目的信息全写在全局里换项目后模型老记混后来才拆开。这一点如果你也想搭模板第一步就要想清楚不然后面维护成本会很高。2.3 模板文件的内部格式约定每个命令模板我基本都遵循同一套结构任务目标用一两句话说明要完成什么背景与输入哪些信息由模板自带哪些信息需要用户补充执行步骤按顺序列出模型应该怎么做输出格式定义最终交付物长什么样自检清单让模型在输出前检查一遍是否有遗漏。还有一个约定模板里用$ARGUMENTS接收用户输入。比如输入/debug 登录接口偶发 500模板里的$ARGUMENTS会被替换成登录接口偶发 500。这个占位符非常有用我后面所有模板都依赖它。2.4 从零跑起第一条模板第一步创建一个测试命令文件mkdir -p .claude/commands cat .claude/commands/echo.md EOF 用户输入的内容是$ARGUMENTS 请把这段内容整理成三条要点然后逐条说明你理解的意图。 EOF第二步在终端启动 claude-code输入/echo 我希望你帮我做一次数据库性能分析第三步观察输出。如果生成的回复明确提到了数据库性能分析并且做了三点整理说明命令机制已经生效。接下来就可以把日常反复使用的任务逐步沉淀到commands/目录里。这一步是整个模板库从概念到落地的关键不要跳过。3. 五种高频模板的完整写法和设计思路我的commands/目录里真正高频使用的主要有五个。每个都会给一个简化但可用的版本并说明我为什么这么设计。3.1 代码审查模板把随便看看变成按清单排查代码审查是我最常用的场景。早期我直接说review 一下我的代码改动模型会给我泛泛的建议代码清晰、逻辑正确、建议补充测试。这种输出没有用。后来我改成下面这个模板请对当前 Git 分支中尚未合并的改动进行代码审查。 背景说明 - 项目语言与框架$PROJECT_LANG如未配置先读取 .claude/CLAUDE.md - 审查重点$ARGUMENTS可为空空则按以下默认重点 必须依次完成 1. 先查看 git diff列出所有变更文件并按影响范围排序 2. 对每个文件检查逻辑正确性、边界条件、资源泄漏、安全隐患 3. 特别关注本次改动是否破坏了原有的公共接口或数据结构 4. 对可疑行给出具体行号和建议修改片段。 输出要求 - 按问题严重程度分组输出阻塞问题、建议修改、可选优化 - 每个问题必须包含文件路径、行号、问题描述、修改建议 - 最后追加一段总结说明本次改动的整体风险等级。这个模板的核心在于把审查拆成了可执行的步骤。特别是先查看 git diff 再逐文件检查这一步它强制模型不要凭空想象而是先建立事实清单。我试过不加这个步骤时模型会一本正经地审查一个不存在的文件。实际使用中我发现参数里写没有空则按默认重点很重要。有一次我输入/review 重点看并发安全问题它就会把默认重点暂时放一边集中检查锁和线程安全。如果你希望模板更稳可以把$ARGUMENTS作为可选项而不是必填项。3.2 报错排查模板让模型先诊断别急着开药方排查报错也是高频场景。很多人在 claude-code 里贴一段日志然后问怎么解决模型会直接给一个可能的修复方案。这个方案的命中率取决于日志信息量。我的模板强制先诊断请帮我排查一个错误。 错误现场 $ARGUMENTS 执行流程务必遵守 1. 先复述你看到的错误现象不超过三句话 2. 列出可能导致该错误的三个根因按概率从高到低排序 3. 针对概率最高的根因告诉我需要查看哪些文件、执行什么命令来验证 4. 在我提供验证结果之后再给出修复方案。 禁止事项 - 禁止在验证根因之前直接给出修改代码 - 禁止只凭日志猜测而不读取项目中的相关代码 - 如果日志信息不足必须先明确询问还需要哪些信息。这个模板的价值在于把诊断和治疗分开。很多模型包括我在用 claude-code 时也发现天生倾向于快速给答案但这在调试场景是危险的万一改了错误的地方问题反而更隐蔽。加了禁止在验证前给修复方案之后输出质量明显提升尤其适合那些你不太熟悉的第三方库报错。3.3 技术调研模板把帮我查查变成一份决策备忘技术选型或者调研新库时我的模板长这样我需要做一个技术调研最终输出一份决策备忘。 调研主题$ARGUMENTS 约束条件 - 如果项目背景中已有技术栈信息必须基于现有栈做对比 - 优先考虑稳定性、社区活跃度、与现有代码的兼容性 - 不要求面面俱到但要给出明确倾向和建议。 输出格式 1. 一句话结论 2. 备选方案横向对比表维度维护状态、API 稳定性、学习成本、适用场景 3. 推荐方案及理由 4. 落地时可能遇到的三个主要风险 5. 如果推荐方案不采用Plan B 是什么。这个模板直接改变了调研类对话的质量。之前我让模型比较一下 ORM 框架选型它会给我一篇冗长的文章什么都说了但看完了我还是不知道选哪个。现在模板要求一句话结论在开头模型就必须把它真正思考过的倾向说出来。哪怕这个倾向不完全对我也能快速进入质疑和讨论而不是面对一堆信息。3.4 重构计划模板让一次大改动变成有序步骤重构是最容易在模板里翻车的领域因为不同项目的差异太大。我现在的模板只约束计划而不直接让人改我要对现有代码做一次重构请帮我制定一个可执行的重构计划。 重构目标与范围$ARGUMENTS 步骤要求 1. 先梳理当前代码结构与关键入口列出涉及的文件清单 2. 识别重构风险对外接口、数据格式、错误处理、性能瓶颈 3. 将重构拆分为多个小步骤每个步骤必须可以独立提交且不破坏现有功能 4. 在每一步骤中标注需要补充哪些测试 5. 最后给出回滚方案。 输出要求 - 不要一次性给出改完所有文件的大补丁 - 每个步骤都要包含目标文件、关键改动、验证方式。这个模板最适合那些你心里知道要重构但不知道怎么切分的场景。它迫使模型把大改动拆成小步并且强制包含验证和回滚方案。我第一次用它拆一个两千行模块的重构时模型给出的步骤比我之前自己分的还清晰我只需要逐个步骤执行和验证。3.5 提交信息与变更说明模板沉淀团队的表达习惯最后一个模板相对简单但价值常常被低估请根据当前 git diff 生成提交信息或者变更说明。 输入信息$ARGUMENTS 要求 1. 先读取 git diff --stat了解改动文件范围 2. 再读取 git diff提取主要变更点 3. 按照动机-改动-影响的结构组织内容 4. 提交信息控制在 50 字以内变更说明可以适当扩展 5. 如果改动涉及破坏性变更必须单独标注。 输出格式 - 提交信息一句话 - 变更说明按模块列出 - Breaking Change 列表如有。这个模板帮我解决了一个之前很烦的问题模型每次生成的 commit message 风格都不同。有人喜欢动词开头有人喜欢描述业务而模板可以统一风格。更重要的是它要求先看git diff --stat再细读 diff避免模型根据文件名乱猜。4. 模板怎么和项目上下文协作而不是互相打架模板不是孤立存在的。它和CLAUDE.md、项目结构、用户输入这三者共同作用。很多模板效果不好不是因为内容不对而是因为上下文粒度没配好。4.1 占位符设计从必填卡槽到可选补充模板里不是信息越多越好。我给模板设计输入时只保留两类占位符必填项没有它任务就无法开始通常放在$ARGUMENTS里可选项有它可以让结果更精确没有则用默认规则替代。比如代码审查模板里$ARGUMENTS是可选的因为默认审查行为已经足够。而在技术调研模板里$ARGUMENTS就是必填的因为连调研对象都没有整个任务没有锚点。这个逻辑听起来很简单但我看过很多人的模板把所有可能用到的变量全部列了一遍模型一上来先被变量列表绕晕了。4.2 用 CLAUDE.md 管背景命令模板管动作这是我认为目前最顺手的协作方式。项目背景放在.claude/CLAUDE.md命令模板里不需要重复描述项目技术栈。比如我的项目 CLAUDE.md 里有一段# 项目背景 - 语言Python 3.11 - Web 框架FastAPI - 数据库PostgreSQL通过 SQLAlchemy 访问 - 目录约定api/ 放路由services/ 放业务逻辑models/ 放 ORM - 测试pytest httpx测试数据库使用 sqlite 内存模式然后我的review.md模板里只要写请结合项目背景信息进行代码审查而不用把上面这段再抄一遍。模板负责告诉模型要审查、怎么审查CLAUDE.md 负责告诉模型这个项目的常识是什么。两层分离之后同一个模板在不同项目里都会自动带上对应的项目认知。4.3 用分支指令让模板保留弹性模板的执笔思路不该是一条直线。如果条件 A走流程 B如果条件 C走流程 D这种方式可以让模板具备适应性。比如调试模板里我加了这么一段如果错误信息包含timeout或timed out - 优先检查网络超时配置、连接池大小、外部接口响应时间 如果错误信息包含null或空值 - 优先检查数据初始化流程、SQL 结果集为空时的处理逻辑 如果错误信息包含permission denied - 优先检查文件权限、鉴权中间件、数据库用户权限。你不一定需要覆盖所有错误类型但只需要把你常见的那三四种写进去模板的命中率就会提高很多。模型本身理解不了这段项目里最长出现哪些错这种抽象统计但你能。4.4 两段式模板先采集再执行有些任务需要先收集信息才能动工比如帮我修一个偶现 bug。如果你在模板里直接要求模型修复它手上的信息太少了。我的做法是把一整个流程拆成两段放在同一个模板里第一段信息采集 - 请列出定位该问题需要知道的五项关键信息 - 对于每个信息告诉我可以通过什么命令或查看哪个文件获得 - 不要执行修改操作。 第二段执行条件 - 在我提供上面五项信息之后你才开始提出修复假设 - 修复假设必须给出验证方式并通过实际操作完成验证。这种模板看上去没有一步到位实际上却把最难的 bug 排查变成了一个标准化的信息收集流程。模型被要求先问问题我的思考负担大大降低只需要按清单提供信息。5. 模板库的版本维护、验证与团队落地模板不是写一次就完了。它会随项目演化也会因为 claude-code 版本更新而改变效果。如果你只是在自己的终端里用可以不那么规范但一旦想分享给团队下面这些事情就必须做。5.1 把模板当作代码一样做版本管理我给自己的模板建了一个独立 Git 仓库并且通过脚本批量复制到各个项目的.claude/commands/目录。每次改动都会提交并写明原因。这样做最大的好处是改坏了能快速回滚。如果你懒得维护独立仓库最低限度也要把.claude/目录纳入项目仓库。否则团队成员各自维护一份很快又会出现同一个命令在不同人那里行为不同的情况。我的提交信息通常是这样的feat(commands): 新增按严重程度分组的代码审查输出 - 调整 review.md 的输出结构 - 将阻塞问题/建议修改/可选优化分组改为必填 - 增加行号缺失时的自动补充逻辑不要小看模板库的提交记录它承接着团队的无形知识。几个月后你再回头看能清楚知道当时为什么这么做。5.2 模板的回归验证方法模板改动最怕的是这次输入效果变好了但另一次输入效果变差。为了对抗这种不确定性我给高频模板准备了一份固定的回归用例集。具体做法是每个模板对应一个测试输入存在一个test_cases/目录里。改动模板后把测试输入作为$ARGUMENTS跑一遍人工检查输出结构是否完整、关键步骤是否保留。比如review.md的回归用例是review 本次新增的 authentication 模块改动重点检查越权漏洞。只要输出里包含文件路径、行号、漏洞分析、修改建议就算通过。这个方法不复杂但它能阻止你越改越差。尤其是共享给团队之后你不想在改动模板的第二天收到同事的抱怨。5.3 团队共享时的命名与权限约定模板一旦进入团队命名就要规范。我的建议是模板名任务类型典型场景review审查分支代码审查debug调试报错根因分析research调研技术选型对比refactor重构模块结构优化commit写作提交信息生成不要用test-help、write-code这样含义模糊的名字更不要用拼音。命令是会被频繁输入的东西越短越好。等团队成员都习惯这套命令后协作成本会显著下降一个人说跑一下 /review所有人都知道结果长什么样。5.4 避免模板成为个人英雄主义产物我有一个很深的教训第一版模板全是我个人偏好的体现团队里用了几天几个人开始抱怨生成的代码风格干巴巴模板太霸道。问题不在模板而在于我没有留出团队自定义的空间。后来我在项目CLAUDE.md里增加了一个团队补充约定的区块允许各模块负责人在里面追加自己的边界规则。比如有人要求所有涉及数据库操作的函数必须显式释放连接就会写进这个区块。模板只提供共性流程团队差异由项目级配置承载。这样模板库才不会变成推行的阻力。6. 那些翻过车之后我留了教训的模板写法最后这部分我想直接讲失败经验。很多最好的模板设计不是一次想出来的而是踩坑踩出来的。6.1 模板太长模型找不到重点最早我把代码审查模板写成了 80 行涵盖了从代码风格到架构一致性的所有检查项。结果模型每次输出都是一篇千字长文看着全面实际几乎没有可执行的结论。原因很简单模板给的信息量太大目标和边界反而糊了。后来我把模板压缩到核心步骤那些细致的检查项全部变成一个引用列表放在参考但不强制的位置。效果反而更好模型能集中精力处理真正重要的逻辑问题。模板不是越完善越好而是越聚焦越好。6.2 强制 JSON 输出导致的循环有一段时间我非常迷恋结构化输出要求所有模板以 JSON 结尾。模型确实会照做但代价是它花大量时间思考如何把内容塞进 JSON schema而不是思考任务本身。尤其是一次输出超长时模型会更频繁地改写 JSON 格式甚至出现自己跟自己较劲的情况。这个坑让我反思模板强制的是思维流程不是序列化格式。后来我只在少数确实需要程序读取的模板里保留 JSON 输出其他模板一律使用 Markdown 分组输出。可读性大大提高模型也更愿意给出细节。6.3 把版本号写死在模板里我在技术调研模板里曾写死过一句优先使用 XinYun 依赖库 3.2.1 版本几个月后这个版本停维护了。另一个项目里我写死过 Node 版本导致后来切到新环境时模板一直在给出被弃用的安装方式。模板里的具体版本号、硬编码路径、过期的命令都是定时炸弹。现在我规定模板里凡是涉及版本和路径的地方一律从项目CLAUDE.md读取或者在模板里注明以项目中实际使用的版本为准不要自己假设。这个规则的受益面非常大。6.4 一个模板试图适配所有语言早期我的代码审查模板有很重的 Python 痕迹比如检查列表推导式是否过度使用结果切到 Go 项目时模型还在输出 Python 相关建议。后来我学乖了模板开头加一句在开始审查前先确认当前项目的编程语言与框架并基于该语言的惯例进行审查如果语言是 Go忽略 Python 专属建议。虽然这句更像防呆设计但确实拦截了大多数跨项目水土不服的场景。模板里可复用的是审查逻辑而不是某个语言的具体教条。现在我对模板库的态度是它就是一个每天都会小步更新的工具集不需要完美但必须真实反映项目状态。每当我发现同一个任务连续三次都要手工微调提示词就会把它吸收进模板每当我发现某个模板连续两周都没用就会把它删掉或合并。模板的价值在于让 claude-code 更贴近你的团队和项目而不是让你变成一个只会打命令的机械工。最后分享一个我现在还在坚持的习惯每次给模板升级时我都顺手写一条备注记录它解决的是哪件真实的事。比如review 模板增加行号检查是因为上周漏掉一个越权问题。记录得越具体模板库越不容易腐烂。