我有段时间对 Claude Code 又爱又恨后来想明白一件事我从来没给它准备过一套像样的 claude-code-templates。爱的是它写起代码来确实快恨的是它老自作主张——让它修一个小 bug它顺手把你的测试文件全部重构了让它加一个查询接口它把整个目录结构都改了美其名曰“更清晰”。仔细想想这真不完全是工具的错它每次启动时对我的项目一无所知不犯错才奇怪。于是我花了两周时间整理了一套自己的 Claude Code 模板体系把项目背景、常用命令、代码规范、禁区约束全部写进模板文件。效果立竿见影Claude Code 的输出质量、一次通过率都有了肉眼可见的提升。这篇文章就把我的完整思路和可直接抄的模板写出来希望能帮你少走点弯路。1. 先从一次让我差点崩溃的对话说起1.1 一次“自作主张”的典型事故当时我在维护一个 Java 服务上游有三个系统在调用我们的接口。我让 Claude Code 给用户资料模块加一个修改接口逻辑很简单半小时的活。但它看过代码之后大概是觉得我原来的 Controller 命名风格不够标准自作主张把一批接口路径从动词风格改成了 RESTful 风格还顺手把所有 controller 方法的命名统一重写了一遍。结果就是联调环境直接炸了上游三个系统的调用全部 404CI 挂掉我花了整个下午回滚代码、排查是哪几个路径被改了。我当时气得不行第一反应是这工具真不靠谱。但冷静下来之后我意识到问题出在哪我没告诉它“接口路径不能改调用方太多”我没告诉它“Controller 命名风格是团队历史约定”我也没告诉它“改动接口必须全局搜索调用方”。这些信息我脑子里有但它的脑子里没有。1.2 问题的本质每次会话都是失忆的Claude Code 这类 AI 编程工具的核心机制是模型自带海量通用知识但它对你手里的项目一无所知。你可以在对话里粘贴文件、说明背景但这些信息只存在于当前会话会话一关全部清零。下次开一个全新会话它又变回那个对你项目毫无概念的“外来者”。你可以把它想象成一个能力很强但记性极差的新同事。他第一天入职就写过很多项目但对你这个项目的历史、约定、坑一无所知。你每次让他干活都要重新交代一遍背景不交代他就按自己的通用经验来。而通用经验往往不是你这个项目的真实情况。模板就是干这个用的。它把这些“每次都要重复交代的内容”固化成文件让 Claude Code 在每次会话启动时自动加载。它不是教模型写代码而是给模型一份“入职手册”告诉它你这个项目有哪些规矩、哪些雷区、哪些固定流程。1.3 模板到底值不值得花时间说实话在整理 claude-code-templates 之前我也犹豫过。写模板本身要花时间而且写完了还要维护看起来不如“每次对话直接说明”来得快。但用了一周之后我确认这笔投入非常值得原因有三点第一省重复劳动。以前每次开新会话都要花五分钟粘贴背景、说规范、强调约束现在一句话都不用多说模型自动知道。第二输出质量更稳定。模板写清楚的项目模型每次都在同一个知识基线上干活不会这次记得这个约定、下次忘了。第三可复制。模板是文件可以进 Git 仓库团队里每个人 clone 下来就能获得同样质量的 AI 辅助体验不需要单独培训。2. CLAUDE.md 的加载机制你的模板在什么时候生效2.1 Claude Code 的三层内置上下文Claude Code 会把模板文件当作“长期记忆”自动加载进每次对话。目前它主要读取两个位置的模板用户级和项目级。用户级~/.claude/CLAUDE.md对所有项目生效相当于个人偏好和通用习惯。项目级项目根目录下的./CLAUDE.md只对当前项目生效放项目专属的规范、命令和约束。这两层之外还有一个系统提示词层那是模型底层的设定用户改不了也不用管。真正的可操作空间就在用户级和项目级这两份 CLAUDE.md 上。当对话请求产生时Claude Code 会把这些上下文组合进提示词里。越具体的、越靠近任务场景的内容在模型决策时的权重越高。项目级模板排在用户级模板之后加载所以它对当前项目的行为约束力更强。这个顺序设计是合理的个人偏好不应该压过项目规则。2.2 作用域的选择放全局还是放项目判断一条信息该放哪一层我有一个很简单的标准这句话换一个项目还成立吗还成立的比如“默认用中文回答”“代码注释用英文写”“不要主动升级依赖版本”放全局~/.claude/CLAUDE.md。只在这个项目成立的比如“本项目接口统一走 /api/v1 前缀”“不要改 legacy 模块下面向第三方开放的接口”放项目根目录的./CLAUDE.md。很多人第一个模板就写反了把个人偏好放进了项目模板导致团队其他人用起来很别扭或者把项目专属约束写进了全局模板换一个技术栈完全不同的项目模型还在遵守上一套规范干扰很大。作用域选错了,模板越多越乱。2.3 自动加载不等于自动合理CLAUDE.md 是自动读取的不需要你手动粘贴也不需要每次启动时指定。只要文件存在模型就会在对话开始时拿到里面的内容。这是它在设计上最方便的地方但也是最容易让人大意的地方。正因为自动加载模板里的每一句话都会持续影响模型的行为。写得好它就是隐形的高质量上下文写得太长、太泛、过时了它就是持续的噪音。所以模板不是写完就完事的它需要像代码一样被 review、被迭代。后面我会专门讲怎么避免把模板写成一本没人看的废稿。3. 项目级模板一份可以直接抄的完整示例3.1 完整模板长什么样先给一份可以直接改改就用的项目级 CLAUDE.md 模板。我用一个常见的 Node.js 服务举例你可以根据自己的项目替换内容。# 项目背景 这是一个用户数据管理服务对外提供 REST API底层存储使用 MySQL。上游有三个系统依赖本服务的接口。 # 常用命令 - 启动开发服务npm run dev - 运行单元测试npm test - 构建产物npm run build - 执行数据库迁移npm run migrate:up - 代码检查npm run lint # 技术栈 - Node.js 20 TypeScript - Express 4 TypeORM - MySQL 8 # 代码风格约定 - 目录按功能划分controllers / services / repositories - 接口路径统一使用小写中划线如 /user-profiles - 函数命名以动词开头布尔返回值用 is/has/can 开头 - 注释只解释 why不要解释 what - 禁止修改 repository 层已有方法的签名影响面太大 # 架构关键信息 - controllers 只做参数校验和响应包装业务逻辑必须下沉到 services - 所有对外接口统一使用 /api/v1 前缀 - JWT 认证中间件已在 app.ts 中全局注册新接口无需重复实现 - 数据库表结构变更必须同步编写 migration 文件 # 任务工作流 1. 接需求时先查看 controllers 和 services 下相关文件理解现状再动手 2. 修改任何对外接口后必须全局搜索旧调用方确认是否需要同步修改 3. 提交前运行 npm test 和 npm run build确保通过 4. 如涉及数据库变更先写 migration 再改实体代码 # 禁止事项 - 不要升级或改动 package.json 中现有依赖版本 - 不要修改 public 目录下的静态文件 - 不要把业务逻辑塞进 controller - 未经确认不要删除任何导出函数3.2 为什么每个区块都必不可少先说“项目背景”。两句话就够不需要长篇大论。它给模型建立的是一个基础语境避免它提出完全不适配当前项目的方案。比如你告诉它这是个老服务、有多个上游依赖它就不会轻易建议你对接口做破坏性重构。“常用命令”是我觉得投入产出比最高的区块。模型不用猜“这个项目怎么启动、怎么测试”直接照着执行。这里有一个格式细节指令要写“目的命令”不要只丢一条命令。因为模型需要知道什么场景匹配哪条命令只给命令不给场景它遇到问题时仍然不知道怎么选。“技术栈”起的是收敛作用。同样一个问题模型脑子里有无数种答案写了具体技术栈之后它给出的方案会自动收敛到你这个项目真实使用的生态里。不写的话它偶尔会给你一个看着很标准但完全无法落地的方案。“代码风格约定”是模板里最值钱的部分直接解决了我开头说的那种“自作主张”问题。模型不是不懂规范而是不知道你的规范。你自己写清楚命名规则、注释规则、禁止修改的签名它就能按你的规矩来。“架构关键信息”是防止错误重构的关键。Claude Code 非常有重构热情这是它的优点也是它的风险。告诉它分层职责、认证中间件已经全局注册、表结构变更要写 migration它才会在边界内动手。“任务工作流”是把长期经验步骤化。Claude Code 对流程性指令的遵循度很高你把“接需求先看现状、再动手改完接口搜索调用方”这种顺序写清楚它就会像模像样地按流程走。这是我发现的最有效的控制方式。“禁止事项”是整套模板的防呆设计。每个写模板的人都会在正面清单上花很多时间但真正防止事故的反而是负面清单。模型很多严重错误不是不会写代码而是不知道哪些不能碰。3.3 两个容易被忽略的写法细节第一命令区块一定写项目真实可用的命令。有些项目有自己封装好的脚本比如用 pnpm、用 turbo、有自定义的迁移工具不写进模板的话模型只会按通用的 npm 命令来找不到就自己编一个结果就是你经常看到它执行了一个根本不存在或者用途错误的命令。第二把输出语言偏好写进去。如果团队用中文交流建议在全局模板里加一句“回复时使用中文代码注释使用英文”。这个看似不起眼实测下来影响很大。模型切换语言的时候代码风格、注释密度、命名习惯都会跟着变模板里明确约定能省掉很多格式来回拉扯。4. 斜杠命令模板把高频操作固化成一句话4.1 命令模板的机制与存放位置CLAUDE.md 解决的是“启动时默认加载”的问题斜杠命令模板解决的是另一类问题有些操作你反复要做但每次都要重新描述一大段要求太累了。Claude Code 支持自定义斜杠命令用法很简单在~/.claude/commands/目录下建一个 Markdown 文件文件名就是命令名。比如建一个commit.md在对话里输入/commit它就会读取这个文件的内容作为新的指令上下文。斜杠命令本质上是“预置好的提示词小抄”。它不是编程语法就是自然语言指令你可以写得很细也可以在文件开头用 YAML frontmatter 声明参数允许调用时传入临时信息。这一点非常实用等于你把重复的提示词工程沉淀成一份可维护的文档换人换机器效果都一样。4.2 三个可以直接用的命令模板第一个是/commit帮我彻底解决了提交信息质量不稳定的问题。--- description: 根据 git diff 生成 Conventional Commits 格式的提交信息 argument-hint: [可选] 本次提交的重点说明 allowed-tools: Git --- 先用 git diff --staged 和 git diff 查看当前改动。 如果没有暂存任何改动先提示我执行 git add。 根据改动内容生成提交信息格式遵循 Conventional Commits - 类型使用 feat / fix / refactor / chore / docs / test - 正文简洁说明 why 而不是 what - 如果有破坏性变更在 footer 中明确标注第二个是/review做代码审查用的。AI 审查不一定能替代人但能快速帮你发现低级问题。--- description: 对指定代码变更进行代码审查 argument-hint: 文件路径或功能点 allowed-tools: Git --- 请对指定的代码变更做审查重点检查 1. 是否有副作用或对旧调用方的影响 2. 错误处理是否完整有没有吞掉异常 3. 是否遵循项目 CLAUDE.md 中约定的代码风格 4. 并发、性能上有无明显隐患 输出格式按严重程度分为 blocker / warning / nit 三档并给出修改建议。第三个是/explain用来快速理解陌生代码。接手旧项目的时候特别好用。--- description: 用通俗语言解释指定代码的作用 argument-hint: 文件路径或函数名 --- 用通俗的语言解释用户指定的代码要求 1. 先说明这段代码在整个系统中的位置和职责 2. 逐段解释关键逻辑遇到复杂算法用生活化类比 3. 指出潜在的脆弱点或可疑写法 4. 最后用一段话总结让没看过代码的人也能听懂这三个命令模板的共同点是它们把“要求模型以什么方式回答问题”这个过程的稳定部分固定下来了每次调用只需要传入变化的参数。4.3 frontmatter 字段与参数传递斜杠命令模板支持 YAML frontmatter几个常用字段的用途你需要了解。description描述命令的用途。这个字段不只是给人看的它会参与 Claude 的智能匹配。写得好你甚至不用完整输入命令名Claude 会根据语义自动匹配到对应命令。argument-hint提示用户调用时需要传入什么参数有很好的引导作用。allowed-tools限制这个命令可以使用的工具集合。比如/commit只需要 Git 和读取文件不需要其他能力限制之后能减少模型分心。参数传递的用法是这样输入/commit 本周完成了登录模块的重构冒号后面的文字会作为$ARGUMENTS传入模板。你在模板正文里可以用$ARGUMENTS占位Claude 会把用户输入填充进去。我习惯在模板中留一个可变参数入口让每次调用都能带上具体上下文这样命令模板既稳定又灵活。5. 模板设计的原则和踩过的坑5.1 我踩过的最大的坑追求大而全我第一版 CLAUDE.md 写了差不多 200 行觉得越详细越好把项目历史、模块设计细节、每个服务的调用链全写了进去。结果模型在长上下文里抓不住重点该遵守的最关键约束反而被淹没在大量背景信息里。这就像你跟新同事交代工作一口气讲了三个小时他记住的反而是你随口提的一个无关细节。模板越长注意力越分散。后来我把项目级模板压到了 60 到 80 行只保留三类内容高频要用的信息、必须遵守的规范、不能碰的禁区。效果反而明显变好。5.2 我踩过的第二个坑只写原则不写禁区第一版模板里我写了很多“注意代码质量”“保持代码风格一致”这类话现在回头看全是废话。模型不会因为这句话就提高质量因为它认为它写的代码质量本来就很好。真正起作用的是具体约束比如“禁止修改 repository 层已有方法的签名”“不要升级 package.json 里的依赖版本”。还有一个更隐蔽的问题只写正面清单不写禁区。正面清单解决“怎么做”禁区解决“不许做”。没有禁区模型会在遇到模糊场景时自作主张。我遇到过一个典型事故模型为了“提高查询性能”自己改了数据库索引配置但项目的生产环境数据库权限根本不允许这样操作结果迁移脚本在测试环境直接跑挂了。如果模板里有“数据库配置变更必须人工确认”这条禁区这个事故完全是可以避免的。5.3 四条经过验证的设计原则第一越具体越有用越原则越没用。“接口命名要规范”不如“接口路径统一小写中划线”。“注意异常处理”不如“调用外部服务时必须捕获超时异常并记录日志”。第二模板只写长期不变的内容。项目在持续演进模板却是一个静态文件。写“当前开发分支是 feature-xxx”这种话两天之后就是错的。模板只承载那种三个月后仍然成立的规则和约定。第三每条约束尽量写一句原因。只写“不要删除导出函数”而不解释为什么模型遇到冲突时可能选择不遵守。但如果写上“该函数被其他服务通过 npm 包调用”模型不但会遵守还能在类似场景下主动追问“这个能不能动”。第四模板保持版本化。每次调整 CLAUDE.md 都要像改代码一样走 review不能想起来就随手加一句。因为你每加一句话都是在改变模型的行为基线随便加行为就会越来越漂移。6. 把模板变成团队资产而不是个人小抄6.1 模板为什么应该进 Git 仓库项目级 CLAUDE.md 本质上是一份项目文档它应该和 README 一样放进 Git 仓库。团队里任何一个人 clone 下代码库Claude Code 自动获得一致的项目上下文。这一点对团队推广 AI 编程工具特别重要。以前团队里每个人用 Claude Code 都是各写各的提示词A 的工具知道项目架构B 的工具完全不知道两个人产出质量完全不一样。模板进入仓库之后大家共享同一套项目规范和约束新人也无需额外培训。6.2 把模板当活文档来养模板不是写一次就完事的。我的习惯是把它当活文档来维护每次有人踩了一个坑就检查是不是模板里漏了对应的约束每次发现模型误操作就回看是不是模板里没写清楚。半年下来这份模板就是团队的隐性知识库。需要提醒一句模板更新一定要走版本控制。有人在本地默默改了 CLAUDE.md然后提交代码时把模板也一起提交了结果团队所有人下一轮对话里行为基线突然变了。这种“静默变更”在团队场景下非常危险每次模板改动都应该在提交信息里体现出来。6.3 从 CLAUDE.md 进阶到 Skills 与 Hooks如果你发现 CLAUDE.md 太长或者信息太杂建议了解一下 Skills 机制。Skills 是文件夹形式的知识包里面包含一个 SKILL.md 和附带的参考资源按需加载。它和 CLAUDE.md 的本质区别在于CLAUDE.md 是启动时全量注入的Skills 是只有在任务匹配时才加载的。这正好解决长模板稀释注意力的问题。Hooks 则是另一条路径它做的是流程自动化。你可以在.claude/settings.json里配置 Hooks在特定事件触发时自动执行脚本比如提交前自动运行格式化、推送前自动跑测试。相比模板Hooks 更接近“规则引擎”适合那种你不希望模型自己判断要不要执行的硬性约束。6.4 我的实际使用习惯我现在的工作方式已经固定成三层全局 CLAUDE.md 管个人偏好项目 CLAUDE.md 管项目约束四五个斜杠命令模板管高频操作。每次开始干活不再花十分钟交代背景直接说增量需求就行。对我来说这套 claude-code-templates 带来的最大改变不是“每次对话少打几行字”而是让我对 AI 编程的输出有了稳定的预期。模板把那些只有老员工才知道的项目规矩装进了新同事的脑子里剩下的就是让它放手干活了。
