如果你正在用 Claude Code 做日常开发大概率遇到过这种情况每次让它改 bug、写单测、做审查都得先把项目背景、技术栈、代码规范重新口述一遍模型发挥全看临场状态。我一开始也是这样直到把平时反复用到的那套提示词和约束规则整理成了claude-code-templates这个模板项目才真正把终端里的 AI 从“偶尔好用的聊天框”变成了“稳定输出的协作者”。这篇文章我会从目录设计、模板语法、实操案例到踩坑记录完整拆一遍这套模板体系是怎么搭起来、怎么维护的。无论你是刚开始接触 Claude Code还是已经用了一段时间但觉得输出不稳定这篇都值得看完再动手。1. 项目定位模板到底解决了 AI 编程里的什么痛点先说清楚一个问题Claude Code 本身已经很强为什么还需要模板体系这事得从一次真实需求说起。1.1 我为什么攒下这套 claude-code-templates有段时间我每天要在三四个仓库之间切换每个项目技术栈不同、目录结构不同、规范也不同。每次开会或者写新功能我在终端里敲claude然后重复输入一大段背景说明“这个项目是 React TypeScript状态管理用的是 zustand组件在 src/components 下测试用 vitest提交前必须跑 lint。”这段话我一天能打十几遍费时不说更麻烦的是每个人都这么说但细节完全不一样——有人会说目录结构有人会忘掉测试框架模型拿到的上下文质量参差不齐。后来我把这些背景说明沉淀成了CLAUDE.md把高频操作比如“审查代码”“写测试计划”“解释某段逻辑”做成了斜杠命令。这才意识到用 Claude Code 的核心不是跟它聊天而是给它一套稳定的“工作上下文”和“操作入口”。模板体系解决的就是两个问题一是减少重复劳动每次不用重新交代背景二是保证交互质量把模型的行为约束在项目认可的范围内。另外还有一层价值是被低估的就是团队一致性。一个仓库如果只有我在用这些模板那它只是个人效率工具但当模板入库、全员共用所有人让 AI 做同一件事时AI 的输出标准和流程就统一了。代码审查该看哪几个维度、测试计划要覆盖哪些边界模板写清楚AI 就按这个来不会因为提问人表达能力不同而出现质量悬殊。1.2 模板体系的三大件CLAUDE.md、斜杠命令、Skills很多新手看到claude-code-templates这个项目名以为只是把提示词堆在一起其实它是三层结构的配合CLAUDE.md项目级/用户级的记忆文件。相当于 AI 的“入职手册”每次进入会话都会自动加载里面写项目背景、代码规范、常用命令、架构约束。斜杠命令.claude/commands/目录下的 Markdown 文件。相当于“快捷键”你在输入框敲/review就能触发预先写好的审查流程支持传参。Skills.claude/skills/目录下带SKILL.md的技能包。相当于“能力模块”模型会根据当前任务自动判断要不要调用适合封装业务专长比如“如何安全重构这个模块”“如何给这个组件写测试”。这三层各有分工CLAUDE.md 管“长期记忆和全局规则”斜杠命令管“主动触发的固定流程”Skills 管“按需激活的隐式能力”。我个人的经验是先做好前两层等遇到真正重复出现的复杂任务再考虑封装成 Skill不然一上来就追求 Skills 很容易陷入过度设计。2. 目录结构与语法拆解让模板能被 Claude Code 正确加载模板不是随便建个文件夹扔进去就完事它有固定的加载规则和格式要求。这部分我会把目录布局和文件语法拆细照着搭基本不会踩坑。2.1 一套靠谱的目录布局长什么样Claude Code 加载模板的路径分几个层级用户级配置在~/.claude/项目级配置在项目根目录的.claude/下。两个层级会在会话中合并项目级优先级更高。我维护的模板项目里最核心的目录结构是这样的claude-code-templates/ ├── .claude/ │ ├── CLAUDE.md # 项目记忆与全局规范 │ ├── settings.json # 权限、钩子等运行时配置 │ ├── commands/ │ │ ├── review.md # 代码审查命令 │ │ ├── plan.md # 编写实施计划 │ │ ├── explain.md # 解释指定模块 │ │ └── test.md # 生成测试方案 │ └── skills/ │ └── refactor-guard/ │ ├── SKILL.md # 技能定义入口 │ └── checklist.md # 辅助资源这套结构里有几个容易被忽略的点。第一commands/下的文件名就是命令名review.md对应/review命名建议用 kebab-case别用大写不然命令不容易敲。第二命令文件和 Skill 里的辅助文件只能写在.claude目录下才能被正确识别放在外面虽然也能读到但会破坏自包含性。第三settings.json不是必须的但如果你想给特定命令配置权限或者挂钩子就要用到它后面会细说。还有一个容易混淆的地方项目根目录也可以放CLAUDE.md.claude/里也可以放。两者都会被读取通常项目根目录那份写“项目背景和技术架构”.claude/CLAUDE.md写“AI 交互规范和命令说明”这样职责分离比塞一个巨型文件更好维护。2.2 Frontmatter 字段决定命令行为的元信息斜杠命令和 Skill 的 Markdown 文件都支持 YAML Frontmatter也就是文件顶部用---包裹的元信息。这部分是模板能不能“活”起来的关键我用的最多的字段就这几个字段作用示例备注description命令的描述模型靠它判断该不该触发对指定目录做一轮代码审查不写大概率命令名对不上写了也尽量具体argument-hint提示用户这个命令要传入什么参数目标目录路径例如 src/core交互时展示在命令名后面allowed-tools允许模型在该命令中使用的工具白名单Read, Grep, Glob不声明时默认继承全局配置model指定该命令走的模型类型sonnet按场景区分模型能力不是所有命令都需要agent指定由哪个子 Agent 执行code适合把命令转交给专门角色处理我给每个字段都能举出真实场景。description是最容易被新手忽略的有人写“代码审查”模型在执行时对命令意图的理解很模糊写“对指定目录做代码审查识别潜在缺陷、安全隐患和不符合项目约定的写法”就清楚得多。allowed-tools这个字段很克制但很有效给/review配上Read, Grep, Glob模型就只能读不能改从源头杜绝“审查命令顺便把代码给改了”的意外。settings.json里的权限配置和 Frontmatter 是配合使用的。比如你想让某个命令完全绕过权限确认可以在 settings 里对特定命令开白名单反过来如果命令涉及高风险操作就在 Frontmatter 里收紧工具范围。这套组合用法我在后面实操里会带到。2.3 参数占位符与正文写法模板正文就是一段标准 Markdown但里面要留出接收用户输入的“插槽”。Claude Code 支持几种占位符$ARGUMENTS接收用户在命令后输入的全部内容最常用。$1、$2等位置参数按空格取第几个参数适合固定参数顺序的场景。${1:default}这类带默认值的写法在不同工具里兼容性不一保守起见我会先给个提示让用户填。在正文里写指令的时候我有一个从始至终的原则把 AI 当成刚入职的实习生把模板当成你亲手写的任务交接文档。不能只写“请审查代码”要写清楚审查哪些维度、按什么顺序、输出什么格式、碰到什么情况要停下来问。不要怕啰嗦模板长度和输出稳定性通常成正比。这里有个容易被忽略的小细节当参数的默认值或者示例里含特殊字符时最好在前后加引号或在说明里注明“请直接传入路径”。我踩过最典型的一个坑是有次在命令里写$ARGUMENTS用户传了带空格的路径模型把路径拆成了两个参数后面排查了半天才发现是引用问题。所以我的模板里统一写$ARGUMENTS然后在argument-hint里提示“如果路径带空格请用引号包住”。3. 从零写一个“代码审查”模板的完整实操理论说了不少这部分直接上实操。我会完整走一遍怎么从场景定义开始写一个能落地的/review命令模板把它从“个人脚本”变成“团队流程”。3.1 先定义场景、输入和输出边界写模板之前先别急着码字先问四个问题这个命令给谁用输入是什么输出要什么边界在哪里拿代码审查来说使用者是项目组的开发人员输入是一个目录路径或文件路径输出是“问题清单 修改建议”边界是“只读不修改任何文件”。这四条确定后命令的行为就有了锚点。我还会额外确定一条审查的严肃程度。个人项目审查可以只列高优问题团队项目就要按“功能正确性、边界条件、安全隐患、可维护性、项目约定符合度”这几个维度全量过一遍。这一步很多人会跳过直接写 prompt结果就是命令时好时坏。我自己的体会是场景定义越具体模板的可复用性越强。你写“审查 src/core 下的模块”和写“审查 src/core/lib 下的状态管理逻辑重点关注数据流和撤销重做”后者的输出质量明显更贴近你的真实需求。3.2 写命令文件和参数传递场景定完开始写文件。我在commands/review.md里放的第一版内容大致是这样--- description: 对指定目录或文件进行系统性代码审查输出问题清单和修改建议 argument-hint: 目标路径例如 src/core allowed-tools: Read, Grep, Glob --- 你是一名拥有十年代码评审经验的高级工程师。请对目标路径 $ARGUMENTS 进行系统性代码审查。 审查前先用 Glob 和 Grep 快速确认目录结构和关键文件不要一上来就逐行精读。 审查顺序 1. 先梳理目录/模块的职责和依赖关系 2. 按以下维度逐项审查 - 功能正确性是否存在明显逻辑漏洞、错误分支、未处理边界 - 安全性是否有注入风险、敏感信息泄露、不可信的输入校验 - 可维护性命名是否清晰、函数是否过长、职责是否单一 - 项目规范文件命名、导出方式、错误处理是否符合 CLAUDE.md 约定。 输出格式要求 - 按严重程度分 [严重]、[建议]、[可选] 三档 - 每个问题必须给出文件与行号、问题说明、为什么这是问题、修改建议 - 最后附一段三句话以内的总体评价。 - 如果目录结构不清晰或者存在看不懂的依赖先停下来向我提问不要强行审查。这个版本已经能用了。注意我特意把“先停下来向我提问”写了进去这是个反直觉但很重要的设计模板不是让 AI 硬着头皮完成而是给它规定“什么情况下要主动暴露不确定性”。代码审查最怕的就是模型明明没看懂却装模作样给出一堆泛泛而谈的问题。用户在命令行敲/review src/core时src/core就会通过$ARGUMENTS注入到正文里模型拿到完整指令开始干活。这就完成了最简单的参数传递闭环。3.3 用 allowed-tools 限制模型权限第一版能用但还不够稳。我最担心的是模型在审查过程中会不会手滑改文件一旦它把“我建议把这里改一下”的念头直接变成“我来改一下”给项目带来的影响是不确定的。这时候allowed-tools就派上用场了。我在 Frontmatter 里声明allowed-tools: Read, Grep, Glob意图很明确这个命令只能读取和检索不能写文件、不能执行命令。设置了白名单之后模型再怎么发挥它也拿不到修改文件的工具。这就是我在这套模板里最喜欢用的约束方式——与其在 prompt 里反复强调“不要修改”不如直接在权限层面让它改不了。配合settings.json还能进一步细化。比如你想让这个审查命令连搜索范围都限定在某个子目录可以在 hooks 里做限制但大多数情况allowed-tools加CLAUDE.md里的约定就够用了。我见过有的团队会额外加一条规则被审查的路径出现在输出里时必须给出相对路径而不是绝对路径这样贴到 PR 评论里时大家能直接点跳转。这种小细节写进模板正文里长期用下来非常提升幸福感。3.4 把它变成团队共享的规范工作流个人命令写得再好如果不能被团队复用价值就少了一大半。模板要变成团队流程我做三步第一步把模板库推到 Git 仓库通过 submodule 或者依赖管理工具引入到各项目里。注意.claude/目录要提交但绝对不能把~/.claude/里的个人密钥和配置混进来。个人化的 hooks 和全局配置留在本地项目里只放规则本身。第二步把CLAUDE.md升级成“团队 AI 协作规范”不只是项目背景还要写明“哪些事 AI 可以直接做哪些必须停下来等人工确认”“输出里的代码示例必须先过 lint 再贴”“不要臆造项目里不存在的依赖”。这一步决定了团队所有人拿到的 AI 行为基线是不是一致的。第三步把命令挂进 hooks。比如我设置了一个PreToolUse钩子当检测到有工具要修改src/core下的文件时强制弹出确认。这样即使有人单独调/chat而没有用/review这层保护也仍然生效。模板不是孤立的它和权限、钩子合起来才构成完整的工作流。4. 常见坑与排查技巧实录使用和维护这套模板一年多踩过的坑比想象中多得多。这部分我按“现象—原因—解法”的方式整理几个高频问题。4.1 命令加载不出来或者行为诡异现象明明在.claude/commands/下放了review.md敲/review却提示未知命令或者命令弹出来了但模型完全不按模板走。原因基本逃不过三种文件路径不对、Frontmatter 格式损坏、description 写得太含糊导致模型选了别的命令。有次我批量新增命令时目录里多了一个隐藏的空文件Claude Code 把它当成非法命令结果整个目录的命令都没被加载。排查方式也很原始删掉新增的隐藏文件重进会话验证。这里我特别想提醒一点改了命令文件后一定要新开一个会话再测。Claude Code 对模板文件的缓存策略在不同版本里表现不一样我在旧版上遇到过编辑后立即测试仍然读到旧内容的情况切新会话就正常了。这个“旧内容”问题非常容易让人误判为模板没写对。4.2 上下文被模板污染输出越来越飘现象用了模板之后前面几轮输出很正常但聊着聊着模型开始跑偏甚至会重复模板里的句子。这个问题的根源往往不是模板写错了而是模板里的指令被当成了“当前对话的持续要求”。尤其是长模板里写了“你是一名资深工程师”这类身份设定模型会一直维持这个设定哪怕后续任务已经完全不在这个上下文里。我的解决思路是把模板当成“一次性任务卡”而不是“永久人设卡”。所以现在我的模板正文会明确写一句“本次回复完成后身份设定自动结束”。另外会话里如果已经跑过一次/review下次执行其他命令时我会手动用/clear清理上下文避免残留影响后续任务。4.3 hooks 和模板联动时的权限与触发问题现象在模板里限制了allowed-tools但实际运行时模型还是能改文件或者在 settings 里配了PreToolUse钩子但钩子根本没触发。先说第一种如果模板里没有声明allowed-tools模型会继承全局配置而全局配置里可能开着Write权限。这种情况不是模板失效而是你根本没在模板里声明工具白名单模型当然按最大权限来。我在 3.3 里说过白名单是声明式约束不声明等于没有。再说 hooks 触发问题。PreToolUse这类钩子匹配方式是靠工具名和工具输入里的字段不同版本对字段名的解析有差异。我踩过最乌龙的一个坑是钩子文件路径写成了相对路径终端在当前目录下能跑换到别的目录就加载不到了。排查时先把 hooks 路径写成绝对路径排除路径问题再谈其他。4.4 排查思路速查表我把日常排障的路径整理成了表格方便照着顺序查现象第一步检查第二步检查常用解法命令不识别文件是否在正确的 commands 目录Frontmatter 是否合法注意---闭合清理隐藏文件新开会话再试命令不按模板走description 是否足够具体是否有其他命令描述相近被抢先匹配重写 description加入项目专属关键词模型有越权行为Frontmatter 是否声明 allowed-toolssettings.json 全局权限是否覆盖了模板在模板显式加白名单重启会话hooks 没触发路径是绝对路径还是相对路径事件名是否匹配Pre/PostToolUse 等改绝对路径检查事件名拼写模板输出越来越偏是否使用了身份设定持续影响下文会话是否携带了过多历史残留在模板写完立即结束身份多用 /clear这张表基本覆盖了我遇到的 90% 问题。核心思路永远一句话先确认模板有没有被正确加载再确认权限有没有按预期作用最后才怀疑模型本身的理解能力。大部分所谓“模型不听话”其实是上面层级的配置问题。5. 进阶扩展模板体系还能怎么玩出效率基础模板用顺了之后我慢慢发现这套机制还能往深了做。这里分享几个我自己觉得收益最高的扩展方向。5.1 用 Skills 让 AI “按需自动介入”斜杠命令的本质是“人主动触发”但有些能力更适合让 AI 判断“什么时候该用”。这就是 Skills 的场景。比如我写前端时经常遇到组件拆分和状态管理重构重复的检查点特别多于是封装了一个refactor-guard技能里面不只有SKILL.md还有一份 checklist专门列重构前后必须确认的事项。区别在哪斜杠命令是“我让你审你就审”Skills 是“模型发现你在改这个模块自己就按重构守则来执行”。模型读SKILL.md里的名称和描述判断当前任务是否匹配匹配了就会把技能里的规则加载进来。写 Skills 的时候SKILL.md的文件名是固定的目录名才是技能名且名称和描述要尽量贴合任务触发场景。比如叫refactor-guard不如叫safe-refactor-guard再加描述“在重构核心业务模块时自动加载检查清单”这样模型命中率会高很多。5.2 把 CLAUDE.md 做成团队规范入口很多人把 CLAUDE.md 当成备忘录想到什么写什么结果文件越来越长模型真正用到的只有前几行。我采用的做法是“入口文件 分层引用”根目录CLAUDE.md只写三部分项目一句话简介、技术栈索引、指向.claude/rules/下具体规范文件的链接。.claude/rules/下按主题拆文件比如code-style.md、git-workflow.md、ai-interaction.md。在ai-interaction.md里集中定义 AI 能做什么、不能做什么。这样做的好处是模型启动时不会被海量信息淹没需要哪个规范时它可以通过读取对应文件获取细节。这个结构和写代码时的“模块化”思路是完全一样的我只在入口暴露接口具体实现按需加载。5.3 模板维护的成本与收益平衡维护模板库也需要付出成本我一度陷入过“什么都要做模板”的误区。后来给自己定了两条准则同一类操作出现三次以上才值得做模板每个模板最多迭代两个版本第二个版本还解决不了问题就回到流程设计上找原因而不是继续堆 prompt。模板不是越多越好。命令目录里躺着几十个命令模型在匹配时反而容易出现歧义用户也不知道该用哪个。我现在每个项目只保留五到八个高频命令低频需求用自然语言直接对话解决。claude-code-templates这个项目最大的收获不是拥有了多少模板文件而是摸清了“把 AI 交互规范化”这件事的边界——哪些环节能靠模板提效哪些环节必须保留人在回路里的判断。维护成本控制好了这套体系才真的能被长期用下去。另外说个小技巧我每次改完模板会顺手在命令文件里加一行“最后更新日期 原因”不是为了给别人看而是提醒自己为什么要改这个版本。几个月后回看能帮你判断这个模板是越改越好还是在同一个问题上反复打转。模板维护和写代码一样最怕的不是没有方案而是不知道为什么做了这个方案。