干了一年多 Claude Code我越来越确认一个判断在 AI 编程工具里模板体系是最容易被低估、也最值得花时间沉淀的东西。Claude Code 本身用起来很简单装完包、进到项目目录、启动对话一条自然语言指令就能让它开始读代码、改代码、跑测试。但项目一复杂你会发现同一个模型、同一套工具在不同仓库里的表现能差出几个量级。差在哪绝大多数时候不是模型不够强而是你没有给它一套稳定、可复用、有约束力的模板。这也是我为什么专门把“claude-code-templates”拿出来写一篇。很多人在网上问“Claude Code 那个 CLAUDE.md 到底怎么写”也有人把模板理解为“提示词集合”其实都不完整。模板不只是给它一段话而是一整套结构化的项目记忆、行为守则、命令封装和角色定义。这篇文章就讲讲我实际搭模板时踩过的坑、沉淀下来的结构以及一些从文档里翻不出来的细节。1. 为什么 Claude Code 需要“模板”体系1.1 Claude Code 的模板到底管住哪几层先对齐一下概念。Claude Code 是跑在终端里的 AI 编程代理它直接操作你的代码仓库读文件、写文件、执行命令、开 issue、提 PR 都能做。它的核心交互是自然语言但你每次对话都从一轮新的上下文开始模型对你的项目一无所知它只能靠“当前对话携带的信息”加上“它能读到的文件内容”来行动。这里就出现了模板的存在意义。模板不是给用户看的界面皮肤而是给模型看的“项目初始化记忆”。它管住三个层次项目身份层这个仓库是做什么的、技术栈是什么、目录怎么组织、有哪些约定俗成的东西。行为约束层模型能跑哪些命令、不能碰哪些目录、输出格式要遵循什么规范、遇到问题时该按什么顺序排查。能力封装层把高频操作做成可复用的命令、Agent、提示词片段让模型按标准流程执行而不是每次重新解释。很多教程只讲了第一个层次把 CLAUDE.md 当成一个加大版的 README。但实际上后两层才是模板真正产生杠杆效应的位置。行为约束直接决定模型是“乱跑还是稳着跑”能力封装决定你是把时间花在重复打字上还是花在真正需要判断力的事情上。1.2 不写模板的典型症状提示词坍缩与上下文浪费我在开始用 Claude Code 的前两周没有系统写模板全靠对话框里现场打长指令。看起来也没啥大问题但项目推进到中等规模后三个症状非常明显第一个是提示词坍缩。同一件“帮我跑单元测试并修复失败用例”这件事我每次都要把项目背景重新解释一遍“我们这是个 Rust 项目测试用 cargo testCI 里还会跑 clippy……”。解释一遍还好问题是解释完它还是会遗漏部分约束比如某些目录不能改、某些测试依赖外部服务。你会发现自己变成了复读机助手变成了“每次听完都忘一半”的实习生。第二个是上下文浪费。模型能一起携带并处理的信息窗口是有上限的当前是 200K token 级别你说废话它留给真实代码的信息就少。你每次重复项目背景等于从大窗口里白白扣掉一截更糟糕的是这些描述往往不如一份精心编写的 CLAUDE.md 精确。第三个是行为漂移。同一个项目今天让它改接口明天让它重构目录它给出的代码风格、提交信息格式、测试覆盖标准前后不一致。看上去每个单次任务都完成了合起来却像几个人接力写出的不同风格代码。模板本质上就是把这些变量提前钉死。所以我的结论很简单Claude Code 的使用水平某种程度上就是“模板设计水平”。工具本身只会执行你的意图模板负责把你的意图结构化、稳定化。2. Claude Code 模板的目录结构与文件类型2.1 分清 CLAUDE.md、CLAUDE.local.md 和 .claude/ 的角色模板的第一个基本功是弄明白哪些文件会被 Claude Code 自动读取以及它们的优先级。这里有个容易混乱的点因为既有普通文件又有目录既有全局配置又有项目配置。先说项目根目录下的CLAUDE.md。这是最常用的项目记忆文件里面写的所有内容会在每次启动会话时注入给模型。你可以把它的地位理解为“项目立规矩的地方”。技术栈、目录结构、构建命令、测试命令、代码风格、常见操作禁忌都可以放进去。它是最顶层、最容易被模型读到的一份模板。再看CLAUDE.local.md。如果CLAUDE.md是想共享给团队的项目规范那CLAUDE.local.md就是你私有、不进版本库的本地记忆。适合放一些“只有你自己关心”的东西比如你本机的开发环境路径、个人常用工作流、当前正在解决的一个 issue 的上下文。它存在的意义是把“团队共识”和“个人偏好”分离避免向同事暴露你的私人笔记也避免个人内容污染团队模板。然后是.claude/目录。这是 Claude Code 的项目级配置目录里面能放的东西比单个文件复杂得多。常见结构包括.claude/ ├── agents/ │ └── senior-engineer.md ├── commands/ │ ├── review.md │ └── test-and-fix.md ├── hooks/ └── settings.jsonagents/放子代理定义相当于给模型准备几个“虚拟角色”比如代码评审员、测试工程师、架构咨询师commands/放自定义斜杠命令用/xxx就能触发一段特定的模板化工作流hooks/放自动化钩子能在模型执行特定动作前介入。这套结构不是摆设。Claude Code 对项目内信息的读取是分层级的越靠近当前任务目标的指令权重越高。你在CLAUDE.md里写的是宏观规范在.claude/commands/里写的是微观执行动作在agents/里写的是某类任务的专属专家。真正完整的模板体系应该把这三层都用起来而不是只塞一个CLAUDE.md。2.2 记忆的优先级与“先读谁”的规则理解了文件角色之后下一个问题就是这些配置同时存在时模型先听谁的。Claude Code 有一个目录加载优先级逻辑企业级策略组织统一配置优先级最高用户级配置~/.claude/CLAUDE.md作用于你所有项目项目级CLAUDE.md仓库内共享规范CLAUDE.local.md仅本地生效覆盖项目级也就是说越具体的配置越能覆盖通用配置。团队规范说“提交信息用英文”你本地文件可以覆盖成“提交信息用中文但标准格式不变”。这种覆盖机制设计得比较合理但它也带来一个陷阱如果你的~/.claude/CLAUDE.md里写了一大堆适用于所有项目的规则而某个项目有特殊结构需要不同的处理方式你得小心区分哪些是“通用铁律”、哪些是“按项目可覆盖”。我个人的经验是用户级配置只放三类内容通用的代码风格偏好、全局工具链说明、禁止执行的危险操作列表。凡是与具体项目强相关的东西一律下沉到项目内。另外有个细节Claude Code 也可以主动搜索项目里的CLAUDE.md文件并且支持通过目录形式组织比如docs/claude/CLAUDE.md。但根目录的CLAUDE.md是默认注入、无需显式引用。为了可预期性我建议所有核心规范都放在根目录子目录里的.claude文件只负责局部增强。2.3 自定义命令与 Agent 子代理模板的定位再往里走一层就到了模板真正发力的地方/commands和agents。自定义命令的形态是你创建一个 Markdown 文件文件名去掉.md后缀就变成了斜杠命令名。比如你创建一个.claude/commands/test-and-fix.md那对话里直接输/test-and-fixClaude Code 就会读取这个文件里的指令模板并执行。这个机制非常像 VS Code 里的代码片段只不过它生成的不是一段文本而是一整套行为流程。我在命令模板里通常写这四段结构# /test-and-fix 运行项目的完整测试定位失败用例修复代码并确保新代码不破坏已有功能。 ## 执行步骤 1. 先运行 {test_command}保存输出。 2. 逐个分析失败用例找出根因不要只修表面症状。 3. 修复后重新运行测试直到所有用例通过。 4. 如果失败原因涉及依赖或环境先报告不要擅自改配置。 ## 约束条件 - 不要修改与失败用例无关的文件。 - 不要更新依赖版本。 - 如果修复涉及架构变更先列出方案再动手。而 Agent 子代理模板则更进一步。它定义的是一个完整的“虚拟角色”可以有自己的系统提示词、自己的输出风格、甚至不同的模型参数设置。这相当于你项目里提前养了几个“不同工种的 AI 同事”一个帮你盯代码质量一个帮你搜资料一个帮你做重构。模板的作用是把这些角色的工作方式固定下来避免每次临时拼凑。3. 从零搭建可复用模板的完整实操3.1 第一步先做“项目体检”确定模板边界不要上来就翻文档照着模板大全抄那是给自己埋坑。正确做法是先回答一组问题这个项目最核心的技术栈是什么构建和测试命令是什么哪些操作是 AI 绝对不允许做的哪些目录是高危区域你希望 AI 每次动手前先确认什么我在一个新项目里会先跑一次“体检”操作其实就是让 Claude Code 自己读一遍仓库然后告诉我它观察到了什么。这个步骤有两个作用一是验证当前没有任何模板时它的表现基线二是它自己读出来的东西往往比我凭记忆写下的更全。我会把它概括的目录结构、构建流程再结合我的经验做修正最后形成模板初稿。模板的边界原则是“宁缺毋滥”。新手最容易犯的错是恨不得把公司 wiki 里所有开发规范都搬进去。结果模板本身占了大量 token模型反而没有余力关注真实的代码细节。边界划定的判断标准就一条这条规则如果某天缺失会不会导致 AI 做错事或者做出不可控的事会就留下仅仅是“写得好看”就删掉。3.2 第二步编写 CLAUDE.md 的黄金结构经过多次迭代我推荐的项目级CLAUDE.md结构大概是这样的# 项目概述 一句话说明项目定位以及这个仓库在更大系统里的角色。 # 技术栈与命令 - 语言、框架、关键依赖 - 启动命令 - 测试命令 - 代码质量检查命令 # 目录结构与职责 说明每个核心目录的作用特别指出 AI 不要碰的目录。 # 开发规范按重要性排序 1. 命名与代码风格 2. 测试要求 3. Git 提交规范 4. 依赖管理规则 # 常见任务操作流程 把最高频的 3-5 个任务写成可执行流程。 # 安全与禁忌 列出绝对禁止执行的操作。这里有个关键每个部分都要写“为什么”或者至少写“否则会怎样”。模型理解规则时不仅需要知道“不许改这个目录”最好知道“因为它是生成产物改了会冲突”这样它在碰到边界情况时才能做合理判断。纯命令式的模板也能用但灵活性差很多。另外写CLAUDE.md时有一个很强的经验要点所有命令必须给完整命令而不是“跑一下测试就行”这种模糊指令。模糊指令会逼模型去猜而猜的行为是不可预测的。明确写出cargo test --all-features和npm run test:unit它执行的准确性会高非常多。3.3 第三步沉淀自定义命令与角色模板CLAUDE.md完成后下一步就是把你平时反复手动输入的复杂指令变成/commands和agents。我会给每个团队项目至少建四个命令/review代码变更评审。自动读取 git diff对照模板里预置的代码规范逐项检查输出问题清单。/fix针对失败测试的一整套处理流程。先跑测试再定位失败再修复再回归。/refactor带约束的重构流程。先读代码结构、列改动方案经确认后才动手。/docs根据当前代码状态生成或更新文档自动保持文档与实现一致。再配上两个常用 Agentsenior-engineer代码质量视角专门做设计评审。它在回复时会更关注抽象边界、接口设计、可维护性。root-cause排障视角专门分析日志和错误堆栈。它的系统提示词会强调“不要只处理表面症状要追到根因并验证修复”。千万别觉得这些命令是一次性建好就能一劳永逸的。命令和 Agent 模板一定要放在版本库里随着项目演进持续修改。我见过最好的团队实践是命令文件像普通代码一样接受 PR有人改了约定就有人更新对应命令模板。4. 模板里的高阶技巧与注意点4.1 精简优先模板不是文档库写模板最大的坑就是把它写成文档库。很多团队的CLAUDE.md动辄几十上百行事无巨细什么都往里面装。结果是模型每次对话都背着沉重的历史包袱在真正需要理解代码时token 已经被项目背景吃干净了。我的量化经验是这样的一个中等规模的仓库CLAUDE.md控制在 50 到 80 行效果最好。超过 150 行就会出现两个问题一是模型对长文末端的规则关注度下降你写在最后的“禁忌事项”反而最容易被忽略二是每次会话都强制携带这些内容成本会持续累积。如果确实有大量详细文档需要模型参考正确做法不是塞进CLAUDE.md而是在模板里只写一句“详细架构说明在docs/architecture.md需要时再读”。让模型按需去读取比一次性全部注入高效得多。模板是索引和操作守则不是知识库本身。4.2 变量注入与多项目复用很多人没有意识到模板文件本身也可以带“参数”。Claude Code 的自定义命令支持在文件头部通过 YAML frontmatter 声明变量也可以在指令正文里用尖括号占位。比如我在.claude/commands/review.md里会预留一个参数--- description: 执行代码评审可指定评审范围 argument-hint: [文件名或路径可选] --- # 代码评审 相当于一位高级工程师进行详细评审重点关注 - 逻辑正确性和边界条件 - 错误处理是否完整 - 性能风险 - 是否符合项目架构约定 评审范围{argument}这样我在对话里输入/review src/utils/format.ts时它会精确地把评审目标注入指令中。如果省略参数则自动默认评审全部未提交改动。多项目复用则靠用户级模板。我在~/.claude/CLAUDE.md里放的是跟具体项目无关的全局规范Git 提交类型前缀、禁止使用rm -rf类危险命令、默认要求解释每一步操作理由。再结合每个项目的CLAUDE.md就形成一套“全局底料 项目特色菜”的结构。这样开任何新项目都不必从零开始。4.3 团队协作时模板如何共享与演进模板共享这件事最自然的载体就是 Git 仓库本身。把.claude/目录和CLAUDE.md提交进版本库团队成员拉下来就能用。不用额外引入工具链也不用担心配置漂移。但团队模板有一个特殊之处不同人的习惯、对 AI 的使用深度差异很大。有的人喜欢让 AI 天天跑整套流程有的人只让它做小任务、不希望它动太多文件。我在团队里采取的策略是公共的CLAUDE.md只放大家公认的硬规则把所有带个人风格、有主观性的内容移到CLAUDE.local.md。这样既保持了模板的统一底线又给每个人留了自由度。另一点经验是模板文件要有版本记录。我给模板提交信息里会写“CLAUDE.md新增迁移类任务操作流程禁止 AI 直接执行 DB 迁移命令”。这样等某天模型行为变得不可理解了你可以回退到上一个版本的模板快速找出是哪个规范变化导致的行为漂移。模板的演进频率也要保持克制。频繁改动会让团队无所适从也会让模型在不同会话之间的行为基线不稳定。我一般把模板变更需求攒成一个清单每周统一更新一次而不是想到什么就马上改。5. 常见问题与排查实录5.1 模板没生效按这四层排查用模板用得多了你就会碰到一件非常“灵异”的事明明写了CLAUDE.md但它好像没在起作用。这是最常被问到的排查问题。我的排查顺序永远是第一确认文件在不在正确位置。项目根目录必须是CLAUDE.md不是README.md不是docs/CLAUDE.md也不是你自己创建但没被约定的名字。第二确认有没有被更高优先级的规则覆盖。如果本地配置或企业级配置里写了冲突规则项目模板的部分内容可能直接被压掉。第三看会话上下文里有没有明确的历史指令。有时候你在某个会话中给它布置过一项特定任务它会优先执行任务要求而不是模板里的通用规则。第四确认模板语法没有意外。尤其是自定义命令YAML frontmatter 一旦少写一个冒号整份文件都可能被跳过。碰到“模板没生效”我强烈建议直接问模型“你有没有读过 CLAUDE.md”。它通常能准确告诉你哪些内容被纳入了上下文哪些没有。这一步诊断效率极高省得你自己瞎猜。5.2 上下文超长与行为漂移怎么用模板对冲上下文超长是另一个高频问题。项目大、对话历史长模板虽然精简但叠加代码阅读内容后token 消耗依然可观。这里有个纪律模板不仅要影响模型行为也要影响你自己的习惯。我每天开始新任务时都会主动使用/clear清空会话历史或者用/compact把历史浓缩成摘要。模板保证“项目记忆”不会因此丢失所以你清掉的只是历史对话垃圾而不是项目的核心背景。行为漂移则更隐蔽。同样一个模板昨天表现好今天突然变得激进或者拖沓。这种现象往往不是模板本身变了而是上游模型行为随时在变化。我可以接受这种变化但不能每次都措手不及。应对措施是在模板里加入“执行前确认”机制凡是删除代码、修改依赖、执行危险命令的操作必须在执行前停下来说明方案。有了这个保险即便模型变得激进了也不会直接做出破坏性操作只会“多问一句”。5.3 模板文件的版本管理与回滚最后提一下模板自身的版本控制。模板文件的改动看起来轻量但因为它的影响范围是全局性的一个小小的措辞变化可能引起模型一连串行为变化。我在团队仓库里把CLAUDE.md和.claude/目录纳入常规 Git 管理对每一次模板调整都单独提交。出现下面几种情况时我会立刻回滚模板某次模板更新后连续几个任务的代码风格变了模型开始频繁追问一些模板里本已说明的问题或者模型开始尝试执行之前明确禁止过的动作。这三种情况都是模板出了问题的信号往回退一版通常就能恢复。这样做还有另一个好处新成员加入项目时让他看模板的提交历史能让他在更短时间里理解整个项目的约定是怎么逐步建立的而不是面对一份已经定稿的文档空想“为什么这里要这么写”。最后讲一个我自己的经验吧。真正让我在 Claude Code 上效率起飞的不是什么神奇的提示词而是把模板体系当成代码一样对待写清楚、测过、放进版本库、持续演进。最初花了两三天把一套模板打磨成型之后几乎每一个新任务都在吃这套模板的红利。建议你先从小处入手哪怕只写一个十行的CLAUDE.md和一个/review命令跑几天感受一下再逐步丰富。模板这种东西不是拿来攀比的是拿来给未来的自己省时间的。
