Claude Code 模板库全解析：从规则配置到 AI 辅助开发工作流

如果你和我一样每天要在终端里跟 Claude Code 打交道大概率会经历这样一个阶段先是被它那种惊人的完成度惊艳到然后开始反复输入几套固定的提示词——“按项目规范写代码”“给这次改动生成测试”“帮我审视这段逻辑有没有隐患”。等你把同样的指令打到第三遍你会意识到一个事实真正该被模板化的不是代码而是这些被打断的脑回路。所以我做了claude-code-templates这个项目。它不是某个单一配置文件而是一整套可以直接搬进 Claude Code 工作流的模板资产覆盖项目级规则、斜杠命令、子代理、钩子脚本四个维度。这篇文章会把它的设计思路、关键配置、接入步骤和踩坑记录全部拆开给想要把自己的 Claude Code 用法体系化、或者正在纠结“为什么我的 Claude Code 不够听话”的开发者一个可以直接抄作业的参考。1. 先别急着写代码Claude Code 模板到底解决什么问题1.1 从“每次重新调教”到“一次配置终身复用”的转变我见过不少团队用 Claude Code 的方式相当原始不加 CLAUDE.md不配自定义命令每次对话都靠现场口述项目背景、代码规范、技术栈细节。第一批需求确实能完成毕竟模型底子够好。但用到一个星期后大家都会撞上同一堵墙——同样的背景信息每次都要重讲一遍而每次讲的版本还不一样。今天心情好就多说两句设计模式明天赶进度就一句“按项目风格写”草草带过。结果就是 AI 产出的代码质量完全取决于你当时的口条清不清楚这显然不靠谱。模板体系的第一个价值就是把那些“每次都要重复交代的东西”固化下来。我在claude-code-templates里用一份 CLAUDE.md 统一管理项目的人格、约束和默认工作流。新项目只需要把这个文件搬进去再改掉项目专属字段Claude Code 就能在每次对话中自动加载这些背景不需要你张嘴。第二个价值是把高频操作做成固定入口。比如 code review、生成单元测试、写 commit message这些操作我全部做成了斜杠命令一行/review就能触发。命令内置了完整的执行步骤、输出格式、质量门槛不用每次临时设计提示词也不怕漏掉某个审查维度。1.2 不是“套提示词”而是“定义协作协议”很多第一次接触模板的人会误会觉得这不就是把几个还不错的提示词存成文件吗其实差得很远。提示词是给模型的“一次性指令”而模板是给整个协作流程定义的“协议”。举个最直接的例子一份写在 CLAUDE.md 里的“单次改动不要超过 300 行”是规则但只有规则还不够。在模板库里我会配套一个plan命令一旦估算改动规模超过阈值就自动触发先写重构计划、再动手改代码的流程。规则、命令、子代理三者互相咬合形成一个完整的闭环。我在设计claude-code-templates时的核心思路就一句话与其每次祈祷模型“理解到位”不如把上下文、流程和边界条件都变成可持续维护的工程资产。模板化了之后你投入在“怎么跟 AI 说话”上的时间是一次的之后每一次调用都在摊薄这笔成本。2. 模板库的骨架目录结构、命名规范与设计取舍2.1 仓库目录结构每个文件负责一类事整个模板库的目录结构是经过几轮调整后才定下来的现在的形态非常克制claude-code-templates/ ├── system/ │ ├── CLAUDE.md # 全局工作协议覆盖所有项目 │ └── project-template.md # 新项目的 CLAUDE.md 模板占位符版 ├── commands/ │ ├── review.md # 深度代码审查命令 │ ├── test.md # 单元测试生成命令 │ ├── refactor.md # 重构任务命令 │ ├── commit.md # 提交信息生成命令 │ ├── plan.md # 改动计划命令 │ └── docs.md # 文档同步命令 ├── agents/ │ ├── reviewer.md # 代码审查子代理 │ ├── test-engineer.md # 测试开发子代理 │ └── architect.md # 架构评审子代理 ├── hooks/ │ ├── auto-lint.yaml # 文件写入后自动检查 │ └── pre-commit.yaml # 提交前校验 └── README.md这个结构的划分依据很简单按触发方式和使用频率切分。系统级规则CLAUDE.md 和 project-template.md是你希望模型“无时无刻都知道”的背景commands 是高频、主动发起的操作agents 是低频但需要专业深度介入的任务hooks 则是希望模型自动触发的流程。分开维护的好处是修改某一类不会影响到其他部分。2.2 命名规范里藏着易用性的门道命令文件名就是斜杠命令名所以命名必须短、直白、无歧义。我踩过一个坑早期我把代码审查命令命名为deep-code-review看起来挺严谨结果每次敲命令都要多打七个字母而且容易打错。后来统一改成单动词形式review、test、refactor、commit、plan、docs。文件后缀统一用.md因为 Claude Code 的原生命令格式就是 Markdown 文件可以用frontmatter写描述信息。以review.md的开头为例--- description: 对当前分支的改动做一次多维度审查 --- 请对当前分支的 git 改动执行以下审查流程 1. 读取 git diff --stat 和 git diff 输出明确改动范围 2. 按正确性、安全性、性能、可维护性、测试覆盖五个维度逐项分析 3. 对每一个发现的问题给出文件路径、行号、问题说明、修改建议 ...description字段会出现在命令提示里所以它不只是写给模型看的功能描述更是写给使用者看的“这命令能干嘛”。选词上要尽量让第一次接触仓库的开发者看到描述就能判断该不该用。2.3 一个关键设计取舍全局模板 vs 项目模板模板库里做了两级模板的区分这是很多同类项目没想到的地方。system/CLAUDE.md是全局行为准则我会在里面定义所有项目通用的规则比如“不要在没有验证的情况下删除用户数据”“修改公共接口前先列出所有调用点”“单次输出代码块尽量控制在 300 行以内”。这类规则不依赖具体技术栈放进全局生效。但每个项目的技术栈各不相同全局模板写得太多反而会干扰模型对当前项目上下文的判断。所以又设计了system/project-template.md它是给新项目用的骨架里面有占位符比如{{PROJECT_NAME}}、{{TECH_STACK}}、{{TEST_COMMAND}}。新建项目时复制一份替换占位符二十分钟就能得到一个完全贴合项目的上下文文件。这个两级设计解决了“模板库本身不能太霸道”的问题。如果你直接抄一份功能完整的全局 CLAUDE.md 到自己的项目里它大概率会和项目现实打架——模板里要求用 pytest但你的项目是 jest。分级之后通用规则进全局项目专属信息进项目模板各管各的互不污染。3. 三份核心模板的完整拆解从提示词到可复用资产3.1 CLAUDE.md 项目规则模板把团队口头约定变成显式规则CLAUDE.md 是整个体系中优先级最高的文件。我见过不少人写过 CLAUDE.md但大部分都写得像产品需求文档长篇大论模型加载之后上下文里全是废话。这个文件的价值不在于字数而在于每条规则是否能在实际协作中被执行。我的project-template.md只保留四类内容每类都极其克制# 项目角色 你是一名参与 {PROJECT_NAME} 开发的全栈工程师需要兼顾架构合理性、 代码可维护性和业务需求的快速落地。 # 技术约束 - 前端框架{FRONTEND_FRAMEWORK}样式方案{CSS_SOLUTION} - 后端框架{BACKEND_FRAMEWORK} - 禁止新增大型依赖除非在计划阶段明确说明理由 - 所有对外接口必须附带 OpenAPI 描述 # 工作流要求 - 改动超过 300 行时先输出实施计划不要直接写代码 - 每个功能实现后必须同步更新对应测试 - 错误处理统一使用 {ERROR_HANDLING_STYLE} 模式 # 完成定义Definition of Done - 所有测试通过命令{TEST_COMMAND} - 代码通过 lint 检查命令{LINT_COMMAND} - 不残留 debug 日志和临时注释注意这里没有任何“请做一个好工程师”这种正确的废话每条规则都可能被模型在某个具体动作中触发。我在设计时参考了团队里 Code Review 时最常提出的意见把它们前置成了规则。3.2 review 命令与 reviewer 子代理审查的层次感审查类任务我做了两个层级/review是执行级审查针对当前改动的 diff快速、聚焦reviewer子代理是架构级评审针对整个文件或模块输出更宏观的改进建议。两个层级在提示词设计上有本质差异。/review命令要求模型“你是此次代码审查的执行者”直接读取 diff按维度给出清单结果--- description: 对当前改动做多维度代码审查并输出问题清单 --- 你对当前分支的 git diff 做交互式审查 1. 先查看 git diff --stat再逐个文件查看 diff 2. 对每个问题按 P0/P1/P2 分级 - P0可能导致线上故障或安全漏洞 - P1影响功能正确性或有明显性能风险 - P2代码风格、可维护性建议 3. 输出格式 - 【级别】文件路径:行号 - 问题描述 - 修改建议 4. 全部问题列出后汇总一个 200 字以内的总体评价而reviewer子代理的定义则完全不同。它在.claude/agents/reviewer.md里通过 frontmatter 声明自己的角色和描述--- name: reviewer description: 模块级别的架构评审专家适合在改动较大时使用 tools: Read, Grep, Glob --- 你是一名有 15 年经验的架构评审专家。当被要求评审某个模块时 1. 先读取该模块的入口文件梳理模块的整体结构 2. 画出数据流和依赖关系用文字描述禁止用图 3. 重点检查模块边界是否清晰、是否存在循环依赖 4. 对每个架构风险给出分级的重构建议 5. 最后用三段式输出现状分析、风险清单、改进路线之所以把这两个分开是因为消费场景完全不同。日常迭代只需要快速定位 diff 的问题用/review就够了但当一个模块积累了足够多的小改动需要整体审视它的结构是否还健康时就应该交给角色更专业的reviewer。层次感清晰之后模型不会在轻量任务里输出大量不必要的架构建议也不会在大评审时停在表面问题上。3.3 test 命令和 test-engineer 子代理让测试工作流化测试生成是我试用过最多提示词的一个场景。早期我直接说“帮我写测试”输出结果基本没法用——生成一堆 trivial 样例全是对实现过程的复述而不是对行为的验证。后来我把测试生成的提示词重构成“先理解再设计后实现”的三段式。/test命令要求模型先读取被测文件和相关依赖然后输出一份测试计划列清楚要覆盖的正常路径、边界条件、异常分支用户确认后才写具体代码--- description: 为指定文件生成单元测试 --- 针对 {TARGET_FILE} 生成单元测试 1. 先读取目标文件及它直接依赖的模块分析输入输出契约 2. 列出测试计划覆盖的正常路径、边界条件、异常情况 3. 等待用户确认测试计划后再编写测试代码 4. 测试代码遵循以下约束 - 测试用例命名格式test_[被测场景]__[期望行为] - 禁止模拟被测模块自身的行为 - 每个测试只设置一个核心断言组 5. 生成后给出运行方式test-engineer子代理的定位更偏向“测试设计顾问”。当我接手一个老项目测试基础设施很差时我会直接问它“看看这个项目的测试现状给出基础设施的改进方案。”它能读取项目结构、分析现有测试覆盖情况然后从测试金字塔、可测试性改造、优先级排序等维度输出建议。这里有一个经验测试生成的准确性高度依赖于模型对项目上下文的掌握程度。模板命令里强制要求模型先列出测试计划再动手就是在给模型一个“先充分理解再输出”的缓冲过程。加了这一步之后测试代码的可运行率提升得非常明显。4. 把模板库接进日常工作流的完整操作演示4.1 第一步用两周时间验证全局 CLAUDE.md 的规则颗粒度拿到模板库之后不建议直接全量铺开。我建议先只引入system/CLAUDE.md在自己的主力项目里跑上两周验证每一条规则的实际效果。为什么因为全局规则一旦写得太粗会到处都不疼不痒写得太细又会在不需要的场合打断模型的工作节奏。我的system/CLAUDE.md里有一条规则经历了反复调整“修改超过 300 行先输出实施计划”。最初我定的阈值是 100 行结果每次改个样式都要先写一堆计划烦不胜烦。后来调到 500 行又发现确实有些 400 行的改动牵扯到多个模块省略计划直接动手容易跑偏。最终稳定在 300 行这个阈值在实际项目中属于“比较大的改动”和“常规改动”之间的一个合理分界线。验证两周之后再继续引入 commands 和 agents。分批导入的好处是如果某个规则有问题你能比较精确地定位到是它的锅而不是一堆新元素混在一起分不清责任。4.2 第二步把模板文件拷进项目的正确位置Claude Code 读取模板文件的路径有讲究。命令放在.claude/commands/目录下子代理放在.claude/agents/目录下而项目级 CLAUDE.md 放在项目根目录。如果你希望某些命令只在特定项目生效就放项目下的.claude如果希望全局所有项目都能用则放在用户主目录的.claude下。以导入review命令为例# 全局导入对所有项目生效 mkdir -p ~/.claude/commands cp commands/review.md ~/.claude/commands/ # 项目级导入仅当前项目生效 mkdir -p .claude/commands cp commands/review.md .claude/commands/子代理的导入方式类似mkdir -p ~/.claude/agents cp agents/reviewer.md ~/.claude/agents/项目 CLAUDE.md 的导入有点不同。system/CLAUDE.md是全局规则放在~/.claude/CLAUDE.md而project-template.md需要复制为项目根目录下的CLAUDE.md并且替换掉里面的占位符。4.3 第三步完整跑一次“审查-修改-测试”闭环光讲配置不演示流程等于白讲。我拿一个实际的例子走一遍假设我在一个 Python 项目里刚给某个 API 加了一个分页参数想用这套模板库完成一次完整的闭环。先在终端运行/reviewClaude Code 读取当前 git diff输出审查结果 【P1】app/routes/users.py:42 - 分页参数 page_size 未做上限校验 恶意请求可传入极大值导致数据库全表扫描建议限制为 1-100 【P2】app/services/user_service.py:81 - SQL 查询未使用参数化绑定 存在 SQL 注入风险建议改用 ORM 的查询构建器 【P2】app/models/user.py:15 - 新增字段缺少注释说明看到两条 P1 和一条 P2我直接说“把 P1 和 P2 都修掉按建议改但保持对外接口兼容”。模型会自动读取相关文件并进行修改改完会主动执行一次 lint 和新增测试。这时再跑/test指定目标文件app/services/user_service.py。模型先输出测试计划、等待我确认然后生成测试代码。测试跑完之后我执行/commit让模型生成符合项目规范的提交信息整个闭环就完成了。整个流程中我只需要操作三次斜杠命令、做一次修改确认剩下的事情全部由模板驱动的流程自己完成。第一次跑通的时候我最大的感受是Claude Code 终于不再像一个需要随时盯着才能干活的实习生而更像一个按标准作业程序执行的老手。5. 跑了两周后我踩过的坑和对应的规避方案5.1 全局规则太“重”导致模型频繁跑偏用上模板库的第二周我开始觉得 Claude Code 的输出变“重”了——明明只是改一个按钮的颜色它也要先输出一段计划再动手。原因是全局 CLAUDE.md 里的规则太多了模型在任何一个简单任务里都在刻意迎合规则反而忽略了任务本身。这个问题的根源不在模板库而在使用方式全局 CLAUDE.md 里的每一条规则都应该和“项目的生死存亡”有关而不是和“代码风格偏好”有关。我把一部分偏向特定技术栈的规则从全局搬到了项目模板全局只保留真正的底线规则比如“必须验证任何删除操作”“不要在未明确用户意图时修改公共 API”。规则数量也从二十多条减到了八条。减量之后模型的输出明显更轻快同时底线规则依然被严格遵守。5.2 命令模板里的变量不生效浪费了半小时Claude Code 的命令文件支持变量注入比如{TARGET_FILE}这类占位符会在调用时被替换成实际参数。我早期在/test命令里写了{TARGET_FILE}以为是万能变量结果运行的时候模型报告说找不到目标文件。排查之后才发现变量注入依赖调用时的参数传递。如果用户只是敲了/test而没有附加文件名参数变量实际就是空的。后来我在命令模板里补了一层 fallback 逻辑如果{TARGET_FILE}为空就默认审查 git diff 中涉及的文件。这既保证了命令能用又保持了灵活性。5.3 hooks 把上下文吃掉了自动执行也要设边界hooks 是 Claude Code 里最强大的自动化能力也是最容易失控的。我配了一个PostToolUse钩子每次文件写入后都自动跑一遍 lint。听起来很美好实际跑起来灾难——每改一个文件模型都要额外启动一次 lint 子进程连续改十几个文件就卡得要命而且 lint 输出占用了大量的上下文空间把本来用于理解代码的上下文挤掉了。后来我改成只对特定文件类型、特定操作触发 hook并且给 hook 加了“静默失败”的容错lint 失败时只记录问题摘要不把完整报错堆栈塞进对话。这个边界画清楚之后hook 才真正从干扰项变成了守门员。这里给大家一个实操建议hook 的触发条件要窄动作要轻反馈要短。宁可漏掉一次自动检查也不要让自动化流程喧宾夺主。5.4 子代理的工具授权不足导致评审质量打折我第一次用reviewer子代理评审一个模块时输出结果非常空洞翻来覆去都是“建议增强模块内聚性”这样的套话。查了日志才发现这个子代理的工具列表里没有配Grep和Glob它只能靠Read一个个读文件根本没法高效地理解模块的调用关系自然给不出有信息量的建议。这是模板库里特别容易被忽视的一个坑。定义 subagent 时tools字段决定了它能用哪些工具而工具集直接决定了它能完成什么级别的任务。评审类任务至少需要Read、Grep、Glob三件套缺了 Grep 就等于让审计员没有显微镜。5.5 不同项目的命令互相打架第三个坑来自多项目切换的体验。我一开始把命令全放在全局目录下本来想着省事。结果在两个技术栈完全不同的项目之间切换时/test和/commit的行为就有了明显差异因为全局命令模板里硬编码了一些只在某个项目中适用的规范。解决方式是把所有技术栈相关的命令下沉到项目.claude/commands/目录下全局只保留像/review、/docs这类与技术栈无关的通用命令。这样每个项目内部的命令行为稳定跨项目之间也不会串味。6. 模板库的日常维护与后续演进方向6.1 把模板当代码来维护版本标签与更新日志模板库不是一锤子买卖它需要持续演进。我现在的维护方式是把它当成一个真实的代码仓库来管每一次大版本调整都打一个 tag比如我整理出v1.0这个初始版本之后每次有结构性变化就升小版本。每条规则或命令的修改记录都写进更新日志这样你引入一个旧版本模板后能清楚地知道新版本改了什么、为什么改。我印象最深的一次变更是我把 review 命令从“一次性输出全部维度”改成“分维度逐步推进”。原因是模型一次性输出所有维度的审查结果时后面的维度往往流于形式而逐步推进能逼迫模型在每个维度上都给出足够深度的分析。这个改动可以直接从更新日志里追溯到原因。6.2 吸收团队复盘会里的高频问题模板库维护最大的灵感来源不是别人的模板而是自己项目的复盘。每次 Code Review 或者线上事故复盘时我会把高频出现的问题记录下来然后思考“这个问题能不能通过模板规则或命令来预防”。比如有一次线上事故是因为环境配置差异导致的我就在测试命令模板里加了一步“优先读取 CI 配置中的环境变量而不是假设本地默认值”。这种从实践里长出来的规则比任何教科书上的模板都更贴合实际项目。这也是为什么我在使用说明里特别强调模板库应该是你项目实践的显式化而不应该反过来让项目去迁就模板。6.3 值得尝试的扩展方向最后聊几个我打算继续探索的方向给有兴趣的读者一些思路。第一个方向是多 Agent 协作的模板化。现在agents/目录下的子代理是独立工作的下一步我想做一套固定流程让architect、reviewer、test-engineer以流水线方式依次介入一个大型改动形成一个人工可控的“AI 团队作战手册”。第二个方向是把这个模板体系推广到团队所有成员。每个人都维护一份自己的全局 CLAUDE.md 通常会导致行为和风格的分裂。团队落地可以统一维护一个团队级 CLAUDE.md成员之间通过版本控制协作让 AI 的“行为基因”在团队内保持一致。第三个方向是结合 CI/CD 做更细粒度的质量门禁。当前 hooks 只做了写入后的 lint 检查实际还可以扩展出测试覆盖率阈值检查、依赖安全审计等更硬性的门禁。那样的话模板库就不只是提升 AI 生产力了它同时是质量防线的一部分。说实话claude-code-templates最开始只是我个人的“偷懒工具”但维护到现在它的意义已经远超偷懒。每次新增一条规则我都要想清楚它是不是真的值得被所有项目继承每次重构一个命令我都要考虑它在未来半年会不会依然有效。这个过程反过来也在逼着我更清晰地理解自己到底是怎么做开发的。如果你也想整理一套自己的 Claude Code 模板我的建议是从最小闭环开始先写一份只包含十条以内硬规则的全局 CLAUDE.md再配一个/review命令跑两周。等你习惯了这种“规则先行”的工作方式再慢慢往上加东西。别急着一步到位模板是长出来的不是拼出来的。