用AI写代码这件事大多数人的日常还停留在“复制报错信息、粘贴到对话框”的阶段但真正把Claude Code这类命令行AI编程代理用出效率的团队和个人几乎都会做同一件事整理自己的提示词模板库。这套东西在圈子里叫“claude-code-templates”它不是一个官方插件也不是某个固定仓库的名字而是一种实践方式——把项目级指令、子代理定义、斜杠命令、钩子脚本统一收拢成一套可复用、可共享、可持续迭代的模板体系。我自己的体会是模板库建得好不好直接决定了Claude Code是“高级自动补全”还是“真正能接手部分工程任务的协作者”。这篇文章我会完整展开这套模板体系的搭建思路。从Claude Code的配置机制讲起到目录设计、核心模板编写、参数化技巧再到一套完整的实操记录和问题排查清单。适合正在用Claude Code但总觉得发挥不出效果的人也适合准备在团队里统一AI协作规范的技术负责人。看完你能直接照着搭一套属于自己的模板库而不是零散地写一堆一次性的prompt。1. 为什么要建模板库从“会用”到“用得好”1.1 Claude Code的核心机制回顾Claude Code是Anthropic推出的命令行AI编程代理跑在终端里能读项目文件、执行命令、调用工具链本质上是一个拥有完整环境操作能力的AI代理。和网页版聊天不同它天然具备操作项目的权限也因此更需要被约束和引导。这里的约束和引导就是通过一系列配置文件和模板来实现的。它的指令体系有几个关键载体。第一个是CLAUDE.md这是项目根目录下的指令文件Claude Code每次启动会话都会自动读取相当于给整个会话注入“项目级行为准则”。第二个是用户级别的~/.claude/CLAUDE.md作用范围覆盖所有项目。第三个是用户自定义目录下的Markdown模板包括斜杠命令和子代理定义分别对应交互式指令和专项任务代理。第四个是hooks钩子脚本可以在特定事件触发前后自动执行外部脚本。理解了这套机制你就知道模板库并不是“把prompt存起来”那么简单。它的本质是在AI代理启动、执行、交接的每个环节都塞进一套稳定的工程规范。没有这套规范同样的任务这次做和下次做的差异可能非常大有了规范行为一致性会明显提升。1.2 三个必须解决的痛点为什么不直接用对话临时描述需求我给三个理由。第一是重复成本。代码评审、单测生成、重构、提交信息整理这些任务每周要发生几十次。每次都在终端里重新输入“请你帮我看看这次改动有没有问题”这种话效率太低了。斜杠命令把这类高频操作固化成一个/review指令触发后模板自动填充角色、流程、输出格式。第二是行为漂移。AI模型每次会话的状态都是全新的没有跨会话记忆。你这次花半小时调整好它的输出风格下次开新会话它就忘光了。模板库就是它的“长期记忆”每次启动都强制恢复到你的预期行为基线。我实测下来一个写好的模板能把新会话的“预热成本”从几百字缩减到一句命令。第三是协作标准。一个人用怎么都行一个团队用就必须有统一模板。谁负责安全审查、代码规范按什么执行、测试覆盖率至少多少这些写成模板放进仓库就是团队里“无声的约定”。新人拿到项目输入/review得到的评审标准和老手完全一致。1.3 模板体系能带来哪些实在收益从结果上看一个维护良好的模板库至少能带来三方面的提升。上下文质量提升。模板让Claude Code的注意力更集中在任务本身。我以前让它做代码评审它经常输出“这段代码看起来不错”这种废话或者通篇复述代码再给一句结论。模板里约束了“必须按bug、性能、安全、可维护性四个维度逐一排查每类至少给出一个具体的文件和行号”输出质量立刻不一样。执行稳定性提升。没有模板时它的行为会随着对话长度、措辞变化而波动。有模板时只要任务入口一致执行路径就基本一致。这一点在批量处理任务时特别重要比如一次重构二十个文件每个文件的结构和提交内容都应该是统一的。可维护性提升。prompt散落在聊天里是没法维护的但模板是文件可以版本管理、Code Review、持续改进。我自己的模板库已经迭代了半年每一次踩坑都沉淀成一条规则这比在终端里重复“纠正它的行为”要靠谱得多。2. 模板库的整体布局目录结构、命名规范与注入顺序2.1 推荐的目录结构模板库不是把一堆Markdown堆在一起它有自己的分层逻辑。我目前在实际项目中稳定使用的一套目录结构是这样的项目根目录/ ├── CLAUDE.md # 项目级指令全项目共享 ├── .claude/ │ ├── commands/ # 斜杠命令/xxx 直接触发 │ │ ├── review.md │ │ ├── test.md │ │ ├── refactor.md │ │ └── commit.md │ ├── agents/ # 子代理定义专项任务实体 │ │ ├── reviewer.md │ │ ├── tester.md │ │ └── docs-writer.md │ └── hooks/ # 钩子脚本事件触发 │ ├── pre-commit.sh │ └── lint-after-tool.sh 用户主目录/ ├── ~/.claude/ │ ├── CLAUDE.md # 全局指令所有项目生效 │ └── commands/ # 用户级斜杠命令可选这里要啰嗦一句CLAUDE.md和.claude/commands是两回事。CLAUDE.md是全项目自动加载的守则适合放“应该怎么做”commands里的模板是手动触发的“任务执行清单”适合放“具体做某件事的步骤”。很多人把两者混在一起在CLAUDE.md里写大量任务流程结果每次会话都被迫加载一段并不相关的长文本既浪费上下文窗口又容易让AI在执行其他任务时误入歧途。2.2 加载优先级与作用范围多个指令文件同时存在时遵循就近优先的叠加逻辑。用户级~/.claude/CLAUDE.md最基础项目根目录的CLAUDE.md在此基础上增强项目内的子目录也可以放CLAUDE.md做局部覆盖。实际生效的指令是逐级拼接的也就是子目录的规则会叠加在根目录规则之上。这个机制带来的实用价值是全局文件放通用底线项目文件放业务规范。我在全局CLAUDE.md里只写“不要编造不存在的文件路径”“所有代码改动必须附带解释”这类普适规则在具体项目的CLAUDE.md里才写“本项目的包管理器是pnpm”“模块位于src/modules下”“提交信息需包含Jira单号”这类项目专属约束。2.3 命名规范与团队共识模板文件的命名直接影响使用的顺畅度。我给几条原则命令名用动词开头review、test、refactor、commit一看就知道触发后干啥全小写加中划线避免大小写混用导致的记忆负担团队项目建议加统一的业务前缀比如pay-review.md、order-refactor.md避免在命令列表里分不清业务场景。文件名一旦定好斜杠命令名就跟着定了。比如.claude/commands/review.md对应/review.claude/commands/pay-review.md对应/pay-review。命令名改动意味着所有使用习惯要跟着改所以稳定命名比追求花哨重要得多。3. 高质量模板的编写要点参数化、边界与约束3.1 模板的标准结构一份优质的Claude Code模板应当包含五个固定的组成部分角色定义、任务目标、执行步骤、输出格式、约束条件。有些模板还需要第六个部分输入上下文。下面是一个代码评审模板的完整示例它展示了我上面说的五个部分如何落地--- name: review description: 对指定范围的代码改动执行多维度的代码评审 --- 你是一名资深代码评审专家重点审查改动范围的质量。 ## 任务目标 - 评审以下路径或范围的代码改动{{path}} - 改动来源{{diff}} ## 执行步骤 1. 先读取{{path}}对应文件的最新内容确认改动上下文 2. 按以下维度逐一检查当前改动 - 正确性是否存在明显的逻辑错误、空指针、越界等缺陷 - 性能是否有冗余计算、无效循环、高复杂度操作 - 安全是否存在注入风险、敏感信息硬编码、越权问题 - 可维护性命名、结构、注释是否合理 3. 对每个发现的问题给出文件、行号、问题描述、修复建议 ## 输出格式 使用Markdown表格输出至少包含四列严重级别高危/中危/低危/建议、位置文件:行号、问题描述、修复建议。修复建议必须能直接落地禁止输出“建议优化”这种空话。 ## 约束条件 - 只评估给定的{{path}}和{{diff}}范围不要扩大到整个项目 - 不输出与代码评审无关的客套话 - 每个问题必须能追溯到具体行号无法定位的写入“存疑”分类注意模板里的{{path}}和{{diff}}这是参数占位符。Claude Code在解析模板时会用实际的参数填充。定义一个良好的参数接口是模板能跨场景复用的关键。3.2 参数化设计与动态指令生成参数化模板的威力在于模板本身是静态的参数是动态的两者组合出的执行指令完全是针对当前任务定制的。设计参数时要克制不是参数越多越好而是只暴露确实会变化的字段。比如代码评审模板核心变量就是评审范围和改动内容其他所有细节都应该是固定的。参数来源可以分成三路。第一路是手动传入用户执行/review src/modules/pay.ts时src/modules/pay.ts就是参数值。第二路是自动注入比如在模板里要求AI先执行git diff把结果作为输入这样用户不需要手动粘贴diff。第三路是环境感知通过指令让AI读取当前分支名、最近提交信息、项目配置文件等自行推导出参数值。我强烈建议在模板里同时设计“自动读取”和“手动覆盖”两套机制。默认情况下AI执行git diff获取改动内容如果用户指定的范围比较特殊也允许手动传参。这个逻辑我用了一个固定句式“优先使用git diff获取最近改动若用户提供了具体文件路径则以用户提供的为准。”3.3 让AI输出可落地的结果很多模板写得挺丰满但输出结果没法用根本原因是对输出格式没有硬约束。举几个反面现象让AI列出优化点它给你三条泛泛的“建议”让它改代码它给你一段没有上下文的新函数让它整理问题它不分优先级全列在一起。输出格式约束要具体到“结构”这个层面。代码类任务可以要求“输出完整的代码块并标注需要替换的起始行号”问题类任务可以要求“必须用表格且每条记录包含优先级标签”流程类任务可以要求“先输出执行计划确认后再执行”。这些要求不算苛刻但对AI的行为约束力非常强。我实际用下来还有个心得在模板里直接给一个“输出示例”。比如重命名指标类模板我会在约束条件后面附一个12行的结果示意告诉AI“最终输出长这样”。说明性模板比描述性约束更管用因为AI对具体样例的遵循度远高于对抽象规则的遵循度。3.4 边界约束防止AI越界操作Claude Code拥有终端操作能力这是效率来源也是风险来源。模板里的约束条件不仅仅是“输出规范”更要包含权限边界。我会在每个模板里明确写出两类边界。第一类是文件范围边界。代码类任务必须限定涉及的文件集合避免AI“好心”改了不该改的文件。模板里写“只允许修改{{path}}范围内的文件其他文件一律不碰”并交代“需要改动其他文件时必须先征求用户确认”。第二类是操作边界。某些模板需要执行命令但要约束命令的类型。比如可以在约束条件中写明“只允许执行只读命令如ls、cat、git diff、git log禁止执行修改类命令”。这种约束在大规模重构场景下尤其重要防止AI在没确认的情况下把项目改得乱七八糟。提示CLAUDE.md和hooks也是边界约束的载体。全局CLAUDE.md里可以写“任何情况下不得操作.git目录”hooks里可以配置在AI调用危险命令前弹出确认。模板负责任务级约束这些文件负责环境级约束两者配合才是完整的防护体系。4. 从零搭建一套个人模板库完整实操记录4.1 初始化全局指令文件搭建模板库的第一步不是写花哨的模板而是把全局的CLAUDE.md建起来。这个文件是所有项目的共同守则所以内容要克制、通用、长期稳定。我的~/.claude/CLAUDE.md只包含这几类内容角色定位你是资深工程师回答要直接、专业、尽量精简、编程语言偏好一个新项目默认用TypeScript除非用户明确指定其他语言、通用规范不编造不存在的文件、不修改未要求的文件、不把敏感信息打印到终端、输出偏好代码块必须标注语言长的输出要先分段再细化。实操里需要注意一个问题全局指令和项目指令冲突时的处理规则要明确。我在全局文件里写了一句“项目CLAUDE.md的优先级高于本文件若两者冲突遵循项目文件”。这个规则避免了项目特定规范被全局文件覆盖的隐患。4.2 编写第一个斜杠命令模板我建议第一个模板从/review开始因为它是普适性最强、最容易看出效果的命令。咱们把上一节的评审模板精简一下塞进.claude/commands/review.md再配合参数化处理就可以直接上线。创建好文件后在终端执行# 重启Claude Code会话让模板生效 claude # 在会话中执行评审命令 /review第一次执行时会看到AI读取模板并开始逐步执行。如果模板路径写错或者没有重启会话/review会提示命令不存在。这一步是新手最容易卡壳的地方我放在后面的排查清单里专门展开。在模板积累到几个之后我会把这一类“评审、测试、重构”的常态化模板整理成一个仓库推到团队GitLab上。模板也纳入版本管理每次改进都有记录回滚也方便。4.3 配置子代理做专项场景斜杠命令适合“一次性任务流程”但更复杂的专项工作比如全天候代码审查助手、专门的文档撰写引擎更适合用子代理来承载。子代理是一类有独立人格和工具权限的代理实体它比模板的“一次性注入”更接近一个常驻虚拟团队成员。子代理定义放在.claude/agents/目录下。一个测试子代理的示例--- name: tester description: 自动化测试专家负责生成与维护单元测试和集成测试 tools: Read, Write, Bash --- 你是一个专业的测试工程师精通vitest、jest、pytest等主流测试框架。 ## 核心职责 - 根据模块代码自动生成测试用例覆盖正常路径、异常路径和边界条件 - 对测试失败场景给出诊断和修复建议不直接修改业务代码 - 确保新增测试可执行、可断言不产出无效的“恒真”用例 ## 工作方式 1. 读取目标模块梳理公开接口和依赖关系 2. 评估当前测试覆盖情况列出缺失场景 3. 生成测试代码并附加一段说明解释每个用例验证什么行为定义好子代理后在主会话中指定它处理任务就能把测试工作交给这个虚拟角色。子代理的好处是它的行为边界、工具权限、输出习惯都是独立的不会污染主会话的上下文。多个子代理协同干活时主对话只需要负责调度和汇总。4.4 用hooks实现自动化防线模板解决的是一次次会话里的“软约束”hooks解决的是会话之外的“硬防线”。hooks是一组事件驱动的脚本可以挂在AI调用工具的各个生命周期节点上。我目前最常用的是PreToolUse钩子每次AI准备执行shell命令或写文件前先触发一个检查脚本。比如一个简单的防护钩子检查AI准备写入的文件是否在允许范围内# .claude/hooks/verify-write-path.sh #!/usr/bin/env bash WRITE_PATH$1 ALLOWED_DIR$2 if [[ $WRITE_PATH ! $ALLOWED_DIR* ]]; then echo Blocked: Write outside allowed directory: $WRITE_PATH exit 1 fi exit 0hooks的实现细节需要配合Claude Code的hook配置格式使用但思路是固定的把那些“绝对不能做”的事从模板里的文字约束升级为脚本里的强制拦截。我见过有人用hooks自动在AI执行测试前先跑一遍lint也见过在AI生成代码后自动格式化。核心原则是模板管方向hooks管底线。5. 常见问题与排查技巧实录5.1 模板没有被加载或命令不存在这个问题排在我踩坑榜的第一名。“为什么我把review.md放在.claude/commands里了但执行/review提示命令不存在”原因通常是这三个一是目录层级搞错了命令文件必须放在.claude/commands/很多人放到.claude/根目录甚至项目根目录里二是会话没有重启模板加载发生在会话启动时你改了文件还在旧会话里硬试三是文件名和命令名大小写不一致比如文件名是Review.md但命令记忆成了/review。我现在的习惯是任何模板文件的增删改都先用/status确认Claude Code已经识别到新配置再执行对应命令。如果/status里没看到就退出会话重新启动。别嫌麻烦多十秒的确认能省十分钟的排查。5.2 模板里的参数没有被正确解析模板里写了{{path}}但AI当成了字面量没有替换成实际路径。这个问题的原因通常是当前版本的Claude Code对这个参数语法不支持或者参数格式需要特定的引号包裹。不同版本的参数语法确实会有一些调整我用的{{参数}}这一套在大多数场景下可用但仍需要验证当前版本的具体要求。参数解析失败时的应急方案是在模板里同时写一个“手动回退”逻辑。比如“如果{{path}}没有被正确替换请直接询问用户要处理的具体文件路径”。这个兜底条件让模板在极端情况下仍然可用不至于僵在那里。5.3 上下文太长导致模板效应衰减模板再好也架不住会话被塞满无关内容。对话一旦超过上下文窗口限制AI会开始遗忘早期的指令模板的约束力逐渐衰减。你可能会发现执行到第二个、第三个任务时AI的行为越来越“失忆”甚至忘记模板要求的输出格式。对策有两层。会话内的对策是主动做/compact压缩上下文或者干脆/clear开始新会话然后重新执行模板。模板设计的对策是让模板本身足够“短小高能”把核心约束压缩到有限的篇幅内减少被压缩算法裁掉的风险。长模板不是不行但要区分哪些是每轮都需要的硬约束哪些是特定任务的详细说明。硬约束放进CLAUDE.md详细说明放进命令模板两层配合不容易被上下文稀释。5.4 模板膨胀一份模板塞了太多任务还有一种常见问题模板越写越长今天加一个规则明天加一个场景最后一份test.md里有五百行执行任何一个小任务都要先加载完这五百行。这是模板库最危险的演化方向。我的经验是一份命令模板只负责一个任务不要把“生成测试、跑测试、修测试、分析覆盖度”塞到同一个模板里。如果这些流程频繁在一起出现正确的做法是配置子代理或者定义一条“组合命令”依次触发多个单职模板。拆分的界限是如果模板里的执行步骤超过七步大概率需要拆分。注意模板库也需要定期“减肥”。每隔两个月我会把命令列表过一遍问自己“这个模板最近用过吗”“这条规则还符合现在的项目状态吗”。没用的删掉过时的改掉才能保持整套体系的轻盈可靠。写在最后的一个建议关于模板库我真的建议大家从“小而精”开始而不是一上来就建一堆。先建一个/review、一个/commit用两个星期感受一下哪些地方不顺手再迭代。我自己最早犯的错就是一次性写了十几个模板结果绝大多数都在吃灰反而真正高频的几个没打磨到位。模板库的维护是个持续过程它应该跟着你的工作习惯一起演化——这也是它比一次性聊天气泡有价值的地方。等到某天你发现新开个会话、跑一条命令、拿到一份高质量结果的链路已经稳定了那时候整个团队可能都该用上这套模板了。