最近终于有空把 claude-code-templates 这套模板体系从头到尾重写了一遍。玩 claude-code 也有一阵子了刚开始我跟大多数人一样把它当成智能问答终端用遇到问题直接开问结果就是每次会话都像跟一个新同事合作它不认识我的项目结构不理解我的代码风格每次都要重新交代背景回答出来也总差点意思。后来我才慢慢搞清楚claude-code 真正值得花时间研究的不是单条提示词而是一整套 templates 机制——它才是决定 AI 协作质量的上限。这篇文章不是什么教程复读是我从零搭建模板库、跑完几个真实项目之后整理的实操记录包括模板分层逻辑、具体写法、踩坑实录和进阶玩法。适合两类人刚接触 claude-code 想直接上手的新手还有那种已经在用但总觉得“哪里不对劲”的开发者你可以把我的经验当镜子对照自查。1. 模板体系到底在解决什么问题1.1 没有模板时项目协作有多痛苦我先还原一个场景。假设你手上是一个 Express Prisma 的后端项目目录结构、命名规范、错误处理方式都是团队花了很长时间定下来的。你随手打开 claude-code 说“帮我在订单模块加一个查询接口”在没有模板的情况下它可能会按照它脑子里的“标准做法”来写结果就是接口命名风格跟项目现有代码不一致、数据库字段命名对不上、错误处理没有走你封装的统一方法。你只能一边看一边改跟改一个陌生人的代码差不多。这种痛苦的本质是一次性的上下文是空的模型只能依赖自己的通用知识来猜测你的项目到底是什么样。一次两次还好如果每天要开十几个会话每次都要把“项目背景、技术栈、目录约定、代码风格”重新说一遍成本就非常可观了。更麻烦的是不完整的背景经常导致模型做出完全偏离方向的建议——它可能建议你引入一个你根本不需要的依赖或者把已经封装好的工具函数又实现了一遍。1.2 模板不是“提示词收藏夹”很多人一听到模板就以为是把几句好用的提示词存起来。这个理解偏差不小。claude-code 里的模板本质是一套上下文装配机制它通过文件系统把最关键的背景信息自动注入每次会话把高频操作固化成可复用的命令让 AI 在动手之前就站在一个“了解项目”的起点上而不是每次从零猜起。我习惯把整个机制分成四个层次来理解。第一层是项目记忆文件也就是项目根目录下的 CLAUDE.md它定义“这个项目是谁”第二层是全局记忆文件定义“使用者是谁”也就是你个人的偏好、习惯和通用工作流第三层是命令模板放在 .claude/commands 目录下面它把“审查代码”“写提交信息”“生成计划”这类固定动作变成一句斜杠命令第四层是技能与钩子技能可以把一整套带步骤的流程交给模型执行钩子则在特定时机自动触发预设动作。四层各管一段组合起来才构成完整的模板体系。打个生活化的比方CLAUDE.md 相当于新员工入职手册说明公司的组织架构、代码规范、常用工具命令模板相当于处理日常事务的“流程表单”员工不用每次现编流程个人记忆文件相当于给员工配上“你习惯看图说话”这类沟通偏好。有这份手册和表单沟通效率自然是另一个量级。2. 核心文件结构与配置细节2.1 CLAUDE.md写给 AI 看的项目入职手册CLAUDE.md 是 claude-code 的核心记忆文件通常放在项目根目录每次启动会话时它会被自动读入上下文。很多人的第一个误区是把它当成技术文档来写恨不得把整个 README 复制进去。实际上这个文件最忌讳的恰恰是“全”。我的经验是只写五类内容。第一一句话说明项目是做什么的别超过两行。第二技术栈与核心依赖写清楚“底层是 Prisma 还是 TypeORM”因为这会直接影响生成的代码。第三目录结构与关键路径约定比如“controllers 只负责参数校验业务逻辑全部放 services 目录”这类硬约束不写模型就很容易放飞。第四常用命令包括开发启动、测试、数据库迁移、构建这些命令要一字不差给出因为它们随项目变化很大。第五代码风格和潜规则比如“错误统一返回 ApiError不允许裸 throw”。参考写法我拿一个 Node 项目举例# 项目简述 订单服务负责订单创建、支付回调与售后流程基于 Express Prisma。 # 非技术约束 - 不在代码注释中解释“为什么”只在复杂逻辑处写简短说明 - 用户可见文案统一走 i18n禁止硬编码 # 常用命令 - 开发启动npm run dev - 测试npm test - 数据库迁移npx prisma migrate dev # 代码约定 - controller 只做参数校验与响应封装 - 业务逻辑必须写在 service 层 - 数据库查询统一走 Prisma不写裸 SQL - 错误统一抛出 ApiError由全局异常处理器兜底2.2 命令模板把固定动作变成一句话如果说 CLAUDE.md 解决的是“背景信息”命令模板解决的就是“高频动作”。claude-code 支持在 .claude/commands 目录下放 Markdown 文件每个文件对应一条斜杠命令文件名不带扩展名就是命令名。放一个 review.md你就能直接输入 /review 触发代码审查流程。命令文件支持 YAML 格式的 frontmatter最重要的字段是 description 和 argument-hint前者告诉模型这个命令是干什么的后者用来提示用户应该输入什么参数。命令正文则是给模型的完整指令可以引用参数也可以引用外部文件。description 建议写成单行多行容易在解析阶段出问题这个我后面在排查章节会再提到。举个实际的 /commit 命令模板--- description: 根据本次改动生成符合 Conventional Commits 规范的提交信息 argument-hint: 改动概述可选 --- 请执行 git diff --staged 查看暂存区改动如果没有暂存内容则查看未暂存改动。 基于改动内容生成提交信息 1. 提交信息格式为 type(scope): subject例如 fix(order): 修复订单超时未回调问题 2. type 只允许 feat、fix、refactor、docs、test、chore 3. 如果有 $ARGUMENTSsubject 优先贴合用户给的概述 4. 不允许添加 Signed-off-by 或任何多余尾部说明这里最关键的处理是 $ARGUMENTS用户在斜杠命令后面输入的内容会原样替换进去。比如执行 /commit 修复订单超时问题模板里的 $ARGUMENTS 就会变成“修复订单超时问题”模型在生成提交信息时会把它当作约束条件。这样既保留了命令的通用性又允许每次微调。2.3 全局记忆文件沉淀你自己的工作习惯项目 CLAUDE.md 负责“项目视角”而全局记忆文件管的是“个人视角”。它位于用户目录下的 ~/.claude/CLAUDE.md会被所有项目自动加载。适合写那些与具体项目无关、但与你长期协作方式相关的内容。我自己的全局文件里写了这么几类第一默认回复用中文代码内注释用中文还是英文第二默认的输出格式偏好比如列计划时用 Markdown 表格还是列表第三通用安全约束比如“不执行可能破坏环境的命令执行前必须先说明后果”第四一些个人工作流的偏好比如我习惯在代码审查时先给总体评价再列具体问题。这里一定要控制这条线全局文件千万不要写跟某个项目强绑定的内容比如某个项目的专属依赖名、专有目录结构。一旦写了你会发现在其他项目里模型会莫名其妙地提起那个依赖产生严重的上下文污染。所有与项目强相关的东西都应该下沉到项目自己的 CLAUDE.md 里。3. 从零搭建一套可复用的模板库3.1 先别急着写模板先盘点需求我见过不少朋友打开编辑器就开始写模板一下午写了十几个结果两个月过去了真正用到的只有两三个。模板的核心价值是复用而复用的前提是“高频”。所以搭模板库的第一步不是写而是盘点。我的做法是把过去一个月的工作流翻一遍凡是重复出现三次以上的动作都记下来。举个典型的盘点结果高频场景对应模板触发方式新写一个模块或接口项目背景记忆 /plan 计划模板启动会话自动生效代码改完准备提交/commit 提交信息模板手动触发提交前检查改动质量/review 代码审查模板手动触发写完代码要补测试/test 测试用例生成模板手动触发排查线上报错/debug 日志分析模板手动触发从这个清单能看出来真正值得做成命令模板的是那些你几乎每天都会做的固定动作。一次性任务或者低频任务完全不值得占用模板目录的宝贵位置。3.2 搭目录五个步骤搞定基础结构盘点完之后就可以动手搭目录了。这里给一份可以直接照着做的五步流程。第一步在项目根目录创建 .claude/commands 目录mkdir -p .claude/commands第二步在项目根目录创建 CLAUDE.md并写上项目基本背景。这一步别贪多先写清楚“项目是什么、技术栈是什么、命令怎么跑”就够了。后续用到什么再补充模板是可以迭代的。第三步把高频动作的命令模板放进去。建议从一个 /plan 开始它价值最高也最容易写。之后一次只加一个加完真实用一周再决定要不要保留。第四步把自己跨项目的偏好写进 ~/.claude/CLAUDE.md注意不要跟项目 CLAUDE.md 冲突。第五步把 .claude 目录和 CLAUDE.md 纳入 Git 版本管理。这一步很多人不做但团队场景下它才是模板发挥最大价值的地方后面第 5 章会细说。目录搭好之后一个最小可用模板库就成型了。不要追求一步到位先让系统跑起来再通过真实使用慢慢打磨。3.3 写三条最核心的命令模板下面给出三条我项目里每天都会用到的模板写法可以直接抄再按自己的项目改。第一条是 /plan它的作用是让模型在动手写代码之前先产出计划避免一头扎进实现里--- description: 分析任务背景并生成实施计划 argument-hint: 任务描述 --- 请先理解项目背景与 CLAUDE.md 中的约束再根据用户的 用户需求$ARGUMENTS输出实施计划。 计划必须包含 1. 问题定位任务涉及哪些文件为什么需要改动 2. 影响面分析改动会牵动哪些关联模块和测试 3. 分步实施顺序每步做什么依赖什么前置条件 4. 风险提示哪些地方可能出错怎么规避 在用户确认计划之前不要开始写任何业务代码如果计划里需要补充信息先向我提问。第二条是 /review它解决“写完代码不知道从哪看起”的问题--- description: 对当前改动执行代码审查按项目规范给出修改建议 --- 请先运行 git diff 获取当前改动再对照 CLAUDE.md 中的约定逐项审查。 审查顺序固定为 1. 是否存在违反项目目录职责划分的问题 2. 错误处理是否走了统一封装有没有裸 throw 3. 数据库操作是否符合约定有没有绕过 Prisma 的裸 SQL 4. 命名是否与前后缀规范一致 5. 是否存在明显的边界条件遗漏 输出格式先给总体结论通过/需修改再按严重程度列出问题清单每一条都要标文件与行号并给出修改建议。不要输出“看起来很棒的代码”这种空话。第三条是 /test用来自动生成和当前改动匹配的测试用例--- description: 为本次改动生成或补充测试用例 argument-hint: 测试重点可选 --- 定位本次改动的函数与业务逻辑按项目现有测试风格生成测试用例。 要求 1. 覆盖正常路径、临界值、异常路径三类场景 2. 优先复用项目中已有的测试工具与夹具不要重复造轮子 3. 每个用例都必须有可断言的断言语句不允许空跑 4. 生成前先读取现有测试文件保持命名风格一致这三条模板覆盖了“开始前、开发中、收尾”三个阶段配合 CLAUDE.md 的背景记忆基本能把日常开发的重复沟通过程压缩掉一大半。3.4 模板与 MCP、Hooks 的配合模板体系拼图里还有两块容易被忽略MCP 和 Hooks。MCP 可以理解为给模型外接的工具集比如把项目 Wiki、数据库 Schema、内部组件库通过 MCP 暴露给模型而 Hooks 则是 claude-code 执行生命周期里特定时机的钩子最典型的是 PreCompact 钩子在上下文快被压缩前触发。我的建议是先把基础的四层模板跑顺再考虑 MCP 和 Hooks。原因很简单MCP 会引入额外的信息和配置Hooks 的调试成本也不低基础模板都没磨顺就上这些高级能力排查问题时会非常痛苦。等模板稳定之后再接入外部工具你会更容易判断问题到底出在模板还是出在工具链上。4. 常见问题与排查技巧实录4.1 模板不生效先检查这四件事模板写完不生效是最常见的问题而且原因通常特别低级。我整理了一个排查顺序照着查基本能解决。先说文件位置。命令模板必须放在 .claude/commands 目录下文件名就是命令名不带 .md 扩展名。注意是项目根目录下的隐藏目录不是系统目录也不是 src 里的子目录。放错位置是最高频的失误。然后是 frontmatter。命令文件开头的 YAML 块必须严格放在第一行前面不能有空行字段名不能拼错。description 建议写成单行多行解析容易出问题这个在前面也强调过。接着是重启会话。模板文件在会话启动时被加载如果你在会话中途新建了模板大概率要新开一个会话才能认到。这个不算 bug是它的加载机制。最后是全局与项目的覆盖问题。如果你在全局文件和项目文件里对同一件事给了相反的指令项目的 CLAUDE.md 通常会优先但更稳妥的做法是避免冲突全局只写通用偏好项目只写项目细节。症状常见原因解决方式斜杠命令不存在命令文件不在 .claude/commands 或者目录名拼错检查路径文件名去掉 .md 再试命令能触发但行为不对frontmatter 字段缺失或正文引用错误核对字段名与 $ARGUMENTS 写法模板内容没生效会话是中途创建的模板没被加载新开一个会话验证全局模板污染项目全局记忆写了项目强相关内容把项目相关内容移到项目 CLAUDE.md4.2 上下文被模板吃光越用越蠢模板用的时间一长你可能会发现一个诡异的现象模型开始变“笨”了。它经常忘记你刚交代的细节回答质量明显下降。这通常不是模型本身的问题而是上下文被大量模板和对话历史占满了模型真正用来思考的空间被压缩。我遇到过最极端的情况全局记忆文件加项目 CLAUDE.md 加每次会话自动注入的命令说明加起来超过 5000 token几乎相当于把大半身家压在了背景信息上。这会带来两个后果一是每次请求的延迟变高二是关键信息在长上下文中容易被稀释。解决办法是给模板做“瘦身”。CLAUDE.md 只保留最重要的信息低频细节放到独立文件中用 文件路径 语法按需引用而不是全部塞进自动加载区。比如下面的写法只加载真正需要的部分# 本次任务优先级 开发订单模块新增的 3 个接口先实现再优化这其实也是模板设计的一个核心原则自动加载的内容越少越好按需调用的能力越强越好。别让模板成为上下文的负担。4.3 模板约束过强代码变成流水线产品跟模板“太弱”对应的另一极是“太强”。我在早期把模板写得特别详细恨不得每一步都规定死结果模型生成的代码高度趋同注释啰嗦扩展点几乎不存在改一个参数要动半层结构。模板把模型的判断力给“自动化”掉了。后来我调整了原则模板只定义约束和边界不定义实现细节。比如代码风格可以规定“不使用 magic number常量必须集中定义”但不需要规定每个函数怎么写错误处理可以规定“统一走 ApiError”但不规定每个模块内部怎么分支。边界管住剩下交给模型根据具体问题发挥。还有一个细节是显式禁止废话。很多模板生成的代码里会有大量重复注释什么“检查参数是否合法”这种跟代码一模一样的话。我会在 CLAUDE.md 里明确写一句“注释只解释复杂逻辑的目的不重复描述代码行为”模型在生成时就会收敛很多。4.4 多项目、多语言场景下的隔离策略同时维护好几个项目的人都会遇到一个问题全局模板和项目模板打架。比如你在 Node 项目的全局文件里写了“依赖统一走 npm”结果切到 Python 项目时模型还在念叨 npm这就是典型的上下文污染。我的隔离方案分三层。第一层项目 CLAUDE.md 只写技术栈相关的东西包括语言、框架、包管理器这些跟项目绑定的信息第二层全局文件只写与语言无关的协作偏好比如中文回复、输出格式、审查顺序第三层如果多个项目共享一套子模板比如几条通用的代码风格约定可以抽成单独的模板文件用加载指令在需要时引用。这样做的好处是切换项目时不需要维护两套完全不同的模板只需要通过各自的 CLAUDE.md 把通用的部分“点”进来。隔离做得好不好直接决定了多项目场景下模板是否可用。5. 进阶玩法与我的真实心得5.1 把模板库纳入版本管理模板库跟代码库一样值得纳入 Git 管理。项目里的 .claude 和 CLAUDE.md 可以直接提交到项目仓库新成员 clone 下来就能获得全套项目上下文不需要口头交接。团队场景里这个收益非常明显新人第一次跑项目的理解成本会从“翻文档 问老人”降到“直接开问”。全局模板的管理可以用 dotfiles 的思路把 ~/.claude/CLAUDE.md 和自定义命令目录做成一个独立仓库再通过软链接同步到用户目录。我用的是一个很轻的做法mkdir -p ~/dotfiles/claude cp ~/.claude/CLAUDE.md ~/dotfiles/claude/ ln -sf ~/dotfiles/claude/CLAUDE.md ~/.claude/CLAUDE.md这样换机器、换环境时同步一遍仓库就相当于把整套路迁移过去了。配置文件也可以放进仓库里配合脚本做环境初始化。模板是你的第二大脑让它跟着 Git 走你走到哪它就在哪。5.2 模板不是写完就完它应该是活的模板跟代码一样需要持续迭代。我给自己定的维护节奏是这样的每次会话里如果同一个问题被纠正了两次就把它记下来等有空的时候沉淀到对应模板里如果某个模板连续三个月没用过就狠下心来删掉它大概率已经过时了。迭代的原则是“少即是多”。模板的核心不是让模型多干活而是让模型在正确的方向上下力气不是把每条指令都写出来而是把容易跑偏的关键路径卡住。好的模板是越用越薄、越用越准的而不是越堆越厚。5.3 关于模板效果的个人体会把 claude-code-templates 这套体系跑顺之后我最直观的感受是它不是在给模型加限制而是在给模型减负。过去模型要一边猜项目背景一边写代码现在它只需要专注于任务本身。不管是个人开发者还是小团队都值得花一点时间把模板库搭起来它会成为你使用 claude-code 时最划算的一笔投入。最后再分享一个小技巧不要一开始就追求“完整模板库”先从一个 CLAUDE.md 加一个 /plan 命令开始真实使用一周你自然会发现哪里该加、哪里该删。模板的成长速度和你的使用深度是正相关的用得越狠它越好用。