第一次把claude-code-templates这个仓库建出来的时候团队里还有人问我这不就是把几个 markdown 文件放在一起吗当时我没法反驳因为最开始它确实就是几个 markdown 文件。但跑了三个项目之后所有人都闭嘴了——新项目接上模板库Claude Code 的行为稳定性肉眼可见地提升代码评审通过率、测试覆盖率这些数字也跟着变得好看。这篇文章我想把这套东西完整复盘一遍为什么模板库能解决真实问题核心模块怎么拆落进项目时要躲哪些坑以及它怎么从个人收藏夹长成团队基建。适合正在用 Claude Code 写业务代码、又苦于每次都要重新教模型我们项目怎么干活的开发者如果你只是想把模型当一次性问答工具那这篇对你意义不大但如果你打算让它持续、稳定地参与工程流程建议看完。1. 为什么我会专门建一个 claude-code-templates 仓库1.1 先还原一下没有模板时的真实状态今年年初我们组开始把 Claude Code 放进日常开发流。刚开始一切都很美好让它写个单测、解释一段业务逻辑又快又准。但两周之后问题就出来了——每个项目根目录下的 CLAUDE.md 写得五花八门有的写了两行你是优秀工程师有的塞了三百行公司历史有的干脆没建。更麻烦的是各个项目里散落着一堆自己整理的 agent 定义和 hooks 脚本A 项目里验证有效的规则B 项目完全不知道新人接手项目时模型就像一个没看过入职手册的实习生屡屡踩团队早就不踩的坑。那种感觉很像你请了个很聪明的助理但你每次见他都要重新交代一遍邮件怎么回、会议纪要怎么记、别在客户面前说某句话。一次两次可以每个项目都来一遍迟早崩溃。于是我开始琢磨能不能把这些对模型的约束和指导做成一份可以继承、可以版本化、可以一键复制到新项目的模板库claude-code-templates就是在这个背景下诞生的。1.2 模板库沉淀的不只是提示词很多人一听模板就觉得是提示词集合。这是最大的误解。真正跑起来之后你会发现模板库里装的是一整套工程配置至少包含三样东西规则与记忆CLAUDE.md告诉模型项目背景、技术栈、代码规范、命令约定解决模型不知道你们团队怎么干活的问题。角色与能力agents子代理和 skills技能让模型在特定场景下切换到不同身份和流程解决一个上下文干所有事的问题。自动化机关hooks在模型执行动作前后插入校验和记录解决模型做错了事没人拦着的问题。这三类资产对应的文件位置和作用完全不同放在一张表里看更清楚模块主要文件作用常见误区项目记忆CLAUDE.md给模型当前项目的背景、规范、常用命令写成超长说明书模型反而选择性遗忘子代理.claude/agents/*.md定义专用角色如 code-reviewer、test-writer给子代理过多工具权限等于没设防技能.claude/skills/*/SKILL.md封装可复用的做事流程和知识和 agent 混为一谈导致职责不清钩子.claude/settings.json或项目settings.json在工具调用前后做拦截、校验、记录matcher 写太宽误伤正常流程把模板库当成万能咒语大全是另一个常见的失败姿势。咒语解决的是这句话怎么问的问题模板库解决的是这个模型在项目里怎么长期稳定工作的问题。前者是一次性的后者是结构性的。1.3 什么样的团队和个人适合搞这个我不建议所有人一上来就搭全套模板。如果你只是个人写点小脚本一个全局的~/.claude/CLAUDE.md就足够了。但如果你是多项目开发者每周在三个以上代码库里切换不想每个项目重复教模型同样的事情小团队负责人希望组内所有人使用 Claude Code 时行为基线一致而不是各调各的平台/基建方向想把 AI 编码工具纳入统一研发流程和 lint、CI、评审系统打通。满足任意一条claude-code-templates就值得投入。它本质上是把优秀工程师使用 Claude Code 的经验从个人脑子里搬到仓库里变成团队资产。这也是我后来才想明白的模板库不是写给模型看的是写给未来包括你自己在内的每一个开发者看的。2. 拆解模板库的核心模块CLAUDE.md、agents、skills、hooks2.1 CLAUDE.md项目级记忆与行为规范CLAUDE.md 是 Claude Code 最基础也最重要的记忆文件。它解决的问题很朴素模型每次启动时对当前项目一无所知你需要用一份文件把你是谁、这个项目是什么、规矩是什么讲清楚。我见过的最糟糕写法是照搬 README。CLAUDE.md 不是 README 的替代品它应该是一份写给模型看的工作手册核心内容我一般控制在四块项目定位与技术栈两三句话说清项目做什么、用的什么框架、关键目录是什么。常用命令与执行方式构建、测试、lint、单测分别怎么跑命令写死别让模型自己猜。架构与目录约定哪些目录绝对不能乱动、新增代码放哪里、命名是什么风格。质量底线与工作流改代码必须补测试、提交前必须过 lint、遇到某类问题要走到哪一步才能停。下面是一个我实际在用的精简示例# Project Memory ## What this project does A backend service for processing order events. Python 3.12 / FastAPI / PostgreSQL. ## Commands - Run tests: make test - Run lint: make lint - Start dev server: uvicorn app.main:app --reload ## Architecture rules - New business logic goes into app/services/, keep routes thin. - Never modify files under migrations/generated/. - Database queries should use SQLAlchemy 2.0 style. ## Quality bar - Every change that touches business logic MUST include a unit test. - Run make lint make test before finishing a task. - If an error seems infrastructure-related, stop and ask for confirmation before fixing it blindly.另外还要区分两个层级存放在~/.claude/CLAUDE.md的全局规则和存放在项目根目录的 CLAUDE.md。全局文件写你所有项目的共性习惯比如不要编造命令优先给出最小可执行方案项目文件才写这个项目的专属内容。把项目特有的东西塞进全局换了项目就全是噪音模型反而分不清优先级。2.2 agents把模型拆成专用角色CLAUDE.md 管的是默认状态下的行为但真实开发里需要模型切换角色。比如让它写测试时你希望它极端抠边界让它做 code review 时你希望它抓的是设计缺陷而不是格式问题。这些场景靠一个主对话上下文硬切效果时好时坏。agents子代理就是解决这个问题的每个 agent 是独立的上下文有独立的 system prompt、工具集和温度参数。在 Claude Code 里agent 文件放在.claude/agents/目录下基本结构是 YAML frontmatter 加正文说明。拿我最常配的 code-reviewer 举例--- name: code-reviewer model: claude-sonnet-4-5 tools: Read, Grep, Glob, Git_Status temperature: 0.2 description: Code reviewer that focuses on design issues, test coverage, and security. --- # Code Reviewer You are a senior engineer doing a thorough code review. ## Process 1. Read the diff and identify the core intent. 2. Check for correctness risks, security issues, missing tests. 3. Only report actionable issues; separate must fix from suggestion. 4. Output review comments in Markdown, grouped by severity. ## Tone Be direct and specific. Refer to concrete line numbers and symbols. No generic compliments.配置里有两个点特别值得关注。第一是tools一定要给最小权限——reviewer 不需要 Edit 和 Write给了它反而可能在 review 过程中偷偷改代码我踩过这个坑。第二是temperature做审查、测试这类确定性任务调低一些0.1~0.3更稳做头脑风暴类任务可以调高一点。不是所有 agent 都用最强模型简单的分类任务用小模型省成本跑得快但代码生成和审查我建议保留能力上限较高的模型。2.3 skills把能力做成可插拔技能skills 和 agents 经常被搞混。我的理解是agents 是角色skills 是流程。agent 控制系统里谁来干skill 定义怎么干。一个 skill 通常是放在.claude/skills/skill-name/SKILL.md下的一组说明文件Claude Code 会在需要时根据 description 自动加载也可以被显式调用。一个 SKILL.md 的典型结构--- name: tdd-iteration description: Use when implementing a new feature with test-driven development ---正文部分我会写完整的执行流程先写失败测试→跑测试确认失败→实现最小逻辑→跑测试确认通过→重构→提交。如果某个技能需要多次执行我会把关键约束提炼成清单# TDD Iteration Skill ## Steps 1. Add a failing test describing the behavior you want. 2. Run make test and confirm the new test fails. 3. Implement the minimal code to make it pass. 4. Run the full test suite; no unrelated failures allowed. 5. Refactor while keeping tests green. ## Constraints - Never skip step 2. - If a test passes before implementation, the test is probably wrong. Stop and rethink.什么内容值得做成 skill标准是这套流程在你的项目里会被反复用到并且每一步顺序和判断标准都很明确。比如新人接手某个微服务时的排查流程、上线前的检查清单、数据库迁移的评审步骤。流程类型的东西写成 skill 后模型每次执行都更不容易漏步骤。它和 agent 不是竞争关系而是配合关系——一个 agent 可以声明自己会调用某个 skill。2.4 hooks给关键节点加防护栏模板库如果没有 hooks等于只教了模型该怎么做却没设置做错了怎么办。hooks 是在 Claude Code 的特定事件节点触发的外部脚本或命令常见的有PreToolUse工具调用前、PostToolUse工具调用后、Stop模型生成结束。hooks 写在.claude/settings.json里。下面是个实际例子我在PreToolUse阶段拦截对package-lock.json的自动修改{ hooks: { PreToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: bash ./scripts/guard-lockfile.sh, blocking: true } ] } ] } }matcher决定了哪些工具调用触发这个 hook。最常见的问题是 matcher 写得太宽比如直接用matcher: Bash想拦所有命令结果正常执行git pull也被脚本拦下来。我的经验是新写的 hook 先用非阻塞模式blocking: false记录日志观察一段时间没有误伤再改成阻塞。这跟灰度发布的思路一样。另外要记住 hooks 是给关键节点设防不是给所有操作加锁。每加一个 hook就是给模型多一道行政手续加多了模型速度会明显变慢团队的怨气也会涨上来。模板库里 hooks 的最佳数量是少而准一两个安全护栏一两个审计记录足够了。3. 搭建一套可复用的模板库目录设计与一条龙落地步骤3.1 我目前用的主目录结构模板库本身的目录结构我调整过三次现在长这样claude-code-templates/ ├── common/ │ ├── CLAUDE.md # 全局通用规则复制为 ~/.claude/CLAUDE.md │ ├── agents/ │ │ ├── code-reviewer.md │ │ ├── test-writer.md │ │ └── docs-architect.md │ └── skills/ │ └── tdd-iteration/ │ └── SKILL.md ├── hooks/ │ ├── guard-lockfile.sh │ ├── log-tool-calls.sh │ └── settings.sample.json ├── project-scaffold/ │ ├── CLAUDE.md.tpl # 项目级模板含占位符 │ └── agents/ # 项目可选 agent └── scripts/ ├── init-new-project.sh # 一键铺设到新项目 └── sync-from-template.sh # 模板更新后同步差异common/下放所有项目通用的配置project-scaffold/放业务项目才需要的骨架hooks/放脚本和配置样例scripts/放自动化脚本。这样的好处是边界清楚通用和专用分开脚本和配置分开后面做版本回滚也容易定位。3.2 用脚本把模板铺到新项目最开始我是手动复制文件复制了三个项目就受不了了——总会漏掉某个 agent或者忘记更新 hooks 配置。后来写了个简单的初始化脚本核心逻辑是把common/和project-scaffold/的内容复制到新项目同时用占位符替换项目名和描述。#!/usr/bin/env bash set -euo pipefail PROJECT_DIR${1:?Usage: init-new-project.sh project-dir} PROJECT_NAME$(basename $PROJECT_DIR) mkdir -p $PROJECT_DIR/.claude/agents $PROJECT_DIR/.claude/skills install -m 644 common/CLAUDE.md $HOME/.claude/CLAUDE.md install -m 644 common/agents/*.md $PROJECT_DIR/.claude/agents/ install -m 644 hooks/settings.sample.json $PROJECT_DIR/.claude/settings.json sed s/__PROJECT_NAME__/$PROJECT_NAME/g \ project-scaffold/CLAUDE.md.tpl $PROJECT_DIR/CLAUDE.md echo Template installed in $PROJECT_DIR你可能会问为什么不直接用符号链接我试过结论是模板库和项目文件必须用复制不要用链接。原因是项目里的 CLAUDE.md 和 agents 经常会根据项目情况做本地修改如果它们是链接模板一更新项目里的个性化配置就被悄悄覆盖了。复制则天然隔离保留了项目的自适应空间。但复制也有代价模板更新后老项目不会自动跟上。所以我写了sync-from-template.sh它不做暴力覆盖而是用 diff 生成差异清单让我逐个确认哪些更新要合并进项目。这个脚本本质上就是一个模板升级的 PR 流程避免更新模板库变成一次破坏性事故。3.3 把模板纳入项目初始化流程到这一步模板库已经从个人收藏夹变成了项目脚手架的一部分。再往前走一步就是和团队的初始化流程打通。我们的做法是在新仓库创建时固定走一遍运行init-new-project.sh铺好基础配置。把模板库以git submodule或普通目录的方式挂进项目参考文档方便模型查阅模板来源。在 README 里写清楚改模型配置前先看模板库是否已有约定。模板库自身的版本管理也很重要。我给它打语义化版本 tag比如v1.2.0每次变更都写 CHANGELOG。不要觉得这是过度工程——当你同时维护五六个项目并需要回答为什么 review agent 的行为变了时版本和变更记录能帮你省好几个小时。4. 模板真正落进项目时的配置细节与常见坑4.1 CLAUDE.md 越长模型就越选择性记忆第一次搭模板库时我犯的错误是追求全面什么规则都往 CLAUDE.md 里塞最终一份文件写到了五百多行。结果模型的行为不但没有更规范反而开始出现这次记住、下次忘掉的随机表现。原因不复杂上下文有限模型会倾向于关注更靠近当前位置、更频繁出现的信息而一份五百行的文件会让关键优先级被淹没。后来我做了两件事效果立竿见影。第一是压缩把 CLAUDE.md 砍到一百五十行以内用短句和清单只留真正会被高频使用的规则。原来详细的技术方案挪到docs/下需要时让模型去读而不是塞进初始上下文。第二是分层根目录只放全局共识子目录如果有特殊规则比如frontend/下的样式强约束就在子目录放局部 CLAUDE.md避免全局文件膨胀。这和人脑的工作记忆是一个道理你要的不是让他背一本百科全书而是给他一份高频速查卡。4.2 hooks 的误伤事件一次真实的前车之鉴有一次我往模板库里加了一个自以为很聪明的 hook在所有Bash命令执行前检查如果命令包含git push就弹出确认。上线当天下午队里一个同事来吐槽Claude Code 每次跑完测试要自动提交推送结果连续被拦整个任务直接卡死。复盘原因我在settings.json里写的matcher是Bash于是只要是走 Bash 工具执行的命令无论它是不是git push相关全部经过确认脚本脚本里又用了过于宽泛的grep -q git push把正常提交也拦下来了。这个问题在测试环境几乎测不出来因为你满脑子都是怎么拦截很少代入正常流程里它有多频繁被触发。现在模板库里的 hook 设计原则变成了matcher 尽量精确比如Edit|Write而不是Bash避免把所有命令都卷进来。脚本内部显式处理非目标命令立即退出返回 0绝不默认放行。先非阻塞运行一段时间用日志验证命中率再决定要不要开blocking。4.3 子代理的工具权限不是越多越好给 agent 配tools时我最开始是有什么给什么code-reviewer 也给了 Edit、Write、Move看起来是让它更全能。结果有一次它 review 到一半直接动手优化了一段代码把业务变量名改成了自己觉得更优雅的写法还自信地留下了 summary。这提醒了我agent 的工具权限就是它的权力边界给得越宽失控的破坏半径越大。现在的模板库对 agent 权限做模板化限制角色tools是否允许写代码预期产出code-reviewerRead, Grep, Glob, Git_Status否review 意见不产生 difftest-writerRead, Write, Grep, Glob是仅限测试文件新增/修改测试代码docs-architectRead, Write, Grep是仅限 docs/技术文档和流程图这里还有一个细节如果你在模板库里定义了多个 agent记得在 description 里写清楚什么时候该选它。因为模型判断要不要用某个子代理靠的正是这段描述。描述写得太模糊模型可能永远不触发它写得太宽模型又可能什么任务都交给它。4.4 模板更新后旧项目的配置跟不上了怎么办这是模板库规模化之后最头疼的问题。新项目用新模板老项目还停留在老配置模板更新过几版之后老项目的模型行为和新项目明显不一致。解决这个问题的核心不是技术而是流程。我的经验是把模板更新当作一次普通但独立的开发任务先跑sync-from-template.sh生成差异报告然后人工审查每一项差异决定采纳、拒绝、还是本地保留。审查的时候特别注意如果项目里的某个规则是模板里没有的那可能是项目特定需求不要覆盖如果模板里的规则项目不需要也不要盲目引入。对多项目团队来说模板库的治理原则是通用部分大家看齐特殊部分各自保留二者通过 diff 显式区分。这个流程如果觉得繁琐也可以让 Claude Code 自己来干——我后面会展开讲。5. 模板库的进阶玩法工作流编排、跨项目回灌与自我维护5.1 把模板当做可组合的指令集来编排工作流当 CLAUDE.md、agents、skills 各自稳定之后模板库的另一层价值才真正体现出来它变成了可组合的指令集能编排完整工作流。举个例子我们处理一个普通的功能需求时一条完整链路可能是主模型根据项目 CLAUDE.md 读取需求并产出实施计划调用plan-revieweragent 对计划做一轮批判性检查进入tdd-iterationskill按红-绿-重构循环实现提交前由code-revieweragent 审查 diff最后由 hooks 里的Stop事件触发收尾检查确认测试结果和改动文件清单。这套流程不需要写任何外部编排代码它完全靠模板库里的组件被按需触发来运转。每个组件单独看不复杂组合起来就像给模型装了一条流水线。模板库真正厉害的地方也正在于此它让复杂工作流的每个环节都有了可替换、可升级的标准件。5.2 从业务项目往模板库回灌经验模板库不能只靠初始设计它必须持续吸收业务项目里验证过的优秀配置。我们有过一个很典型的案例某个项目因为线上事故频发在 CLAUDE.md 里加了一条改到时间处理逻辑必须额外补充时区测试的规则连续两个月没有重复事故。当时其他项目没有这条规则同样的问题完全可能再犯。所以我把规则提炼成通用表述如果业务代码涉及时间、金额、状态机修改时必须补充对应边界测试然后加进模板库。这就是经验的回灌项目里新产生的有效规则经过提炼和去业务化沉淀回模板库再扩散到所有项目。需要注意的是回灌之前一定要做通用性审查把项目特有的路径、名称、背景全部剥掉只留下所有同类项目都成立的行为约束。5.3 让 Claude Code 自己当模板库管理员模板库维护到后面琐碎工作越来越多检查哪些 skill 已经没人用了、确认几个 agent 的 description 是不是过时、审计 CLAUDE.md 里有没有互相冲突的规则。这些事完全可以交给 Claude Code 自己干。我建了一个audit-templateagent专门负责定期审阅模板库。让它干三件事检查各 skill 的 description 是否和当前使用场景匹配找出 CLAUDE.md 和 agents 之间互相矛盾的规则统计 hooks 脚本的命中日志标记长期零命中的冗余项。你甚至可以在 hooks 里加一个轻量统计每次 skill 被调用就追加一行日志。积累一段时间之后对哪些技能是高频的、哪些是死代码就有数据支撑了。模板库的版本迭代也从我拍脑袋想改哪变成了模型审计加人工决策。最后说一个我自己的体会claude-code-templates越到后期越不像一个AI 配置仓库而是像一个团队的开发方法论仓库。那些 CLAUDE.md、agents、skills、hooks 不是写给模型看的冰冷文件它们是整个团队过去一年踩坑、复盘、验证后的经验结晶。模型只是执行者真正让它表现稳定的是你愿意花多少功夫把你们怎么干活这件事讲清楚。这个仓库最值钱的地方从来不是那几个模板文件本身而是沉淀它们的过程——这个过程一旦跑起来后续每一个新项目、每一个新同事都在为它持续加分。