接触 Claude Code 大半年，从单兵作战到带团队统一使用，最大的感触是：工具本身差距不大，拉开效率差距的，是每个人喂给它的那套“初始设定”。有人写完 CLAUDE.md 就开始起飞，也有人从网上抄来一份长长的配置一股脑堆进去，结果 AI 每次都在无关的规则里翻找有效信息，反而越用越乱。为了不让大家重复踩坑，我把团队里的项目指令、命令模板、自动化钩子和规范说明整理成了一个模板库，名字就叫 claude-code-templates。
这篇文章不是工具文档的翻译，而是我这段时间维护、推广这套模板库的真实记录。里面包括目录结构怎么设计、每一份模板文件该写什么、怎么写才不会被 AI 忽略，以及推到团队时踩过的那些坑。如果你正准备在项目里引入 Claude Code，或者已经在用但觉得效果不稳定，这份经验可以直接抄走。
1. 模板库要解决的真问题：为什么同样的工具，有人用得飞起有人想卸载
刚给团队装好 Claude Code 的那阵子，可以用“冰火两重天”来形容。几位习惯写文档的同事很快就把项目背景、架构说明、常用命令写进了 CLAUDE.md，配合起来相当顺手；但另外几位同事直接问“这东西和 ChatGPT 有什么区别”，试了两次觉得回答太泛、改代码不精准，就丢到一边了。
我把两边的会话记录对比了一下，发现问题根本不在模型能力上，而在“喂给模型的初始上下文完全不一个量级”。用得好的人，开局就已经通过 CLAUDE.md 把项目是什么、技术栈是什么、代码目录怎么组织、有哪些约定俗成的规矩讲清楚了；用得不好的人，等于让 AI 在一个完全空白的对话里猜项目背景，猜一次错一次，来回纠正几轮就不耐烦了。
更深一层的问题是，团队里的经验没法沉淀。A 同事调教出一套特别适合写单元测试的指令，他关掉终端就什么都没了；B 同事摸索出让 AI 遵守项目现有代码风格的方法，也只在本地会话里生效。这些经验没有落到项目仓库里，就成了个人秘方，既不可复现，也没法传承。
我建 claude-code-templates 这个仓库，说白了就为三个目标：
- 把“项目级上下文”标准化，让每个人打开终端就能获得同样的基础信息，不用从零描述。
- 把“高频操作”固化成可复用指令，比如代码评审、写单测、整理 CHANGELOG，一行斜杠命令搞定。
- 把“自动化门禁”沉淀成钩子脚本，让 AI 的每次操作都经过可审计的流程，再也不用担心它在仓库里乱改文件。
如果你所在的团队用的是深度定制的开发环境，那这套模板库的核心理念一样适用——把上下文显式化、把流程脚本化、把经验版本化。
2. 仓库结构怎么设计：先分清“项目配置、个人指令、团队规范”三层
很多人在建模板库时容易犯一个错，就是把所有内容都堆进一个超大的 CLAUDE.md 文件里。这个文件确实会被 Claude Code 自动加载，但加载的内容是要消耗上下文窗口的，塞得越满，留给实际代码分析和对话的空间就越少。
我的模板库采用三层分离的结构，每一层管不同的事。
claude-code-templates/ ├── CLAUDE.md # 项目级全局说明，放仓库根目录 ├── .claude/ │ ├── commands/ # 斜杠命令，按业务场景拆分 │ │ ├── code-review.md │ │ ├── unit-test.md │ │ ├── changelog.md │ │ └── refactor.md │ ├── skills/ # 复杂技能，按能力域拆分 │ │ ├── frontend-audit/ │ │ └── database-migration/ │ ├── hooks/ # 自动化钩子，控制 AI 行为边界 │ │ ├── pre-commit.sh │ │ └── post-tool-use.sh │ └── settings.json # 工具级配置（权限、模型等） └── docs/ ├── template-usage.md # 模板库使用说明 └── faq.md # 常见问题与排查2.1 根目录 CLAUDE.md：管“项目这个角色”
根目录的 CLAUDE.md 是 Claude Code 在项目里默认读取的核心指令文件，相当于给 AI 的一份“入职手册”。它描述的是项目本身：项目目标、技术栈、目录结构、开发规范、测试要求、常见陷阱。
这份文件应当克制，只写项目级不变量。写多写杂的代价是每条规则都在稀释真正的重点，AI 判断“当前任务优先遵循哪条规则”的难度也会上升。
2.2 .claude/commands/：管“高频动作”
commands 目录下的每个 Markdown 文件对应一条斜杠命令。比如在终端里输入/code-review，Claude Code 就会读取 code-review.md 的内容作为本次任务的附加指令。
它适合放那些“技能稳定、重复度高”的场景：审查本次改动、生成单元测试、更新文档、检查安全漏洞。我把命令模板设计成循环可用的，而不是一次性写死的 Prompt，每条命令都留了参数位，方便在不同仓库里复用。
2.3 .claude/skills/：管“需要步骤拆解的项目”
Skills 是比 Commands 更重的封装，适合需要多步骤执行的流程。比如一次完整的前端性能审计，可能需要先扫描路由，再分析打包产物，最后对照预算表输出报告。这类技能用一个 Skill 描述整体流程，内部再分为多个阶段，每一步都有明确的输入输出。
我个人把 Skills 当作“把专家的操作手册喂给 AI”的一种方式。它不只是几句指令，而是把专家做事的背景知识、判断标准、检查清单都结构化地写在里面。
2.4 hooks：管“AI 行为的边界与安全”
hooks 目录里放的是事件触发的脚本，比如在 AI 修改代码前、在它调用某个工具后。hooks 能做的事情很多，我主要利用它做两类事：一类是安全检查，比如禁止 AI 在生产环境目录上执行危险命令；另一类是质量门禁，比如提交前自动跑一遍格式化和单元测试。
这一层是很多开源模板库里被忽略的部分，但恰恰是它能让 AI 从“建议者”变成“受控的执行者”，也方便团队审计 AI 到底做过什么。
3. CLAUDE.md 逐段拆解：这份模板为什么能一用到底
一份合格的 CLAUDE.md 不需要华丽，但必须结构清晰，让 AI 知道自己面对的是一个什么样的项目，以及在这个项目里什么能做、什么不能做。我的基础模板长这样，你可以直接复制后按自己的项目改：
# 项目名称与一句话定位 XX 服务，负责用户画像数据的采集与聚合，为推荐系统提供实时特征。 ## 技术栈 - 语言：Go 1.22 - 框架：Gin + Ent - 存储：PostgreSQL 15 + Redis 7 - 消息：Kafka（topic: user-profile-events） - 部署：Docker + K8s，镜像仓库在 xxx ## 目录结构速览 - cmd/server：服务入口 - internal/service：业务逻辑 - internal/repository：数据访问层 - api/proto：gRPC 接口定义 - scripts：本地脚本 ## 常用命令 - 本地启动：make dev - 跑全部测试：make test - 生成 mock：make mock - 数据库迁移：make migrate-up ## 编码规范 - 错误处理：一律使用 errors.New / fmt.Errorf，禁止 panic - 日志：使用 slog，区分 Info 与 Error，请求日志打 trace_id - 命名：接口名必须以 Service 结尾，repository 层方法必须写注释 ## 测试要求 - 新增业务逻辑必须配套单测，核心路径覆盖率不低于 80% - 涉及外部调用的逻辑使用 mock，不依赖真实环境 ## 禁区 - 不要直接改生产数据库 - 不要绕过 service 层直接调用 repository - 不要在提交代码前关闭 lint ## 当前迭代背景（可随迭代更新） - 正在做 v2 特征接入，旧的 v1 接口暂时保留，但新代码不要继续往 v1 里加逻辑3.1 为什么“技术栈”和“目录结构”要放在最前面
Claude Code 在生成代码时，最怕的是“看着像通用的方案，实际上不符合项目现状”。比如一个用 Ent 做 ORM 的项目，AI 如果按 GORM 的习惯写查询，后面接手的同事会非常痛苦。把技术栈和目录结构摆在前面，相当于给了 AI 一个强约束：你的建议必须符合这套既定设计。
这里有一个细节值得多说一句：目录结构不用列全，只列与 AI 编写代码最相关的部分。如果项目有 50 个目录，全列出来不仅占用上下文，还会让 AI 分不清主次。我习惯只写五到八个核心目录，并标注每个目录的职责边界，AI 定位文件的速度会快很多。
3.2 “常用命令”是让 AI 真正跑起来的关键
很多模板会忽略常用命令，但我的使用经验里，这部分价值极高。当 AI 需要验证自己的改动、跑测试、启动服务时，如果没有现成命令，它就会凭感觉猜，可能会出现go run ./main.go这种跑不通的指令，或者不知道要先启动依赖的数据库。
把这些命令写清楚，AI 不仅会直接使用，还会在你让它“改了代码后跑一下测试”时，主动选择 make test 而不是自己拼一个看起来很像的命令。等于是把项目里约定俗成的操作方式一次性教给它。
3.3 “禁区”宁可写少，不能写漏
禁区是模板里最需要斟酌的部分。写太少，AI 可能在生成代码时随意破坏架构约束；写太多，每条禁令都在消耗注意力，AI 反而会忽略其中的大部分。
我维护的一个原则是：只写那些“违反了会导致严重事故或者返工”的规则。比如不能直接改生产数据库、不能绕过 service 层、不能在事务里调用外部 HTTP 接口。像“变量名不要用拼音”这种风格问题，放编码规范那段就够了，不用零散地堆进禁区。
4. 命令模板实战：把代码评审和写单测做成一条斜杠命令
CLAUDE.md 解决的是“项目背景认知”问题，但实际工作里，我们更需要的是把一套稳定的操作流程固化成指令。这就是 .claude/commands/ 目录的价值。举一个我每天都在用的例子，代码评审命令。
--- description: 对当前的改动做一轮代码评审，输出问题清单 agent: code-reviewer model: sonnet --- 你正在参与一次代码评审。请按以下步骤执行： 1. 先用 git diff 查看当前工作区的改动，明确变更范围。 2. 确认改动涉及的模块与文件，阅读相关上下文。 3. 从以下五个维度逐项审查： - 逻辑正确性：是否存在边界条件遗漏、并发安全问题。 - 架构一致性：是否遵循 CLAUDE.md 中定义的目录职责和分层约束。 - 性能风险：是否在循环中执行了不必要的 I/O 或数据库查询。 - 可测试性：是否有必要的单元测试，测试是否覆盖异常路径。 - 安全风险：是否泄露密钥、是否缺少输入校验和权限校验。 4. 输出格式： - 问题按严重级别用 [P0]、[P1]、[P2] 标注，P0 代表必须修复。 - 每个问题给出文件路径、行号、原因和修改建议。 - 最后用三句话总结本次改动的整体质量。 如果改动内容少于 20 行，跳过性能风险这一项。4.1 frontmatter 里的 agent 和 model 怎么选
命令模板的 frontmatter 可以指定 agent 和 model，这在多人协作时非常有用。比如代码评审这种任务，需要更强的推理能力，可以固定用更高级的模型；而整理 CHANGELOG 这种轻量任务，用默认的快速模型就够了，成本更低、响应更快。
我倾向于在命令模板里显式指定 agent，而不是完全留给使用者选择。原因很简单：既然已经沉淀出一条稳定的评审流程，就不该让每次运行的模型差异导致输出质量忽高忽低。等团队跑顺了，再把模型选择权放开也不迟。
4.2 把“步骤”写成交互式流程，而不是一次性的输出要求
早期的命令模板我写得像一次性大 Prompt，让 AI “做一次全面检查并给出报告”。后来发现这种写法的问题在于：上下文一长，AI 容易漏掉步骤，而且也不会主动追问信息。
现在我把命令设计成交互式流程。比如写单测的命令，第一轮只让 AI 列出需要补充测试的函数清单，等用户确认后再动手写代码。这样做的好处是，AI 不会自作主张把整个项目的测试都改一遍，而是在关键节点等待人的确认，可控性高得多。
命令模板里的内容也不宜过长。我控制每条命令正文在 400 到 600 字左右，超过这个量，AI 对指令末尾部分的遵循度会明显下降。如果流程真的很复杂，就拆成多个命令，让用户一步一步调用。
5. 上下文预算与性能参数：模板写得再好，上下文满了照样拉胯
维护模板库的过程中，我慢慢意识到一个容易被忽视的问题：CLAUDE.md 和 commands 再好，如果上下文管理不当，AI 在中后期会话里依然会“失忆”。只有把上下文预算和会话管理纳入模板体系，整个方案才真正完整。
5.1 上下文窗口不是无限大的，默认配置要会调
Claude Code 的会话上下文是有限的。项目级 CLAUDE.md、命令模板、对话历史、工具返回的文件内容、测试输出，全都挤在同一个窗口里。当上下文接近上限时，模型会压缩早期信息，很多重要的项目约束就会被挤掉，表现为“明明 CLAUDE.md 里写了不要绕过 service 层，它还是直接在 repository 层写逻辑”。
我常用的方法是分层控制上下文占用：
- CLAUDE.md 控制在 150 行以内，只写高优先级项目信息。
- 命令模板里明确要求 AI “只读取与当前任务相关的文件，不要一次性读取整个目录树”。
- 长文档通过指令让 AI 先看目录结构再决定读取范围，避免把整份几千行的文件一次塞进来。
- 定时使用 /compact 压缩历史对话，把已经讨论完的结论保留下来，细节让出位置。
5.2 settings.json 里的权限模式与服务配置
.claude/settings.json 是容易被新手忽略的文件，它控制 AI 可以做什么、不能做什么。我的模板库里给了一个稳妥的默认配置：
{ "permissions": { "defaultMode": "acceptEdits", "allow": [ "Bash(npm run lint)", "Bash(npm run test)", "Read" ], "deny": [ "Bash(git push)", "Bash(rm -rf *)", "Edit(secrets/**)" ] }, "model": "sonnet", "env": { "DISABLE_TELEMETRY": "1" } }defaultMode 用 acceptEdits 意味着 AI 可以直接改文件，但执行命令需要用户确认。这对日常开发效率影响最小，又能避免 AI 在没有监督的情况下运行危险命令。deny 列表里的 git push 和 rm -rf 是我特意加上的，经验告诉我，AI 在高强度多轮操作后，确实可能做出开发者本人都没预料到的危险动作。
5.3 什么时候该重新开会话，而不是一直续着聊
模板库里还要写入一条使用习惯：发现 AI 开始反复出现前后矛盾的判断时，别继续补 Prompt 了，重建一个会话可能更高效。老会话里积累的错误判断和混乱上下文，会给新指令造成严重干扰。
我在 command 模板里甚至写了一条固定要求：当 AI 回答开始偏离主要目标，提示用户“当前上下文可能过载，建议执行 /clear 开启新会话，并把任务拆小”。让 AI 自己学会建议重置，团队整体使用体验会提升一个档次。
6. 给团队推这套模板，我踩过的四个坑
模板库从“我自己的效率工具”变成“团队共用基础设施”的过程中，我踩了不少坑，有些现在想起来还挺痛的。写出来省得大家再走一遍。
6.1 坑：照搬网上热门模板，文件厚得像本字典
最早我图省事，参考了一份很流行的模板，里面把代码风格、沟通礼仪、回答格式、技术栈、项目背景、部署流程、API 设计原则全部写在一起，整整三百多行。结果 AI 每次启动都要加载这一大坨内容，真正干活时反而被堆积的规则绑住手脚，经常纠结于“回答是否礼貌”而不是“代码是否正确”。
后来我把模板瘦身到一百行以内，删掉了所有与“这个项目具体怎么做”无关的内容。通用性的建议，比如“请尊重用户”“请做代码审查”，其实放不放在模板里差别不大，AI 本来就被训练得很好。模板只放项目专属信息。
6.2 坑：命令模板里混进危险操作，没加人工确认
有段时间我写了一条“部署到测试环境”的命令，里面包含了构建镜像和更新 K8s 的脚本。第一次在团队里公开，就有同事反馈 AI 在没有明确确认的情况下执行了某些外部命令。虽然测试环境没有出大事，但这暴露了一个设计问题：命令模板内部的操作必须分阶段加人工确认，不能为了图省事把整条链路全部自动跑完。
之后所有涉及外部系统变更的命令，我都在模板里明确要求 AI “在每一步执行前用中文说明将要做的操作，并等待用户输入 y 确认”。这个约束写进模板后，再也没有出现过不可控的自动化操作。
6.3 坑：模板更新了，旧会话还在用旧配置
Claude Code 会在会话启动时读取模板文件，但如果你在会话中间改了 CLAUDE.md 或命令模板，当前会话不会自动重新加载。团队里有同事遇到过一种情况：他更新了命令模板里的输出格式要求，但旧会话里的 AI 一直按旧格式回答问题，他还以为模板没生效。
排查了半天，最后发现是缓存和会话加载的问题。现在的流程是：每次修改模板后，在群里发个通知，让大家执行 /clear 重启会话。如果模板改动频繁，我会让 hook 在检测到模板文件变化时自动提示用户。
6.4 坑：权限模式一刀切，导致没人敢用
刚开始我把权限设得很死，默认 deny 所有 Bash 命令，AI 只能改文件不能跑命令。结果团队瞬间怨声载道，因为 AI 改完代码后没法自己跑测试，每次都要人手动敲命令去验证。
后来我把权限策略改成“默认允许只读操作和常见开发命令，危险命令单独 deny”。既保留了一定自主性，又把真正会出事儿的操作挡住。权限模型一定要跟着实际使用场景迭代，不要寄希望于一次性配好。
7. 从模板库到工作流：hooks 自动化和模板的持续迭代
模板库的价值不仅仅在于静态的 CLAUDE.md 和命令文件，它还可以挂上 hooks，让 AI 的操作自动经过质量门禁。这是我从“手工驱动”走向“自动化驱动”的关键一步。
7.1 一个简单的 pre-commit hook 示例
下面这个脚本放在 .claude/hooks/ 下，会在 AI 准备执行某些操作前运行，检查它是否试图修改受保护的目录：
#!/usr/bin/env bash # 检查 AI 是否意图修改 src/legacy/ 下的代码 if [[ "$CLAUDE_TOOL_NAME" == "Edit" && "$CLAUDE_TOOL_INPUT" == *"src/legacy/"* ]]; then echo "operation blocked: legacy directory is read-only" exit 1 fi exit 0实际环境里，我会把 hook 逻辑写得更完整，比如允许在特定分支下修改、允许特定用户绕过等。但核心思路就是给 AI 套上一道程序化的缰绳，让它在规则边界内工作。hooks 的日志输出还会记录到文件里，方便事后审计 AI 做了哪些操作、在哪个环节被拦下来。研发团队对这个功能的接受度很高，因为它让 AI 的不可控风险变得可回溯。
7.2 用模板库生成新的项目脚手架
当 claude-code-templates 里的模板稳定下来后，我又往前推了一步：把模板库变成新项目脚手架的一部分。新仓库初始化时，自动复制一份标准 CLAUDE.md 和基础命令文件，再根据项目技术栈微调技术栈章节。
这样做得到的效果是：团队里新项目从第一天起就具备相同的 AI 协作基础，不存在“老项目用得很顺、新项目从头调教”的割裂感。模板库本身用 git 管理版本，每次更新都有 diff 记录，谁改了什么一目了然。
7.3 持续迭代的节奏与版本管理
模板库不是一次性交付物，它需要跟着团队的使用反馈不断调整。我的做法是每两周回顾一次模板库的使用情况，收集同事们的吐槽点，再针对性地修改命令模板或者 CLAUDE.md。
这种做法对复盘能力的要求比较高。操作流程是这样的：打开仓库的 commits 记录，把同事们的提问和讨论串起来，能发现很多“当时以为没问题，用起来才发现不对”的细节。模板的版本号强烈建议和代码项目分开管理，否则会互相污染，很难定位问题到底出在代码还是模板。
另外要提醒一句：模板库是辅助工具，不是银弹。如果项目本身的工程质量很混乱，AI 拿到再好的模板也只能做到“在混乱中制造有序的幻觉”。先把代码分层、目录职责、测试规范这些基础问题理清楚，模板库才能真正放大团队效率。
原理与Python实战)
