claude-code-templates 这个项目说白了就是一套给 Claude Code 用的“工作手册”仓库。先说一个场景我自己刚用 Claude Code 那段时间每次开新会话都得在 prompt 里反复交代同样的背景——“先读一下 README 再动手”“别碰 lock 文件”“测试用 pnpm 跑”“代码风格不要乱改”。稍微复杂点的任务光前情提要就能打满半个屏幕而且只要哪回少说一句对话质量就立刻掉档。后来我把这些重复指令整理成了一个模板库让 Claude Code 在每次开始任务前自动加载发现整个使用体验完全不一样了。这个项目就是我整理出来的那套模板集合包含按场景拆分的 CLAUDE.md、自定义斜杠命令、以及配套的使用文档。它解决的核心问题是让 AI 在项目里像一个真正“知道上下文”的老成员而不是每次都重新认识一遍这个仓库。适合所有在用 Claude Code 做日常开发的人也适合想在团队里统一 AI 工作流的同学参考。1. claude-code-templates 到底在解决什么问题1.1 模板化不是因为懒而是因为对话是“一次性”的Claude Code 的工作方式跟普通聊天窗口不太一样你给它一个任务它基于当前会话的上下文去理解、规划、执行。但每次新开会话它对这个项目的认知基本等于零。它不知道你的项目是干嘛的、代码风格是什么、测试怎么跑、哪些文件绝对不能改。这些信息你每次都得重新喂一遍这就是“一次性对话”的弊端。一个很直观的类比是开会。如果你请来一个顾问每次开会都从“我们这个公司是做什么的”讲起那这个会的前十分钟就废了。如果你提前给他一份公司简介、一份会议议程、一份决策边界说明他进来就能直接聊正事。claude-code-templates 里的模板就是这份资料包它把你希望 AI 默认知道的项目背景、行为规范、工作流约定全部固化成文件让 AI 在对话开始时就自动“读过”一遍。我最初是被这个痛点逼着才去搞模板的。当时有个小项目我连续三四个会话都在跟 Claude Code 重复同一批指令最后实在烦了把常见的七八条约束写进 CLAUDE.md结果下一轮对话它就主动说“根据项目约定我先跑一遍现有测试再定位问题”。那一刻我是服气的——它不是变聪明了而是终于有了一份靠谱的入职手册。1.2 模板的边界不是越详细越好很多人在了解模板机制后容易走向另一个极端把模板写成一本几百行的“百科全书”。这反而是我见过最多人踩的坑。模板的核心价值是“固定高质量默认行为”不是替代需求文档。它应该写清楚的是AI 在这个项目里扮演什么角色、在开始任务前必须做什么、代码和流程上有哪些约定、哪些操作绝对不能碰。至于某个具体功能怎么做、某个模块怎么优化这是你每次在 prompt 里该给的信息不该塞进模板。否则模板会变得又长又杂AI 在长上下文里反而会丢失关键约束。我自己对模板的取舍有个标准如果这条规则适用于这个项目的绝大多数任务它就值得进模板如果它只适用于某个特定场景那就应该放进按需加载的场景模板或斜杠命令里而不是堆在全局模板里。这也是 claude-code-templates 这个项目把模板按任务类型拆成多个文件的原因——不是为了好看是为了让 AI 在什么场景只读什么该读的内容上下文更干净指令更不容易被稀释。2. 模板里的核心技术点CLAUDE.md 的加载机制与字段设计2.1 CLAUDE.md 的加载机制与分层记忆要玩转模板库必须先理解 CLAUDE.md 是“怎么被 AI 读到的”。Claude Code 有一套内置的记忆加载约定项目根目录的 CLAUDE.md 会在会话开始时被自动加载作为项目级长期记忆用户主目录下的全局配置也可以放一份那是跨项目的用户级偏好。除此之外项目里还可以用.claude/commands/目录放自定义斜杠命令需要的时候输入/命令名才会临时加载对应的模板内容。理解这一层很重要因为很多人的模板“不生效”根本不是内容写得不好而是文件放错了位置或者没理解加载时机。我见过有人把项目专用规则写进了全局模板结果打开任何项目 AI 都在执行那套规则冲突不断也有人以为改完 CLAUDE.md 当前会话马上生效实际必须重开会话才会重新加载。在我的项目里模板是分层设计的最底层是全局模板只写放之四海皆准的原则比如“不要在没有确认的情况下执行批量删除”“遇到模糊需求先提问”往上一层是项目级 CLAUDE.md写这个仓库的具体玩法比如技术栈、启动命令、文件组织约定再往上是按场景拆分的命令模板比如代码评审、写单测、提交信息这些只在特定时候才需要被加载的内容。三层各管各的互不污染。2.2 六个关键字段构成一份靠谱的模板骨架我拆过很多模板包括自己反复迭代的版本最后发现一份能稳定起作用的模板其实就六个关键模块。不用每次全写但至少要有三到四个否则这个模板很难“立住”。第一是身份与目标。告诉 AI 它在这个项目里应该以什么视角工作。比如“你是一名重视可维护性的后端工程师”和“你是一个快速出原型的脚本选手”这两种身份下的行为偏好完全不同。第二是环境与背景。项目用什么语言、什么包管理器、测试跑什么命令、构建流程是什么。这部分是最能减少无效追问的因为 AI 不用再猜也不用靠读文件去推断。第三是启动流程。约定任务开始前的固定动作。比如“接到任务后先看 README 和 docs/ 目录”“先列出你对任务的理解再动手”。这招对防止 AI 拿着半懂不懂的需求直接开码非常管用。第四是工作约定。包括代码风格、提交信息格式、命名习惯、单测要求等。这里我特别建议写得像“checklist”而不是散文AI 对这种格式化要求的执行明显更稳定。第五是边界与禁忌。比如“不要修改 lock 文件”“不要做全文件格式化”“批量替换前必须逐一确认”。这是我自己最看重的一块因为 AI 闯祸通常不是因为它不会做事而是它太会做事——你让它优化三行代码它顺手给你格式化了整个目录。第六是输出偏好。方案对比用表格、代码块必须标注语言、解释问题要给出前提假设。这能让对话效率上一个台阶。我挑一段自己模板库里的骨架给你看你现在写 CLAUDE.md 完全可以照这个结构起步# 身份与目标 你是这个仓库的核心维护者优先保证现有功能不被破坏再考虑代码组织优化。 # 环境与背景 - 技术栈Node.js TypeScript - 包管理器pnpm - 测试命令pnpm test - 代码规范ESLint Prettier不要自动格式化整个文件 # 启动流程 1. 接到任务后先简述你对需求和改动范围的理解。 2. 改动前先确认当前分支必要时建议新建分支。 3. 完成后跑一次 pnpm test再提交改动说明。 # 边界与禁忌 - 不修改 package-lock.json / pnpm-lock.yaml。 - 不做大范围格式化或全局替换。 - 遇到不确定的接口调用先查调用方的实际用法。2.3 场景化命令把长模板拆成随用随取的“技能包”如果说 CLAUDE.md 是默认加载的“常驻记忆”那斜杠命令就是按需取用的“技能包”。这是 claude-code-templates 里做得比较顺手的一部分。例如我仓库里有个/code-review命令它对应的模板文件里只写了“按以下维度评审本次改动逻辑正确性、边界遗漏、可测试性、命名与可读性、性能隐患。输出格式按严重程度排序并给出修改建议”。平时这个模板完全不会加载但你一旦输入/code-reviewAI 就立刻进入代码评审专家模式。这个设计思路非常像工具包常驻记忆只放最常用的几把“基础工具”各种专业用途的“专用工具”都收纳在柜子里用的时候再拿。好处是会话上下文不会被大量无关指令占满AI 对关键规则的注意力明显更强。我自己实测过一个场景同一批代码用不加载任何命令的普通会话去让它评审和加载/code-review模板后去评审后者给出的结果深了不止一个级别因为它有明确的评审维度不会天马行空乱说。3. 从零搭建自己的模板库路径、结构与迭代流程3.1 先做一周“高重复输入”记录别急着写如果你也想搭一套自己的 claude-code-templates我先劝你一句不要凭借大脑里的模糊印象上来就写。我第一版模板就是凭印象写的结果里面一半规则是我自己想当然的另一半是重复两三次才发现的真问题写完后 AI 的行为并没有显著改善。后来我换了个笨办法连续一周每次跟 Claude Code 交互时把那些“你又输了第二遍”的内容记录下来。不一定是长篇大论可能就是“先跑测试”“别改配置”“用中文回复提交信息”“保持小步提交”这类的短句。一周下来你会发现真正高频率出现的其实就是那么十来条而它们大多数可以归纳成“启动动作”“输出偏好”“边界禁忌”三类。这一步的核心价值是让你的模板从“感觉可能需要”变成“实际被反复需要”。模板不是写给 AI 看的规则清单而是你过去工作习惯的真实投影。只写你真正依赖的规则AI 才能真正帮到你写一堆你都不会遵守的规范AI 执行了反而添乱。3.2 从最小可用模板开始别一口气上全量我强烈建议第一版模板定一个小目标能覆盖你日常 80% 对话的背景交代就够。不要试图把代码规范、评审标准、CI 流程、文档要求全部塞进去那只会让第一版既难维护又难调。我自己的第一版 CLAUDE.md 其实非常朴素只有五条先读 README 再回答任务开始前列出理解保持现有代码风格不碰 lock 文件提交信息用约定式格式。就这么五条已经让新会话的“寒暄成本”大幅下降。后面每遇到一个新的重复痛点再往模板里加一条持续迭代滚动。这样的好处是你知道是哪一条规则让 AI 行为变好了哪一条其实是无效甚至有害的。如果一上来就写二三十条AI 出问题你根本不知道是哪条在捣乱。3.3 文件放哪、优先级是什么这部分别搞错模板文件的放置位置直接决定了它的生效范围。我的做法是这样项目级 CLAUDE.md 放在仓库根目录跟着项目走只描述这个项目相关的东西。用户级全局配置放在个人主目录的.claude/下写放之四海皆准的工作习惯。斜杠命令则放在项目级.claude/commands/或用户级~/.claude/commands/里项目级会覆盖用户级同名命令。这个分层如果没理清很容易出现“AI 在 A 项目里执行了你在 B 项目里设定的规则”这种低级事故。我自己就翻过车某次在全局模板里写了“所有交互使用 XX 约定”结果另一个项目的 AI 也被强制套用造成了不小的混乱。现在我的原则是——全局模板只写心态层面的原则比如“不盲猜需求”“动手前先确认”一切与具体技术栈、目录结构、工具链相关的内容全部下沉到项目级或按需命令里。给一个目录结构参考这也是 claude-code-templates 仓库本身的组织方式claude-code-templates/ ├── templates/ │ ├── CLAUDE.md # 项目级常驻模板 │ ├── code-review.md # 代码评审场景模板 │ ├── bug-fixing.md # 修 bug 场景模板 │ └── refactoring.md # 重构场景模板 ├── commands/ │ ├── code-review.md # 对应 /code-review 命令 │ ├── write-tests.md # 对应 /write-tests 命令 │ └── commit.md # 对应 /commit 命令 ├── docs/ │ ├── design.md # 模板设计思路 │ └── usage.md # 使用说明 └── README.md # 项目入口这里的关键是把“模板内容”和“命令绑定”分开。templates/里的文件是给人读的素材commands/里的文件才会被 AI 真正按需加载。这样你不需要改命令体系就能调整某个场景的模板内容维护起来清爽得多。3.4 模板库本身也要用 Git 管理并且值得开源共享最后给一个很容易被忽视的建议模板库本身也要纳入版本管理。我一开始就是本地建了个文件夹直接改后来发现改坏了没法回退也不知道是哪次改动让 AI 表现变差。把模板仓库纳入 Git 后每次改模板就像改代码一样有迹可循出问题可以直接git diff看改动效率一下就上来了。更近一步这类模板其实非常适合开源。因为好的模板经验是高度可复用的——每个团队在“启动动作”“边界禁忌”上的写法大同小异真正有差异的只是技术栈和业务约束。把模板开源出来一方面有人帮你 review 问题、提优化意见另一方面你也在给整个 Claude Code 生态沉淀方法。claude-code-templates 这个项目就是这样从个人实践慢慢长成了一套可复用方案的。4. 实测中的常见坑与排查思路4.1 改完模板没反应多半是会话没有重新加载这是我被问过最多的问题“我改了 CLAUDE.mdAI 没有变化啊。”原因很简单Claude Code 对 CLAUDE.md 的读取主要发生在会话启动阶段你在一段已经开始的对话里改文件它大概率不会动态感知。要像改完代码重启服务那样重开一个新会话新模板才会生效。另外还要确认你没有把小写打错。文件名必须严格是CLAUDE.md才能被识别claude.md或者claude.MD都不行。这种看一眼很蠢的坑我身边真有人踩过而且排查了半小时才发现是大小写问题。4.2 模板越长AI 反而越“笨”这是我另一个深刻的教训。有段时间我把各种“经验”都往 CLAUDE.md 里塞什么“遇到性能问题优先考虑缓存”“ORM 字段别用前缀”“时间字段统一存时间戳”……写了两百多行。结果发现 AI 在执行基础任务时反应明显变慢而且经常抓不住重点把一些边缘规范当成首要约束。原因其实可以理解上下文是有容量的模板越长核心约束在相对位置上就越不显眼。AI 可能看得到但注意力被分散了。现在我的策略是严格分层全局和项目级 CLAUDE.md 控制在 20 到 30 行以内只保留最高频、最关键、收益最大的规则那些适用于特定场景的丰富细节全部挪到斜杠命令的模板文件里。效果很直接——AI 对核心规则的遵循率明显回来了。4.3 模板规则与实际需求冲突了怎么办模板是默认行为不是铁律这一点必须在模板里写清楚。比如我的某个项目里模板写了“不自动修改 lock 文件”但某次升级依赖确实必须更新 lock 文件这时如果模板没有任何关于“例外处理”的说明AI 大概率会卡在规则上反复询问或者干脆自作主张绕开。合理的做法是在模板里补一句当任务明确需要违反某条禁忌时先说明理由并争取确认而不是直接拒绝或硬执行。这不仅是给 AI 的指令也是对团队协作边界的定义规则存在的意义是防止手滑而不是限制决策。有了这一句“例外说明”模板就从一个僵硬的检查表变成了一个灵活的协作协议AI 的行为会合理得多。4.4 快速排查自查表现象可能原因处理方式改模板后行为没变会话未重新加载记忆重开会话再试模板完全没生效文件名或路径不对检查是否为根目录的CLAUDE.md注意大小写规则偶尔执行偶尔不执行模板过长核心约束被稀释精简常驻模板细节下放到命令模板项目间规则串味全局模板里写入了项目专属内容把具体技术栈规则移到项目级模板出现矛盾指令全局与项目级模板内容冲突以项目级为准并删除全局中的冗余描述不清楚 AI 到底读了哪些规则模板加载状态未知在对话里直接询问它做了哪些预设让它复述最后一条我自己现在经常用。遇到 AI 表现奇怪我第一件事不是看日志而是直接问它“你现在记住了哪些项目规则请逐条列出。”它复述出来的内容立刻能暴露问题——是没加载到还是加载了但理解偏了一目了然。5. 场景选型速查与模板演进5.1 常见场景模板选型对照模板库最忌讳的就是一刀切因为你的任务类型差异极大。评审代码和写测试需要的上下文完全不同维护老项目和新项目的行为约定可能完全相反。我整理了一张自己常用的选型表你可以按需取用使用场景推荐模板核心内容建议位置日常小改动项目级 CLAUDE.md角色、启动动作、输出偏好、基础禁忌项目根目录代码评审code-review 模板评审维度、严重级别排序、修改建议格式.claude/commands/写测试write-tests 模板测试范围、用例命名、mock 约定.claude/commands/修 bugbug-fixing 模板先复现、再定位、改后回归验证.claude/commands/重构refactoring 模板保持行为一致、避免大范围改动、小步提交.claude/commands/提交代码commit 模板提交信息格式、前置检查.claude/commands/这张表不是标准答案而是一个起点。你可以对照自己的实际工作流去增删。关键点是默认常驻模板要克制斜杠命令要丰富。常驻模板负责“不出错”命令模板负责“做得好”。5.2 模板是活代码需要随项目一起演进模板库不是写一次就一劳永逸的东西。项目在变你的工作流在变AI 工具本身也在变模板必须跟着项目一起演进。我自己大概每一到两周会翻一次模板做一次“清理”删掉那些 AI 已经形成惯性、不再需要提醒的规则。比如某个项目里早就不需要强调“先跑测试”因为它每次都跑了这条就可以从模板里拿掉给更重要的新约束腾地方。然后补上最近踩过的新坑。比如我某次发现 AI 在重构时差点改了公共接口回来后我就在 refactoring 模板里加了一条“涉及公共 API 变更前必须列出所有受影响调用方。”这个“清理—补充”的节奏比任何一次性的精心设计都重要。因为模板的价值永远不在于纸面上的完整性而在于它对当前阶段的真实工作是否还有指导意义。一份好久没动的模板跟一份好久没维护的代码一样会慢慢变成团队里的“僵尸文档”。5.3 最后说一点个人体会在做 claude-code-templates 之前我一直觉得让 AI 干活的核心是“prompt 写得好”。后来发现prompt 写得好不如把高频的公共上下文沉淀成模板来得稳定。前者靠临场发挥后者靠体系复用。用 Claude Code 到现在模板库是我改动频率最高的“基础设施”之一它在不知不觉中提升了每一次对话的下限——就算某一轮我懒得写太多细节AI 也不会从零开始而是站在模板给它搭好的肩膀上干活的。如果你刚开始做这件事我只建议你记住一句话模板要越用越“贴手”不用怕改不用怕删。把模板当代码写慢慢迭代它会在你日常开发里变得比想象中更值得依赖。