刚接触Claude Code那阵子我其实挺不以为然的。这不就是个挂在终端里的对话窗口吗无非能把代码库读完、能帮你跑命令而已。真正让我改观的是某次新开一个会话准备继续开发时发现自己又在重复粘贴同样的项目背景、技术栈说明、测试命令、编码规范……差不多的文字这个月我已经粘贴了七八次。那一刻我才意识到Claude Code这个工具真正的分水岭不在“对话能力”而在你有没有一套属于自己的 claude-code-templates。模板化之后的效果是很直接的原来一个新会话从零进入状态至少得花掉两三千token去“交底”而且对话一长上下文稀释它还是会忘记前面交代过的约定。现在打开终端Claude自动就把项目背景、技术规范、工具链逻辑全部加载好了不用你多说一个字它就知道项目是干什么的、代码往哪放、测试怎么跑、commit格式长什么样。那种感觉相当于从“每次面试一个聪明但没有记忆的新人”变成了“手下有一个看过你全部文档、完全清楚你规矩的老员工”。这篇文章我不打算讲怎么装Claude Code那属于官方README的范围。我想记录的是更实用的部分一套完整的、可复用的、能直接抄作业的模板体系该怎么搭包含CLAUDE.md该怎么写、斜杠命令怎么设计、hooks怎么挂、子代理怎么分以及我实测踩过的各种坑。适合已经用Claude Code跑过基础对话、觉得它“还行但不够顺手”的开发者。1. 模板到底是什么从裸对话到可复用工作流的转变1.1 我的低效现状每次对话都在重复交底先说个真实场景。我的一个中型全栈项目技术栈是Next.js TypeScript Prisma PostgreSQL测试用JestLint用ESLint代码规范里有一堆约定——比如组件目录用kebab-case、数据库表名用snake_case、commit message必须符合Conventional Commits。在没有模板之前我每次打开一个新终端窗口启动Claude Code都要在第一条消息里把这些写一遍。起初还好后来项目大了光项目结构说明就能写一大堆。更要命的是Claude Code虽然是带记忆的但对话窗口一长它还是会“忘事儿”——不是它傻是上下文窗口塞满了修改记录、报错信息早先交代的规范被挤出去了。于是我不得不把“项目记忆”压缩成一段核心说明在每次新会话开头重新粘贴。这就是最原始的“模板”但效率太低了。1.2 模板化的本质把“上下文”和“流程”固化成资产后来我开始研究Claude Code提供的模板能力才意识到我需要的不是“一段能复制的文字”而是一整套系统。简单说claude-code-templates的核心理义是把上下文资产化项目背景、技术栈、规范这些“一次写清、反复使用”的信息固化到自动加载的文件里不用再每次手动给。把流程系统化高频任务写commit、做code review、生成接口文档、补测试固化成一条条斜杠命令一条命令就是一个标准作业流程。把自动化落在关键节点上通过hooks机制让Claude在执行某些操作前后自动触发检查省去人工盯细节。打个比方你请了个实习生能力很强但对你这个项目一无所知。你每天都要花二十分钟给他讲背景、讲规矩、布置任务。模板系统就是给这个实习生准备的一份《岗位手册》外加一套《标准作业流程》。手册他每天自动读一遍布置任务不用你说话——你只需要敲一下命令按钮他看完SOP就开始干活。你省下来的是每天重复的“交底时间”。1.3 模板解决的典型场景清单我实际使用下来模板体系对下面这些场景的价值最大新项目初始化说完需求模板自动带入技术栈约定和目录结构开局不用从零解释。多项目并行切换切到A项目Claude自动加载A的规范切到B项目自动加载B的规范两者互不污染。团队协作规范落地把团队的Git规范、命名规范、评审清单写进模板每个成员在同一条起跑线上。高频任务标准化生成commit、提MR、写测试、刷文档这种重复劳动全部命令化减少心智负担。自动化质量检查hooks在文件变更后自动触发Lint或测试不等代码写完就发现问题。1.4 和“普通prompt库”的本质区别有人会问模板不就是一堆prompt吗我把常用提示词存个小本本要用的时候复制粘贴不一样吗说实话我一开始也是这么想的甚至真用过一阵子“个人prompt收藏夹”。但用起来完全是两码事。差别可以这样看维度普通prompt收藏模板化体系加载方式手动复制粘贴Claude自动加载或一条斜杠命令触发上下文能力只有提示词无项目认知能结合自动读取的项目文件和代码库上下文自动化无支持hooks在关键节点自动执行操作工程化纯文本可版本化、可目录化、可团队共享维护成本零散容易过期结构化维护随项目演进持续迭代所以如果你只把templates理解成“收藏夹”你会错失它真正有价值的部分——自动加载和流程触发机制。这两件事纯靠复制粘贴是做不出来的。2. 拆解Claude Code模板的四根支柱我给自己的模板体系总结了四根支柱CLAUDE.md、自定义斜杠命令、hooks、子代理。下面逐个拆开讲都是实际在用的东西。2.1 CLAUDE.md项目记忆文件模板的地基CLAUDE.md是Claude Code的“项目记忆文件”。它放在项目根目录或全局用户目录每次Claude启动时会自动读取把里面的内容当作长期记忆和行为准则。用一句话概括这是Claude对这个项目的“入职培训”每一天开工自动重播一遍。我的CLAUDE.md长这样这是简化后的结构# 项目概况 - 项目名称XX零售后台管理系统 - 技术栈Next.js 14 TypeScript Prisma PostgreSQL - 核心目录app/页面路由、server/API逻辑、lib/工具与中间件 # 开发约定 - 组件文件一律使用 kebab-case 命名 - 新增数据库表必须同时生成迁移文件 - API返回统一包裹为 { code, data, message } 结构 - 单测用Jest测试文件与源码同目录后缀 .test.ts # 常用命令 - dev: npm run dev - test: npm run test - lint: npm run lint - migrate: npx prisma migrate dev # 行为规则 - 修改涉及数据库schema时必须先执行 migrate 生成SQL预览确认后才执行 - 对代码做大规模重构前先给出改动影响面清单 - 所有新增依赖需说明用途避免无意义引入这里有个关键设计原则只写Claude需要用到的信息不是项目README的搬运。README是给人看的CLAUDE.md是给AI执行规则用的。什么东西该写、什么不该写我后面会在踩坑部分详谈这里先记住一个判断标准——这条信息如果Claude不知道会导致它做出错误决策那就该写如果只是“项目背景知识”写不写无所谓那就别写。另外CLAUDE.md可以按目录细分。Claude Code支持在子目录里放子CLAUDE.md当它在该目录下操作时会额外加载。我通常在server/目录下放一份专门记录API设计规范在app/目录下放一份记录页面开发规范。这样既避免主文件过长又能让规则精确命中对应代码区域。2.2 自定义Slash Commands把高频任务固化成斜杠命令Slash Commands是模板体系里最容易获得成就感的部分。简单说就是你自己定义“/命令”把复杂任务拆解成一套预置流程。我在初始版本中做的第一件事就是把一周内重复三次以上的操作全部命令化。命令用YAML定义我习惯放在项目的.claude/slash-commands/目录里。目录结构长这样.claude/slash-commands/ ├── commit.yaml ├── review.yaml ├── test.yaml └── api-doc.yaml拿最常用的commit命令举例看它的完整定义description: 生成符合Conventional Commits规范的提交信息 agent: Code allowed-tools: Read, Grep prompt: | 你的任务是分析当前工作区中的git diff生成一条符合Conventional Commits规范的commit message。 步骤 1. 运行 git diff --staged 查看已暂存的改动 2. 运行 git diff 查看未暂存改动 3. 归纳本次变更的类型feat/fix/refactor/chore/docs等 4. 输出 commit message格式为类型(模块): 简短描述 5. 附加body说明影响范围关联issue编号如有 注意 - 不要将多个类型合并成一条 - 描述控制在50个字符以内 - 如有breaking change在commit message中标注看到这个结构的价值了吗你不需要每次跟Claude解释“什么是Conventional Commits”不需要每次说明“看staged和unstaged的diff”更不需要强调“commit message要写清楚impact”。这些全固化在命令里了。你只需要在终端敲/commit它自己按SOP走完流程。我个人的经验是命令数量控制在5到8个最舒服。太少覆盖不了高频任务太多则维护成本和误用概率同时上升。值得做命令的标准很简单——一周内这个操作你重复做了三次以上就有理由固化成命令。2.3 Hooks在关键节点挂上自动化检查如果CLAUDE.md是“入职培训”斜杠命令是“标准作业流程”那hooks就是“贴在工位上的巡检横幅”。Hooks的作用是在Claude执行某些动作的节点上挂载你自己的逻辑。常用事件节点有PreToolUseClaude调用某个工具之前触发。适合做“安全门禁”比如禁止写某个敏感目录。PostToolUse工具执行完成后触发。适合做“自动检查”比如改完代码自动跑Lint。StopClaude完成回复准备结束。适合做“收尾校验”。我的hooks配置长这样JSON格式放在项目级.claude/hooks.json{ PostToolUse: [ { matcher: Edit, hooks: [ { type: command, command: npm run lint -- --quiet, timeout: 30 } ] } ], PreToolUse: [ { matcher: Write, hooks: [ { type: command, command: bash scripts/check-protected-paths.sh, timeout: 10 } ] } ] }第一个hook的效果是每当Claude使用Edit工具修改代码后自动运行Lint检查。它改完代码如果引入了Lint错误马上就能看到不用等到最后才爆雷。第二个hook的效果是当Claude准备写文件时先检查是不是敏感目录比如node_modules、.git、dist阻止误写入。hooks有一个执行顺序问题需要注意多个hook按配置顺序执行任意一个hook返回非零退出码Claude就会被通知中断当前操作。所以快递门禁类的hook要写在最前面检查类的hook可以靠后放这样即使后续检查失败门禁逻辑也已经执行过了。2.4 子代理Subagents把专用任务拆给专职Agent最后一个支柱也是我后面越来越依赖的子代理Subagents。如果说斜杠命令是“把任务流程化”那子代理就是“把人设专业化”。默认情况下Claude像一个全能选手什么任务都能接但也意味着它处理专项任务时不够“专”。比如我让它写测试它默认会用一种通用思路未必贴合这个项目的Mock约定让它做代码审查它会按通用Best Practice来未必了解团队特定的安全规范。子代理的思路是定义一批“专职员工”每个Agent拥有自己独立的人设、专属指令和工具权限。Claude主进程像一位项目负责人遇到对应任务就委派给专职子代理来完成。我的子代理放在.claude/agents/目录下一个文件一个代理。以我的测试工程师子代理为例name: test-engineer description: 负责单元测试与集成测试的编写与执行熟悉Jest测试框架和项目的Mock约定 tools: Read, Grep, Write, Edit, Bash prompt: | 你是这个项目的测试工程师。你负责编写和修正测试用例。 项目测试规范 - 测试文件与源码同目录命名后缀为 .test.ts - 优先使用 describe/it 结构描述行为 - 数据库相关测试必须使用内存数据库不依赖本地PostgreSQL实例 - 涉及外部API调用的测试使用 jest.mock 隔离 当你接到测试相关任务时 1. 先阅读相关源码理解被测函数的边界输入 2. 查看同目录是否有既有测试约定可参考 3. 编写/修正测试用例 4. 运行针对性测试命令验证失败则继续修复这样定义的好处是一旦我提出“给这个模块补测试”的需求Claude会把这个任务委派给test-engineer而test-engineer自带的记忆让它在第一轮产出就更贴合项目约定不再需要我临时啰嗦一遍Mock规范、命名规则、数据库注意事项。子代理的核心理念是“把人员分工做在配置里而不是每次对话里”。团队成员越多、规范越细这个支柱带来的收益就越明显。3. 手把手实战从零搭出一套“能用的模板”理论说了一圈接下来是我建议的实操路径。我踩过的弯路是一开始试图把模板设计得大而全结果写了一堆规则真正跑起来反而被自己的规则绊住脚。后来我调整了策略先画流程再写规则最后加自动化。3.1 先画流程再写规则模板设计的前置思路动手写CLAUDE.md之前我先花半小时做了一次任务盘点。方法是翻出过去两周和Claude的对话记录按任务类型分组数一下每类任务出现多少次。我当时的高频任务排序大概是生成commit message做代码审查 / 解释一段复杂逻辑写接口文档补单元测试排查某个报错对应这个清单我决定第一版只做四件事写一份精简CLAUDE.md定义/commit和/api-doc两条斜杠命令挂一个自动Lint的hook其余的都放后面。这个“最小可用模板”的思路帮我快速跑通了整套机制后面再逐步增加其他功能。如果你盘下来发现高频任务完全不同那完全没问题——模板的设计就是从你的真实工作流里长出来不是别人给你一套通用的就完事了。3.2 第一步写一个“克制”的CLAUDE.md“克制”是我反复强调的词。我见过不少人的CLAUDE.md写得跟法典一样几百行规则结果实际用起来效果奇差——token消耗大而且规则之间互相冲突Claude会陷入“先遵守哪条”的两难。我建议按这个框架写第一版# 角色 你是本项目的开发助理。你的目标是高效、安全地完成用户交代的编码任务并严格遵守项目规范。 # 项目背景2~3条 一句话说明项目是什么、主要服务谁、代码库多大。 # 技术栈与目录3~5条 列出最关键的技术栈、核心目录的用途。不写成结构说明书只写Claude要干活时必须知道的路标。 # 常用命令最多5条 dev / test / lint / build / migrate按需列举。 # 硬性规范最多8条 只放违反后会导致严重问题的规则比如数据库迁移流程、敏感信息保护、必须运行测试等。 # 行为禁忌3~5条 明确告知什么不能做例如不要假设删除不存在的文件、不要绕开Prisma直接改数据库等。每一条规则都要能被快速验证。写完之后检查一遍这条规则如果删掉Claude的行为会立刻变差吗不会的话就删了。保持文件在你常对话轮次内不把上下文撑爆是模板长期好用的关键。3.3 第二步定义两个高频命令拿到即时反馈接着定义命令。我当时最需要的是/commit和/api-doc。commit命令的YAML前面展示过了这里看下/api-docdescription: 为指定API路由生成接口文档 agent: Code allowed-tools: Read, Grep, Write prompt: | 请基于以下信息生成该API接口的Markdown格式文档。 目标文件$ARGUMENTS 生成步骤 1. 读取指定路由文件理解HTTP方法、参数结构、返回结构 2. 查询对应的Prisma模型或数据库表结构定义 3. 输出文档包含接口地址、HTTP方法、请求参数表名称/类型/必填/说明、 返回示例、错误码列表如有 4. 文档输出到 docs/api/ 目录下文件名与路由名一致 注意文档中不包含任何敏感信息如数据库连接串、内部跳转地址。这里有个细节$ARGUMENTS是斜杠命令内置的参数占位符。我执行/api-doc server/routes/user.ts时Claude会把server/routes/user.ts替换进prompt里。这让一条命令能适用于同类型的多个目标文件而不是把文件路径烧死在命令里。两条命令上线后我当天就感觉到变化commit不再是我逐字敲的煎熬事接口文档从“拖延到被催”变成了“顺手生成”的状态。这就是即时反馈带来的正循环你会自然而然地想继续加命令。3.4 第三步配置hooks让模板真正做到“自动化”斜杠命令解决的是“主动触发的任务”hooks解决的是“需要被动拦截或自动检查的场景”。要让模板真正变得“省心”这一步不能省。我强烈建议第一个hook先做“Lint自动检查”收益最直接。在你确认能稳定运行之后再加“PreToolUse安全拦截”。我记得第一次配置hooks时踩了个坑没有设置timeout结果有一次Lint执行卡住整个Claude操作被挂起终端像死了一样。后来养成习惯了所有command类hook都带上timeout单位按秒。Lint这种通常10到30秒足够写死30秒就对了。另一个经验是hooks的matcher要尽量写准。matcher是匹配工具名称的比如Edit、Write、Bash。如果你希望在“写文件时”才触发检查matcher写Write不要让无关的工具触发。范围宽了容易误触发范围窄了有漏网之鱼这个度要靠一段时间的运行日志来调。3.5 第四步目录化与版本化让模板可复制、可演进模板最怕的是“一次性搭建用完就忘”。我的处理方式是把它做成独立的Git仓库目录结构是这样claude-code-templates/ ├── templates/ │ ├── next-fullstack/ │ │ ├── CLAUDE.md │ │ ├── .claude/ │ │ │ ├── hooks.json │ │ │ ├── agents/ │ │ │ └── slash-commands/ │ │ └── docs/ │ └── python-fastapi/ │ └── ... ├── scripts/ │ └── apply.sh └── README.md每个业务项目对应一套模板模板仓库独立保存版本历史。新项目开工时跑一下apply.sh传入目标项目路径脚本把对应模板的CLAUDE.md和.claude目录复制过去再根据项目名替换少量变量即可。版本化带来的最大好处是“可演进”。每次你在项目里调整了一条规则、新增了一个命令改动沉淀在模板仓库里下个项目直接继承最新版本。我自己的模板仓库到现在迭代了十几个commit每次改动都有记录不会出现“改着改着忘了当初为什么这么改”的糊涂账。4. 模板调优与踩坑实录实测中的参数参考和翻车现场这一部分是我最想分享的。网上讲Claude Code模板设置的教程不少但大多停留在“介绍有哪些功能”层面真正操作时会遇到的坑只有自己踩过才知道。下面是我实测几个月攒下来的调优经验和翻车记录。4.1 坑一CLAUDE.md写成了“字典”token被无效消耗第一版CLAUDE.md我几乎是把项目文档和API手册浓缩了一下全塞进去了。结果每次对话的token消耗明显上涨而且Claude的行为并没有因为有“完整文档”而变好——因为信息量太大关键规则反而被淹没了。后来我做了个清理把CLAUDE.md压缩到约2500 token以内只保留“行为规则”和“关键路径”两类信息其余背景知识全部移到docs目录Claude需要时再去检索。效果立竿见影不仅token消耗降下来了规则命中率也高了。现在我的经验参数是CLAUDE.md主文件控制在 1 ~ 3 KB 左右对应约 500 ~ 1500 token看你项目复杂度。超过3000 token就强烈建议拆分把细粒度规范移到子目录的CLAUDE.md或文档文件中。记住CLAUDE.md不是让你把文档翻译一遍而是给AI指路和定规矩用的。4.2 坑二斜杠命令的命令权限过宽那次是给一个斜杠命令配置了比实际需要更多的工具权限。命令本身是生成文档的我却把allowed-tools写成了Read, Grep, Write, Edit, Bash。结果Claude在执行过程中自作主张跑了个Bash命令修改了某个配置文件——虽然改动不致命但足够吓人。从此以后我严格执行“最小权限”。写文档的命令给Read, Grep, Write就够了永远不会给它Edit和Bash。做审查的命令给Read, Grep足矣。需要跑测试、改代码的命令才放Bash, Edit进来。这个原则跟给服务器开防火墙端口是一样的默认拒绝按需放行。4.3 坑三hooks误触发与死循环这是我踩过最严重的一次坑。当时挂了一个PostToolUse hook逻辑是“每当工具执行完自动运行一次测试”。问题是当Claude运行测试命令本身时Bash工具执行完也会触发PostToolUse于是又触发一次测试……直接形成无限循环最后被Claude的自我保护机制中断。排查过程比较痛苦我一度以为是Claude变傻了后来翻了hooks的执行日志才发现死循环的根因是“hook没有排除自己”。解决方案是在hook脚本里加一个判断如果正在执行的命令包含测试命令自身就跳过本次触发。或者更简单的做法把自动触发条件限定为只对Edit工具生效如下{ PostToolUse: [ { matcher: Edit, hooks: [ { type: command, command: npm run lint -- --quiet } ] } ] }现在配置里对Edit工具的触发仍然是安全的但“无限循环”这个词成了我在团队里的警示教材。设计hooks时务必问自己这个hook触发后产生的动作会不会反过来再次触发同一个hook4.4 坑四模板版本与Claude Code版本兼容性Claude Code的迭代速度非常快。配置文件格式、命令定义字段、hooks事件的详细参数都可能在某个小版本更新后发生变化。我最初写的hooks配置格式是参考当时的文档来的结果两个月后升级Claude CodePostToolUse的配置结构变了之前能用的hook静默失效。我现在做两件事来避免这类问题模板仓库的README里记录“最后验证的Claude Code版本号”。比如我当时验证的是 1.0.x 系列换版本前先看Release Notes。升级Claude Code后不急着切全部项目先在一个测试项目里跑一遍模板的核心命令和hooks确认无误后再做全面切换。这是个听起来不够酷但极其有效的流程。工具版本是流水模板是基石基石跟着流水漂一定会出问题。4.5 什么才是好的claude-code-templates我的几条判断标准几个月用下来我把“好模板”的标准沉淀成几条可验证的规则分享给你作为调优基准高频命令化一周内重复3次以上的操作就应该做成斜杠命令。如果一条命令你用了不到5次考虑删掉。规则数克制当CLAUDE.md里某条规则已经“三个月没有被触发”时说明它不是刚需大胆删。命令权限最小化每个命令的allowed-tools只给够用的多一个都不行。hooks留日志给hook脚本的执行结果留日志出现异常时能快速定位。模板可迁移新项目套上模板后半小时内能达到“Claude已经很懂这个项目”的状态否则说明模板还不够好。还有一个容易被忽略的点模板是人机协作的契约不是枷锁。设计时留出“允许偏离规则”的空间。CLAUDE.md里有几条禁忌其实Claude偶尔会违背我的处理是看违背之后的结果是好是坏再决定要不要把禁忌写得更硬。完全没有弹性空间的行为规则会让工具显得僵化而它的优势恰恰是比普通脚本更灵活。项目跑了大半年我的模板仓库已经更新了十来个版本每次调整都来自真实使用中的反馈。模板不是写出来的是长出来的。刚开始你可能只有一个好的CLAUDE.md用着用着你开始觉得某个操作值得一条斜杠命令某个环节需要挂一个hook某个固定任务应该拆给专用子代理。这个过程才是模板化玩法真正有价值的地方。最后分享一个小技巧给CLAUDE.md末尾留一个“升级日志”区块让Claude每次更新记忆时顺便记录一下改动。它会成为你最诚实的模板使用史也是回看自己工作流进化轨迹的好材料。