1. 从两条 command 到一套模板库Claude Code 使用进阶的转折点开始用 Claude Code 的时候大多数人做的事其实差不多新建会话给它一段项目背景然后一个问题一个问题地聊。聊到第三天你就会发现自己每天在重复讲同样的话比如“这个项目的测试在哪个目录”“为什么不能直接改这个文件”“生成的文件不要提交”。我是在连续三周早上都重复同样背景之后才痛下决心把模板这件事认真做起来的。这里的“模板”不是一个狭义的文件模板而是一整套让 Claude Code 在进入项目时就能获得稳定上下文的方法。你可以把它理解为一份给 AI 同事的岗位说明书项目是什么样的、规矩是什么、常用动作怎么做、哪些事碰都不能碰。有了这份说明书它每次进来都先读一遍再开始干活而不是边摸索边问你。这篇文章主要写给希望通过 Claude Code 做工程化交付、而不是只把它当聊天机器人用的开发者。它适合那些手里有多个仓库、需要统一团队 AI 使用体验的人也适合刚接触这套工具、想从一开始就养成良好习惯的新手。下面讲的都是我在真实项目里的做法和取舍。1.1 模板在 Claude Code 里的三种存在形态先说一个容易混淆的点Claude Code 语境里的模板不是一个文件而是三层体系各管各的事。第一层是项目说明文件一般叫 CLAUDE.md。它描述项目的静态事实这个仓库是什么、核心代码在哪、用什么技术栈、有哪些约定和禁区。它跟随 Git 走新成员拉下仓库就自动生效。这一层相当于宪法管的是“项目是什么”。第二层是命令模板。Claude Code 支持把一段固定的指令固化成一条斜杠命令例如/review、/gen:test。你可以给它定义参数、描述和输出格式要求。每次使用的时候它把同样的指令用标准化的方式执行一遍不必每次重新用自然语言描述。这一层管的是“标准动作怎么做”相当于操作手册。第三层是挂钩脚本和工作流。hook 能在特定事件发生时执行外部脚本比如在会话开始时读取 git 状态、在文件保存后自动跑类型检查把上下文准备和质量校验自动化。这一层管的是“环境怎么自动搭好”相当于自动化的仪式流程。这三层不是互相替代的关系而是层层递进。CLAUDE.md 解决认知问题命令模板解决效率问题钩子解决一致性问题。我见过很多人只用第一层把 CLAUDE.md 写得满满当当但日常操作还是靠手打会话质量仍然不稳定因为效率和信息密度并没有真正上去。我的经验是三层都要有才能算一套完整的模板体系。1.2 为什么这件事值得专门折腾我经常被问到AI 都这么智能了为什么还要费劲写模板直接让它自己看仓库不行吗能不能能。但问题出在“自己看”上面。大型仓库动辄几十万行代码AI 在每轮对话里能携带的上下文有限如果没有任何指引它第一步往往就是浏览目录结构然后在最显眼的文件里开始猜。这个过程的失败率非常高。而模板的作用就是用尽量少的 token 把最重要的信息提前喂给它让它不必在探索上消耗有限的注意力。我做过一个很粗糙的统计在一个中等规模的服务端仓库里没有模板的情况下一次典型需求对话中我平均要输入 8 到 12 次背景纠正比如“测试在 tests/unit 下面”“这个服务是 Node 写的不要用 Python 语法”“生成的类型定义不能手动改”。这些纠正每次都要打断思路质量还很不稳定。加了 CLAUDE.md 之后这类纠正基本降到了两三次以内命令模板再消掉一批整天的使用体验完全是两个等级。所以我的判断是模板不是配置洁癖也不是为了“显得专业”它是在用确定性的成本换回每一次会话的稳定性。你花半天把模板设计好之后每一次使用都从这套配置上获益而复利效应在团队里会更明显——有一份好的模板等于所有人都站在同一个起点上跟 AI 协作。1.3 一个模板库的基本目录布局这部分直接给可以直接抄作业的目录结构。我的团队现在所有项目都用同一套布局放在仓库根目录下的 .claude 目录里.claude/ ├── CLAUDE.md # 项目级说明也可以放根目录 ├── commands/ │ ├── review/ │ │ ├── security.md # /review:security 安全审查 │ │ ├── perf.md # /review:perf 性能审查 │ │ └── general.md # /review:general 通用审查 │ ├── gen/ │ │ ├── test.md # /gen:test 生成测试 │ │ └── doc.md # /gen:doc 生成文档 │ └── fix/ │ └── lint.md # /fix:lint 修复 lint 错误 ├── hooks/ │ ├── session-start.sh # 会话开始时的状态检查 │ └── on-save-typecheck.sh # 保存后类型检查 └── workflows/ ├── add-test.md # 给模块补测试的多步流程 └── release-check.md # 发版前检查流程这个目录结构的核心思想是分层和分类清晰凡是命令放进 commands 并用子目录做分组凡是脚本放进 hooks凡是需要多步骤编排的流程放进 workflows。CLAUDE.md 放在根目录作为项目认知的入口其他文件都是它的补充。目录一旦稳定下来你几乎不需要再操心组织方式精神全部可以放在内容本身上。2. CLAUDE.md 要写成“入职指南”而不是“简历”CLAUDE.md 是整层体系的地基。写得好不好直接决定后续所有模板的上限。我见过很多个版本的 CLAUDE.md有人把它写成了简历大段介绍自己和团队的背景有人把它写成了代码库百科全书事无巨细全往里塞。这两种都偏离了它真正的功能。2.1 写什么不写什么CLAUDE.md 的核心功能是给 AI 一份足够精准的坐标系。简单说它在第一轮对话之前用最短的篇幅告诉 AI“你将会高频面对什么”。我的写作框架是四段式定位、约定、操作、禁区。定位是五句话以内的项目描述。不需要写公司的愿景不需要写“我们致力于提供卓越的用户体验”只需要让 AI 知道这是什么仓库主模块在哪里用什么语言和框架数据流向哪里。举个例子“本仓库是文档解析服务PDF、Word、图片三种格式通过抽象接口进入解析管道切面在 src/services 下入口是 src/index.ts”这句话的信息量顶得上 AI 自己逛目录十分钟。约定是那些“不知道就会做错”的具体事实。常见的几类包管理器是 pnpm、npm 还是 yarn测试跑的是 vitest 还是 jest。哪些目录是构建产物或自动生成的人工不能改。配置文件怎么拆分环境变量在哪里注入。代码风格上有没有特殊偏好比如禁止使用 any、禁止把业务逻辑写在路由层。这些信息看起来琐碎但对 AI 来说是致命的。有一次我在一个仓库里每轮对话都要求 AI“不要用 npm 装依赖”它还是用了 npm install直到我把“依赖管理使用 pnpm”写进 CLAUDE.md这个问题才彻底消失。因为人是靠记忆纠错AI 是靠上下文纠错你的上下文里没写它就只能靠运气。操作清单是 AI 可以直接执行的动作步骤。比如“定位 bug 时先读取 logs/app.log 最近的 20 行再根据错误栈反向搜索源码”“做 code review 时先跑一遍静态检查再按严重级别从高到低评论”。这类过程性的指引放在 CLAUDE.md 里特别有价值因为 AI 默认的探索路径不一定是你团队习惯的路径。禁区是很多人最容易忽略的部分。项目里总有几个“不能碰”的地方不能自动修改的合规文件、不能在生产环境执行的重命名、不能提交到仓库的本地配置。把这些明确写成“不要做 X”效果远好于在每轮对话里反复叮嘱。Claude Code 会把 CLAUDE.md 里的负面约束当作硬规则对待所以禁区一定要放在核心文件里不能只是某个对话里的临时指令。同时要克制住“什么都写”的冲动。CLAUDE.md 不是文档站不需要包含架构演进史、历史决策记录和团队八卦。每多一段无关背景每轮对话的上下文就要多背一点AI 当前的注意力就被稀释一点。所以我的硬性要求是CLAUDE.md 保持在一百到两百行之间超过就拆分。2.2 指令去重的顺序法则如果你只维护一个仓库CLAUDE.md 怎么排都无所谓。但现实是全局有配置仓库有配置子目录还可能有配置这里就涉及优先级问题。我的原则非常朴素越靠近具体代码的说明越优先。全局配置里只写跨项目通用规则比如“回复尽量给出可直接执行的命令”“在修改任何文件前先确认意图”这类零风险的默认行为。仓库级的 CLAUDE.md 写所有项目特有的约定和结构。子包或子目录里如果还需要细分就在那一个局部范围内写专项说明。要让这个层级体系稳定最关键的一点是避免不同层级之间互相矛盾。最典型的冲突是全局写着“所有前端项目统一使用 pnpm”某个仓库实际用的是 npm而仓库级 CLAUDE.md 里没写这个差异AI 就会把全局规则默认为真跑出一堆 npm 命令等报错之后才反应过来。我的做法是把全局配置限定在极少数真正跨项目成立的规则上其余一律下沉到仓库级写死。规则越少冲突越少。2.3 一段可以直接抄的 CLAUDE.md 示例我放一个我在 Node.js 服务仓库里现成的精简版本。重点不是代码本身而是你看到这种组织方式后能往自己的仓库里迁移。# DocPilot API 服务 ## 项目定位 - 本仓库是文档解析服务处理 PDF、Word、图片三种格式的输入。 - 核心解析逻辑在 src/services 下HTTP 入口是 src/index.ts。 - 仓库不包含前端代码请不要尝试运行任何前端任务。 ## 约定 - 依赖管理统一使用 pnpm禁止 npm install 或 yarn。 - 测试使用 vitest测试文件放在 tests/unit 和 tests/e2e 下。 - src/generated/ 目录下的文件由 protoc 自动生成严禁手动编辑。 - 环境变量从 .env.local 读取生产环境变量在部署管道注入不要硬编码。 ## 常用操作 - 启动开发服务pnpm dev - 运行全部测试pnpm test - 生成 protobuf 代码pnpm run gen:proto - 提交前必须通过pnpm lint pnpm test ## 禁区 - 不要修改 src/generated/ 下任何文件。 - 不要提交 .env.local、.env.* 到 Git。 - 不要在生产环境执行数据迁移命令必须先走发版流程。注意最后那段“禁区”不是威胁性措辞而是硬性规避指令。它背后都有真实事故有一次 AI 手滑改了生成文件导致类型定义和 protobuf 定义错位排查了整整一个下午。从那以后所有自动生成目录都被我写进禁区同类问题再也没出过。3. 命令模板把重复动作变成可靠快捷键CLAUDE.md 解决了“AI 知道自己在哪个项目、要守什么规矩”的问题但每天真正消耗你的往往是那些重复性动作审查一段代码、生成测试、修复 lint、解释一段逻辑。如果这些都用自然语言逐次描述效率会很低而且每次的输出风格还不一样。命令模板就是把这类动作固化成可复用、可传参、输出格式稳定的标准化指令。3.1 前缀命名法和参数克制我第一次建命令模板的时候用的名字特别随意/code-view、/mktest、/fixlint每个都拍脑袋想的。用了一周命令列表长得跟杂货铺一样翻菜单的时间比手写提示词还长。后来我痛定思痛改成前缀命名法功能前缀 动作。比如所有和代码审查相关的命令统一用review:前缀生成类命令用gen:前缀修复类用fix:前缀。实际显示的斜杠命令就变成/review:security、/gen:test、/fix:lint。这样有两个直接好处第一菜单里一列出来就自动分组找的时候不费脑子第二团队里新人看到命令名基本不需要问“这个命令是干嘛的”前缀已经告诉了他类别。参数的设计则要克制。命令模板支持参数替换这很好用但参数一多就回到手写提示词的老路。我的经验是单个命令的参数最多不超过三个能用一个“目标文件路径 一句附加要求”解决的就不要拆成五个字段。比如/review:security file就够了附加的说明可以在输入时补上后缀。命令模板是让重复劳动变轻不是让轻劳动变重。3.2 一个高频 code review 命令模板的实际效果我就拿review:general这个命令模板来拆解。它在我的团队里被用了很多次输出风格包括顺序和格式都非常统一后续筛选问题的时候很省事。--- description: 对指定文件做一轮代码审查按类型、安全、性能、可读性的顺序输出 argument-hint: 文件路径 [可选:重点关注的方面] --- 请对文件 $ARGUMENTS 执行一次代码审查。按以下顺序输出结论 1. 类型与编译问题是否有明显的类型错误或编译隐患。 2. 安全隐患重点关注注入、路径遍历、敏感信息泄漏、权限校验缺失。 3. 性能风险是否有重复计算、未释放资源、不必要的同步阻塞。 4. 可读性与命名注释是否必要、命名是否准确、是否存在误导性抽象。 每条结论控制在三句话以内按严重级别标注[阻塞]、[建议]。 不要修改代码只输出审查意见。这个模板最关键的细节是“要不要修改代码”这个边界。默认模板里带上“不要修改代码只输出审查意见”可以避免 AI 自作主张动刀改代码防止它陷入“改完一处又牵动另一处”的连锁反应。等到你确认了审查意见再专门用另一个命令模板让它执行修改每一步都是一个可确认的节点。3.3 什么时候该拆分什么时候该合并命令模板不是一次写完就完事它需要根据使用频率不断调优。高频动作要尽量拆分得更细低频动作可以合并成通用命令。比如代码审查我在早期只有一个/review后来发现安全问题和性能问题的关注点完全不一样就直接拆成security、perf、general三个子命令每个的输出顺序和重点互不相同。这样每次调用时指令更精确结果也更对路。反过来一些低频但逻辑相似的操作适合合并。比如生成 API 文档和生成 README 都属于“文档生成”用一个/gen:doc配合一个参数指定文档类型就够了不必为每种文档单独建命令。拆与合的标准只有一条它是否在反复消耗你的输入成本。如果一条命令每次使用都需要你额外补充大段说明它就该拆如果你需要维护的命令数量已经让你记不住那它就该合。4. 工作流模板与钩子从单次会话到持续交付命令模板和 CLAUDE.md 都还是在“给 AI 足够的输入”而钩子和工作流模板做的事是直接改变 AI 每轮对话的生产环境。这一步是模板体系从“好用”到“靠谱”的分水岭。4.1 会话开始时自动注入状态AI 不知道当前工作区的真实状态这是很多错觉和误判的根源。我见过 AI 说“这个文件已经删除了”但实际上文件还在也见过 AI 基于旧分支的状态做了重构建议而当前分支已经完全不同。最稳妥的办法是让它在每次会话开始时就拿到一份新鲜的 git 状态快照。我用的方案是在.claude/hooks/下放一个 session-start 脚本大致思路是会话启动时执行git status --short、git branch --show-current、git log -1 --oneline把三行结果写到一个临时状态文件里然后让 AI 先读取这个文件再回答任何问题。这个脚本很简单但效果立竿见影。它让 AI 在第一轮就具备了“当前在哪个分支、哪几个文件有改动、最近一次提交是什么”这些基本信息后来提出的问题质量明显提高至少不会再拿旧状态当现在的状态。4.2 保存文件后立即校验把质量内环做成闭环另一个让我工作量下降非常明显的 hook 是“保存后自动校验”。在开发过程中我经常需要 AI 帮我改一个 TypeScript 文件它改完我保存然后我自己跑一遍tsc --noEmit发现报了一堆类型错误再把它丢回给 AI 去修。这个循环低效而且让人烦躁因为 AI 在中间有一段是“盲目”的。加了保存后 hook逻辑变成当我对某个.ts文件执行保存动作时自动触发pnpm exec tsc --noEmit。如果校验失败把错误信息作为新的上下文返回给 AI。这样 AI 在下一轮回复里就能看到具体的错误行和错误类型直接修正代码而不需要我手动把错误粘贴过去。从质量内环的角度看这是把“改代码—跑检查—修正”三个环节变成一个连续闭环省掉了人肉搬运工的角色。这类 hook 的配置量其实不大但要注意脚本本身要做错误处理和超时控制。我踩过一个坑当保存的触发过于频繁时检查还没跑完又触发了新的检查导致进程堆积。后来我在脚本里加了锁机制检查过程中如果又收到触发事件就等前一个进程结束再做逻辑上类似一个简单的队列。没有这个锁反而会因为 hook 本身影响开发体验。4.3 多文件工作流编排第三类是工作流模板。这类模板的特点是任务天然需要跨越多个文件和多个步骤不能靠一条命令搞完。人工来做的时候还需要脑子记着一串检查点而模板可以把这个“串”固化下来。我举一个具体的例子给新模块补测试。这个任务在传统流程里至少包含五个步骤读取模块入口文件、根据导出函数列表确认待测点、生成测试骨架、跑一次覆盖率、输出覆盖率报告。没有模板时我每做一次都要向 Claude Code 重复描述整个流程它中途还经常漏步骤我也要看前一步的结果再手动触发下一步。写成工作流模板之后我只需要输入“给 src/user-service 补测试”这一句它就会按预先定义的顺序执行完整过程中间即使有分支比如某个函数没有导出接口也会按模板里预设的规则处理。这类多文件编排模板的价值不在于让 AI 一次性做完而在于让整个过程可预期、可复现。团队里任何人都可以调用同一个工作流不需要掌握写提示词的技巧也不存在“这个人写得好那个人写得差”的问题。它把个体经验变成了团队资产。5. 我在真实项目里踩过的模板坑写到这里我觉得有必要专门用一节说说失败经验。模板体系这个东西写出来看着美好实际运行起来有一堆问题尤其是当它开始被团队其他人使用、进入多个仓库之后问题会成倍放大。5.1 模板放进 Git 仓库之后队友集体报错有次我把一个个人仓库里的 .claude 目录整体复制到团队仓库一直很顺利。直到第二天早上三个同事都说自己打开会话就报错并且报错信息很含混不是直接说“文件不存在”而是会话初始化被中断。排查过程很费劲因为我本地是好的模板文件排除了语法问题命令内容也很常规。最后让同事手动执行了一次 hook 脚本才发现脚本引用了另一个内部工具的绝对路径那个工具只装在我自己的开发机上。这个事故给我三个教训。第一hook 脚本里所有外部依赖都要在本地做存在性检查不存在就输出明确的中文提示不要让错误被上层吞掉。第二模板目录里不要写绝对路径全部用相对仓库根的路径。第三任何新增的 hook 或命令都要先在一个干净环境里验证不能只在个人机器上试。后来我在模板库的 README 里加了一节“环境要求”把依赖列表写得清清楚楚团队环境才稳定下来。5.2 全局规则和项目规则打架另一个很隐蔽的坑是全局配置和项目级配置互相覆盖。Claude Code 可以在全局设置里写一些通用规则比如“回复尽量简洁”“不要主动删除文件”。这些全局规则在大部分仓库里没问题但一旦某个仓库的 CLAUDE.md 里写了相反的规则AI 的行为就可能变得不可预测。我遇到过一次真实事故一个仓库里明确写了“删除文件前必须确认”但全局规则里有一条“为了保持仓库整洁可以清理无用的文件”结果 AI 在一次清理任务里顺手删了几个其实还在用的模板文件。幸好 Git 里有历史能恢复但从那以后我把全局配置的全部规则重新过了一遍凡是和具体项目行为相关的全部移除只保留“不要在不询问的情况下修改 Git 配置”“不要执行未确认的破坏性命令”这类零风险的大原则。项目特有的规则一律下沉到仓库级 CLAUDE.md 里。5.3 上下文过载写太多也是病还遇到过一种相反方向的问题模板写得过于细致把 CLAUDE.md 撑到三四百行。信息来源包括仓库背景、团队规范、发布流程、某次事件的复盘……写完后第一天的效果极差AI 的回复变得又慢又空因为它每次都要在大量背景信息里分辨哪些和当前任务相关。后来我做了个“拆文件”的调整CLAUDE.md 只保留定位、约定、操作、禁区四块核心内容所有长篇幅的背景说明、历史决策记录、复盘文档统一放到 docs/ 目录下需要时让模型按相对路径去读取。这样既保留了信息又不污染每轮对话的上下文窗口。我建议你可以定期检查一下 CLAUDE.md 的行数超过两百行就是一个强烈的信号该拆了。5.4 一张踩坑对照表我把这几个常见问题和对应的预防办法整理成一个表格方便你自查症状根本原因解决方式hook 在队友环境里报错脚本引用了本机绝对路径或外部工具未安装脚本内做存在性检查并为外部依赖写明环境要求全局规则和项目规则冲突模板层级之间互相矛盾全局配置只保留零风险通用规则项目规则下沉到仓库级AI 回复变慢变空CLAUDE.md 过长上下文被背景信息挤爆核心模板控制在一百到两百行长文拆到 docs/ 目录命令模板找不到命名随意没有分组和前缀统一使用前缀命名法按子目录归类AI 做的和模板里不一致模板被别处的全局规则覆盖定期检查全局配置确认无冲突规则这张表不是标准答案但它覆盖了大多数团队在从个人摸索转向模板库使用时会踩到的坑。6. 模板迭代的两个原则先服务自己再服务团队最后说说模板库怎么维护。模板不是一次建好就一劳永逸的静态资产它会随着你的使用习惯和项目演进逐步变化。我总结下来有两件事对长期维护特别重要。6.1 每次手动纠正都是一次模板更新机会我有个习惯在跟 Claude Code 的会话中只要我发现自己需要补充背景信息或者 AI 做错了方向我就会在对话结束后去检查对应范围的模板有没有漏掉。如果同一类问题出现了两次我基本确定要把这个经验写进 CLAUDE.md 或对应的命令模板里。这个过程非常朴素但它是模板库真正的“生长机制”。模板不是靠你开工前一口气脑补出来的它的信息密度来自每天的真实互动。你每纠正一次就是往模板里注入一条团队级经验。时间长了模板会慢慢地从“通用说明”变成“这个项目的隐形历史”新加入的同事打开模板相当于直接继承了过去几周的试错成果。6.2 团队协作时的“共识即模板”模板库做到足够稳定之后可以把它沉淀成一个 starter 仓库或脚手架。我们团队现在所有新项目开场第一件事就是把这份模板库复制过去再修改 CLAUDE.md 里项目特有的部分。这个操作只需要一两次会话的适配时间但从那以后每天节省下的反复描述时间远超这个启动成本。对团队来说模板还有一个额外价值它把“隐性约定”显性化了。以前“为什么这个仓库不能用 npm”“为什么这个目录不能碰”这些知识都存在于某个老同事的脑中现在全写进模板任何时间翻开都能看到也不会因为人员流动而流失。这也是我坚持把模板库当作项目基础设施的原因——它不只是给 AI 读的说明更是团队的可执行共识。最后分享一个做法我在模板库里放了一个CHANGELOG.md每次新增或修改模板规则都顺手记一笔。一个月后回看你就能清楚地知道哪些规则是真正经过使用检验的哪些是一次性冲动的产物。好的模板库最终会变成那个熟谙项目脾气的同事平时不多话但一旦开口就都能说到点子上。