如果你也跟我一样几乎每天都泡在终端里跟 Claude Code 打交道大概率遇到过这种场景昨天它还记得“不要动 dist 目录里的产物”今天你让它改个配置它顺手就把编译后的文件也重构了你明明告诉过它测试命令是pnpm test它却执着地敲npm test然后对着不存在的脚本报错一脸无辜。这不是模型变笨了而是你没有给 Agent 一本足够清晰的“操作手册”。Claude Code 的模板体系本质就是给 Agent 写操作手册。而我要说的 claude-code-templates就是一套把这份手册做成可复用、可版本管理、可跨项目同步的完整方案。这篇文章不是介绍 CLAUDE.md 格式有多么简单——那在官方文档里三分钟就能看完而是分享我自己在多个项目里把模板体系真正跑起来之后沉淀下来的目录划分、模板实例、翻车记录和迭代方法。适合那些已经用上 Claude Code、但还在靠口头叮嘱来约束 Agent 行为的人。1. Claude Code 模板的底层逻辑CLAUDE.md 到底在管什么1.1 CLAUDE.md 不是文档是行为约束器很多人第一次接触 CLAUDE.md会下意识把它当成一份 README 的变体写点项目介绍、技术栈、目录说明然后就不管了。这是最大的误解。Claude Code 在每次会话启动时会把当前目录及上层目录中的 CLAUDE.md 内容注入上下文作为跨会话的长期记忆。也就是说你在终端里每一次跟它交互无论聊需求还是让它改代码这份文件里的规则都在后台“压着”模型的输出。它既是操作手册也是行为约束器更是一套持久化的提示词系统。差异体现在什么地方我用一个真实例子说明。我的某个项目里CLAUDE.md 写了这样一条规则“任何时候不要删除 tests 目录下没有出现过的临时快照文件除非用户明确要求清理。”之后 Agent 在做重构时看到遗留的快照文件会主动询问“这些快照需要保留吗”而不是自作主张地删掉。反过来没写这条规则之前它会把快照当作“无用产物”直接清掉导致测试状态回溯困难。所以说CLAUDE.md 里的一句话很可能变成 Agent 行为边界上的一堵墙。模板本质上就是把“我知道在这个项目里该怎么干活”这件事变成稳定的、可以复制到其他项目里的规则集。这也是 claude-code-templates 这套东西能成立的根本原因。1.2 模板的加载机制与作用域要设计好模板先要搞清楚 Claude Code 到底会加载哪些文件。目前我实测下来它会按作用域读取下面这几层作用域文件位置适用场景全局~/.claude/CLAUDE.md所有项目的通用规则比如代码风格偏好、输出语言、通用安全红线项目根目录project/CLAUDE.md当前项目的基础规范、构建命令、目录结构、业务约束子目录project/modules/foo/CLAUDE.md对某个子模块的额外约束比如“该模块禁止直接操作数据库”个人覆盖project/CLAUDE.local.md同一份代码库内你自己的私有规则不随仓库提交关键点来了这些文件之间不是“覆盖”关系而是“拼接”关系。也就是说全局模板里的规则和项目模板里的规则会同时生效如果两者对同一件事的描述出现矛盾Agent 会倾向于按更具体、更靠近当前目录的那份执行。这带来的直接问题就是——全局模板不能写得太“重”。我见过有人把全局 CLAUDE.md 写成了一本上百行的百科全书结果每个项目里 Agent 的行为都被这套厚重的全局规则“绑架”项目模板里的精细约束反而被稀释掉。后面我会专门讲这个坑。设计模板的第一原则就是全局只放通行规则项目才放具体规则。2. 我的模板目录架构把模板拆成三层来管2.1 按“基础规范 技术栈 任务场景”划分早期我只有一份 CLAUDE.md所有规则都堆在里面。项目少的时候还好项目一多就失控了不同技术栈的约束互相冲突任务型指令和长期规范混在一起模板改一处就要重测一遍。后来我把模板仓库重构成了三层结构稳定多了claude-code-templates/ ├── base/ │ ├── CLAUDE.md # 通用项目规范模板 │ └── CODE_REVIEW.md # 通用代码审查规则 ├── stacks/ │ ├── frontend-react.md # React/前端项目专用规范 │ ├── backend-python.md # Python 后端专用规范 │ ├── backend-node.md # Node.js 后端专用规范 │ ├── infra-terraform.md # 基础设施仓库专用规范 │ └──>#!/bin/bash # apply.sh - 将所需模板组装到当前项目 set -euo pipefail TEMPLATE_DIR$(cd $(dirname $0)/.. pwd) STACK${1:-} # 例如 python / react / node DEST${2:-.} # 目标目录默认当前目录 # 1. 复制基础模板 cp $TEMPLATE_DIR/base/CLAUDE.md $DEST/CLAUDE.md # 2. 追加技术栈规范如果指定了 if [[ -n $STACK -f $TEMPLATE_DIR/stacks/$STACK.md ]]; then echo $DEST/CLAUDE.md echo ## 技术栈专属规范 $DEST/CLAUDE.md cat $TEMPLATE_DIR/stacks/$STACK.md $DEST/CLAUDE.md fi echo 已生成 $DEST/CLAUDE.md (stack: ${STACK:-none})用法很简单cd my-new-project ~/claude-code-templates/scripts/apply.sh backend-python .脚本没有任何黑科技但它强制了一个好习惯模板的组装过程是可重复的而不是每次靠记忆。哪怕哪次忘了追加技术栈规范看一眼生成的 CLAUDE.md 立刻就能发现。3. 可以直接抄走的几个高价值模板实例3.1 通用项目 CLAUDE.md 模板base 层下面这份是我 base 层模板的核心骨架去掉了业务相关的内容保留了所有项目通用的约束。如果你只想先跑起来从这个版本开始就够了。# 项目操作手册 ## 项目定位 - 用不超过 20 个字描述这个项目在做什么 - 目标用户是谁服务端还是客户端内部工具还是对外产品 ## 常用命令 - 启动开发环境: 填写 - 运行整个测试套件: 填写 - 运行单个测试文件: 填写 - Lint 检查: 填写 - 构建产物: 填写 ## 目录结构约定 - 业务代码放 src/测试代码放同级 tests/或对应框架约定 - 新增文件必须放在语义正确的目录下不要随手丢到根目录 ## 不可触碰的红线 - 不得删除或重命名用户没有明确要求删除的文件 - 不得修改 .git/、node_modules/、dist/ 等自动生成目录内的内容 - 不得在未确认的情况下批量替换字符串尤其是涉及配置项的值 - 运行 destruct 类命令rm -rf、git reset --hard 等之前必须打印将要执行的动作并征求确认 ## 协作习惯 - 主动汇报计划再动手写代码改动超过 200 行时先给变更说明 - 测试挂了先看日志定位原因不要第一时间改测试 - 完成一个任务后用简洁中文总结改动内容和影响范围注意“不可触碰的红线”这一节是所有模板里最值钱的部分。Agent 的默认行为是“尽可能完成任务”如果你不划定边界它就会在不该动的地方乱动手。这些红线词句写得越具体越不容易被误解。3.2 技术栈规范模板示例stacks 层以backend-python.md为例这一层要把 CLAUDE.md 里写不下的技术细节补齐。放的内容不是“怎么用 Python”——模型本来就懂——而是“这个项目的 Python 应该怎么写”。## Python 后端项目约束 ### 依赖与虚拟环境 - 使用 uv 管理依赖不要直接编辑 requirements.txt - 新增依赖时运行 uv add package统一用 pyproject.toml 记录 ### 代码风格 - 类型标注所有新增函数的入参和返回值必须标注类型 - 优先使用 dataclass 代替手写 __init__ - 异常处理捕获异常时必须指定异常类型禁止裸 except ### 测试规范 - 测试框架使用 pytest断言用原生 assert - 新功能必须附带单元测试覆盖正常路径和异常路径 - 与外部服务交互的测试必须 mock避免真实网络请求 ### API 约定 - 接口返回格式统一为 {code: 0, data: ..., message: ...} - 分页参数统一使用 page 和 page_size - 错误响应不能把内部堆栈直接抛给客户端这份模板的价值在于减少了“反复拉齐”的成本。以前跟 Agent 协作每周都要它“记得用 uv”“记得写类型标注”现在这些内容随模板注入它自己就能遵守。技术栈模板要随实际项目的pyproject.toml、package.json同步更新否则容易变成一张废纸。3.3 Code Review 任务模板tasks 层任务型模板不走 CLAUDE.md而是每次通过命令行临时指定。我用 Claude Code 的非交互模式搭配管道把 Code Review 流程固定下来。下面是我放在tasks/code-review.md里的内容。你是一位资深代码审查者。请按照以下维度审查我提供的 diff 1. 正确性是否存在逻辑错误、边界遗漏、并发隐患 2. 可维护性命名是否清晰、函数是否过长、有没有重复代码 3. 安全性是否有注入风险、敏感信息泄露、权限绕过 4. 性能是否有多余的循环、N1 查询、大对象拷贝 5. 测试关键逻辑是否有对应测试覆盖 输出要求 - 按“严重问题 / 建议改进 / 疑问”三部分输出 - 每条评论必须标注文件路径和行号 - 如果没有任何严重问题明确写“未发现问题”不要为了凑数而硬挑毛病 - 全部使用中文配合管道执行的效果是这样的git diff HEAD~1 | claude -p $(cat ~/claude-code-templates/tasks/code-review.md) --output-format text-p参数直接走非交互模式输出干净的审查结论。任务模板的好处在于强制一致每次 Code Review 的口径都是稳定的不会因为今天心情好就少看两个维度也不会因为项目快上线就放水。这份 prompt 我用了小半年真正让我省时间的是“不要硬挑毛病”这一条——它让模型不再输出一堆“建议给变量换个名字”式的废话。4. 模板配置中最容易翻车的几个坑4.1 模板过载上下文膨胀导致“记不住重点”Claude Code 的上下文窗口是有限的别指望它能无限承载你的规则。我踩过最狠的一次是给某个项目写了一个 300 多行的 CLAUDE.md把什么都写进去了连“发版时先跑版本号更新脚本”这种低频规则都包含在内。结果项目正常对话时Agent 开始频繁“忘事”——不是真的忘了而是模板里 80% 的规则跟当前任务无关稀释了真正重要的那条约束模型在长上下文中抓不住焦点。后来我把 CLAUDE.md 严格控制在 60100 行低频、琐碎、动态的信息全部挪到单独文件里用 语法按需引用。比如# 项目操作手册 ## 常用命令 - 构建: pnpm build - 测试: pnpm test ## 例行发版检查 docs/release-checklist.md这样 Claude 只在涉及发版任务时才会去展开release-checklist.md的完整内容平时对话根本不占用上下文。模板维护的核心思路就四个字按需加载。4.2 全局模板与项目模板互相打架全局模板和项目模板拼接生效的机制决定了它们之间一旦出现“覆盖式冲突”Agent 的行为就会摇摆不定。我有一次在全局模板里写了“代码注释用中文”某个国际化项目却在项目模板里写了“必须使用英文注释”结果 Claude 每次改写都会留着中文注释再主动解释一句“根据全局规则需要保留中文”气得人直冒火。解决的办法是定规则全局模板里只放与项目无关的通行规则比如“不要使用不规范的语言”“不要在未确认时执行破坏性命令”所有跟具体技术栈、具体业务相关的规则一律放项目模板。顺便说一句Claude Code 新版本支持的CLAUDE.local.md是个好东西个人私有习惯比如“我偏好使用 pnpm”放这里不会污染团队共享的 CLAUDE.md。4.3 规则写得太抽象模型无从执行模板里最忌讳的一句话是“代码要写得好、写得规范。”这句是废话——模型没有任何具体的执行抓手。约束不是用形容词写出来的是用可验证的行为写出来的。我总结了一个“三条检验标准”每写一条规则前都过一遍这条规则能不能被代码检查或人工快速验证这条规则是否描述了具体的动作而不是模糊的品质这条规则针对的问题是否在近期重复出现过用这三条标准过滤很多装饰性内容会被直接砍掉。比如“注意代码质量”这种改成“新增函数必须写类型标注”“超过 100 行的函数必须拆分”才有实际意义。规则越具体模型越容易执行你也越容易判断它有没有执行。4.4 把过时信息留在模板里模板是会腐烂的。常见情况是依赖从requests换成了httpx但模板里还写着“外部调用统一使用 requests”构建工具从 webpack 换成了 vite模板里命令还停留在npm run build:webpack。过时的模板比没有模板更可怕——它会让 Agent 自信地按错误的方式做事造成的偏离往往更隐蔽。我的做法是每隔几个迭代周期就让 Claude 自己读一遍近期的对话记录和项目配置文件然后尝试更新 CLAUDE.md跑一遍git log --oneline看项目近期变化再对着package.json或pyproject.toml核验命令是否一致。模板的生命力就在这种定期的“体检”里。另外一个补充做法是动态信息不放 CLAUDE.md放 NOTES.md把“发版前要改哪些文件”这种流程说明放在外部模板里用 引用这样即使流程变了改 NOTES.md 即可无需动主模板。5. 模板的版本管理与持续迭代5.1 用独立仓库维护模板项目里只留引用既然模板是一套需要长期演进的东西那它理应有自己的仓库、提交历史和版本号。我不建议把模板文件直接复制进每个项目里否则改一处模板要同步五六个项目迟早会漏。我的做法是维护一个独立的claude-code-templates仓库就是标题里那个名字各个项目通过脚本或 git submodule 引用。项目根目录里只保留一份组合生成的 CLAUDE.md同时把模板仓库的版本号记录在最底部方便回溯。像这样## 模板来源 - 模板仓库: claude-code-templates v2.3.0 - 技术栈: backend-python v1.1.0 - 最近一次组装: 2025-06-15这样做最大的收益是“变更可以被追溯”。哪天项目 Agent 行为突然变得奇怪先查模板版本是不是被动过比从头排查规则要高效得多。5.2 模板效果测试复盘对话记录判断规则是否生效模板写得好不好不能靠感觉要复盘。Claude Code 会在本地保存历史会话记录我会定期挑几条典型任务检查它们是否遵守了模板里的关键约束。把每条规则当成一个“测试用例”点对点核对。现学现卖一个检查思路模板里写了“禁止裸 except”那就翻看本周 session 里有没有产出裸except:的代码写了“函数超过 100 行必须拆分”就看生成代码里最长的那几个函数是否超标。规则没被遵守就两条路要么是措辞不够明确要么是这条规则根本不重要——后者的出路是删掉而不是加重语气再写一遍。规则是“删”出来的不是“加”出来的这句话是我维护模板这么久最深的一点体会。5.3 迭代节奏与模板库的演进方向我对模板库的迭代思路是“小步快跑”每次任务中发现 Agent 做了一个不符合预期的动作先判断这是偶发失误还是系统性缺失。系统性缺失才值得写进模板偶发失误只需在当次对话里纠正即可。这样模板不会疯长也始终保持在对当前工作最有帮助的状态。现在每次新建项目我第一件事不是装依赖而是把模板仓库拉下来、跑一次组装脚本生成好 CLAUDE.md 再开始写业务代码。这多花的五分钟在后面几周的协作里省下的远远不止五十分钟。如果你也被 Claude Code 的“健忘”折磨建议从今天开始也建一个自己的模板仓库先把红线清单和命令表填进去剩下的边用边补。
