如果你和我一样最近半年把 Claude Code 当作日常编码的“第二大脑”大概率会遇到一个很微妙的场景同一个项目今天你花了十分钟把背景、约束、验收标准讲清楚它交出来的代码非常漂亮明天你手一滑开了个新会话只丢给它一句“把这个接口改一下”它立刻化身考古学家翻半天代码也不知道你到底想要什么。问题不在模型在上下文。模型没有长期记忆它的记忆就是你喂给它的那些文字。于是“怎么给 Claude 做一套靠谱的入职培训”就变成了一个工程问题——claude-code-templates这个念头就是从我自己的这种反复拉扯里长出来的。这篇文章不聊概念就聊我实际怎么把 CLAUDE.md 从“随手写几句的便利贴”变成了一套结构化、可复用、能分发给团队的模板工程。1. CLAUDE.md 模板到底在解决什么问题1.1 模型的“临时工困境”我先说一个扎心的观察。很多人第一次接触 Claude Code 的 CLAUDE.md是看到官方文档提了一句“把项目约定写进这个文件Claude 就会自动读取”于是照猫画虎写了三行这个项目是电商后台 代码风格保持简洁 有问题先问我然后发现没什么用Claude 依然我行我素。这不是工具失效而是你压根没理解 CLAUDE.md 的定位。它本质上是一个跨会话的上下文持久层。每次会话开始Claude Code 会把这个文件的内容自动加载进上下文里相当于给模型做了一次“岗前培训”。但培训要有质量得看你给的材料。真正的痛点不是模型读不读文件而是绝大多数人根本没有系统性地整理过“这个项目到底该怎么干活”。你脑子里的约定项目文档里的技术选型代码评审时反复强调的规范——这些信息散落得到处都是CLAUDE.md 恰恰是把它们汇总到一处的那个“收口位置”。1.2 团队协作时AI 的行为分叉会吃掉效率claude-code-templates的价值在个人项目里其实体现得还不明显一进团队就完全不一样了。我见过一个真实案例同一个仓库同事 A 的 CLAUDE.md 里有“任何改动都必须跑完现有测试再提交”同事 B 什么都没写。结果两人让 Claude 改同一个模块A 那边流程走得很稳B 这边模型因为完全不熟悉项目约束经常提出一些“看起来很合理但明显违反项目架构”的方案。为什么因为模型在不同会话里表现出的“性格”完全取决于你给了它什么模板。团队里十个人就有十种 prompt 风格AI 协作的质量方差极大。模板工程解决的就是这个方差问题——把“这个项目的正确工作方式”标准化成一份可以被统一加载的规范而不是依赖每个人临时组织语言。1.3 模板和普通 prompt 有什么本质区别这点我得掰开讲。很多人觉得 CLAUDE.md 不就是个“大号 prompt”嘛还真不是。普通 prompt 是临时对话说完就散下一次还得重新交代。CLAUDE.md 是常驻规则它不参与你具体的业务讨论但它悄悄地在后台约束着模型的行为边界。更关键的是它有一套自己的优先级机制文件里用#开头的指令最高优先##次之###再次之。用户在当前对话里明确说的话又可以覆盖文件里的默认设定。这套机制意味着模板不是死板的教条它更像一个“默认配置 运行参数”的框架。你可以在模板里写死“绝对不要动 migrations 目录”这是最高优先级也可以写“默认使用 pnpm 安装依赖”这是次一级的偏好遇到特殊情况你在对话里手动补充一句“这次用 npm”瞬间覆盖。理解了这一层你就知道模板设计真正难的地方在哪了不是把信息堆进去而是把信息分层确保模型在任何场景下都分得清哪些是不可逾越的红线哪些是灵活可变的偏好。2. 一套能落地的模板工程三大分层与板块设计2.1 全局模板个人工作习惯的基线我理解的claude-code-templates不是一个孤零零的项目级文件而是有分层结构的。最底层是用户级全局模板路径在~/.claude/CLAUDE.md。这个文件我写什么我不写任何具体业务知识只写两件事一是通用的代码风格偏好比如“默认优先写 TypeScript”“函数式风格优先于面向对象”“注释只在解释为什么的时候写不解释是什么”二是通用的工作流偏好比如“涉及破坏性变更时先列出影响面再说方案”“提交信息用 Conventional Commits”。为什么要有这一层因为你会发现如果你换了新项目项目级的 CLAUDE.md 可以换但你自己对代码的品味和习惯是跨项目一致的。没有这一层每个项目模板里都得重复一遍这些个人偏好维护成本一下就上去了。全局层就像你电脑的 dotfiles一次配置处处生效。2.2 项目模板和 .gitignore 同级的存在第二个层级是项目根目录的CLAUDE.md。这个文件是核心我后面会放完整示例。它的定位是回答四个问题这个项目是干什么的边界在哪技术栈是什么哪些技术栈是雷区约定的开发流程是什么提交前必须做什么有哪些绝对不能碰的底线我见过很多项目写的 CLAUDE.md 只有技术栈清单其实浪费了。技术栈这玩意儿模型大概率已经看过代码了你在 CLAUDE.md 里写“React 18 Vite TS”不如写“这个项目虽然用的是 webpack但新代码统一走 vite 的构建路径不要手动改 webpack 配置里的 loader”。前者是陈述事实后者是给行为划线。2.3 模块级模板把约定下沉到子目录第三个层级的模板很多人不知道子目录也可以有自己的 CLAUDE.md。比如src/components/CLAUDE.md、api/CLAUDE.md。这个文件的作用域只在这个子目录之内Claude 处理该目录下的文件时会优先参考它。模块级模板特别适合放那些“局部规则”。举个例子我们项目的src/features/目录下有个CLAUDE.md里面写死了一条“所有新功能必须走FeatureFlag不允许直接在业务代码里写 if/else 判断新旧逻辑”。这个规则只对新功能开发相关代码生效你总不至于把这条写进全局模板吧全局模板是宪法项目模板是部门规章模块模板是岗位手册——三者粒度不同解决的问题不同。我个人强烈建议CLAUDE.md一定要放在 git 仓库里跟代码一起走。这样代码评审的时候模板变更也能被 review新人克隆仓库拉下来的不光是代码还有这个项目“怎么被 AI 正确协作”的全部约定。2.4 模板板块到底怎么排现在放一个你们可以直接抄作业的项目级模板骨架。我不搞虚的这是我从自己claude-code-templates仓库里摘出来的精简版# 项目身份 你是这个电商中台项目的主力开发助手。项目采用微服务架构当前仓库是 order-service。 你的目标是帮助我高效、安全地完成 order-service 相关的编码任务。 最高优先级指令 - 绝对不要修改任何数据库迁移文件migrations 目录除非我明确要求 - 绝对不要把访问密钥硬编码到代码或配置文件中 - 涉及线上环境问题时先输出影响分析不要直接动代码 ## 技术栈与架构约束 - 主语言Java 17 Spring Boot 3.2 - 新代码默认遵循现有分层结构controller - service - repository - 禁止引入新的重量级依赖如需要请在方案中说明理由 - Redis 只用于缓存不承担消息队列职责 ## 开发工作流 1. 实现功能前先列出你计划改动的文件清单 2. 单元测试使用 JUnit 5覆盖核心分支即可不需要追求 100% 行覆盖 3. 涉及接口变更时同步补充 OpenAPI 注解 4. 提交信息遵循 Conventional Commits 规范 ### 质量底线 - 编译错误为零 - 改动影响范围 3 个文件时必须先输出改动计划 - 不确定架构归属的代码先问再写看到分类了吧#是红线必须无条件遵守##是默认偏好大多数情况下遵守###是更低优先级的补充说明。这个优先级不是玄学是 Claude Code 官方定义的指令语义你用对了模型才能分清主次。3. 模板仓库的落地与协作从个人脚本到团队基建3.1 把模板做成独立仓库用同步脚本分发模板写好只是第一步真正的工程化在于分发与维护。我建议把整套模板放到一个独立仓库里维护命名就叫claude-code-templates或dotfiles-claude都行然后用一个脚本把它软链到各个项目。我的仓库目录结构长这样claude-code-templates/ ├── global/ # 全局模板 │ └── CLAUDE.md ├── project/ # 项目级模板 │ ├── web-frontend.md │ ├── spring-boot-service.md │ └── python-data-pipeline.md ├── modules/ # 模块级模板 │ ├── react-components.md │ ├── api-controller.md │ └── sql-migrations.md ├── hooks/ # 配套的 Hook 脚本 │ ├── pre-commit-check.sh │ └── security-scan.sh └── install.sh # 一键安装脚本同步脚本的思路很简单克隆仓库把global/CLAUDE.md复制到~/.claude/CLAUDE.md然后把对应项目的模板内容按需生成到项目根目录。我写了一个install.sh核心逻辑也就二十几行#!/usr/bin/env bash set -euo pipefail TEMPLATE_REPO$(pwd)/claude-code-templates # 安装全局模板 mkdir -p ~/.claude cp $TEMPLATE_REPO/global/CLAUDE.md ~/.claude/CLAUDE.md echo [OK] 全局模板已安装到 ~/.claude/CLAUDE.md # 按项目类型生成项目模板 if [ -f .claude-project-type ]; then PROJECT_TYPE$(cat .claude-project-type) cp $TEMPLATE_REPO/project/$PROJECT_TYPE.md ./CLAUDE.md echo [OK] 项目模板已生成: $PROJECT_TYPE else echo [SKIP] 没有 .claude-project-type 文件跳过项目模板生成 fi注意那个.claude-project-type文件相当于给项目打了个类型标签。拉新项目时只要创建这个文件并写一行spring-boot-service再跑一下脚本项目级模板就自动就位了。3.2 变量注入模板不能写死要留活口模板工程容易犯的第二个错误是把模板写得太死。一个团队多个项目都共用同一份 spring-boot-service 模板但项目 A 的包名是com.company.order项目 B 的包名是com.company.payment你能在模板里写死吗不能。Claude Code 支持多种变量注入。在 CLAUDE.md 里可以直接使用的变量包括$CWD当前目录、$USER用户名、$FILE_PATH当前处理文件的路径等这些由工具自动填充。但更关键的是你可以通过配置文件传自定义变量。我通常在.claude/settings.json里做一些项目级的定制{ env: { PROJECT_NAME: order-service, PACKAGE_ROOT: com.company.order, TEAM_OWNER: middleware-group } }然后在模板里写成## 项目标识 - 项目名$PROJECT_NAME - 包根路径$PACKAGE_ROOT - 所属团队$TEAM_OWNER这样模板文件本身是通用的具体项目的差异全部通过变量注入。换项目时不用改模板只改 settings.json这才是工程化的正确姿势。3.3 Hooks 与 Commands模板的自动化配套CLAUDE.md 是“静态约定”而 Hooks 和 Commands 是“动态执行”。模板里写了“提交前必须跑测试”模型真的每次都会自觉跑吗说实话有时候会忘。Hooks 就是用来兜底的。我在这套模板仓库里配了几个核心 Hook。比如PreToolUse事件拦截危险命令{ hooks: { PreToolUse: [ { matcher: Bash(rm -rf|git push --force|drop table), hooks: [ { type: command, command: echo 危险操作被拦截请确认意图后单独执行 exit 1 } ] } ] } }这个 Hook 的意思是当 Claude 尝试执行rm -rf、强推git push --force、drop table这类高危命令时直接阻止并提示确认。模板里写一百遍“不要乱删文件”不如一个 Hook 来得实在。Commands 则是把一些高频操作模板化。在.claude/commands/目录下放一个commit.md--- description: 按约定生成规范的 git 提交信息 argument-hint: 可选提交内容的简短描述 allowed-tools: Bash --- 请按以下流程帮我完成提交 1. 先执行 git diff --stat 和 git diff --cached --stat 查看改动内容 2. 根据改动内容推荐 3 个符合 Conventional Commits 规范的提交信息候选 3. 请我确认后执行 git commit -m 选定的信息 4. 提交完成后简要说明如何推送到远端这样模板不只是“告诉模型不要干什么”还变成了一套“标准操作流程”。团队的每个成员都有一模一样的/commit命令提交信息的格式乱象直接消失。3.4 团队落地的三个关键点最后聊一下团队推广时容易忽视的事。模板这个东西光是丢到群里让大家“自行使用”基本没人用。我踩过坑之后总结出三个关键点第一模板必须进代码评审。CLAUDE.md 一旦进了仓库就是代码的一部分任何人对模板的修改都要走 MR 评审流程。否则你不知道谁偷偷往里面加了一条“给我生成测试的时候不要跑集成测试”这种规则会直接影响 AI 的输出质量。第二模板要有变更记录。我会在模板仓库里维护一个CHANGELOG.md记录每次模板变更的原因和影响面。比如“2025-06-10新增禁止使用已废弃的 Joda-Time 库”这样复盘的时候能说清楚每条规则是怎么来的。第三负责人机制不能少。团队里至少要有一个“AI 协作规范管理员”负责收集大家在用 Claude Code 时遇到的共性问题然后决定要不要把解法沉淀到模板里。模板不是写出来就完事的静态文档它需要有人持续维护这和维护一个 npm 包没什么区别。4. 我踩过的坑模板不是写出来就算完4.1 把模板写成了“正确的废话”我第一次设计 CLAUDE.md 模板时写的最多的是“请编写高质量的代码”“保持代码整洁”“注意性能优化”。后来发现这些全是废话。Claude 不会因为你在模板里写“注意性能”就真的去分析时间复杂度它只会把这些词当成上下文噪音处理。真正有效的模板条目是可验证的、有明确判据的。比如把“注意性能”改成## 性能约束 - 列表类型接口返回的数据量超过 1000 条时必须使用分页 - 禁止在循环体内执行数据库查询 - 新增索引必须先评估存量数据量再执行这些规则模型能直接执行而且执行完你能检查它有没有遵守。垃圾模板和有效模板的分水岭就在这你的模板是在要求模型“表现好”还是在给它“可执行的清单”4.2 指令自相矛盾模型直接懵了模板工程做了一阵子你一定会遇到指令冲突。我举个真实的例子项目模板里我写了“所有新代码必须使用 React Hook”但模块模板src/legacy/CLAUDE.md里又写了一条“保持此目录下的类组件风格不要混用 Hook”。结果 Claude 在改动 legacy 目录时候有时候按项目模板来有时候按模块模板来行为完全不可控。后来我明白了一个道理模板的层级越高规则的表达应该越抽象层级越低越具体。冲突的时候低层级应该覆盖高层级。所以我在全局模板和项目模板里都加了一条款遇到与本文件冲突的低层级规则时优先使用层级更低的规则。这相当于给了模型一个明确的仲裁方案。同时我在模板里统一用“必须”“禁止”“建议”三个词来区分规则强度避免出现语义模糊。4.3 敏感信息泄漏与权限失控这个坑比较严重必须单独说。早期我把一些内部服务的连接方式写进了项目模板想着“反正这是内网工具”结果仓库权限设置不当模板被外部可见。CLAUDE.md 是跟代码一起进仓库的它的敏感度和代码一样。凡是不能写进代码的东西一律不允许写进模板。另外要配合settings.json的权限配置。我现在的项目级 settings 里会明确拒绝一些敏感路径{ permissions: { deny: [ Bash(npm publish), Read(./.env), Read(~/.ssh/private_key), Write(.env*) ] } }模板是告诉模型“你应该怎么做”权限配置是告诉工具“你不能这么做”。两套体系配合使用才能真正管住 AI 的行为边界。4.4 模板越长越好算笔 token 账很多人有个误区觉得 CLAUDE.md 写个几千字才显得专业。我一度也这么干过直到发现每次会话光读模板就消耗掉了大量上下文窗口真正留给业务讨论的额度反而变少了。比如模板 3000 字约合 4000 到 5000 个 token这还没算钩子、命令、其他上下文。多轮对话后很容易达到上下文上限模型开始“遗忘”前面的关键信息。我的建议是项目级模板控制在 1000 到 1500 字以内。超过这个体量说明你的项目代码本身可能有严重的不一致性问题需要靠模板来给模型“洗脑”治标不治本。精简的办法也很简单把那些“模型看代码就能判断出来的信息”比如用了什么框架删掉只保留“模型无法从代码中直接推断出来的隐性约定”比如为什么这个模块要这么设计、哪块代码是遗留技术债不要重构。模块级模板则可以更短300 到 500 字即可只聚焦该目录下的局部规则。全局模板控制人格与风格项目模板控制流程与红线模块模板控制局部细节——三者加起来不超过 2200 字才是健康的状态。5. 模板的持续迭代把它当成代码来经营5.1 从对话记录里反推模板缺口模板工程不是一个一次性项目它需要像代码一样迭代。我养成了一个习惯每周翻一遍自己和 Claude Code 的会话记录凡是出现以下信号的都标记为模板缺口同一类问题我重复纠正了 Claude 两次以上比如“这个模块不用加缓存”“这个接口不要走消息队列”我花费了大量 prompt 才能让 Claude 理解某个项目的隐性约定某次会话中我发现自己把同样一段背景说明复制粘贴了好几次每次发现缺口我就把它补进对应的模板里。积累几周之后同一个项目里 Claude 的表现会有非常明显的变化——它变得更像“老员工”了不用你反复交代背景。这个“模板—使用—发现问题—更新模板”的闭环是这个项目的核心方法论。它本质上是在做一件事把人类协作中的默契逐步固化成可复制的制度。5.2 模板的版本管理与项目结构演进项目本身在演进模板当然也要跟着改。比如原来项目是单体应用CLAUDE.md 里写的全是单体约束半年后拆了微服务模板就得同步更新目录结构和模块边界。我用的是两种方式管理模板演进一是模板仓库里用 git tag 打版本比如v1.2.0二是项目 CLAUDE.md 的第一行固定写一个“模板版本号” 模板版本v1.2.02025-06-15 更新这样当你打开一个很久没动的项目一眼就能看出它的模板是不是过期了。配合模板仓库的 changelog你能快速知道“从 v1.1.0 升到 v1.2.0 到底改了哪些规则”再决定要不要重新同步。5.3 让模板跟上工具本身的变化节奏Claude Code 这个工具本身迭代非常快几乎每周都有新功能尤其是权限模型、Hook 事件、命令定义这些基础能力经常调整。模板工程必须跟着工具的更新节奏走否则很容易出现“模板里写了个推荐做法但工具已经换了一种更好的执行方式”的过时状态。我的做法很简单订阅官方更新日志重点关注三个文件——settings.json 的 schema 变化、hooks 事件的增减、CLAUDE.md 指令语义的调整。每次大版本更新都要重新过一遍自己的模板仓库看看有没有可以简化的地方。工具升级带来的往往不只是兼容问题还有新的表达方式。最后再分享一个我自己体会很深的小技巧模板里所有规则都要有一个“可验证的结果”。不要写“代码要规范”要写“新代码通过npm run lint时不允许有新的 warning”不要写“要写好测试”要写“每个工具函数至少覆盖一个 happy path 和一个异常分支”。模型是概率机但概率机也吃规则你给它越明确的判据它输出的稳定性就越高。这套claude-code-templates我从个人项目用到团队协作最大的感受不是“AI 变聪明了”而是“同一套标准下AI 的行为终于可以被预期了”。如果你也打算把 CLAUDE.md 提上日程别急着写内容先按这套分层和板块思路把骨架搭起来——细节可以慢慢填框架对了后面一切都会顺很多。 Claude Code 模板工程：用 CLAUDE.md 分层管理 AI 协作上下文
如果你和我一样最近半年把 Claude Code 当作日常编码的“第二大脑”大概率会遇到一个很微妙的场景同一个项目今天你花了十分钟把背景、约束、验收标准讲清楚它交出来的代码非常漂亮明天你手一滑开了个新会话只丢给它一句“把这个接口改一下”它立刻化身考古学家翻半天代码也不知道你到底想要什么。问题不在模型在上下文。模型没有长期记忆它的记忆就是你喂给它的那些文字。于是“怎么给 Claude 做一套靠谱的入职培训”就变成了一个工程问题——claude-code-templates这个念头就是从我自己的这种反复拉扯里长出来的。这篇文章不聊概念就聊我实际怎么把 CLAUDE.md 从“随手写几句的便利贴”变成了一套结构化、可复用、能分发给团队的模板工程。1. CLAUDE.md 模板到底在解决什么问题1.1 模型的“临时工困境”我先说一个扎心的观察。很多人第一次接触 Claude Code 的 CLAUDE.md是看到官方文档提了一句“把项目约定写进这个文件Claude 就会自动读取”于是照猫画虎写了三行这个项目是电商后台 代码风格保持简洁 有问题先问我然后发现没什么用Claude 依然我行我素。这不是工具失效而是你压根没理解 CLAUDE.md 的定位。它本质上是一个跨会话的上下文持久层。每次会话开始Claude Code 会把这个文件的内容自动加载进上下文里相当于给模型做了一次“岗前培训”。但培训要有质量得看你给的材料。真正的痛点不是模型读不读文件而是绝大多数人根本没有系统性地整理过“这个项目到底该怎么干活”。你脑子里的约定项目文档里的技术选型代码评审时反复强调的规范——这些信息散落得到处都是CLAUDE.md 恰恰是把它们汇总到一处的那个“收口位置”。1.2 团队协作时AI 的行为分叉会吃掉效率claude-code-templates的价值在个人项目里其实体现得还不明显一进团队就完全不一样了。我见过一个真实案例同一个仓库同事 A 的 CLAUDE.md 里有“任何改动都必须跑完现有测试再提交”同事 B 什么都没写。结果两人让 Claude 改同一个模块A 那边流程走得很稳B 这边模型因为完全不熟悉项目约束经常提出一些“看起来很合理但明显违反项目架构”的方案。为什么因为模型在不同会话里表现出的“性格”完全取决于你给了它什么模板。团队里十个人就有十种 prompt 风格AI 协作的质量方差极大。模板工程解决的就是这个方差问题——把“这个项目的正确工作方式”标准化成一份可以被统一加载的规范而不是依赖每个人临时组织语言。1.3 模板和普通 prompt 有什么本质区别这点我得掰开讲。很多人觉得 CLAUDE.md 不就是个“大号 prompt”嘛还真不是。普通 prompt 是临时对话说完就散下一次还得重新交代。CLAUDE.md 是常驻规则它不参与你具体的业务讨论但它悄悄地在后台约束着模型的行为边界。更关键的是它有一套自己的优先级机制文件里用#开头的指令最高优先##次之###再次之。用户在当前对话里明确说的话又可以覆盖文件里的默认设定。这套机制意味着模板不是死板的教条它更像一个“默认配置 运行参数”的框架。你可以在模板里写死“绝对不要动 migrations 目录”这是最高优先级也可以写“默认使用 pnpm 安装依赖”这是次一级的偏好遇到特殊情况你在对话里手动补充一句“这次用 npm”瞬间覆盖。理解了这一层你就知道模板设计真正难的地方在哪了不是把信息堆进去而是把信息分层确保模型在任何场景下都分得清哪些是不可逾越的红线哪些是灵活可变的偏好。2. 一套能落地的模板工程三大分层与板块设计2.1 全局模板个人工作习惯的基线我理解的claude-code-templates不是一个孤零零的项目级文件而是有分层结构的。最底层是用户级全局模板路径在~/.claude/CLAUDE.md。这个文件我写什么我不写任何具体业务知识只写两件事一是通用的代码风格偏好比如“默认优先写 TypeScript”“函数式风格优先于面向对象”“注释只在解释为什么的时候写不解释是什么”二是通用的工作流偏好比如“涉及破坏性变更时先列出影响面再说方案”“提交信息用 Conventional Commits”。为什么要有这一层因为你会发现如果你换了新项目项目级的 CLAUDE.md 可以换但你自己对代码的品味和习惯是跨项目一致的。没有这一层每个项目模板里都得重复一遍这些个人偏好维护成本一下就上去了。全局层就像你电脑的 dotfiles一次配置处处生效。2.2 项目模板和 .gitignore 同级的存在第二个层级是项目根目录的CLAUDE.md。这个文件是核心我后面会放完整示例。它的定位是回答四个问题这个项目是干什么的边界在哪技术栈是什么哪些技术栈是雷区约定的开发流程是什么提交前必须做什么有哪些绝对不能碰的底线我见过很多项目写的 CLAUDE.md 只有技术栈清单其实浪费了。技术栈这玩意儿模型大概率已经看过代码了你在 CLAUDE.md 里写“React 18 Vite TS”不如写“这个项目虽然用的是 webpack但新代码统一走 vite 的构建路径不要手动改 webpack 配置里的 loader”。前者是陈述事实后者是给行为划线。2.3 模块级模板把约定下沉到子目录第三个层级的模板很多人不知道子目录也可以有自己的 CLAUDE.md。比如src/components/CLAUDE.md、api/CLAUDE.md。这个文件的作用域只在这个子目录之内Claude 处理该目录下的文件时会优先参考它。模块级模板特别适合放那些“局部规则”。举个例子我们项目的src/features/目录下有个CLAUDE.md里面写死了一条“所有新功能必须走FeatureFlag不允许直接在业务代码里写 if/else 判断新旧逻辑”。这个规则只对新功能开发相关代码生效你总不至于把这条写进全局模板吧全局模板是宪法项目模板是部门规章模块模板是岗位手册——三者粒度不同解决的问题不同。我个人强烈建议CLAUDE.md一定要放在 git 仓库里跟代码一起走。这样代码评审的时候模板变更也能被 review新人克隆仓库拉下来的不光是代码还有这个项目“怎么被 AI 正确协作”的全部约定。2.4 模板板块到底怎么排现在放一个你们可以直接抄作业的项目级模板骨架。我不搞虚的这是我从自己claude-code-templates仓库里摘出来的精简版# 项目身份 你是这个电商中台项目的主力开发助手。项目采用微服务架构当前仓库是 order-service。 你的目标是帮助我高效、安全地完成 order-service 相关的编码任务。 最高优先级指令 - 绝对不要修改任何数据库迁移文件migrations 目录除非我明确要求 - 绝对不要把访问密钥硬编码到代码或配置文件中 - 涉及线上环境问题时先输出影响分析不要直接动代码 ## 技术栈与架构约束 - 主语言Java 17 Spring Boot 3.2 - 新代码默认遵循现有分层结构controller - service - repository - 禁止引入新的重量级依赖如需要请在方案中说明理由 - Redis 只用于缓存不承担消息队列职责 ## 开发工作流 1. 实现功能前先列出你计划改动的文件清单 2. 单元测试使用 JUnit 5覆盖核心分支即可不需要追求 100% 行覆盖 3. 涉及接口变更时同步补充 OpenAPI 注解 4. 提交信息遵循 Conventional Commits 规范 ### 质量底线 - 编译错误为零 - 改动影响范围 3 个文件时必须先输出改动计划 - 不确定架构归属的代码先问再写看到分类了吧#是红线必须无条件遵守##是默认偏好大多数情况下遵守###是更低优先级的补充说明。这个优先级不是玄学是 Claude Code 官方定义的指令语义你用对了模型才能分清主次。3. 模板仓库的落地与协作从个人脚本到团队基建3.1 把模板做成独立仓库用同步脚本分发模板写好只是第一步真正的工程化在于分发与维护。我建议把整套模板放到一个独立仓库里维护命名就叫claude-code-templates或dotfiles-claude都行然后用一个脚本把它软链到各个项目。我的仓库目录结构长这样claude-code-templates/ ├── global/ # 全局模板 │ └── CLAUDE.md ├── project/ # 项目级模板 │ ├── web-frontend.md │ ├── spring-boot-service.md │ └── python-data-pipeline.md ├── modules/ # 模块级模板 │ ├── react-components.md │ ├── api-controller.md │ └── sql-migrations.md ├── hooks/ # 配套的 Hook 脚本 │ ├── pre-commit-check.sh │ └── security-scan.sh └── install.sh # 一键安装脚本同步脚本的思路很简单克隆仓库把global/CLAUDE.md复制到~/.claude/CLAUDE.md然后把对应项目的模板内容按需生成到项目根目录。我写了一个install.sh核心逻辑也就二十几行#!/usr/bin/env bash set -euo pipefail TEMPLATE_REPO$(pwd)/claude-code-templates # 安装全局模板 mkdir -p ~/.claude cp $TEMPLATE_REPO/global/CLAUDE.md ~/.claude/CLAUDE.md echo [OK] 全局模板已安装到 ~/.claude/CLAUDE.md # 按项目类型生成项目模板 if [ -f .claude-project-type ]; then PROJECT_TYPE$(cat .claude-project-type) cp $TEMPLATE_REPO/project/$PROJECT_TYPE.md ./CLAUDE.md echo [OK] 项目模板已生成: $PROJECT_TYPE else echo [SKIP] 没有 .claude-project-type 文件跳过项目模板生成 fi注意那个.claude-project-type文件相当于给项目打了个类型标签。拉新项目时只要创建这个文件并写一行spring-boot-service再跑一下脚本项目级模板就自动就位了。3.2 变量注入模板不能写死要留活口模板工程容易犯的第二个错误是把模板写得太死。一个团队多个项目都共用同一份 spring-boot-service 模板但项目 A 的包名是com.company.order项目 B 的包名是com.company.payment你能在模板里写死吗不能。Claude Code 支持多种变量注入。在 CLAUDE.md 里可以直接使用的变量包括$CWD当前目录、$USER用户名、$FILE_PATH当前处理文件的路径等这些由工具自动填充。但更关键的是你可以通过配置文件传自定义变量。我通常在.claude/settings.json里做一些项目级的定制{ env: { PROJECT_NAME: order-service, PACKAGE_ROOT: com.company.order, TEAM_OWNER: middleware-group } }然后在模板里写成## 项目标识 - 项目名$PROJECT_NAME - 包根路径$PACKAGE_ROOT - 所属团队$TEAM_OWNER这样模板文件本身是通用的具体项目的差异全部通过变量注入。换项目时不用改模板只改 settings.json这才是工程化的正确姿势。3.3 Hooks 与 Commands模板的自动化配套CLAUDE.md 是“静态约定”而 Hooks 和 Commands 是“动态执行”。模板里写了“提交前必须跑测试”模型真的每次都会自觉跑吗说实话有时候会忘。Hooks 就是用来兜底的。我在这套模板仓库里配了几个核心 Hook。比如PreToolUse事件拦截危险命令{ hooks: { PreToolUse: [ { matcher: Bash(rm -rf|git push --force|drop table), hooks: [ { type: command, command: echo 危险操作被拦截请确认意图后单独执行 exit 1 } ] } ] } }这个 Hook 的意思是当 Claude 尝试执行rm -rf、强推git push --force、drop table这类高危命令时直接阻止并提示确认。模板里写一百遍“不要乱删文件”不如一个 Hook 来得实在。Commands 则是把一些高频操作模板化。在.claude/commands/目录下放一个commit.md--- description: 按约定生成规范的 git 提交信息 argument-hint: 可选提交内容的简短描述 allowed-tools: Bash --- 请按以下流程帮我完成提交 1. 先执行 git diff --stat 和 git diff --cached --stat 查看改动内容 2. 根据改动内容推荐 3 个符合 Conventional Commits 规范的提交信息候选 3. 请我确认后执行 git commit -m 选定的信息 4. 提交完成后简要说明如何推送到远端这样模板不只是“告诉模型不要干什么”还变成了一套“标准操作流程”。团队的每个成员都有一模一样的/commit命令提交信息的格式乱象直接消失。3.4 团队落地的三个关键点最后聊一下团队推广时容易忽视的事。模板这个东西光是丢到群里让大家“自行使用”基本没人用。我踩过坑之后总结出三个关键点第一模板必须进代码评审。CLAUDE.md 一旦进了仓库就是代码的一部分任何人对模板的修改都要走 MR 评审流程。否则你不知道谁偷偷往里面加了一条“给我生成测试的时候不要跑集成测试”这种规则会直接影响 AI 的输出质量。第二模板要有变更记录。我会在模板仓库里维护一个CHANGELOG.md记录每次模板变更的原因和影响面。比如“2025-06-10新增禁止使用已废弃的 Joda-Time 库”这样复盘的时候能说清楚每条规则是怎么来的。第三负责人机制不能少。团队里至少要有一个“AI 协作规范管理员”负责收集大家在用 Claude Code 时遇到的共性问题然后决定要不要把解法沉淀到模板里。模板不是写出来就完事的静态文档它需要有人持续维护这和维护一个 npm 包没什么区别。4. 我踩过的坑模板不是写出来就算完4.1 把模板写成了“正确的废话”我第一次设计 CLAUDE.md 模板时写的最多的是“请编写高质量的代码”“保持代码整洁”“注意性能优化”。后来发现这些全是废话。Claude 不会因为你在模板里写“注意性能”就真的去分析时间复杂度它只会把这些词当成上下文噪音处理。真正有效的模板条目是可验证的、有明确判据的。比如把“注意性能”改成## 性能约束 - 列表类型接口返回的数据量超过 1000 条时必须使用分页 - 禁止在循环体内执行数据库查询 - 新增索引必须先评估存量数据量再执行这些规则模型能直接执行而且执行完你能检查它有没有遵守。垃圾模板和有效模板的分水岭就在这你的模板是在要求模型“表现好”还是在给它“可执行的清单”4.2 指令自相矛盾模型直接懵了模板工程做了一阵子你一定会遇到指令冲突。我举个真实的例子项目模板里我写了“所有新代码必须使用 React Hook”但模块模板src/legacy/CLAUDE.md里又写了一条“保持此目录下的类组件风格不要混用 Hook”。结果 Claude 在改动 legacy 目录时候有时候按项目模板来有时候按模块模板来行为完全不可控。后来我明白了一个道理模板的层级越高规则的表达应该越抽象层级越低越具体。冲突的时候低层级应该覆盖高层级。所以我在全局模板和项目模板里都加了一条款遇到与本文件冲突的低层级规则时优先使用层级更低的规则。这相当于给了模型一个明确的仲裁方案。同时我在模板里统一用“必须”“禁止”“建议”三个词来区分规则强度避免出现语义模糊。4.3 敏感信息泄漏与权限失控这个坑比较严重必须单独说。早期我把一些内部服务的连接方式写进了项目模板想着“反正这是内网工具”结果仓库权限设置不当模板被外部可见。CLAUDE.md 是跟代码一起进仓库的它的敏感度和代码一样。凡是不能写进代码的东西一律不允许写进模板。另外要配合settings.json的权限配置。我现在的项目级 settings 里会明确拒绝一些敏感路径{ permissions: { deny: [ Bash(npm publish), Read(./.env), Read(~/.ssh/private_key), Write(.env*) ] } }模板是告诉模型“你应该怎么做”权限配置是告诉工具“你不能这么做”。两套体系配合使用才能真正管住 AI 的行为边界。4.4 模板越长越好算笔 token 账很多人有个误区觉得 CLAUDE.md 写个几千字才显得专业。我一度也这么干过直到发现每次会话光读模板就消耗掉了大量上下文窗口真正留给业务讨论的额度反而变少了。比如模板 3000 字约合 4000 到 5000 个 token这还没算钩子、命令、其他上下文。多轮对话后很容易达到上下文上限模型开始“遗忘”前面的关键信息。我的建议是项目级模板控制在 1000 到 1500 字以内。超过这个体量说明你的项目代码本身可能有严重的不一致性问题需要靠模板来给模型“洗脑”治标不治本。精简的办法也很简单把那些“模型看代码就能判断出来的信息”比如用了什么框架删掉只保留“模型无法从代码中直接推断出来的隐性约定”比如为什么这个模块要这么设计、哪块代码是遗留技术债不要重构。模块级模板则可以更短300 到 500 字即可只聚焦该目录下的局部规则。全局模板控制人格与风格项目模板控制流程与红线模块模板控制局部细节——三者加起来不超过 2200 字才是健康的状态。5. 模板的持续迭代把它当成代码来经营5.1 从对话记录里反推模板缺口模板工程不是一个一次性项目它需要像代码一样迭代。我养成了一个习惯每周翻一遍自己和 Claude Code 的会话记录凡是出现以下信号的都标记为模板缺口同一类问题我重复纠正了 Claude 两次以上比如“这个模块不用加缓存”“这个接口不要走消息队列”我花费了大量 prompt 才能让 Claude 理解某个项目的隐性约定某次会话中我发现自己把同样一段背景说明复制粘贴了好几次每次发现缺口我就把它补进对应的模板里。积累几周之后同一个项目里 Claude 的表现会有非常明显的变化——它变得更像“老员工”了不用你反复交代背景。这个“模板—使用—发现问题—更新模板”的闭环是这个项目的核心方法论。它本质上是在做一件事把人类协作中的默契逐步固化成可复制的制度。5.2 模板的版本管理与项目结构演进项目本身在演进模板当然也要跟着改。比如原来项目是单体应用CLAUDE.md 里写的全是单体约束半年后拆了微服务模板就得同步更新目录结构和模块边界。我用的是两种方式管理模板演进一是模板仓库里用 git tag 打版本比如v1.2.0二是项目 CLAUDE.md 的第一行固定写一个“模板版本号” 模板版本v1.2.02025-06-15 更新这样当你打开一个很久没动的项目一眼就能看出它的模板是不是过期了。配合模板仓库的 changelog你能快速知道“从 v1.1.0 升到 v1.2.0 到底改了哪些规则”再决定要不要重新同步。5.3 让模板跟上工具本身的变化节奏Claude Code 这个工具本身迭代非常快几乎每周都有新功能尤其是权限模型、Hook 事件、命令定义这些基础能力经常调整。模板工程必须跟着工具的更新节奏走否则很容易出现“模板里写了个推荐做法但工具已经换了一种更好的执行方式”的过时状态。我的做法很简单订阅官方更新日志重点关注三个文件——settings.json 的 schema 变化、hooks 事件的增减、CLAUDE.md 指令语义的调整。每次大版本更新都要重新过一遍自己的模板仓库看看有没有可以简化的地方。工具升级带来的往往不只是兼容问题还有新的表达方式。最后再分享一个我自己体会很深的小技巧模板里所有规则都要有一个“可验证的结果”。不要写“代码要规范”要写“新代码通过npm run lint时不允许有新的 warning”不要写“要写好测试”要写“每个工具函数至少覆盖一个 happy path 和一个异常分支”。模型是概率机但概率机也吃规则你给它越明确的判据它输出的稳定性就越高。这套claude-code-templates我从个人项目用到团队协作最大的感受不是“AI 变聪明了”而是“同一套标准下AI 的行为终于可以被预期了”。如果你也打算把 CLAUDE.md 提上日程别急着写内容先按这套分层和板块思路把骨架搭起来——细节可以慢慢填框架对了后面一切都会顺很多。