我有段时间对 Claude Code 又爱又恨，后来想明白一件事：我从来没给它准备过一套像样的 claude-code-templates。爱的是它写起代码来确实快，恨的是它老自作主张——让它修一个小 bug，它顺手把你的测试文件全部重构了；让它加一个查询接口，它把整个目录结构都改了，美其名曰“更清晰”。仔细想想，这真不完全是工具的错，它每次启动时对我的项目一无所知，不犯错才奇怪。
于是我花了两周时间整理了一套自己的 Claude Code 模板体系，把项目背景、常用命令、代码规范、禁区约束全部写进模板文件。效果立竿见影，Claude Code 的输出质量、一次通过率都有了肉眼可见的提升。这篇文章就把我的完整思路和可直接抄的模板写出来，希望能帮你少走点弯路。
1. 先从一次让我差点崩溃的对话说起
1.1 一次“自作主张”的典型事故
当时我在维护一个 Java 服务，上游有三个系统在调用我们的接口。我让 Claude Code 给用户资料模块加一个修改接口，逻辑很简单，半小时的活。但它看过代码之后，大概是觉得我原来的 Controller 命名风格不够标准，自作主张把一批接口路径从动词风格改成了 RESTful 风格，还顺手把所有 controller 方法的命名统一重写了一遍。
结果就是：联调环境直接炸了，上游三个系统的调用全部 404，CI 挂掉，我花了整个下午回滚代码、排查是哪几个路径被改了。我当时气得不行，第一反应是这工具真不靠谱。但冷静下来之后，我意识到问题出在哪：我没告诉它“接口路径不能改，调用方太多”；我没告诉它“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 编程的输出有了稳定的预期。模板把那些只有老员工才知道的项目规矩装进了新同事的脑子里，剩下的，就是让它放手干活了。
