我第一次用 Claude Code 的时候其实不太顺利。每开始一个新任务都要在提示词里重新交代项目背景、技术栈、代码风格、验收标准一套流程下来等我折腾完热情已经消耗一半。更麻烦的是就算交代了它也经常在中间环节忘记我后面的约束。后来我试着把经常用的 prompt 整理成模板统一放进一个仓库管理这才终于体验到“一条命令就进入状态”的感觉。这篇文章就聊聊我的 claude-code-templates 积累过程包括模板分类、目录结构、加载方式以及那些真正踩过的坑。1. 为什么需要一套 claude-code-templates1.1 真正的问题不是 AI 不聪明而是你每次都在重新解释Claude Code 本身能力不弱但是它的“记忆”完全依赖当前会话里的上下文。你给它看了什么、说了什么它才知道什么你没写的它只能靠猜。一旦项目变大你不可能每次都把几十个文件的核心约束重新粘进对话里更不可能要求每个参与的人都记得同样一套规则。我印象很深的一次让 Claude 帮忙重构一个订单服务类。我在对话里写了“不要动接口签名保留现有日志不要引入新依赖”结果几分钟后它直接把方法签名改了还顺手加了一个我没见过的工具库。问题不是它能力不够而是我给的指令只对当前轮有效下一轮它开始自由发挥。后来我把这类约束写成一个固定模板每次调用时自动带出来效果立刻稳定很多。1.2 模板解决的是“上下文与状态”的确定性模板的本质是把一组经过验证的、跨任务复用的指令沉淀成静态资产。你可以把它理解成菜谱。菜谱不会替你煎牛排的熟度但它能保证你每次下锅前都知道要放多少油、用多大火不会因为今天心情不同就乱洒调料。Claude Code 也是一样模板化的 prompt 能降低两件事的不确定性模型的输出风格和关注点是否稳定你和模型在最开始的若干轮里到底把注意力花在“对齐规则”还是“解决任务”上。用模板还有一个隐性好处省 token。同样一句“先给方案不要直接改代码”写死在一个文件里你只需要在模板里出现一次如果靠现场手写大概率每次都要重复最后还写得不如模板精确。1.3 这套模板适合谁、能覆盖什么场景我最推荐下面几类人认真整理自己的 claude-code-templates已经在用 Claude Code 写业务代码但觉得每次对话“启动成本”很高的人团队有多人共用同一个仓库希望 AI 的 Review 和提交信息风格保持一致的人希望把个人经验沉淀成资产而不是每次靠临场发挥的人。它覆盖的场景很广日常任务拆解、代码审查、重构、生成提交信息、补文档、定位线上问题几乎每个动作都可以模板化。唯一不太适合模板化的是那种一次性的纯知识问答比如“解释一下什么是 B 树”这种情况直接问就好套模板反而显得累赘。2. 模板的核心分类与设计拆解2.1 角色与行为模板先在开头把“人设”立住很多人使用 Claude Code 时喜欢一上来就甩任务但忘了一个关键步骤告诉模型它现在扮演谁、受什么约束。一个没有角色边界的模型回答问题的自由度太高容易跑偏。所以我第一个模板通常是“角色与行为约束”它的作用相当于给模型划定工作半径。我常用的基础模板长这样你是一名资深后端工程师熟悉 Java/Spring Boot 项目。 当前项目背景 - 技术栈Java 21 Maven PostgreSQL - 包结构按业务模块分包repository 层统一使用 MyBatis-Plus - 代码风格Google Java Format私有方法放在类底部 工作原则 1. 先理解需求再给出方案不要直接改代码 2. 所有建议必须说明对现有模块的影响面 3. 不引入不必要的依赖优先复用现有工具类 4. 涉及删除代码时先说明删了会影响哪些调用方。 输出要求 - 使用 Markdown 列表简洁为主 - 代码块必须标注语言 - 存在风险点放在“注意”一栏。这个模板的价值不在文采而在把团队约定固化下来。实际使用中我发现角色说明越具体越能减少“我本来想让它在某条业务线上做纵深它却在通用能力上泛泛而谈”的情况。注意不要写成一篇几千字的“人格设定”模型不会和你玩扮演游戏它只需要清晰、可执行的边界。2.2 任务拆解模板从一句话到可执行计划用户给 Claude Code 最常提的说法是“帮我做一个功能”这其实是反模式。缺少目标、约束和验收条件的任务模型只能靠猜而且容易一步到位地改代码。我后来强制自己使用“任务拆解模板”把模糊请求变成结构化指令。模板的设计分成五个部分目标、约束、输入、输出、验收标准。请按以下结构完成开发任务 目标 {一句话描述你要达成的结果} 约束 - 不能改动 {受保护的文件/接口} - 保持与现有 {模块/风格} 一致 - 性能要求{例如单次查询耗时不超过 200ms} 输入 - 相关代码文件{路径列表} - 相关业务背景{补充说明} 输出 1. 实现方案简述 2. 关键代码 diff 3. 自测步骤 4. 潜在风险。 验收标准 - {标准 1可执行的检查项} - {标准 2可执行的检查项}这套模板让我最受益的地方是“验收标准”一栏。以前 Claude 经常告诉我“完成了”但到底怎么算完成双方理解完全不同。现在有了验收项它会在动手前自己先核对一遍极大减少了“做完但没做对”的返工。2.3 代码审查模板让 Review 不停留在“看起来没问题”把 Claude Code 用于代码审查其实比写代码更稳。生成代码时它会兴奋地“创造”但审查时它更容易调用分析能力。不过如果你只丢一句“帮我 review 一下”它大概率会回你一堆“看起来很好”的空话。我需要的是一个能强制它逐项检查的 checklist 模板。下面是我一直在用的审查模板请审查当前代码改动重点检查以下维度 1. 正确性 - 是否存在空指针、越界、并发问题 - 边界条件是否被覆盖 - 异常路径是否会导致状态不一致。 2. 性能 - 是否有 N1 查询或不必要的全表扫描 - 是否创建了重复对象 - 大数据量下是否存在内存隐患。 3. 安全 - 是否存在 SQL 注入 / XSS 等风险 - 是否对用户输入做了校验。 4. 可读性与维护性 - 命名是否清晰 - 是否有可以抽取的重复逻辑 - 新增代码是否遵循项目现有模式。 5. 测试 - 关键逻辑是否有对应单测 - 测试是否覆盖了失败路径。 输出格式 - 按严重程度分级阻塞 / 重要 / 建议 - 每个问题必须附上具体文件和行号 - 没有问题的维度也要明确写“未发现问题”不要默认跳过。这个模板执行一次后我基本不需要再追问补充意见。它最核心的一点是“没有问题的维度也要写未发现问题”这会倒逼模型真实检查而不是敷衍地夸一句。对个人项目和团队 Review 都适用。2.4 文档与提交信息模板把琐碎收尾变成固定动作开发中最容易被忽略的是收尾动作。写完代码后提交信息和更新文档属于枯燥但必不可少的步骤。模板在这里的价值不是提高生成速度而是保持风格统一让 Git 历史看起来像一个“人”提交的。我这里的提交信息模板基于 Conventional Commits 做了简化请根据当前改动生成提交信息。 要求 1. 使用 Conventional Commits 格式 2. type 从以下值中选择 feat, fix, refactor, docs, test, chore, perf, style 3. 主题不超过 50 个字符 4. scope 必须写对应模块名例如feat(order-service) 5. 正文按“为什么改”和“改了什么”两个部分组织 6. 如果涉及破坏性变更在尾部用 BREAKING CHANGE 标注。 当前改动 {可以由模型读取 git diff 后自动填充}文档模板则是给“写完代码后补一段设计说明”用的一般包含背景、方案选型、调用方式、注意事项。用模板的好处很明显Claude 输出的文档不会再出现一堆空话而是按照你关心的维度逐条展开。实践下来文档模板和提交信息模板加起来基本能覆盖项目里 90% 的琐碎收尾。3. 实操从零搭建你的 claude-code-templates 项目3.1 仓库结构与模板格式选择先回答一个常见问题模板用什么格式保存我的答案是纯 Markdown不要用 JSON更不要自定义 DSL。原因有三个Markdown 本身就是 Claude 最熟悉的输入格式它不会理解错层级Markdown 可以用 Git 做 diff模板改动历史清清楚楚团队成员即使不熟悉代码也能看懂模板内容。我的仓库结构非常简单claude-code-templates/ ├── CLAUDE.md ├── README.md └── commands/ ├── review.md ├── task.md ├── docs.md └── commit.md其中CLAUDE.md是给 Claude Code 的“项目级长期记忆”commands/目录放可以一键触发的命令模板。如果是个人使用这个规模完全够了团队用的话可以按业务模块再拆子目录。为什么不做成一个庞大的“全家桶”因为模板一旦太多加载和检索成本反而超过手工写 prompt 的成本。我见过有人收集了几百个模板结果一个都不常用那不是效率工具是收藏癖。真正的模板库应该保持“够用且精炼”。3.2 利用 CLAUDE.md 承载项目级长期约束Claude Code 有一个很关键的特性如果项目根目录存在CLAUDE.md它会在一开始就把这个文件作为长期上下文带入对话。我在模板仓库的根目录放了一份CLAUDE.md内容不是具体 prompt而是仓库说明和调用约定# claude-code-templates 本仓库用于存储和 Claude Code 协作时的高频模板。 ## 目录说明 - commands/ 下的 .md 文件对应同名 slash command - 每个命令文件必须包含 description - 命令内容应保持可执行不要出现空泛描述。 ## 使用约定 - 调用代码审查时使用 /review - 发起任务拆解时使用 /task - 生成提交信息时使用 /commit - 所有模板只写约束不写具体实现细节。如果你只是在普通项目中使用 Claude Code也可以在项目根目录维护一份类似的文件把技术栈、包结构、部署命令、特殊约定都写进去。这样每一次启动对话模型天然知道“我在哪里、能做什么、不能做什么”。我个人的体会是项目级CLAUDE.md比任何复杂 prompt 都管用因为它根本不需要你每次粘贴就已经在上下文里了。3.3 把模板注册成 Slash Command 并调用如果每次用模板都要打开文件、复制、粘贴那使用成本仍然太高。正确的方式是把模板注册成 Slash Command。在 Claude Code 中项目级命令存放在.claude/commands/目录下文件名去掉.md就是命令名。比如我在.claude/commands/review.md里写入--- description: 按团队规范执行代码审查 --- 请审查当前改动重点检查正确性、性能、安全、可读性和测试覆盖。 按阻塞/重要/建议三级输出问题并标注具体文件与行号。保存后在当前项目里启动 Claude Code直接输入/review它就会把模板内容作为指令带入当前会话。这个命令文件里的description字段是给命令选择列表用的写清楚用途很重要否则时间久了你自己都会分不清。用户级的命令可以放在~/.claude/commands/下跨项目全局生效。我一般把最通用的task.md放在用户级把和项目紧密相关的review.md放进各项目的.claude/commands/里兼顾通用和特定约束。3.4 一个完整模板的执行流程以/review为例完整执行流程是这样的在项目根目录建立.claude/commands/放入review.md启动 Claude Code输入/review模型读取命令模板然后调用工具查看当前分支的改动模型按模板清单逐项检查最终输出分级审查结果。实际生成的结果看起来会像这样【阻塞】文件 src/service/OrderService.java 第 132 行 在循环中调用 findById产生 N1 查询。建议改为批量查询后内存匹配。 【重要】文件 src/service/OrderService.java 第 45 行 异常被吞掉后继续执行失败路径无法感知。建议至少记录日志。 【建议】文件 src/controller/OrderController.java 第 67 行 入参校验逻辑和 service 层重复建议提炼公共方法。 未发现问题安全性检查、测试覆盖检查。这套流程的妙处在于模板只负责提供检查框架真正读代码、跑 diff 的动作还是由模型自己完成。你不用在对话里手动贴一堆文件输入一条命令就够了。4. 常见问题与排查技巧实录4.1 模板调用后没反应问题出在哪我遇到过最蠢的情况是模板文件路径写错命令名怎么敲都无效。Slash Command 的搜索路径必须包含.claude/commands/而且文件扩展名必须是.md。如果你放在项目根目录而不是.claude下面那它不会被加载。排查步骤很简单确认路径项目级是.claude/commands/xxx.md确认文件名命令名由文件名的去扩展名部分组成不要用中文空格或大写字符重启 Claude Code 会话命令是启动时加载的新增文件后需要新开会话如果急着用先手动/read .claude/commands/review.md再告诉它“按这个模板执行”。在新会话里加载完毕后调用/review就能看到模板效果。如果仍然没反应多半是description字段缺失导致命令列表无法识别补上就好。4.2 上下文窗口被长模板撑爆模板不是越长越好。我第一次写 review 模板时一口气把几十条检查项塞了进去结果 Claude 的上下文窗口被占掉一大截真正回答问题时反而变得迟钝。后来我把模板精简到 20 行左右只保留最核心的检查维度效果立刻改善。处理长模板有两条经验把模板拆成多个小命令比如review-security.md、review-performance.md需要哪一个就调用哪一个模板只写“原则和清单”不写长篇解释。详细的原理说明应该放在CLAUDE.md里而不是放在每次都会被加载的命令文件里。如果你发现某次对话上下文已经塞得很满可以先用/clear清理会话再继续。模板的意义是让你稳定起步不是让你把整个项目文档都塞进去。4.3 模板太粗或太细怎么找到平衡模板太粗起不到约束作用模板太细会限制模型的合理发挥。我踩过两个方向上的坑节奏感是靠反馈调整出来的。粗的例子“请认真完成这个任务。”这种话没有任何可执行性Claude 只能自由发挥。细的例子强迫它每次输出必须按某个特定格式逐字包含 50 个字段导致大量输出口水话。我的参考区间是一份模板 50200 行。对于代码审查这种需要覆盖多个维度的场景可以靠近 150 行对于提交信息这种单一场景50 行以内就够了。调优方法也很简单每次使用后记录一个“不满意”的点把它作为一行约束加进模板。比如我发现 Claude 总是不写“影响面”就在角色模板里加一行“所有建议必须说明影响面”。迭代几轮模板会越来越贴合你的习惯。4.4 团队如何共用一套模板模板最容易被忽视的价值是团队一致性。如果团队五个人都在用 Claude Code每个人自己维护一套风格完全不同的 prompt结果就是 review 建议风格五花八门。所以我在团队里做了一件事单独建一个claude-code-templates仓库所有成员通过 Git 同步。同步方式有两种直接把整个仓库作为子模块挂到各项目的.claude下用一个简单的 shell 脚本把commands/里的文件复制到本地项目目录。我更倾向脚本同步因为子模块在频繁改模板时会产生很多额外 commit。脚本只做一件事拉取远程模板复制到当前项目的.claude/commands/下。模板变更后每个人执行一次就能更新到最新。团队维护模板还有一个硬性要求必须有description和简短的 README 说明。否则别人看到一堆不认识的命令根本不知道有什么用。我也在 CI 里加了一个轻量检查扫描所有.md文件是否包含description字段不通过就不允许合并。这个动作很小但能避免模板库变成垃圾场。我现在自己维护的 claude-code-templates 里真正高频使用的其实只有六七个文件。但我最大的体会是模板的价值不在于让 Claude 更聪明而在于让我自己重新整理了一遍工作流。每当我踩到一个新坑我就把它写成一行约束加进对应模板下一次就不再犯同样的错。写模板时我还会特意用否定句而不只是肯定句比如“不要引入新依赖”“不要改动接口签名”模型对明确的禁止项比泛泛的目标更敏感。慢慢积攒下来这套模板更像是我和 Claude 协作时沉淀出的第二大脑。