用 Claude Code 模板固化团队 AI 编码规范：从 CLAUDE.md 到斜杠命令

先说结论：我最近把 Claude Code 的使用方式从“每次开新项目口述一遍规则”改成了“直接铺一层 claude-code-templates”。这套模板解决的不是“让 AI 更强”，而是“让 AI 稳定地像同一个老同事”——无论谁打开这个仓库，它都知道项目用什么命令跑测试、提交信息怎么写、审查重点在哪。如果你也遇到过“同一个项目昨天还很好用，今天换个会话或者换台机器，行为完全对不上”的情况，这篇内容应该值得看完。模板本身不复杂，但设计它的思路、放置的位置，以及哪些内容绝不能塞进模板，才是真正的关键。

1. 为什么要把 Claude Code 的配置做成一套模板

1.1 三个逼我动手的场景

我最初用 Claude Code 的方式很简单：开新项目，在会话里写一大段背景说明，告诉它“这个项目是干嘛的、用什么包管理器、测试怎么跑、提交信息要什么格式”，然后期望它整场会话都记住。前几次确实有效，但问题也出得很快。

第一个场景是换机器。我在另一台笔记本上拉下仓库，装好环境，打开 Claude Code，它完全不知道这个项目的一些默认约定。它开始用 npm 乱跑命令，而项目实际用的是 pnpm；提交信息写得五花八门，和团队规范毫无关系。我突然意识到，口头提示就像现场聊天，只会留在那一次会话里，而配置是可以跟仓库一起走的。

第二个场景是团队协作。同事拿到同一个仓库后，各自按照自己的习惯给 AI 下指令。有人让 Claude Code 做代码审查，结果它顺手改了一堆文件；有人让它生成提交信息，结果它把未暂存的改动也算进去了。问题并不在模型能力，而是规则根本没有被沉淀下来，每个人都在重新发明一套用法。

第三个场景更现实：不是项目太多，是重复劳动太多。我同时维护几个不同技术栈的仓库，每次新开一个，都要重新解释一遍“哪些命令能用、哪些目录不要动、完成一个任务的标准是什么”。这些内容里有七成是通用的，剩下的三成才跟具体业务相关。既然如此，为什么不为那七成建一套模板？

1.2 模板化和临时提示到底差在哪

很多人都低估了模板化的意义，觉得“反正 AI 能听懂人话，何必搞一堆文件”。我用一张表说明差别：

这里面最关键的是“命令可发现性”。你不需要记住某个复杂的提示词，只需要知道项目里有 /review 这个命令。斜杠命令在 Claude Code 里会自动列出，团队成员打开项目就能看到，这比任何文档都直观。

还有个隐藏收益：模板化让 AI 的行为可以被 diff。改了一版审查规范，到底改了哪些内容、影响了哪些命令，用 git 看 commit 就行。而聊天记录里的口头约定，既没法 diff，也没法追溯是谁在什么场景下定的。

1.3 模板不是越全越好，先分清三层边界

我早期犯过一个错误：恨不得把所有规则都塞进一个模板文件，结果模板膨胀到几百行，AI 反而该看的看不到、不该看的全是噪音。后来我把模板分成三层，这个思路直接决定了维护成本。

第一层是 base，语言无关、项目无关。比如代码审查的基本原则、提交信息的通用格式、权限边界的默认设置。这一层放在所有项目里都不会错。

第二层是 variant，跟技术栈绑定。Python 项目需要写清楚“测试用 pytest，lint 用 ruff”，React 前端项目需要说明“组件默认放 src/components，样式用 CSS Modules”。每个技术栈一套 variant，按需选用。

第三层是 project，只属于某个具体仓库。比如 API 端点清单、数据库迁移流程、部署验证步骤。这一层不应该放在通用模板里，一旦放进去，模板就变成了各种项目残留习惯的大杂烩。

判断标准很简单：如果两条规则放在一起会互相打架，或者某条规则只对一个项目成立，它就不属于模板。模板要阻挡的是“过度拟合”——把某个特定项目的特殊习惯当作通用规则复制到所有项目里，这是模板库腐烂最快的方式。

2. 拆解 Claude Code 模板的最小骨架

2.1 CLAUDE.md：项目记忆的载体，别写成百科全书

Claude Code 会读取项目根目录下的 CLAUDE.md 作为长期记忆。模板化的第一步，就是把这份文件的骨架固定下来。我实测下来，一份健康的 CLAUDE.md 通常包含这几个板块：

• 项目一句话定位，避免 AI 基于目录名称瞎猜
• 常用命令：测试、单测、lint、构建，一条条写清楚
• 架构边界：哪些目录是核心逻辑，哪些是自动生成不能手改
• 代码规范：命名、组件组织、错误处理风格
• 完成定义：一个任务做到什么程度才算完成
• 明确禁止：哪些操作绝对不能做或需要先确认

一份基础版长这样：

# CLAUDE.md ## 项目定位 一句话描述这个仓库做什么。 ## 常用命令 - 测试：pnpm test - 单测：pnpm vitest run - 静态检查：pnpm lint - 构建：pnpm build ## 工作方式 - 当需要修改多个文件时，先给出执行计划，再动手。 - 涉及删除或重命名文件前，先列出受影响清单。 - 提交信息使用约定式提交（feat/fix/refactor），正文说明动机。 ## 明确禁止 - 不要修改 dist 目录下的任何文件。 - 不要在没有测试覆盖的情况下重构核心工具函数。

这里有个避坑点：CLAUDE.md 最重要的规则应该放在文件顶部，越重要的越靠前。不要把它写成百科全书，更不要在文件里写“当前进度”这种动态内容——它会迅速过期，然后污染 AI 的判断。CLAUDE.md 里写“怎么做”，业务上下文里才写“现在做到哪”。

2.2 自定义斜杠命令：把高频动作沉淀成命令文档

斜杠命令是模板里性价比最高的部分。它们是放在.claude/commands/目录下的 Markdown 文件，文件名就是命令名。比如.claude/commands/review.md对应/review。每个文件由一个简短的 frontmatter 加正文组成，正文就是 AI 执行命令时遵循的指令。

frontmatter 里最常用的是 description 和 argument-hint。description 会在命令列表里展示，让人明白这个命令是干嘛的；argument-hint 提示用户该传入什么参数。示例：

--- description: 对当前分支做一次代码审查，只输出结论 argument-hint: <可选的审查重点> ---

斜杠命令的价值在于它把提示词从“每次现写”变成了“文件描述”。你要做代码审查，不用再解释“请先拉取 diff，再按模块分析，最后给建议”，只需要/review，后面的细节全部由命令文档接管。这些命令模板完全可以跨项目复用，只要写得足够通用。

2.3 settings 与 hooks：模板里最容易被忽略的行为边界

CLAUDE.md 管的是“告诉 AI 怎么做”，settings 管的是“AI 能做什么”。模板化时最容易漏掉的就是这一层权限边界。

settings.json 里可以配置权限规则，比如默认允许哪些命令、拒绝哪些命令。我习惯在 base 模板里做两条基本约束：一是把rm -rf这种危险命令放进 deny 列表，二是让测试、lint 这类只读命令直接可执行，不用每次都弹确认。这样既保证效率，又不容易出事。

hooks 则是另一层自动机制。比如在 AI 执行编辑前或执行后挂脚本做检查。这个地方不同版本的具体配置字段会有差异，建议以自己的claude settings输出为准。模板里保留 hooks 的概念和示例脚本即可，具体字段不必写死，否则升级版本后容易失效。

我遇到过最尴尬的一次：模板里的 hooks 脚本没有执行权限，导致整条流水线静默失败。从那以后我就在模板里加了一条规则——hooks 目录下的脚本必须在 init 时统一chmod +x，并且用一个空参数跑一遍验证。

3. 从零搭建 claude-code-templates：目录与变量设计

3.1 一个实测顺手的基础目录结构

模板库本身也是一个 git 仓库。我目前的目录长这样：

claude-code-templates/ ├── base/ │ ├── CLAUDE.md │ └── .claude/ │ ├── commands/ │ │ ├── commit.md │ │ ├── review.md │ │ ├── test.md │ │ └── explain.md │ ├── settings.json │ ├── hooks/ │ └── agents/ ├── variants/ │ ├── python-web/ │ │ └── CLAUDE.md │ ├── react-frontend/ │ │ └── CLAUDE.md │ └── go-service/ │ └── CLAUDE.md ├── scripts/ │ ├── init.sh │ └── sync.sh └── README.md

这个结构的逻辑是分层叠加，互不覆盖。base 是任何新项目都要落地的底座；variants 是按需选择的增强层；scripts 负责把 base 和 variant 复制到新项目，并做变量替换。命令文件和管理脚本分离，避免模板本身的维护污染到具体项目。

3.2 用变量替换代替“复制后手改”

模板不能直接复制到项目里，因为里面有很多占位符。我统一用__PROJECT_NAME__、__PACKAGE_MANAGER__这类形式做标记，初始化时用脚本统一替换。这样既避免了“复制后忘了改名字”的尴尬，也能保证同一个模板生成的项目行为一致。

# scripts/init.sh（简化示意） cp -r base "$TARGET_DIR" cp -r "variants/$VARIANT" "$TARGET_DIR" cd "$TARGET_DIR" grep -rl "__PROJECT_NAME__" . | xargs sed -i "s/__PROJECT_NAME__/$PROJECT_NAME/g" grep -rl "__PACKAGE_MANAGER__" . | xargs sed -i "s/__PACKAGE_MANAGER__/$PKG_MGR/g"

这个脚本很朴素，但能用。更讲究的做法是用 envsubst 管理模板变量，不过 sed 对大多数场景已经够了。变量设计的原则就一条：任何可能因为项目不同而变化的字段，都先用占位符标记出来，绝不在通用模板里写死。

3.3 base 与 variant 的边界，我用一张表钉死

维护模板最耗心力的地方，就是决定一条规则到底放 base、variant 还是不放。我给自己定了一张对照表：

这张表现在贴在模板库的 README 里，每次拿不准就对照一下。核心就一句话：模板里只保留“换一个环境仍然成立”的规则。凡是会在三个月后变得不准确的，统统别放。

4. 核心命令模板编写实录：从 git 到测试的实战配置

4.1 commit.md：让提交信息不再是自由发挥

大家都会让 Claude Code 生成提交信息，但模板和临场提示的差别在于稳定。我写的 commit 命令长这样：

--- description: 根据暂存区改动生成符合约定式提交规范的提交信息 argument-hint: <一句话描述本次改动> --- 请先依次执行： 1. git status --short，查看暂存区状态 2. git diff --cached --stat，了解改动范围 3. git diff --cached，理解具体变更内容 生成提交信息时遵守项目 CLAUDE.md 中的提交规范： - type 从 feat / fix / refactor / docs / test / chore 中选择 - 正文说明改动动机，而不是罗列改动文件 - 如果 $ARGUMENTS 提供了概述，把它作为提交信息第一行

这里必须强调：一定要用git diff --cached，不要用git diff。后者会把未暂存的改动也算进来，生成的提交信息会包含本次根本没提交的内容。这是新手最容易踩的坑。

4.2 review.md：审查命令必须写明“不许改代码”

代码审查模板是我踩过最多坑的地方。早期版本没写“不修改文件”这句，结果 Claude Code 审查到一半直接开始改代码，又因为权限限制改完还报错，场面非常混乱。后来我把边界写死在命令文档里：

--- description: 对当前分支相对主分支的改动进行代码审查，只输出审查结论 --- 1. 先执行 git diff 主分支...当前分支，获取完整改动 2. 按功能逻辑、错误处理、可测试性三个维度分析 3. 对每个问题给出文件位置和修改建议，但禁止直接修改任何文件 4. 最后用表格汇总严重程度：必须修改 / 建议修改 / 可选优化

这条命令真正好用的地方，是它通过“只输出结论”把 AI 的角色固定住了。审查者和实现者是两个不同的角色，混在一起既做不好审查，也容易把代码改坏。角色边界用模板写死之后，命令的执行稳定性明显提高。

4.3 test.md：让测试反馈形成闭环

测试命令的模板重点不在于“运行测试”，而在于“测试失败之后怎么办”。一个只会跑测试的命令价值有限，真正有用的是拿到失败结果后能定位问题并提出修复建议。

--- description: 运行测试并分析结果，输出修复建议 argument-hint: <可选：指定测试文件路径> --- 1. 执行 pnpm vitest run $ARGUMENTS，超时控制在 120 秒 2. 如果测试通过，简短说明覆盖情况 3. 如果测试失败，先定位失败用例，分析断言和实现之间的差距 4. 不要直接修改源码，先给出根因分析和最小修复方案，等用户确认

这里加了一个细节：超时时间。如果不加，AI 遇到大型测试套件可能会一直等待，或者干脆跑一个超长命令卡住会话。所有涉及长时间运行命令的模板，都应该明确超时或限制范围。

4.4 代理模板：把角色固化成可复用资源

除了斜杠命令，模板库里还可以放代理定义。代理本质上是带有独立角色描述的配置，可以把某类任务完全委托给一个特定人格的执行体。比如代码审查代理、文档撰写代理、重构执行代理。

我的 agents 目录里有一个 reviewer 定义，核心内容大致是：

--- name: reviewer description: 只做代码审查，不修改代码 tools: Read, Grep --- 你是一名严格的代码审查者。你只分析问题，不改动文件。 你的审查重点是正确性、边界处理和可维护性。 对每个问题，请给出文件路径、具体行号、问题说明和修复建议。

代理模板的好处是行为隔离。普通会话里的 Claude 可能要边写代码边审查，角色切换成本很高；代理把审查职责单独拎出来，一个项目可以同时有“写代码的执行者”和“挑问题的审查者”，互不干扰。这是模板体系里相对进阶的一层，但一旦用起来，对团队协作的提升非常明显。

5. 模板的复用、分发与维护

5.1 新项目初始化，我只需要四步

现在我用模板铺一个新项目，整个流程可以控制在十分钟以内：

1. clone 模板仓库，阅读 README 确认版本。
2. 运行scripts/init.sh -n 项目名 -t 技术栈，脚本自动复制 base 和对应 variant，完成变量替换。
3. 进入项目根目录，启动 Claude Code 跑一次/test，确认模板里的命令和实际环境匹配。
4. 根据第一个任务的反馈修正 CLAUDE.md 里的偏差，然后 commit。

第四步很多人会忽略。模板铺进去的时候不一定完全适配当前仓库，所以第一次使用时让 AI 自己检查一遍模板内容是否有效，把检查结果反馈回来。这一步相当于让模板“自检”，能发现大量过期规则。

5.2 如何防止模板慢慢烂掉

模板不是建好就完事的，它会随工具演进慢慢腐蚀。我见过最典型的场景：项目里的测试命令从 vitest 换成了 jest，但 variant 模板里还写着 vitest；团队成员知道模板过时，于是每个人都手动绕开模板，模板逐渐变成摆设。

我常用的反腐蚀手段有三个。第一，定期拿模板生成一个全新的演示项目，跑一遍所有命令，看模板是否符合当前工具链。第二，每次工具链升级后，主动检查模板里的命令和权限规则是否还成立。第三，发现某条规则频繁被绕开时，不要骂人，而是直接把这条规则从模板里删掉——它在模板里已经没有意义了。

5.3 多人协作时的模板演进方式

模板库如果只有一个人维护，很容易变成个人习惯的存档。团队使用的时候，应该把它当作一个普通仓库来维护：变更走 PR，合并前有人 review，重大行为变化要用版本号标记。

我给模板库打 tag，比如 v1.0.0、v1.1.0。每个版本的 README 里记录行为和之前版本有什么差异，特别是权限规则、命令行为这类会影响协作的改动。这样做的好处是，项目里可以固定模板版本，不会出现“昨天还好好的，今天更新完模板行为全变了”的失控感。

另外一个细节：模板库的 commit 信息也要规范。因为它本身就是一个会被多人阅读的仓库，提交说明写清楚“为什么改这条规则”，比写清楚“改了哪些文件”更有价值。

6. 高频问题速查表：模板失效的典型原因与排查思路

还有一个容易被忽略的问题：CLAUDE.md 文件过长。AI 的上下文窗口是有限的，当模板文件超过几百行，它对核心规则的注意力会被大量噪音分散。我实测下来的体感是，CLAUDE.md 超过一百行以后，收益就开始递减。如果模板越写越长，先考虑删减而不是继续添加。

最后分享一个个人偏好：模板里的规则尽量用“如何做”的句式，少用“不要做”的句式。禁止类规则不是没用，但一连串“不要”会让 AI 变得畏手畏脚，稍微遇到模板没覆盖到的新情况就容易卡住。更好的写法是告诉它“遇到 xx 场景时应该怎么做”，这样的模板会随着项目一起演化，而不是变成一道越来越紧的紧箍咒。

我在实际维护中越发觉得，claude-code-templates 的核心价值不是省去写提示词的几秒钟，而是让 AI 编码行为变成可以被管理、被审查、被改进的东西。当每一次审查和不规范提交的原因都能回溯到模板规则，你和 AI 协作的方式就从“碰运气”变成了“做工程”。