用Claude Code模板把AI编程工具调教成老同事

先说结论：Claude Code 这类 AI 编程工具，真正拉开使用体验差距的，不是模型版本，而是你有没有一套自己的 claude-code-templates。我在连续几个项目里把同一个工具用出过两种极端——有时候它表现得像个熟悉项目的老同事，上来就知道该看哪个文件、该用什么模式；有时候它又像个第一天入职且不看文档的新人，什么都要问，问完还自作主张。折腾了大概两个月，反复调整规则、试错、和团队对口径之后，我把这套东西沉淀成了一组模板，现在每个新项目初始化时间从半小时压缩到三分钟。这篇文章就把这套模板的完整思路、实际代码和踩坑过程都摊开讲，适合正在用 Claude Code、或者准备把 AI 编程工具引入团队的人参考。

1. 为什么我最终整理了一套 claude-code-templates：三个让我抓狂的瞬间

先说第一个瞬间。每次开新项目，我都要对着 Claude Code 把技术栈、目录结构、代码规范重新讲一遍。讲得快还好，讲漏了它就开始自由发挥。有一次我忘说"service 层禁止直接访问数据库"，结果它写出来的接口直接绕过 service 层连了数据库，测试居然还跑过了。后来 code review 的时候同事盯着那段代码问了我十分钟"这是什么设计"——其实哪有什么设计，就是我没给它交代清楚边界。

第二个瞬间是误改无关代码。我让它修一个接口的超时问题，它分析完问题之后，顺手把另一个不相关文件的函数签名也改了。那个函数被十几个地方调用，连锁报错一片红。也不是说完全不能约束，但每次都要在对话里加一句"不要动无关文件"，这种话讲多了自己都烦，而且下次换了个新会话，同样的交代又得重来一遍。

第三个瞬间发生在团队协作的时候。同样是给我和同事两个人做辅助，Claude Code 给 A 生成代码的风格和给 B 生成的完全是两套：A 这边的接口返回 snake_case 字段，B 那边返回 camelCase，最后联调的时候两个人对着 JSON 字段名互相怀疑人生。这还不算完，有的人让它用 pytest，有的人让它写 unittest，仓库里两套测试框架并存。

这三个瞬间叠在一起，我意识到问题的根源不在模型本身，而在于每次对话的"初始上下文"都不一样。Claude Code 本身提供了一套机制——通过 CLAUDE.md 文件、Skills、权限配置来预设行为，只是我一开始没好好用。于是我把"每次用嘴交代的东西"全部固化成了文件模板，这就是 claude-code-templates 的雏形。它解决的核心问题很简单：让 AI 在第一次打开项目的时候，就具备我已经调教好的判断力，而不是每次都从零开始。

2. 模板体系设计：三层规则加两层护栏，而不是一个孤零零的文件

很多人一听到"模板"就以为是一个文件，顶多是一份 CLAUDE.md 复制到各个项目里。实际上要让模板真正稳定生效，需要分层设计。我最终定下来的结构是三层规则加两层护栏：

• 全局层：定义所有项目都适用的底线行为。
• 项目层：定义单个项目的技术栈、目录规范、术语表。
• 会话层：定义一次会话内部的临时约定。
• 护栏一：权限配置，控制 Claude Code 能执行哪些命令。
• 护栏二：Hooks 脚本，在危险操作发生前做拦截。

下面展开讲每一层具体放什么。

2.1 全局层：约等于"公司制度"

全局模板放在~/.claude/CLAUDE.md，对所有项目生效。这一层只放"违反一次就会出大事"的规则，比如：修改文件之前必须先读取并理解现状，不能凭空假设；执行删除类命令前必须停下来跟用户确认；不要一次做太多事情，避免无关重构。内容必须短，我控制在 30 行以内。因为 Claude Code 每次会话都会自动加载这个文件，加载进上下文是要占用窗口的，全局规则写太长会挤占项目相关的有效信息。

全局层还有一种特殊用途：约定 AI 的输出风格。比如我团队习惯用中文交流，但代码注释和提交信息必须用英文，这条规则放在全局层最合适，因为它在任何项目里都不应该变。

2.2 项目层：约等于"项目手册"

项目模板放在每个项目的./CLAUDE.md，随仓库一起提交。这一层放的是跟项目强相关的内容：技术栈和版本、目录结构、编码约定、常用命令、术语表。通常我会把"最容易让 AI 犯错的几个点"单独强调出来。比如一个 FastAPI 项目，最容易犯的错是 service 层里直接写 SQLAlchemy 查询、接口返回 ORM 对象而不是 Pydantic schema。这些内容直接写成禁止性规则，AI 一眼能看到。

项目层还需要给 AI 提供"常用操作路径"。比如启动命令是什么、测试命令是什么、lint 规则是什么。AI 知道这些之后，执行任务链的时候就不会反复猜测，省掉很多来回确认的对话轮数。

2.3 会话层：约等于"当日备忘"

会话层对应./CLAUDE.local.md，这个文件不提交 Git，写在.gitignore里。它的作用是记录一些临时性的约定，比如"本周正在重构用户模块，所有涉及 User 模型的改动先跟项目负责人确认"这类只对当前阶段有意义、不值得写进项目长期规则的内容。

之所以单独拆一层，是因为项目级 CLAUDE.md 一旦写进去就很难删——团队成员会默认它是长期约定，你想临时加一条两周后作废的规则进去，很容易造成理解混乱。用 CLAUDE.local.md 承载临时约定，等约定稳定了、确认要长期执行了，再提升到CLAUDE.md里。

2.4 护栏：权限配置与 Hooks

权限配置在.claude/settings.json，用来控制 Claude Code 能跑哪些 Bash 命令。我一开始没配，结果它有一次真的执行了rm -rf来清理临时文件，把我一份没提交的本地修改连带删了。从那以后我所有项目都默认带一份 settings.json，把高频安全命令列入 allow，把高危命令列入 deny。

Hooks 是更强的一层护栏。我主要用它做"破坏性操作确认"：当检测到 Claude Code 要执行rm、dropdb、git push --force这类命令时，先弹一个确认提示，AI 不能继续，必须等人点了确认才放行。实际配置在后面的实例里会给到。

2.5 组织模板仓库的目录结构

把上面的设计落成目录，大概是这样的：

~/.claude/ ├── CLAUDE.md ├── settings.json └── hooks/ └── pre_tool_use.sh <project>/ ├── CLAUDE.md ├── CLAUDE.local.md └── .claude/ ├── settings.json └── skills/ └── review/ └── SKILL.md

我把模板按项目类型分目录维护，后面专门讲。这里想强调一个理念：模板不是一个文件，而是一套"初始化一个项目时该有的 AI 工作环境"。全局规则管底座，项目规则管个性，会话规则管临时变化，权限和 hooks 管安全边界。五件事都做齐了，模板才真正称得上"一套"。

3. 让 AI 真正"听得懂"的指令写法：我沉淀出的五条原则

模板文件写出来很简单，难的是写出来的规则到底有没有效果。我最初几版模板写了一堆"要写出高质量的代码""保持代码整洁""注意可读性"这类话，实际操作里几乎全被 AI 当成了耳旁风。后来我把所有无效规则拉出来复盘，总结出五条写法原则。

3.1 用行为描述，不用形容词

"高质量代码"这种词的问题在于无法被校验。AI 不知道你觉得什么叫高质量，它的训练数据里对应这个描述的输出可能有上千种。但"service 层函数禁止超过 60 行，超过必须拆分"就非常明确。60 是一个硬数字，行数可以被检查，如果它违反了，你可以直接指出来并让它重写。

举两个对照：

3.2 给出正反例，比讲道理有效

模型对"禁止 xxx"的理解，有时候不如"应该这样写"来得直接。我现在的模板里，关键规则都是"错误写法 + 正确写法"成对出现。比如：

- 禁止在 service 层直接使用 db.query，正确做法： - 错误：`db.query(User).filter(User.id == uid).first()` - 正确：`user_repository.get_by_id(uid)`

给出正反例之后，AI 的命中率肉眼可见地提升。这其实跟人一样，你跟新人说"不要乱写"，他一脸茫然；你给他看一份规范代码和一份反例代码，他立刻知道边界在哪。

3.3 把边界写清楚，而不是只写目标

很多模板里写"确保接口安全"，AI 就真的只是在函数上加了@requires_admin装饰器，业务逻辑里的越权一点没管。问题在于"安全"对 AI 来说太抽象。你需要写的是具体的边界规则，比如"查询订单详情时，必须校验 order.user_id 是否等于当前登录用户 id，否则返回 404"。这种规则拆到业务级别，AI 才不会漏。

所以我在模板里专门设了一节"安全边界"，把项目里最容易出现越权、泄露、脏写的场景全列出。代价是要花时间写，收益是 AI 生成的代码基本不用再返工安全 review。

3.4 重要规则放前面，内容宁短勿长

Claude Code 加载 CLAUDE.md 之后，规则并不是"逐字执行"，而是作为上下文影响模型的判断。文件越长，排在前面的内容权重越高，后面写的内容可能被前面淹没。这导致一个常见问题：模板 200 行，AI 只遵守了前 30 行。

我后来定了个规矩：模板超过 80 行就是危险信号，必须砍。怎么砍？把"操作规范类"的内容拆到 Skill 里按需加载，把"背景知识类"的内容拆到 docs 目录里用 @ 显式引用。CLAUDE.md 里只留真正需要每次会话都生效的硬规则。

3.5 为术语建立"项目词典"

AI 在项目里经常搞混业务术语。我做过一个电商项目，模型里同时有 User（登录用户）和 Account（用户绑定的第三方账户），AI 在生成接口时经常把两者交叉引用，一会儿用 Account.id 查 User 的订单，一会儿把两个模型的字段混在一起。这种问题靠一句"注意区分 User 和 Account"根本没用。

正确做法是在 CLAUDE.md 里写一个术语表，用最短的话把每个术语的定义和边界写清楚：

术语表： - User：平台注册用户，对应 users 表，登录主体。 - Account：第三方账号（微信、GitHub）绑定关系，对应 accounts 表。 - 订单：Order 属于 User，不属于 Account。

有了这个词典，AI 在生成代码和查询语句时引用模型就准确多了。

4. 一套可直接复用的模板实例：FastAPI 订单服务的完整配置

光讲原则不够，我直接给一套现在正在用的模板骨架，场景是一个 Python FastAPI 订单服务。你可以直接复制改改就能用。

4.1 全局模板~/.claude/CLAUDE.md

# Claude Code 全局行为约定 ## 沟通方式 - 使用中文回复，代码和终端命令保持英文。 - 先给结论，再给必要过程，不要长篇大论。 - 不要重复用户已经说过的内容。 ## 工作方式 - 修改任何文件之前，务必先读取文件当前内容，确认与项目约定一致。 - 一次只完成一个目标，不要顺手重构无关代码。 - 在执行删除、覆盖、数据库写入等风险操作前，先说明影响范围并等待确认。 ## 输出规范 - 代码遵循项目现有风格，不强行引入新风格。 - commit message 一律使用英文，格式为 type(scope): summary。

这 15 行定义了所有项目的底线，不需要每个项目重复写。

4.2 项目模板./CLAUDE.md

# 项目：订单服务（Python FastAPI） > template: python-api@v2.3 ## 技术栈 - Python 3.11 / FastAPI 0.110 / SQLAlchemy 2.x / PostgreSQL 15 - 包管理使用 uv，禁止新增 requirements.txt - 测试框架使用 pytest ## 目录结构 - app/api：路由层，只做参数校验与响应封装 - app/services：业务逻辑层，禁止直接访问数据库 - app/repositories：数据访问层，唯一允许写 ORM 查询的地方 - app/models：SQLAlchemy ORM 模型 - app/schemas：Pydantic schema，禁止在其他层直接返回 ORM 对象 ## 编码约定 - 行宽 100，所有代码必须通过 `uv run ruff check .` - service 层函数超过 60 行必须拆分 - 禁止在循环内查询数据库；批量操作使用 bulk_create / bulk_update - 涉及金额、库存的修改必须开启数据库事务 ## 安全边界 - 查询订单详情时，校验 order.user_id 是否等于当前登录用户 id，否则返回 404 - 所有写操作接口必须显式校验请求体 schema，禁止使用 `**request.body` 这类展开 ## 常用命令 ```bash uv run uvicorn app.main:app --reload # 启动 uv run pytest # 测试 uv run ruff check . # Lint

术语表

• User：平台用户，订单的归属主体。
• Account：第三方绑定账号，不属于订单模型。
• Order：一笔交易记录，属于 User。

注意里面有一行 `> template: python-api@v2.3`，这是我自己定义的模板版本标记。出现行为异常时，可以通过这行信息快速定位是模板问题还是项目定制问题。 ### 4.3 代码审查 Skill：`.claude/skills/review/SKILL.md` ```markdown --- name: review description: 审查当前分支相对主分支的代码改动，输出问题清单和修改建议。当用户要求"review 代码"、"审查 PR"、"检查这次改动"、"code review"时使用。 --- # Code Review 任务 按以下步骤执行： 1. 运行 `git diff main...HEAD --stat` 获取改动文件清单。 2. 按文件逐个审查，重点关注：越权、未校验的输入、事务缺失、无测试覆盖。 3. 输出格式： - P0：会导致线上事故的问题 - P1：功能逻辑错误 - P2：代码风格与规范问题 约束： - 只输出审查报告，不要直接修改代码。 - 报告用中文，代码标识符用英文。 - 每个问题必须给出对应的文件路径和行号。

Skill 的好处是把这个流程从"每次用嘴要求 AI 怎么审查"变成了一个稳定的命令。用户只需要说"帮我 review 代码"，Claude Code 就会自动加载这个 Skill 按流程执行。

4.4 权限配置：.claude/settings.json

{ "permissions": { "allow": [ "Bash(git *)", "Bash(ls *)", "Bash(cat *)", "Bash(uv run *)", "Bash(curl -I *)" ], "deny": [ "Bash(rm -rf *)", "Bash(git clean *)", "Bash(git reset --hard *)", "Bash(dropdb *)", "Bash(psql *)" ] } }

allow 列表里的uv run *已经覆盖了 pytest、ruff、uvicorn，不会因为权限卡正常开发流程。deny 列表把物理删除和数据库重建类命令全部挡掉，AI 最多只能问你能不能执行，不能直接执行。

5. 多项目切换与模板版本管理：我的实际目录与自动化脚本

模板不是写了一版就结束，实际用起来会面对两个问题：多个项目类型怎么管理、模板更新后怎么同步。我的做法是把模板按项目类型拆开放在~/.claude/templates/下，然后用脚本一键应用。

5.1 按项目类型拆分模板

~/.claude/templates/ ├── python-api/ │ ├── CLAUDE.md │ └── .claude/ │ ├── settings.json │ └── skills/review/SKILL.md ├── frontend-react/ │ ├── CLAUDE.md │ └── .claude/settings.json └──>#!/usr/bin/env bash # apply-template.sh —— 用法: ./apply-template.sh <模板名> <目标项目路径> set -euo pipefail TEMPLATE_ROOT="$HOME/.claude/templates" NAME="$1" TARGET="$2" if [ ! -d "$TEMPLATE_ROOT/$NAME" ]; then echo "模板不存在: $NAME" >&2 exit 1 fi if [ ! -d "$TARGET" ]; then mkdir -p "$TARGET" fi cp -rn "$TEMPLATE_ROOT/$NAME/." "$TARGET/" echo "已应用模板 $NAME 到 $TARGET"

应用模板只需要一条命令：

./apply-template.sh python-api ./new-order-service

脚本里的-n参数保证不会覆盖目标项目里已经存在的文件。如果你已经写了一段 CLAUDE.md，又应用了一个新模板，它不会直接把旧文件冲掉，这是有意为之的安全措施。

5.3 符号链接方案与复制方案的取舍

我一开始用的是符号链接方案：把模板仓库 clone 到本地，然后ln -s到各个项目。好处是模板更新后所有项目同步生效，不需要重新复制。坏处也明显：一是团队其他成员 clone 项目之后符号链接指向的路径在他们机器上不存在，直接坏掉；二是终端和 git 工具在 Windows 上对符号链接的兼容性参差不齐。

后来我换成了复制方案：每个项目初始化时把模板会复制进仓库，后续模板更新通过git pull模板仓库再手动合并，或者干脆直接改项目里的 CLAUDE.md。对单人项目来说，你甚至可以保持符号链接用得很爽；但一旦涉及团队协作，复制方案是更稳的选择。

5.4 用 Git 管理模板版本

我把~/.claude/templates整个目录放进了独立 Git 仓库，模板的每次调整都有 diff 记录。每次改动模板后打 tag：

git add ~/.claude/templates git commit -m "feat(python-api): add order query permission rule" git tag python-api@v2.4

项目 CLAUDE.md 第一行的> template: python-api@v2.3就是跟 tag 对应的。线上哪个项目的 AI 行为出了问题，我只要看这行就知道它用的模板版本，然后git diff python-api@v2.3 python-api@v2.4就能定位是不是模板变更引起的。

6. 落地过程中踩过的四个坑：从现象到根因的完整排查

再完美的模板设计，落地过程也会踩坑。我挑四个印象最深的写出来，每个都是真实的排查链路，不是直接给答案。

6.1 坑一：模板太长，AI 反而"失忆"

第一个版本我把项目模板写到 300 多行，事无巨细全往里塞，以为越全面越好。结果 Claude Code 在项目里执行任务时频繁"忘记"规则，甚至在代码里用了项目明确禁止的模式。

排查过程是这样的：我第一反应是模型上下文不够，换了更强的模型版本，问题依旧。然后我在会话里直接问 Claude Code 一句："这个项目的三条核心约束是什么？"它只答上来第一条，另外两条给出的是"写出高质量、可维护的代码"这种空话。这已经是很明显的证据：CLAUDE.md 确实被加载了，但内容太长，关键规则沉没在中间，模型输出时根本没有引用到。

修复方式：把模板砍到 50 行以内，只保留"不遵守就会出事"的硬约束；把"如何组织代码、架构怎么拆"这类背景知识挪到 docs 里用 @ 显式引用；把代码审查这样的多步骤流程拆成 Skill，按需触发。验证方法很简单，重复上面的问题，三条约束完整复述；再跑一个实际变更任务，行为符合预期。

6.2 坑二：deny 规则没兜住等价危险命令

有段时间我的 settings.json 里 deny 了Bash(rm -rf *)，以为安全了。但 Claude Code 有一次修完代码后主动执行了git clean -fdx，这个命令会删除所有未跟踪文件，行为上等同于一次范围更大的物理删除。我的本地未提交文件就这么被清掉了。

排查后发现，deny 列表写的是"某个精确命令"而不是"某类危险操作"。git clean -fdx不属于rm -rf的字符串匹配范围，所以穿过了防线。修复方式是在 deny 里把所有等价危险命令都列进去：git clean、git reset --hard、git checkout .、dropdb、truncate。我现在的准则是：凡是可能导致数据丢失的命令，一律进 deny 列表。

验证方式也很直接：在对话里让 Claude Code 执行一次git clean -fdx，看它是否给出"权限不足"的反馈。顺便说一句，权限配置改完后新会话才生效，别像我一样以为它在当前会话里就能立刻拦住。

6.3 坑三：中英文规则互相覆盖，输出风格漂移

模板里我先写了一句"使用中文回答问题"，后面的某个项目规则里又写了一句 "always use English for commit messages"。这个看起来不冲突，但 Claude Code 在执行 commit 相关任务时会倾向于把整个回复切成英文，团队成员经常收到大段英文分析，阅读成本一下就上去了。

排查链路比较曲折：我先怀疑是全局模板不生效，检查了好几遍；后来把"回复语言"这条规则挪到 CLAUDE.md 第一行，并把所有语言相关的规则统一成一条，才解决。更准确地说，问题出在多条语言规则在模型眼里形成了"可选的解释空间"，它倾向于挑更具体的英文规则执行。修复后我在模板里明确写了一句"回复语言跟随用户输入语言，代码标识符与符号保持英文"，然后分别用中文和英文提问做回归测试，输出语言稳定跟随。

6.4 坑四：Skill 注册了很多，但从未被调用

我往.claude/skills/里放了五六个 Skill，包括代码审查、依赖升级、接口文档生成。结果实际使用的时候，Claude Code 基本都是等我把 Skill 名念出来才执行，从来不会主动触发。一开始我以为是机制问题，后来翻到 Skill 规范文档才反应过来，问题出在 SKILL.md 的 description 写得太泛。

我最初写的是"help review code"，这种描述对模型来说没有任何触发信号。改成"当用户要求审查代码、review、检查 pull request、code review 时使用"之后，只要对话里出现与之匹配的意图，Skill 就会被自动加载。这个改动让 Skill 的主动调用率显著提升，也提醒我：写模板不光是写规则，连"规则何时被触发"都要写清楚。

7. 模板的持续演进：从个人工具到团队规范的体会

现在这套 claude-code-templates 已经不只有我在用，团队里几个项目都基于它做初始化。我的维护节奏是每两周抽一小时专门整理模板，主要做三件事。

第一，翻出过去两周的 code review 记录，如果 80% 的评论集中在同一类问题上——比如"没做越权校验"——就把对应规则升级进模板。第二，删掉那些"写了但从来没被触发过"的规则。每条规则在模板里都有成本，它会占用上下文、可能干扰其他更重要的指令，无效规则越少越好。第三，每次 Claude Code 版本升级之后，专门跑一遍权限配置和 Skill 的回归测试，确认配置项没有被意外废弃。

最后再分享一个实际体会：模板最珍贵的部分不是效率提升，而是让新同学加入项目时不用再听人讲半小时背景。给他一份 CLAUDE.md，他就能直接开始跟 AI 协作。这套东西的后续扩展方向我也想过——比如针对前端项目、数据管道项目沉淀专属模板——但会等团队实际需求出现再做，现在设计得再完整，不经过真实项目验证都是空中楼阁。