Claude Code模板体系：打造可复用的AI编码工作流

聊到claude-code-templates先说说我自己的经历。最初接触 Claude Code 时我完全没考虑模板这回事每次干活都是在命令行里现场敲提示词今天让 AI 做代码审查明天让它写测试后天让它重构模块。结果就是同一个项目里AI 的行为风格一天一个样有时候它太啰嗦有时候又太沉默该限制的工具没限制不该让它动的文件它反而动了。直到我把整套 prompt、命令、子代理、钩子规则沉淀成模板库才真正把 Claude Code 从一个聪明的对话窗口变成了一个符合我团队习惯的虚拟结对程序员。这篇文章想写的就是这套claude-code-templates模板体系它包含哪些文件、每个文件解决什么问题、怎么从零搭建并复用、多项目怎么同步以及我在实际使用中踩过的坑。不管你是刚接触 Claude Code 的新手还是已经用了一段时间但觉得差点意思的老手这套模板思路都能帮你把 AI 编码工作流固定下来减少重复调教也减少意外破坏。1. 模板体系到底在解决什么问题1.1 没有模板时的工作流痛点我见过太多人用 Claude Code 的方式是裸奔装好命令行工具直接在会话里说帮我看下这个项目。工具确实很聪明但有两个绕不开的问题。第一个问题是上下文管理失控。Claude Code 默认会读取项目文件、git 状态、目录结构但如果项目里没有一份明确的说明文件它对业务规则、代码风格、目录约定的理解全靠猜。你可以在对话里反复纠正但新会话一开它又失忆了。第二个问题是权限和流程不可控。默认配置下AI 可能会尝试执行它认为合适的命令、修改它认为相关的文件而它认为和你认为之间经常存在一条很宽的裂缝。我自己踩过一个典型例子让 AI 修一个前端组件的小问题结果它顺手把 package.json 里的依赖升级了CI 直接红了一下午。问题本身不大但暴露了一个关键点——如果没有模板把哪些操作允许、哪些操作先问、哪些操作绝对禁止说清楚你再怎么在单次对话里强调下个会话还是会忘。模板的本质就是把一次性的口头约定变成项目里持久、可复用、可版本管理的显式配置。1.2 模板体系的核心组成一套完整的claude-code-templates核心是由四种文件组成的我习惯把它们称作四件套CLAUDE.md项目级说明书告诉 AI 这个项目是什么、代码组织方式、技术栈、常用命令、约定和禁忌。它相当于给 AI 的入职手册。commands 目录Slash Commands把高频任务固化成命令比如/review、/fix、/test。每个命令是一个 Markdown 文件里面写清楚触发后 AI 该做什么、按什么步骤做、输出什么格式。agents 目录Subagents定义角色化的子代理比如代码架构师安全审计员测试策略师。每个子代理有独立的人格和行为边界适合在复杂任务中并行分工。hooks 配置在关键事件上挂脚本强制流程。比如用户提交提示词时、AI 调用工具之前、AI 生成回复之后都可以触发脚本做校验或拦截。这四件套分别解决不同层次的问题CLAUDE.md 管背景和记忆commands 管高频操作的标准化agents 管复杂任务的角色分工hooks 管流程的安全兜底。1.3 模板复用的设计原则在动手写模板之前我建议你先想清楚一条原则模板是给 AI 看的代码不是给人看的文档。这句话有两层意思。第一模板内容要有明确的指令性。你写项目使用模块化架构远不如写新增业务代码请放到src/modules/下每个模块包含controller/、service/、dao/三个子目录有用。第二模板要尽量短小、可执行。AI 处理冗长文本时也会注意力稀释写一大堆背景介绍不如直接给它一份目录结构图和三条操作硬规则。另外我强烈推荐把模板库当成代码来维护放进 git 仓库写 commit做版本管理。我甚至会单独建一个templates仓库和项目代码分离然后通过软链接或脚本把模板分发到各个项目里。这样你升级模板时可以批量同步到所有项目。2. 核心文件逐个拆解2.1 settings.json先把权限和安全边界定死很多人容易忽略的一个事实是模板体系里最先应该写的不是 prompt而是权限配置。Claude Code 的权限逻辑通常由settings.json控制分项目级和用户级两层。项目级的放在.claude/settings.json用户级放在用户主目录下的.claude/settings.json。用户级适合放通用规则项目级适合放这个项目特有的边界。我建议至少关注这几个配置项permissions.allow允许 AI 直接执行的操作白名单比如Read、Edit、Bash(npm run lint:fix)。注意白名单越短越安全。permissions.ask需要先询问用户的操作比如Bash(git push:*)、Edit(api/**/*)。permissions.deny绝对禁止的操作比如Bash(rm -rf *)、Edit(credentials.json)。model默认模型可以用model: sonnet或opus来控制复杂度和成本。env为 AI 设置环境变量比写在 shell 里更聚焦。所以哪怕你的 prompt 写得再漂亮只要权限配置不靠谱翻车是迟早的事。命令类的授权粒度要尽可能细。举例来说与其允许Bash(npm install)不如列清楚依赖锁定情况后再决定对于会写入全局状态的命令比如git push、docker compose up务必放进ask列表让 AI 每次执行前都跟你确认。2.2 CLAUDE.md给 AI 写一份高质量“入职手册”CLAUDE.md 是整个模板体系里性价比最高的一个文件但它也是被人误解最深的一个。它不是在写项目介绍而是在写AI 在这个项目里的行为准则。我的写法一般分成五段项目极简摘要用三五句话说明系统是什么、核心业务边界在哪、技术栈要点。命令速查列出开发中最常用的命令比如构建、测试、lint、启动 dev server、数据库迁移。格式是命令作用。目录结构约定不需要贴全部目录树只写关键的、AI 容易猜错的部分。例如src/api/下是路由定义src/services/下是业务逻辑两者不要互相直接调用。代码风格与架构规则这是真正的干货区。比如新代码使用 TypeScript 严格模式错误处理优先返回 Result 类型而不是抛异常数据库表结构变更必须附带迁移脚本。硬性禁忌明确列出 AI 不该做的事比如不要修改dist/目录下的产物不要在没有用户确认时执行git push不要升级第三方依赖的主版本。写 CLAUDE.md 时有个常见误区试图把所有信息都塞进去。实际上 Claude Code 对超长文档的处理是检索式引用的你塞得越多关键信息反而越不容易被触发。更好的做法是保持 CLAUDE.md 本身短小精悍把细节放进项目内的技术文档里然后在 CLAUDE.md 中写明遇到 X 类问题时先阅读docs/architecture.md。还有一个技巧CLAUDE.md 里可以用引用文件的方式把多个分散的说明合并进来但把最核心的规则放在最顶部。因为 AI 读取上下文时对前面的内容权重通常更高把最重要的禁忌清单放在文件头部效果比藏在文末好很多。2.3 Slash 命令模板把高频操作变成按钮CLAUDE.md 解决AI 懂不懂项目的问题Slash 命令解决的是AI 每次干活靠不靠谱的问题。它的思路和快捷键差不多把你反复做的操作固化成/命令名敲下去就不用再重复解释背景和期望了。Slash 命令在.claude/commands/目录下每个命令一个 Markdown 文件文件名就是命令名。文件头部有一段 YAML frontmatter里面可以定义命令的描述、可用工具、模型等元信息核心的description会被展示在命令列表里所以要写得一看就懂比如审查当前分支代码改动并生成审查报告。命令正文就是真正的 prompt它能接收到用户输入的参数。最常用的是$ARGUMENTS代表用户在命令后输入的完整参数。比如/review --focussecurity$ARGUMENTS就是--focussecurity你还以在 frontmatter 里声明参数提示让用户知道该填什么。我实际最常用的几个命令是/review让 AI 审查当前改动按正确性、安全性、性能、可维护性四层输出问题列表。/fix指定文件或错误信息让 AI 局部修复而非大范围重写。/test让 AI 为当前改动补测试输出可执行的测试代码并运行。/explain让 AI 解释一段代码的逻辑输出调用关系图和关键设计取舍。命令的价值在于把质量标准给固定下来。同样是写测试不同程序员心里的标准完全不一样。你在/test命令里写清楚必须包括正常路径、异常路径、边界值三类用例AI 每次执行都会遵守这个标准这就是模板比临时对话强的地方。2.4 Subagents给复杂任务配一个专业角色如果你发现单个 Claude Code 会话同时做架构设计、代码编写、安全检查会很累而且经常上下文混在一起出昏招那就该上 Subagents 了。Subagent 本质上是独立的子任务执行单元有自己的 context window、人设和可用工具工作时不会和主对话互相污染。定义方式是在.claude/agents/目录下建 Markdown 文件每个文件同样有 YAML frontmattername、description、tools、model。description很关键它是主模型判断什么任务该交给哪个 subagent的依据所以写作重点反而是这个 agent 适合处理什么、不适合处理什么。我目前模板库里常驻三个角色代码架构师负责梳理模块关系、评估重构方向、检查依赖隔离。我给它配置了Read和Grep工具但禁止它直接改代码。这样它能给出客观的评审意见而不会手痒去改文件。安全审计员负责检查代码中的注入、越权、敏感信息硬编码、依赖漏洞。它被允许跑Bash(git log *)和读安全相关文件但默认模型选更谨慎的版本。测试策略师负责分析现有测试覆盖率、指出高风险区域、生成测试计划。它生成的用例模版会交给主会话去落地。用 subagent 的最大好处是可以把不同角色的系统提示词彻底隔离。比如安全审计员的 prompt 会反复强调只报告问题不顺手修复禁止在报告中隐瞒高危风险这些约束在一个人格下能稳定执行但混在主对话里很容易被其他任务冲淡。如果你团队里的任务经常涉及多角色配合花时间做好 agents 是你回报最高的投入。2.5 Hooks把流程和安全规则变成强制约束无论模板文件写得多好、命令设计得多细总会有意外情况。Hooks 就是最后一道兜底防线它在关键事件点触发一段预定义脚本脚本会收到事件相关的 JSON 数据然后可以决定放行阻止修改AI 的行为。Claude Code 里常用的 hook 事件包括UserPromptSubmit用户在对话中提交消息前触发适合做敏感词检测或动态注入上下文。PreToolUseAI 准备调用任何工具前触发这是最常用的拦截点基本的安全检查都在这层做。PostToolUseAI 调用完工具后触发适合做文件变更后的 lint、格式化或状态记录。StopAI 生成完回复即将结束时触发可以在这里统一记录会话日志。举个我实际在用的例子。我在PreToolUse里挂了一个脚本匹配条件是Bash且命令中包含git push时直接返回 blocked同时给出提示推送操作请走团队代码评审流程。这个规则单独靠 CLAUDE.md 很难百分百生效因为 AI 一次没被阻止下次可能还会犯但 hooks 是程序级拦截说不行就是不行。再比如PostToolUse里我会监听Edit事件在 AI 修改完文件后自动跑一下prettier --check。如果格式不对就让钩子脚本给 AI 返回一个修正提示相当于给每次自动编辑加了个质量门。这个能力是纯 prompt 做不到的属于规矩写在代码里的典型场景。3. 实操从零搭建一套可复用的模板库3.1 目录结构和初始化我建议你在自己的电脑上建一个独立的模板仓库而不是直接在项目里开写。这样做的好处是可以在多个项目间复用也能单独做版本管理。我常用的目录长这样claude-code-templates/ ├── README.md ├── setup.sh # 一键分发/更新脚本 ├── user/ │ ├── settings.json # 用户级权限 │ └── agents/ # 通用 subagents │ ├── security-auditor.md │ └── code-architect.md └── project/ ├── CLAUDE.md.tpl # 项目说明书模板 ├── settings.json.tpl # 项目级权限模板 ├── commands/ # 通用 slash 命令 │ ├── review.md │ ├── fix.md │ ├── test.md │ └── explain.md └── hooks/ # hooks 脚本 ├── block-push.sh └── prettier-check.sh初始化时我会在用户主目录的.claude/路径下放置用户级文件和通用 agents再把项目级模板分发到各自项目仓库的.claude/目录。setup.sh做的事情很简单先检查.claude/目录是否存在不存在就创建然后把模板文件复制过去。我特意用软链接的方式处理 commands 目录这样模板仓库更新一个命令所有项目立即生效不用再手动同步。不过软链接在 Windows 上需要开启开发者模式团队里的 Windows 同事偶尔会踩这个坑所以我也会在脚本里处理权限问题。3.2 编写核心命令review、fix、test写 slash 命令最重要的原则是不要试图让 AI 理解你的意图要让它执行你的条款。拿/review举例我的命令文件大致是这样的--- description: 审查当前分支的全部代码改动输出分级问题清单 argument-hint: [--focus正确性|安全性|性能|可维护性] --- 你是一名资深代码审查者。请执行以下步骤 1. 运行 git diff HEAD~1 查看当前分支的完整改动。 2. 按以下四个维度逐一审查严禁跳项 - 正确性逻辑错误、边界未判断、资源未释放。 - 安全性注入风险、越权访问、敏感信息泄露。 - 性能明显低效的循环、不合理的 IO、缺失的缓存。 - 可维护性命名模糊、函数过长、重复代码。 3. 若用户通过 --focus 指定了维度则只审查该维度。 4. 输出格式为分级清单 - P0必须修复阻断合入 - P1强烈建议修复 - P2可与后续迭代合并处理 5. 如果所有维度都没有问题输出未发现需要阻塞合入的问题不许为了凑数硬找问题。这里有几个要点给 AI 设一个宁可漏报不可误报倾向能显著减少噪音步骤要明确到先跑什么命令再看什么避免 AI 凭感觉行动输出格式固定后续接 CI 解析或人工 review 都很方便。/fix的写法则完全不同它强调的是限定范围。我的命令里会先让 AI 复述它准备修改的文件清单经用户确认后才能动手。这个预确认机制非常管用因为 AI 最容易犯的错就是一修修一片。那种把 20 个文件的改动直接铺开的操作哪怕内容没错review 成本也高到吓人。/test命令我会把测试策略直接写进模板不追求覆盖率数字但规定每个新增或修改的函数必须覆盖正常路径、异常路径、空值/边界值。这三个词听起来简单但实际执行时 AI 的产出质量会有天壤之别。你手动写一遍这段命令后再对比一下没有命令时候的随意发挥会明显感觉到模板的价值。3.3 设计 subagent 角色模板Subagent 的设计难点不在 prompt 文采而在能力边界的设置。前文提到的安全审计员我最终的 agents 文件大概长这样--- name: security-auditor description: 执行安全审计。适合在代码合并前检查注入、越权、敏感信息泄漏、依赖漏洞等安全问题。不适合做常规代码风格检查。 tools: Read, Grep, Bash model: sonnet --- 你是一名独立的代码安全审计员。以下是你的行为准则 1. 只报告安全问题不要顺手修改代码。除非用户明确要求否则你给出的输出是问题清单而非补丁代码。 2. 审查重点包括 - SQL 注入、命令注入、路径遍历 - 越权访问缺少鉴权或权限校验 - 硬编码密钥、令牌、数据库连接串 - 使用了已知存在漏洞的依赖版本 3. 每个问题必须标注文件路径、行号倒推逻辑、影响等级高/中/低和修复建议。 4. 如果某项风险不存在明确写未发现禁止含糊其辞。 5. 你的输出会被直接贴进代码评审系统所以格式必须结构化。重点在于description里的不适合做部分这能防止主模型啥事都丢给它tools限定了它能读哪些信息防止它乱跑命令model的选择则关乎质量和成本的平衡安全审计这类任务对稳定性要求高用更好的模型回报也更明显。创建 subagent 后你还可以要求主会话调度它。比如 main 任务下Use the security-auditor subagent to review the auth module主模型就会自动委派。多角色并行时注意任务切分要足够独立接口一旦出现相互等待整个流程就会卡住。3.4 配置 hooks 做质量闸门Hooks 的实现和配置是模板体系里最像写代码的部分。以阻止 git push为例步骤是这样首先在项目.claude/settings.json中声明 hook{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: bash .claude/hooks/block-push.sh } ] } ] } }然后编写脚本核心逻辑是从 stdin 读取 JSON判断 command 里是否包含git push如果包含就返回带blocked标记的 JSON#!/usr/bin/env bash input$(cat /dev/stdin) tool_name$(echo $input | jq -r .tool_name) command_input$(echo $input | jq -r .command_input) if [[ $tool_name Bash $command_input *git push* ]]; then echo {\hookSpecificOutput\:{\hookEventName\:\PreToolUse\,\decision\:\block\,\reason\:\git push 不允许直接执行请走代码评审流程\}} exit 0 fi echo {\hookSpecificOutput\:{\hookEventName\:\PreToolUse\,\decision\:\allow\}}这块有两点值得注意。一是hook 事件触发频率很高PreToolUse 每一步都会触发所以脚本必须轻量不要写复杂的循环或网络请求否则整个 AI 响应会明显变慢。二是输出 JSON 格式必须精确一个字段拼错hook 就静默失败了而且往往没有任何报错。我调试时先用一个假样本手动把脚本跑通再接入 Claude Code效率会高很多。PostToolUse 还可以做更高级的事情比如在 AI 编辑完后自动编译相关模块把编译错误回传给 AI 继续修。这就形成了一条自动化的改代码-检查-修错闭环只要规则写得准整个循环就能跑得非常稳。不过要留个心眼这种循环容易导致 AI 反复试错不收敛所以一定要给 PostToolUse 的自动修正加次数上限超过次数就停下来人工介入。3.5 settings.json 权限模板设计权限模板必须和命令、hooks 配合否则命令写得再规范AI 也可能从旁路把事办了。我项目级的settings.json一般长这样{ model: sonnet, permissions: { allow: [ Read, Grep, Edit, Bash(npm run lint:fix), Bash(npm test), Bash(git diff *), Bash(git log *), WebFetch(api.github.com/*) ], ask: [ Bash(npm install *), Bash(git add *), Bash(git commit *), Edit(package.json), Edit(pnpm-lock.yaml) ], deny: [ Bash(rm -rf *), Bash(git push *), WebFetch(*), Edit(config/production.json) ] } }这个模板背后有逻辑allow里只放确定安全、频率又高的操作让 AI 不用每个小动作都回来问你流畅度会好很多ask里放的是会改变项目状态但不一定有害的操作deny里放的是无论什么时候都不该让 AI 自己做的高危动作。一句经验权限配置宁可先紧后松。刚接进项目时让 AI 多做几次询问不是坏事你可以观察它的行为模式等确认它的判断稳定了再逐步放权到allow。反过来一旦出事你把权限收紧整个团队的开发习惯又要重新适应损失更大。4. 常见问题与排查实录4.1 命令加载不出来或行为奇怪命令文件放好之后我经常遇到两类问题要么/review敲下去提示命令不存在要么命令能触发但 AI 完全没有按我 frontmatter 里的描述执行。第一类问题的排查思路几乎总是路径问题。确认你的命令文件放在.claude/commands/目录下文件名后缀必须是.md且目录名不能写错。第二类问题更隐蔽通常和 frontmatter 有关YAML 解析失败会被静默忽略命令倒是能跑但 AI 看不到你的描述、参数提示等元信息自然执行得像是裸奔。解决方法是检查 YAML 语法尤其注意冒号后面是否有空格、多行字符串是否正确缩进。4.2 上下文爆炸与模板过长模板文件太长会让 AI 抓不住重点。我自己早期写过一个 3000 行的 CLAUDE.md觉得自己很全面结果 AI 连最基本的目录约定都会搞错。后来做了减法把文档压到 80 行核心规则加几个遇到 X 时读 Y的指引效果反而好了很多。这个现象背后的原因叫做lost in the middle对 AI 来说超长上下文里中间段落的注意力权重会衰减所以关键规则得放开头剩下细节放文档链接。如果遇到AI 老是读取无关文件的问题可以考虑在 CLAUDE.md 里显式标注忽略以下目录docs/archive/、vendor/、node_modules/。这个操作看起来简单实际对上下文预算的节省非常明显。4.3 多项目模板同步问题当你同时维护五六个项目时模板库能不能干净、及时地同步到所有项目决定了整个体系是否会烂尾。我之前用复制粘贴的方式分发结果有的项目落后三个版本有的项目被我一次性覆盖掉了本地定制内容苦不堪言。后来的方案是模板库 软链接 分级定制通用命令review、fix、test全部用软链接指向模板仓库改一处所有项目生效。项目级 CLAUDE.md 不软链因为几乎每个项目的业务背景都不同它天然该是各写各的。不过我会在模板仓库里维护一份 CLAUDE.md 的骨架模板新项目初始化时由setup.sh复制并引导填空。settings.json 的权限部分做一个基础版但每个项目还要再加一层自己的deny规则尤其涉及生产配置、部署脚本的内容。这样既保证了通用能力的一致更新又给每个项目保留了定制的空间。同步脚本真正执行的时候我还会加一个--dry-run参数先打印将要操作的文件清单人确认后再真正动手。4.4 常用问题速查表症状可能原因解决方案敲/xxx提示命令不存在命令文件放错目录或后缀不对确认放在.claude/commands/后缀为.md命令能触发但行为不对YAML frontmatter 解析失败检查冒号后空格、缩进、非法字符AI 不读 CLAUDE.md文件路径不对或文档超长确认文件名大小写压缩核心规则hook 没有生效settings.json里 hooks 配置语法错误手动跑脚本并用假 JSON 样本调试hook 生效但 AI 特别慢脚本里有重逻辑或网络请求优化脚本提前退出尽量早subagent 总被错误委派description写得太宽泛在 description 里明确写不适合的场景这张表基本覆盖了我被问到最多的场景。其余的大多数问题绕来绕去最后都会回到一句话先确认你自己设的规则有没有真正进入 AI 看到的那份上下文里。5. 模板体系的扩展心得模板固定下来之后你会慢慢发现一个有意思的变化你不再需要操心这次该给 AI 什么提示词而是开始操心这次该跑哪条命令、该让哪个 agent 上。这个心智模型的转变才是模板体系真正的收益。我在实际使用中还会把模板库和一个简单的命令使用手册文档绑定在一起每个命令只写一小段说明加一个示例。这个文档不是给 AI 看的是给团队新同事看的。新人在我的指导下花半天读文档、跑几条命令基本就能掌握用 /review 做合入前检查、用 /fix 做定向修改、把复杂重构拆给架构师 agent这套全流程学习成本低到几乎没有。最后再分享一个小技巧模板库一定要定期复盘。我每两个礼拜会看一眼近期 AI 协作失败的实际案例把新问题沉淀成新的命令参数、新的 deny 规则或者一条新的 CLAUDE.md 条款。模板不是写完就完事的静态文档它应该跟着你和团队的做事方式一起成长。花在这个复盘上的时间比你在单次会话里反复调教 AI 的碎片时间不知道划算到哪里去了。