如果你和我一样几乎每天都在用 Claude Code 写代码、改 bug、做重构那你一定经历过这种循环新开一个项目先花二十分钟把项目背景、技术栈、代码风格、常用命令一条条喂给 Claude Code等它终于表现得像个熟悉项目的同事了项目差不多也要收尾了。换个新项目再来一遍。这套重复劳动逼我做出一个习惯——把整个调教过程全部沉淀成一套 claude-code-templates。这个模板库装的不只是几个 Markdown 文件而是一整套让 AI 编程助手快速进入状态的约定、流程和检查清单。这篇文章会把我的完整思路、目录设计、踩过的坑全部摊开给正在折腾 Claude Code 工作流的人一个可以直接抄作业的参考。1. 反复搭模板的真实动机同一套调教动作我做了不下二十遍1.1 每次新项目都要重新教育AI 助手太浪费了大概从我开始把 Claude Code 当作主力编码工具开始就陷入了一个循环。每接到一个新项目我先建仓库、搭目录结构然后打开终端把项目背景、技术栈选择、目录约定、编译命令、测试命令一条条敲进去。第一天基本都在做这种信息灌输第二天 AI 才开始产出稍微靠谱的代码。后来我意识到这个教育成本其实是完全可以复用的。于是我开始写第一个 CLAUDE.md。起初只是简单记了几条项目约定后来发现每个项目都在重复写相似的内容我就琢磨着把这些内容抽出来做成一套模板。这个模板不能只是几个文件拼在一起而是要区分哪些是全局通用规则哪些是项目特有约束哪些是某个会话里才需要临时说清楚的上下文。分开之后模板的复用性才真正起来。1.2 模板库里该装什么不该装什么先说清楚一个边界claude-code-templates 不是代码片段收集站更不是提示词大全。它在我这里只负责三件事行为约定、流程脚本、项目骨架。行为约定指的是 Claude Code 在项目里应该遵守的规则比如编码风格、命名习惯、禁忌操作。流程脚本指的是那些需要按顺序执行的多步操作比如初始化项目、跑测试、做 code review。项目骨架是空项目结构方便新项目第一时间建起来。不该装的东西我也踩过。以前我试过把一些通用领域知识写进模板比如 Git 操作规范、数据库设计原则写了满满一堆最后发现 Claude Code 本身掌握这些常识重复写进去只会占用上下文窗口让真正重要的项目信息反而被稀释。模板库的定位应该是补充增量不是重复造轮子。2. 模板库的地基CLAUDE.md 三层结构怎么设计2.1 全局层放通用习惯项目层放架构约束会话层放临时上下文我最终把 CLAUDE.md 的分层定为三层全局层、项目层、会话层对应三个不同范围的上下文文件。全局层放在~/.claude/CLAUDE.md里面装的是我个人在所有项目里不变的偏好。比如代码注释用中文还是英文、函数命名倾向、commit message 的格式、禁止在没有测试的情况下直接改核心模块代码。这一层的内容非常克制只写会长期生效的规则不会随项目变化。项目层放在每个仓库根目录的CLAUDE.md内容围绕这个项目本身的架构和技术栈展开。包括项目简介、目录结构、启动和构建命令、依赖管理方式、模块边界、已知的技术债。这一层是 Claude Code 每次会话默认加载的核心上下文写得好不好直接决定 AI 产出的质量。会话层是更细粒度的上下文。Claude Code 支持在子目录里放局部 CLAUDE.md 文件或者我在会话里通过/add-dir临时指定某份说明文档。这一层适合放模块级说明、接口文档摘要、某次迭代的任务清单。三层的作用我用一个表格概括层级文件位置典型内容更新频率全局层~/.claude/CLAUDE.md个人编码偏好、标签规范、安全检查策略几个月一次项目层仓库根目录 CLAUDE.md技术栈、架构约束、构建命令、目录约定项目关键节点会话层子目录 CLAUDE.md 或临时引用当前任务背景、模块细节、迭代目标每次会话都可能变2.2 优先级与覆盖规则越近的规则越优先三层文件同时存在时Claude Code 会合并加载这些上下文但规则之间可能冲突。我在踩过几个坑之后给自己定了一条规定就近优先全局兜底。项目层里如果明确写了这个项目必须使用面向对象写法那全局层里写的函数式优先就自动让位。会话层如果有临时说明这次重构暂不改动接口签名它又比项目层的长期约定更优先。为了减少冲突全局层里我不再用强约束语言而是改成如果没有项目级规则默认这样做。这样既保留了通用习惯又给项目层留足定制空间。2.3 我给 CLAUDE.md 定的语法规范实际写 CLAUDE.md 的时候最忌讳的是大段散文。AI 读得懂自然语言但指令越松散执行越飘。我把自己的模板文件定了几条硬性规范每条规则都写成如果...那么...的形式可执行、可检查每个章节用二级标题分开禁止在一个标题下堆五六个无关主题能用清单表达的就不用段落清单项不超过一行明确标注禁止项因为 AI 对否定指令的执行效果往往比肯定指令更可靠所有命令要写清楚在哪一层目录执行避免路径歧义举一个我全局文件里的例子以前我写的是代码风格要保持整洁后来改成这样当修改 Python 文件时如果函数超过 30 行请主动提出拆分方案新增模块必须包含模块级 docstring说明该模块的职责和边界。这种写法执行起来明显更稳定。3. 模板库里真正值得沉淀的四类模板3.1 项目初始化模板从空目录到可运行状态的第一步项目初始化是使用频率最高的模板。我把它做成了一个自定义 slash command放在.claude/commands/init-project.md里每次新项目直接输入/init-projectClaude Code 就会按照模板走一遍流程。模板的内容分成几个阶段第一阶段是盘点现状。AI 先扫描当前目录识别是不是空仓库、是否已经有部分代码、有没有现成的 README 或构建文件。第二阶段是补齐信息。如果项目背景不明确它会列出需要我确认的几个问题比如目标技术栈、包管理器、运行环境版本。第三阶段是根据我的回答生成项目级 CLAUDE.md 和基础目录结构并给出第一个可运行命令。这个模板之所以值得沉淀是因为它把从无到有的过程标准化了避免每次新项目都靠手动敲命令一点一点喂上下文。3.2 代码审查模板让 AI 当挑剔的同事而不是夸夸机器很多人让 Claude Code 做 code review得到的就是代码看起来不错建议补充测试这种毫无营养的回复。问题不在工具而在模板。我在 review 模板里做了三个强制要求。第一只审查 diff不 review 全文。第二按危险等级分类输出阻塞问题、应该改的问题、可选建议。第三每条建议必须给出为什么和怎么改不允许只说现象。review 命令的头部我会写成这样你现在是一个有十年经验的资深 reviewer。只关注本次提交的代码变更忽略不相关的历史代码。输出格式按阻塞问题/应修改/可选建议三类列出。每条问题必须包含影响范围、复现条件、修改建议。如果本次提交没有阻塞问题明确说明不要为了凑数而挑刺。加上这个约束之后review 质量一下子上来了。有一次它真的在 diff 中发现了一个循环边界问题原因是模板里要求优先检查数组索引和循环条件这个具体约束比泛泛的请仔细检查代码高效得多。3.3 测试用例生成模板先立测试边界再谈覆盖率我在测试模板里沉淀的不是生成测试代码而是生成测试计划。流程是先让 AI 根据需求列出需要覆盖的功能点每个功能点拆成正常路径、边界路径、异常路径三类用例等计划确认之后再生成代码。这个流程写清楚后生成的测试用例明显更有针对性而不是随手补一堆断言。模板里有这么一条是花了很大代价才总结出来的在编写测试之前先列出被测函数的输入约束和可能的状态变更。如果被测函数依赖外部服务明确标记 mock 策略。禁止生成只断言函数被调用过的假测试。这条规则救过我很多次。以前生成的测试看着覆盖率挺高实际上全是空转断言的都是无关紧要的东西。3.4 故障排查模板把猜测变成结构化假设验证Debug 是最容易让人血压升高的工作。Claude Code 一旦被放任自由发挥很容易顺着错误线索一路狂奔。我后来给它设计了排查模板核心是三步走复现、定位、验证。复现阶段只允许做信息收集不允许改代码。要求 AI 先还原报错现场包括完整错误堆栈、输入数据、操作步骤。定位阶段要求列出至少两个候选假设每个假设都要有证据支撑不能凭直觉。验证阶段先做最小改动再跑关联测试。这个模板让排查过程变得极其有秩序。我印象最深的一次AI 本来怀疑是数据库连接池耗尽按模板要求先查连接数曲线结果发现是某个 SQL 没走索引。模板里的证据先行原则直接省掉了一次无效的代码改动。4. 模板可复用的关键把意图写成约束而不是写成描述4.1 约束表达的三要素边界、优先级、验收标准模板里写规则最怕的写法是请生成高质量代码。这句话没有任何可执行性。我后来把每条规则都拆成三要素边界、优先级、验收标准。边界是什么情况下适用这条规则什么情况下不适用优先级是这条规则和其他规则冲突时谁说了算验收标准是做完之后怎么判断做对了。举个例子我在模板里写代码规范时会这样写在修改已有模块时如果新代码与旧代码风格不一致优先沿用旧风格保持一致性除非旧风格存在可复现的 bug。验收标准是 diff 中新增代码与上下文的缩进、命名风格保持一致。有了验收标准之后AI 输出就有了自检依据不需要我每次一遍遍纠正。4.2 变量化设计一套模板怎么服务多类项目模板要复用就得处理不同项目之间的差异。我的做法是把差异点集中到模板头部作为变量区而不是散落在文件各处。比如初始化模板的变量区会要求一次性确认技术栈、包管理器、目录风格、测试框架。后续所有步骤都从这些变量里取值不再中途提问。这套设计让我管理了多个项目之后仍然保持模板稳定。变量区相当于接口具体实现可以各不相同但入口是统一的。如果你手头有 Node 项目、Python 项目、Go 项目一个初始化模板配合变量区就够用不需要给每种技术栈各建一个模板。5. 模板库的版本管理、多设备同步与演进5.1 用 git 管理模板库像管代码一样严格模板库本身就是一个仓库我建议你像我一样用 git 管起来。目录结构大致是这样claude-code-templates/ ├── commands/ # 自定义 slash command │ ├── init-project.md │ ├── review.md │ ├── test-plan.md │ └── debug-trace.md ├── global/ # 全局层 CLAUDE.md 的源文件 │ └── CLAUDE.md ├── project/ # 项目层模板骨架 │ ├── CLAUDE.md.tpl │ └── README.md.tpl ├── scripts/ # 安装与同步脚本 │ ├── install.sh │ └── sync.sh └── docs/ # 模板库自身的说明文档每次更新模板我不直接改文件而是在仓库里先改通过脚本同步到全局位置和各个项目。提交信息会写清楚改了什么规则、为什么改、影响了哪些项目。这套流程后面帮了大忙——我可以回溯某条规则是什么时候引入的避免规则越积越多却说不清来源。5.2 自定义 slash command 的封装技巧自定义命令是模板库最灵活的载体。在.claude/commands/目录下放一个 Markdown 文件文件名就是命令名。文件内容就是指令本身可以引用外层模板文件。这就相当于把一组多步操作封装成一个入口执行时候只需要/review敲一下。我很推荐在命令里用几步小设计开头明确角色的工作前提避免自由发挥中间按步骤拆解任务每一步有输入输出结尾强制输出一个结果确认清单让用户快速判断是否完成比如 review 命令的完整流程是先读取 diff再核对项目级规则里的禁用项然后分三级输出意见最后给出一个修改优先级排序的总结。这套流程封装好之后我只需要敲一句命令它自己会走完整个流程。5.3 模板的更新节奏每次项目收尾做一次复盘模板库必须持续演进否则会僵化。我的节奏是每个项目结束后回顾这次项目中 Claude Code 表现最好和最差的地方。最好的地方固化成新规则最差的地方查明原因要么调整指令要么删掉导致误判的旧规则。复盘的时候我会重点审视新出现的重复劳动。如果这次项目里我又手动纠正了 AI 的同一个错误三次那就说明模板里缺一条规则。如果某个模板在整个项目里一次都没触发过那我会考虑删掉它或者重新设计。模板库的增量更新就像代码重构——保持精简才有价值。6. 实测踩坑模板不是越厚越好写多了反而翻车6.1 上下文过长会稀释关键指令我一度把全局层写得很长涵盖编码习惯、工具链偏好、评论风格、命名规范、提交格式。结果发现 Claude Code 在具体项目里的判断反而变弱了。后来想明白上下文窗口是有限的模板文件挤占了太多空间真正处理项目代码的有效上下文就变少了响应速度也变慢。这个问题的解法是瘦身。全局层只留那些真正跨项目生效且高价值的规则项目相关的东西一律下沉到项目层。瘦身之后Claude Code 的响应质量明显回升。这也让我意识到模板库不是文档库每一行规则都有上下文成本。6.2 指令冲突会让 AI 陷入选择困难模板多了之后另一个常见问题是不同模板间的指令冲突。比如全局模板规定新代码使用函数式风格项目模板规定延续现有类的写法AI 就会来回摇摆甚至在一个文件里混用两种风格。这个问题光靠就近优先还不够还需要在写规则时就尽量避免写入相同维度的对立指令。我更推荐的做法是把规则拆到不同维度。全局层管安全底线和红线项目层管架构走向和代码风格会话层管当前任务细节。如果真出现冲突模板里必须写明冲突时以哪个为准否则 AI 只会随机挑一个。6.3 模板维护中最值钱的一步回填结论最后分享一个很多人都会忽略的动作每次排查完一个复杂问题或者做完一次大重构我会把收获和教训回填到模板库里。回填的时候不是复制总结而是提炼成一条如果...那么...规则。这个动作让模板库越来越贴合自己的使用习惯而不是停留在刚创建时的样子。真正好用的 claude-code-templates 不是一次性写出来的是每个项目一块砖一块砖垒出来的。
