如果你和我一样每天要在不同仓库之间切换一定会遇到这个场景刚把 A 项目的技术栈、目录约定给 Claude Code 讲了一遍切到 B 项目又要重新解释一遍。我用一套叫 claude-code-templates 的模板方案解决了这个问题几周跑下来新项目从打开到进入干活状态基本控制在十分钟以内。这篇文章不聊虚的直接把我沉淀的模板目录、命令写法、踩坑经验全部摊开。适合所有把 Claude Code 当主力编程助手的开发者也适合想给团队统一 AI 协作规范的人。先说结论Claude Code 本身能力很强但它的发挥上限受制于你到底给了它多少有效上下文。templates 不是单纯地把模板文本堆在一起而是把项目的记忆、协作规则、输出格式变成一套可复用、可版本管理、可审查的外部上下文系统。这篇文章里的内容都是我在真实项目里反复调出来的不是官方文档的搬运每一步都标注了为什么这么设计。1. 先搞清楚模板对 Claude Code 意味着什么1.1 模板本质上是项目的外部记忆Claude Code 这类编程助手的会话模式本质上是一次对话一个独立的上下文窗口。你在这个会话里交代了什么它就在这个基础上工作下一次新开会话它不会自动记得上次聊了些什么。很多人觉得AI 不够了解我的项目其实不是模型智商问题而是你每次都没把该说的背景说清楚。模板的作用就是把该说的背景提前写好。Claude Code 启动时会自动加载项目根目录下的 CLAUDE.md也会读取用户目录下的全局 CLAUDE.md这些文件里的内容会成为每一次会话的初始上下文。你把项目说明、技术栈、目录结构、命令规范放在这个文件里等于给 AI 装了一个项目记忆芯片。我见过不少人的做法是每次会话开头手动粘贴一大段项目说明或者干脆让 AI 去读十几个文件。这样不是不行但效率很低。手动粘贴会漏AI 去读文件会占用大量的上下文 token而且读进来的东西可能是过时的。模板的价值就在于一次写对到处复用。1.2 模板体系分三层不是只有 CLAUDE.md很多人的认知停留在模板 CLAUDE.md这其实是把系统用窄了。我实际跑下来Claude Code 的模板体系至少有三层三层各管一件事层级载体生效时机典型用途常驻记忆层CLAUDE.md全局 项目每次会话自动加载项目背景、技术栈、目录地图、软性约定按需命令层.claude/commands/ 下的 markdown 文件用户输入 / 命令时触发commit、review、scaffold 等高频重复动作会话即兴层你手动输入的一段 prompt 片段随时一次性任务、探索性问题、临时分析如果你只把 CLAUDE.md 写好相当于给 AI 配了一个长期大脑但每次要它执行特定动作时还是得在对话里临时解释一堆要求。按需命令层解决的就是这个把怎么生成 commit message、怎么审查代码这类高频动作固化成 slash command你只需要输个/commit它就知道该按什么流程来。1.3 模板值得投入时间是因为它有复利效应为什么我愿意花几个晚上去整理 claude-code-templates因为这玩意是典型的复利资产。第一次搭模板投入两三个小时之后每到一个新项目复制过来改一改项目信息就能用。对于团队来说收益更大一个人打磨好模板全员共享等于把个人经验变成了组织的流程资产。而且模板是文本天然适合放进 Git 仓库。你可以给模板建立独立的代码仓库也可以塞进项目仓库的 .claude 目录。我一直用独立仓库管理通用模板项目里只放差异化的覆盖文件。这样一来模板的演进历史一目了然谁改了什么、为什么改都有据可查。2. 我的模板目录骨架每个文件该放什么2.1 推荐目录结构先把我现在的模板仓库结构摆出来你可以直接复制这个骨架claude-code-templates/ ├── README.md ├── global/ │ └── CLAUDE.md ├── project/ │ ├── CLAUDE.md │ └── .claude/ │ ├── commands/ │ │ ├── commit.md │ │ ├── review.md │ │ ├── scaffold.md │ │ └── pr.md │ └── templates/ │ ├── rfc.md │ └── changelog.md这个目录分了两大块global/存的是全局通用规则project/是往具体项目里放的。很多人的误区是把全局和项目混在一起。全局 CLAUDE.md 只放跟具体业务无关的习惯比如回答时先给结论再给过程、不要重复粘贴用户已经贴出来的代码项目的 CLAUDE.md 才放这个项目用什么技术栈、有哪些目录、有什么坑。2.2 全局层和项目层的职责边界全局 CLAUDE.md 一旦写得太多进到每个项目都会加载等于白白烧掉上下文窗口。我的经验是全局层只保留三类内容跨项目的沟通偏好比如希望 AI 用中文回答还是用英文写 commit通用的代码风格底线比如禁止使用 TODO 敷衍、改动公共接口前必须列影响面兜底的安全规范比如不要删除没有版本控制的文件、执行危险命令前先解释。项目层才承担真正的差异化信息。项目层的 CLAUDE.md 我建议控制在 60 行以内太长了 AI 反而抓不住重点。记住CLAUDE.md 不是文档库它是一种导航仪目的是让 AI 知道往哪看而不是把所有信息灌进去。2.3 CLAUDE.md 脚本应有的核心区块一个合格的 CLAUDE.md至少要覆盖下面七个区块。我拿一个典型的后端 前端全栈项目举例# 项目OrderFlow ## 一句话定位 订单管理系统面向中小电商商家核心是订单流转与库存联动。 ## 技术栈 - 后端Python 3.11 FastAPI SQLAlchemy 2.0 - 前端React 18 TypeScript Vite antd - 测试pytest pytest-asyncio ## 目录地图 - app/api/路由入口每个模块一个文件 - app/services/业务逻辑禁止在路由里写复杂逻辑 - app/models/SQLAlchemy 模型统一继承 Base - tests/api/接口测试文件命名 test_module_api.py ## 常用命令 - make dev本地开发 - make test跑全部测试 - make lintruff mypy ## 约定与禁忌 - 所有时间字段统一 UTC数据库字段名用 snake_case - 禁止在 service 层 import FastAPI Request - 修改公共模型前必须先在 docs/architecture.md 里更新影响面 ## 验收清单 - 新功能必须带测试 - API 响应结构遵循 { code, data, message } - 改动记录同步到 CHANGELOG.md ## 相关文档 - docs/architecture.md - docs/deployment.md注意约定与禁忌这一块别写成空话。代码要写清楚这种没有操作意义禁止在 service 层 import FastAPI Request 这种才能真的拦住错误操作。AI 对禁令的理解比抽象要求要准确得多。2.4 自定义 slash command 的基本写法.claude/commands/目录下的 markdown 文件会被 Claude Code 识别为斜杠命令文件名就是触发词。比如commit.md对应/commit。命令文件可以带一个 frontmatter 头用来声明描述和参数提示正文就是具体的指令。我以一个最常用的 commit 命令为例完整的commit.md长这样--- description: 根据当前 git diff 生成符合规范的中文/英文 commit message argument-hint: [可选提交类型] --- 先执行 git diff --cached --stat 与 git diff --cached 查看暂存区的变更内容。 如果用户提供了类型参数优先使用该类型否则根据 diff 自行判断。 要求 1. 提交信息使用 Conventional Commits 格式type(scope): subject 2. type 只允许 feat / fix / refactor / test / docs / chore 3. subject 不超过 72 个字符使用英文半角 4. 如果 diff 包含破坏性变更必须在 body 中写 BREAKING CHANGE 5. 不要自动执行 git commit只输出建议文本 输出格式 - 第一行提交标题 - 空一行后按变更原因 / 影响范围 / 测试情况三块组织 body文件名的命名规则要留意命令名建议全小写不要带空格。commit.md触发/commitcode_review.md触发/code_review。目录层级上项目根目录下的.claude/commands/只对当前项目生效放在用户级~/.claude/commands/则会成为全局命令。3. 让模板懂项目的几个关键设计原则3.1 少即是多别让 CLAUDE.md 变成信息垃圾场我见过最夸张的 CLAUDE.md 写了三百多行把整个项目的实体关系、每个模块的函数列表全塞进去了。执行任务的时候AI 确实会全部读一遍但上下文窗口是有限的信息密度过高会让真正重要的项目约定被淹没。我自己的标准是CLAUDE.md 只写AI 不读就会犯错的信息。环境变量列表、数据库连接串、第三方 API 密钥这些要么不该写要么不该出现在模板里。依赖清单、包版本号这类信息会频繁变动写进模板里等于制造过时内容正确做法是让 AI 去读pyproject.toml或package.json。3.2 提供一个检索路径比提供全部事实更重要这里有一个很微妙的设计好的模板是指路牌不是地图全集。比如不需要在 CLAUDE.md 里写出所有实体关系只需要告诉 AI- 业务实体定义在 app/models/订单改单逻辑在 app/services/order_service.py - 想了解订单状态流转先看 docs/architecture.md 的 3.2 节这样 AI 需要细节时会主动去对应文件里找而不是依赖模板里的二手信息。这个习惯帮我省了大量维护模板的精力——文件内容改来改去但指路牌的指向结构基本稳定。3.3 给模板加上验收清单和输出格式很多模板只有要求没有验收清单导致 AI 交上来的东西感觉不对劲又说不上来哪有问题。我在做 claude-code-templates 时学到最有用的一件事就是给每个命令模板加上明确的验收输出格式。拿 review 命令举例我会明确要求它输出四段结构严重问题、潜在风险、风格问题、可执行改进建议。每一段用列表展开每条建议前标注是阻塞还是非阻塞。这样 AI 输出格式稳定我扫一眼就知道该处理什么而不是还要从一大段散文里提炼信息。Commit 命令也一样我要求它宁可只输出一个标题也不要生成一段意义模糊的废话。3.4 模板的动态变量要克制使用Claude Code 的命令文件支持通过参数传递信息。比如argument-hint: [可选提交类型]用户输入/commit feat时AI 就能拿到feat这个参数。这是一种动态模板的玩法非常灵活但我建议变量数量控制在两到三个以内。我一开始在 scaffold 命令里设计了六个参数模块名、表名、是否带 CRUD、是否要测试、前端页面还是后端 API、代码风格偏好。结果每次触发命令时我自己都记不住参数顺序AI 也经常理解错。后来砍到只剩一个必选参数模块名剩下的交给 AI 根据项目现状自己判断。模板设计的第一原则永远是让使用者少做决策。4. 实战从零搭一套可复用的 command 模板4.1 commit 命令模板的进化上面的 commit.md 看起来简单其实是迭代了很多版的结果。最初我让 AI 直接执行git commit它经常把测试改动和正式改动混在一起或者生成一个包含四五件事的长标题。后来我在模板里强制加了不要自动执行 git commit只输出建议文本这一条。虽然多了一步复制粘贴但每次提交都是干净的、单责任的长期收益远大于那点麻烦。顺带说一下commit 命令我用了git diff --cached也就是只看暂存区的内容。这事背后有个教训很多 AI 工具默认看的是工作区会把未 add 的改动也纳入分析导致生成的 commit message 和你实际提交的内容对不上。命令模板里必须写清楚它该看哪个数据源这是最容易踩的细节。4.2 review 命令让审查从看一遍变成按维度查一遍代码审查如果只让 AI 随便看一遍大概率收获一堆正确的废话。我在review.md里做了结构化约束--- description: 审查当前分支相比 main 的改动按维度输出结论 --- 先执行 git diff main...HEAD --stat 获取改动文件清单然后逐个文件执行 git diff main...HEAD -- file_path。 审查维度 1. correctness逻辑是否完整边界条件是否处理 2. performance是否存在明显的 N1 查询、重复计算 3. security是否有 SQL 注入、路径穿越、敏感信息硬编码风险 4. style是否与周边代码风格一致 输出格式 - 每个维度单独一节每条问题标注 [阻塞] 或 [非阻塞] - 阻塞问题必须给出具体行号和修改建议 - 最后给一段 50 字以内的总体结论这个模板关键是逼着 AI 按维度审查而不是凭感觉给意见。实际用下来security维度真的能经常抓到硬编码的数据库密码和没鉴权的接口。如果你的模板输出太笼统多半是维度没有拆细。4.3 scaffold 命令让新模块从第一行代码就符合规范每次在项目里新增一个模块都要手动创建路由文件、service 文件、模型文件、测试文件这个动作特别适合用模板固化。我的 scaffold 模板长这样--- description: 生成一个新业务模块的标准骨架 argument-hint: 模块名如 order --- 根据项目现有约定为「$1」模块生成以下文件 1. app/api/$1.py路由定义按项目现有路由风格 2. app/services/$1_service.py业务逻辑返回业务对象而非 dict 3. app/models/$1.py模型定义继承 Base字段风格参考 app/models/ 下的现有模型 4. tests/api/test_$1_api.py覆盖正常路径和至少一个异常路径 约束 - 先读取 app/models/ 下一个现有模型文件完全模仿它的字段风格 - 路由响应统一走项目公共响应结构 - 生成完文件后列出需要人工确认的决策点如唯一索引、外键关系这里有个很关键的技巧我没有在模板里硬编码代码风格而是让 AI 先读取现有文件再模仿。模板写死风格迟早会过时而让 AI 从现网代码里学习风格是维护成本最低的方案。4.4 模板参数与变量使用的注意事项Claude Code 命令文件里可以用$1、$2这类位置参数也可以直接要求 AI 从对话中推断。我实践中发现一个规律必选参数用位置参数可选参数让用户自然说出来。比如 scaffold 里的模块名用$1是合理的但质量偏好这类模糊参数就别做成$2了放自然语言里反而更准。还有一个常见的坑命令触发之后模板正文里的指令和用户随后补充的话容易被 AI 混淆。我的办法是在模板开头就写清楚先完成以上检查再响应用户后续提问给 AI 划出一个明确的执行优先级。模板越复杂越要强调优先级。5. 踩过的坑与调试方法5.1 模板文件貌似没生效的三种原因/commit输进去没反应或者CLAUDE.md里的规则它完全无视这类问题我排查过很多次基本跑不出三个原因文件路径不对。命令文件必须放在.claude/commands/目录下不是.claude/command/也不能放在commands/根目录。CLAUDE.md 必须放在项目根目录放子目录不会被自动加载。文件名大小写或空格问题。Claude Code 的命令触发一般是全小写文件名的文件名里有空格更是直接失效。我吃过这个亏my-command.md触发/my-commandMyCommand.md就容易出问题。没有重启会话。CLAUDE.md 是在会话启动时加载的会话进行中改了文件它不会热更新。我一开始以为改完就能生效结果每次都要新开一个会话再试。排查这类问题建议在命令文件第一行写一句如果能看到这句话说明命令加载成功。跑一次/xxx自然就知道问题出在哪一层。5.2 CLAUDE.md 内容过时导致 AI 一本正经地按旧规范干活模板最大的隐患不是没写而是写了过时的规则。比如项目从 Flask 迁到了 FastAPICLAUDE.md 里还留着路由必须用 Flask Blueprint 注册的约束AI 就会每一条建议都在往旧框架上靠。这比没有模板更危险因为 AI 会自信地按错误信息执行。解决这个问题靠的不是记得去改模板而是从机制上降低过时概率。我现在要求每个项目的 CLAUDE.md 末尾都带一个最后校验日期字段每两周逼自己过一遍。同时在 commit 命令模板里加了一条规则如果发现 diff 涉及的技术与 CLAUDE.md 描述不一致先停下来提示用户确认而不是强行按模板走。5.3 模板里命令太激进AI 动了一些不该动的东西早期我在模板里很爱写自动运行测试、自动安装依赖这类指令。结果有一次 review 命令自动执行了pip install把本地环境搞得一团糟。现在我给自己立了一条铁律所有模板里的操作类指令必须区分自动执行和先展示后执行。只读操作可以自动跑git diff、git status、读取文件这些没有副作用让 AI 放手做有副作用的操作安装依赖、删文件、git push、数据库迁移全部要先给出执行计划和确认提示。这条原则我写在全局 CLAUDE.md 里等于给所有命令模板上了一道保险。5.4 多语言混杂环境下的指令混淆Claude Code 的模板指令写得多了容易中英文混杂。我试验过全中文指令和全英文指令发现一个规律如果模板指令是全英文AI 的输出风格会偏英文全中文则偏中文。如果你既想要稳定的英文 commit又想要中文讨论最好的做法是在模板里显式声明语言偏好而不是靠写模板时的语言去暗示。比如 commit 模板里写清楚subject 使用英文说明 body 使用中文这样 AI 不会自己脑补。语言问题属于典型的你不说明它就会自由发挥的场景。模板里的每一条规则都应该像代码约束条件一样明确而不能依赖模型的推测。5.5 调试模板的终极武器给 AI 配置自检模式任何模板都不可能一次写对。我调试模板的方法是写一个_debug.md命令专门用来检查模板自身--- description: 检查当前项目的模板配置是否合理 --- 请执行以下自检 1. 列出你刚才读取到的 CLAUDE.md 的关键条目逐条判断是否与当前项目实际相符 2. 逐一读取 .claude/commands/ 下的命令文件检查是否存在互相冲突的指令 3. 检查是否有命令模板中提到的文件路径或目录在当前项目中不存在 4. 基于以上检查结果给出一份模板修正建议清单每次改完模板我就在新会话里用一次/debug。AI 会自己发现你让我去看 models/但实际目录叫 entities/这种问题人工排查要花很久让 AI 自己审模板则快得多。6. 从个人到团队的治理经验与收尾心得6.1 模板要进代码审查流程个人用模板全凭自觉团队用模板必须有治理。我建议模板仓库走和代码一样的 MR 审查流程。每个命令的改动都要说明为什么变比如commit 模板增加类型参数是为了支持手动指定提交类型。这样模板的每个设计决策都有迹可循而不是某个人拍脑袋改一下全体人的 AI 行为就跟着变了。6.2 模板的可测试性固定场景回放几周前我开始把模板测试当成正经事做。方法是维护一个小测试仓库里面故意放一些典型的坏味道代码、错误目录结构、过时技术栈描述。每次改完模板就在测试仓库里跑一遍对应命令看输出是否符合预期。这个测试仓库要足够小几秒就能跑完这样你才愿意频繁用它。它起的作用就是模板的回归测试防止改 A 模板时破坏了 B 模板。6.3 我最近的模板使用小技巧最后分享一个这两天在用的技巧我会在项目 CLAUDE.md 的开头加一段当前迭代焦点比如本周重点是提升订单超时处理的准确性。这个信息会和 CLAUDE.md 一起加载AI 在生成代码和提出建议时就会有意识地向当前迭代目标靠拢。虽然只是一段简单文本但实际效果比很多花哨的 prompt 技巧都明显。模板系统不需要做得多么复杂关键是把真正影响协作的信息放到自动加载的位置上。以上这套 claude-code-templates 方案我已经从一个仓库复制到了几十个实际项目里每一步都是真实跑过的。你刚上手时不必一次性把所有模板都铺开从 CLAUDE.md 和 commit 命令开始跑顺了再逐步加 review、scaffold。模板是那种越用越有感觉的东西等你的模板库累计出几十个命令文件后你会明显地感受到AI 协作不再是从零解释而是像一个熟悉项目的搭档在和你一起干活。