我平时大部分编码工作都已经挪到终端里交给AI去做了代码生成、重构、单测、审查现在都是先想清楚再让 AI 动手。但用得越多越发现里面有个绕不开的问题同样的任务每次都要把边界、约束、输出格式重新描述一遍偶尔还会因为描述不到位让 AI 自由发挥结果完全没法用。后来我把常见的编码任务整理成一套模板慢慢就沉淀出了 claude-code-templates 这个项目。它本质上是一套给 Claude Code 用的“工作流脚手架”让 AI 在项目里干重复任务的时候不需要重新交代上下文而是像按按钮一样调用预设的指令模板、CLI 封装和 Agent 工作流。这套模板适合谁用如果你已经在用 Claude Code 做日常开发但觉得每次对话质量忽高忽低、输出格式不稳定那这篇文章就是写给你的。如果你是刚接触终端 AI 编程的新手也可以先从这里理解“怎么用工程化的思路管好 AI 的输入”避免一上来就走弯路。我会把整体设计思路、目录结构、模板写法和踩过的坑都拆开讲。1. 项目整体设计与思路拆解1.1 为什么需要一套“模板工程”而不是随手写 Prompt单次让 AI 改几行代码确实不需要模板直接聊就行。但一旦任务开始重复状态就变了。以代码审查为例我每次审查代码时都要告诉 AI 项目用了什么语言、框架、代码风格、审查重点、输出格式这段话大概 200 到 400 字日积月累就是巨大的重复劳动而且每次上下文稍微不一致审查标准就跟着飘。项目的核心动机就是把这类“隐性经验”固化下来。模板不是简单的提示词复制粘贴而是把任务边界、判断标准、交付物格式、质量红线全部写清楚。Claude Code 本身是会话式 AI一套好的模板相当于给它建立了一个“任务说明书”让它一上来就知道自己该干什么、不该干什么、交付什么样的结果。我在设计这套模板时还观察到另一个问题常规的提示词模板只能约束对话内容但无法约束运行方式。比如批量处理多个文件时我希望用脚本遍历仓库需要读 Git 历史时我希望 AI 自动调用命令而不是自己猜。这时只有提示词模板远远不够还需要 CLI 层面和 Agent 层面的配合。所以 claude-code-templates 最终被设计成一个三层结构用户提示词模板、CLI 命令封装、Agent 工作流。三个层次各管各的事又能自由组合这比单纯一个 prompts.md 文件要实用得多。1.2 三层模板结构用户提示词、CLI 封装、Agent 工作流第一层是用户提示词模板也就是给 AI 看的任务描述。我把它放在templates/目录下按任务类型划分例如code-review/、refactor/、test-generation/、dependency-upgrade/。每个任务类型下都有一个或多个 markdown 文件里面写清任务目标、输入变量、输出格式、约束条件和参考示例。第二层是 CLI 封装。Claude Code 支持通过命令行直接调用例如claude -p 提示词这种非交互式模式。CLI 封装做的事情是把常用的操作变成一行命令比如把“审查某个文件的代码质量”封装成review ./src/foo.ts内部再拼装模板内容把文件路径作为变量注入提示词最后把输出写到固定位置或直接打印到终端。第三层是 Agent 工作流。当任务不是“一次对话”能完成的时候比如“批量重构多个模块并逐个验证编译”就需要把多步骤任务编排起来。这里我用 Claude Code 的 Agent 功能让一个 Agent 负责调度读模板、跑命令、验证结果、继续下一步。三层结构的价值在于解耦。提示词模板可以独立演进CLI 命令可以复用多个模板Agent 工作流也可以换不同的模板。改一行提示词不用动命令脚本加一个任务类型也不用改 Agent 逻辑。这就是我把项目叫做 templates 而不是 configurations 的原因它本质上是“可插拔的 AI 任务组件”。1.3 为什么不用单一提示词文件一揽子解决搭建初期我想过把所有的任务描述全部塞进一个大文件里让 Claude Code 读这个文件再根据对话理解自行决定用哪一段。试了一周就放弃了原因很现实文件越大AI 越容易“挑选”和自己最像的片段但经常挑不到最合适的而且修改的时候总担心破坏别的任务最终导致谁都不敢动这个文件。拆分成独立模板后一个文件只负责一件事长度基本控制在 100 到 250 行之间。AI 上下文窗口虽然大但塞进来的内容越短信噪比越高输出质量越可控。还有一个附加好处模板可以单独测试。刚写完“单元测试生成模板”的时候我可以只测试这一个而不需要担心其他模板干扰结果。这样迭代速度很快质量问题也容易定位。还有一层考虑是版本控制。独立的小文件在 Git 里 diff 起来非常清晰团队协作时也不会为了一个任务改文件名冲突。单一文件模式下两个人同时改一个文件几乎是灾难。2. 核心细节解析与实操要点2.1 目录布局与文件命名规范这套模板库的目录结构是我反复调整过的现在的方案适合绝大多数团队直接抄作业。根目录下按职责划分区块顶部是README.md说明用法接下来是实际内容目录。claude-code-templates/ ├── README.md ├── templates/ │ ├── code-review/ │ │ ├── pr-review.md │ │ └── full-file-review.md │ ├── refactor/ │ │ ├── extract-function.md │ │ ├── rename-symbol.md │ │ └── split-module.md │ ├── test-generation/ │ │ ├── unit-test.md │ │ └── integration-test.md │ └── dependency-upgrade/ │ └── bump-version.md ├── skulls/ │ ├── review │ ├── gen-test │ └── refactor-extract ├── agents/ │ ├── code-review-agent.md │ └── refactor-agent.md └── .claude/ ├── commands/ │ ├── review.md │ └── regen.md └── AGENTS.md这套布局有几个细节值得注意。第一所有文件和目录名都用小写连字符避免大小写敏感系统上出问题第二模板文件内混合使用 frontmatter 和正文frontmatter 记录元信息正文记录具体的任务指令第三skulls/目录存放无扩展名的 shell 脚本方便直接调用。skulls这个词其实是从“命令骨架”借来的意思表示这些脚本是没有业务逻辑的纯包装层。2.2 提示词模板的关键写法与变量处理写提示词模板本质上是在写一份“精确的任务规格说明”。我在实践中总结出四个要点缺一不可。第一任务边界要写在最前面。模板开头先明确“你的任务是 X不需要做 Y不要擅自修改 Z”。这一步能显著减少 AI 的自由发挥空间。比如代码审查模板里会写只审查逻辑错误、性能问题和潜在 Bug不做代码风格建议不重写代码。因为风格建议经常和团队 eslint 配置冲突AI 一旦开始建议风格问题会把真正重要的逻辑问题淹没。第二输入变量必须显式声明。我用{{变量名}}作为占位符在模板正文中直接引用。Claude Code 的 CLI 模式支持通过 stdin 传入上下文但更稳的做法是在提示词中明确告诉 AI 变量的含义和数据位置让它在需要时再去读取文件而不是把整个文件内容塞进去。我这里举个反例如果直接把文件内容拼接到提示词里上下文一下子就被消耗掉了而且 AI 容易把内容“背”下来而不是“看”进去。第三输出格式要硬约束。在模板里写明“最后必须返回一个包含 summary、issues 和 suggestions 三个字段的 JSON 对象”并且给一个示例。对于需要同时给人看和给机器解析的场景我甚至会要求 AI 同时输出一份 Markdown 报告和一份 JSON 机器摘要。这样做的好处是后续处理、CI 集成就非常方便AI 的输出可以直接被脚本消费。第四给 few-shot 示例。代码审查模板里附上一条“好”示例和一条“差”示例能明显提升输出质量。示例不需要多两三条足够关键是展示“什么是符合预期的交付物”。2.3 CLI 封装与 shell 集成要点CLI 封装是很多模板库容易忽略的部分但实际使用体验的差距就在这里。手动复制模板内容、粘贴到对话中和直接运行./skulls/review src/foo.ts完全不是一种效率级别。封装脚本的核心逻辑非常简单先用参数解析拿到目标文件或目标目录然后读取对应的模板文件把变量替换进去最后调用claude -p并处理输出。但有几个细节必须处理到位。第一变量替换不能用 sed 暴力替换。模板里的变量值可能含有特殊字符比如路径、代码片段直接 sed 会破坏整个提示词。我用的是简单脚本比如先读取模板和数据文件再用 Python 或者 Node 脚本做 safe substitution避免转义问题。第二超时处理。claude -p处理较大任务时可能耗时较长脚本需要设置合理超时避免终端一直挂着。第三输出收集不能只打 stdout。我建议把 AI 输出写入文件同时保留终端日志这样排查问题的时候有个凭证。关于和 CI 的集成我通常把skulls/gen-test这类命令暴露到 CI 流程里通过--format json输出测试生成结果再交给后续脚本解析。这里想特别提一点模板库里的 CLI 封装尽量做成“无状态”的即每次调用都是全新流程不依赖环境变量之外的状态。无状态的脚本更容易调试、更容易测试也不容易出现隐藏的全局副作用。3. 实操过程与核心环节实现3.1 初始化模板库从零到可用的骨架搭建我第一次搭这套模板库的时候犯了一个典型错误一上来就闷头写模板提示词写了三天发现整个库没法用——因为脚本、模板、命令之间没有串起来。后来我总结出一个更稳妥的顺序先搭骨架后填内容。第一步是初始化目录结构和 Git 仓库。我习惯把模板库放进主项目仓库里的一个子目录而不是独立仓库。原因是模板与项目强相关——不同项目用的框架、语言、CI 都不同模板脱离了项目就失去意义。开发时先在子目录里创建结构mkdir -p claude-code-templates/{templates,skulls,agents,.claude/commands} cd claude-code-templates git init touch README.md第二步是建立全局规则文件.claude/AGENTS.md。这个文件的作用是定义模板库自身的约定Claude Code 读到它之后会遵循里面的规则。比如我在这里写了“所有模板文件必须包含 frontmatter 中的 name、description、version 三个字段”“所有输出格式默认 JSONMarkdown 双轨制”等规则。这样以后我让 Claude Code 帮我新建模板的时候它生成的模板也会自动符合项目规范。第三步是写一个概念验证用的最小模板。我挑最简单的“依赖版本检查”作为第一个模板因为它的输入输出都非常简单项目路径作为输入GLI 或者 NPM 版本更新列表作为输出。先跑通“模板读取、变量注入、CLI 调用、结果输出”整个链路再逐步增加复杂模板。这个思路和写程序是一样的先打通主路径再填充分支逻辑。3.2 一个高质量模板的完整开发过程以代码审查为例用代码审查模板来展示完整的开发流程因为它是使用频率最高、也最能体现模板价值的场景。整个开发过程分为设计、写模板、测试、迭代四个阶段。设计阶段先明确模板的目标用户和触发方式。我的设计是用户运行./skulls/review 文件路径脚本读取templates/code-review/full-file-review.md注入文件路径参数调用 Claude Code 审查最终输出一份包含 JSON 摘要和 Markdown 报告的审查结果。写模板是核心工作。完整模板内容如下我拆开讲细节--- name: full-file-review description: 对指定文件做完整代码审查输出 JSON 摘要和 Markdown 报告 version: 1.2.0 --- # 代码审查任务 你的任务是审查 {{file_path}} 这个文件并输出审查结果。这个文件属于{{project_language}}项目。 ## 审查范围 只关注以下方面 1. 逻辑错误和边界条件缺失 2. 潜在的并发问题或资源泄漏 3. 性能瓶颈特别是循环内做 IO 操作 4. 安全漏洞注入、权限绕过、敏感信息泄露 不需要关注以下方面 1. 代码风格、格式化问题 2. 命名建议 3. 性能微优化除非是 O(n) 以上级别的复杂度问题 ## 输入 文件路径{{file_path}} ## 输出要求 你必须返回两部分内容 第一部分是 JSON 摘要格式如下 json { file: 被审查的文件路径, issue_count: 问题总数, critical_count: 严重问题数, warning_count: 警告问题数, suggestion_count: 建议数, issues: [ { severity: critical|warning|suggestion, line: 行号或代码段位置, type: bug|performance|security|logic, description: 问题描述, recommendation: 修复建议 } ] }第二部分是 Markdown 报告按严重程度从高到低排列每个问题需要有问题所在的位置行号或函数名、问题描述、为什么这是一个问题、修复建议。示例参考以下输出格式示例节选 ...此处给出 2-3 个带正确格式的示例这个模板设计有几个关键决策点。首先是“审查范围”的严格定义这直接决定了 AI 会不会跑偏。其次是输出双轨制JSON 给机器解析Markdown 给人阅读在 CI 中可以直接对 JSON 做断言统计。最后是示例部分这个部分很多新手觉得无所谓但我测试下来有没有示例对输出稳定性的影响巨大。示例不需要完整覆盖所有场景但必须覆盖格式、语气和详细程度。 模板写好之后立刻进入测试环节。我会用三个不同的文件做测试一个正常的小文件、一个有明显 bug 的中型文件、一个带安全漏洞的边界文件。观察输出质量是否符合预期。测试中特别关注两点一是 AI 是否按照要求只做指定范围的审查二是 JSON 是否严格可被 jq 解析。如果 JSON 格式乱了就说明模板中的格式约束不够强需要加更明确的指令或者在示例中强化结构。 要让模板进入“稳定状态”通常需要迭代两到三轮。第一轮可能会出现输出格式跑偏的问题第二轮修正后可能又会发现审查范围被过度放大第三轮基本稳定。稳定之后我会把测试用例放进 tests/ 目录后续再修改模板时可以直接回归。 ### 3.3 AGENTS.md 规则文件与记忆机制配置 Claude Code 有一个比较实用但不常被提起的机制它会自动读取项目里的 CLAUDE.md 或 .claude/AGENTS.md 文件并把里面的内容作为全局上下文放进每次对话。这个机制对模板库非常友好——它相当于给 AI 做了一个“常驻记忆”让 AI 不用每次从零理解项目背景。 CLAUDE.md 和 .claude/AGENTS.md 的区别在于CLAUDE.md 更适合放项目级的通用说明比如技术栈、构建命令、目录结构AGENTS.md 则更适合放 Agent 的协作规则和行为约束。我自己的实践中两个文件都会用但内容刻意错开。CLAUDE.md 放“项目是什么”的信息AGENTS.md 放“AI 应该怎样运行”的规则。 下面是 AGENTS.md 中的核心规则片段 markdown # Agent 运行规则 1. 当用户请求的任务对应 templates/ 目录中的模板时必须调用对应模板不允许脱离模板自行发挥。 2. 所有输出严格遵循模板中定义的格式。如果模板定义了 JSON 输出格式禁止在 JSON 之外添加额外文字。 3. 执行代码操作前必须先确认命令不擅自修改未指定的目录。 4. 如果发现需要修改文件先评估改动范围在改动前用一句话说明将修改哪些文件和修改原因。 5. 模板中的变量以 {{variable}} 形式出现运行环境会负责注入不要把它当作有效的 shell 语法。 6. 使用 skulls/ 下的脚本作为唯一入口。除非用户明确要求否则不要通过写死命令的方式操作。这些规则最初是我项目里实际遇到的问题的解决方案。比如第一条规则是为了防止 AI 在聊天记录中看到类似任务就直接按记忆做而不是走模板流程这会导致输出越来越不稳定第二条规则是为了保证机器可解析的可靠性第三条和第四条是为了限制 AI 的操作边界防止它擅自改掉不该改的文件。写AGENTS.md的时候有一点要特别注意规则要具体、要能被执行不要写空泛的“请遵循最佳实践”这类话。AI 无法理解“最佳实践”这种模糊概念但能理解“输出 JSON 时禁止附加额外文字”这种确定性指令。记忆机制的另一个层面是context管理。Claude Code 在长会话中可能出现“遗忘”前面约定模板库里每个脚本都是独立进程天然规避了这个问题。所以我更推荐把每个任务做成独立的 CLI 调用而不是在一个长的交互式会话里连续做多个任务。3.4 自定义 slash command 的注册实例Claude Code 支持自定义 slash command格式就是普通的 Markdown 文件放在.claude/commands/目录下文件名不带扩展名部分作为命令名。比如创建一个.claude/commands/review.md文件后在交互式聊天框中输入/review src/foo.ts就能触发这个命令。这个机制比纯 CLI 脚本更友好因为它在交互界面里直接可用不需要切换到终端手敲命令。但它的能力边界和 CLI 略有不同slash command 更偏向于“对话上下文”的注入而 CLI 脚本更偏向于“独立进程”的执行。两种方式我都在用一般建议是重任务用 CLI 脚本轻任务用 slash command。一个典型的轻任务 slash command 是“生成提交信息”内容如下--- name: commit-message description: 根据 git diff 生成规范的提交信息 --- 请根据当前分支的 git diff生成一个符合 Conventional Commits 规范的提交信息。要求如下 1. 类型可选feat、fix、refactor、test、docs、chore 2. 范围scope使用变更模块的名称 3. 正文描述变更动机而不是只罗列改了什么文件 当前 diff 如下这个命令的好处是它保留了交互上下文Claude Code 会自动拼接现有的对话历史所以不需要把 git diff 手动粘贴进去。不过它的可编程能力有限无法做变量替换因此复杂任务还是交给 CLI 脚本更稳妥。实用建议是把两者的场景分清楚。slash command 适合“需要我确认后再做”的任务CLI 脚本适合“直接输出结果到标准输出或文件”的任务。比如代码审查这种输出很长、需要进一步分析的任务我会用 CLI 脚本而生成提交信息、解释某段代码这种轻量交互任务我会用 slash command。4. 常见问题与排查技巧实录4.1 模板被忽略或没有生效的原因排查模板库用了一段时间我遇到最多的问题就是“模板明明写了但 AI 不按模板走”。排查下来本质上无非三种原因。第一种是模板文件格式问题。Claude Code 对 slash command 文件和普通模板文件有不同的解析逻辑如果 frontmatter 格式错误比如name字段缺失或者 YAML 语法错误AI 可能干脆忽略整个文件。解决方法是严格校验 frontmatter 的字段完整性和格式不要随手写。我还在自己的AGENTS.md里加了规则AI 协助修改模板时也要自动检查 frontmatter 完整性。第二种是命名冲突。如果.claude/commands/下的命令名和内置命令或 shell 别名冲突AI 可能会优先执行内置行为。比如我想用/check做代码检查结果它和 Claude Code 自带的命令冲突了。排查方法是运行claude /help查看命令列表确认自定义命令是否被加载。第三种是上下文干扰。交互式会话中如果之前聊了很多无关话题AI 可能被历史上下文带偏即使你调用了模板也不完全执行。这个问题的解决方案是尽量用 CLI 脚本而非交互式输入把模板内容通过-p参数注入。我自己实测下来非交互模式下模板的执行成功率显著高于交互模式。4.2 输出格式不稳定JSON 解析失败怎么办在我早期的模板版本里AI 返回的 JSON 经常带着 Markdown 代码块标记或者夹杂着几句解释文字直接导致jq解析失败。这是提示词工程中一个经典问题模型很“听话”但“听话”的方式不是硬格式而是自然语言。解决这个问题需要多管齐下。第一模板中明确写“不要输出任何解释文字直接从 JSON 开始输出”并且在示例中展示“完整的 JSON 输出是什么样的”。第二注入到提示词的示例必须和真实场景高度相似让模型学到的是“输出风格”而不是“输出内容”。第三在接受输出的脚本里加防御性处理先剥离可能的 Markdown 代码块标记再尝试解析 JSON。这里有一个比较实用的技巧在AGENTS.md里加上“JSON 输出必须内联禁止使用 Markdown 代码块包裹”这种硬性规则。规则写得越绝对模型执行率越高。模糊的表达如“请保证输出格式正确”远不如“禁止在 JSON 前后输出任何其他字符”有效。4.3 团队协作中的模板库维护问题当多个人共用一个模板库时最容易出现的问题是“模板漂移”。每个人都有自己的使用习惯看到不满意的输出就顺手改模板改着改着同一个任务就出现了好几个互不兼容的版本。我的解决方法是把模板库当作正式代码来管理。模板修改必须走 Git 分支和 MR 流程评审人需要关注的不只是文字修改更重要的是输出格式是否保持兼容。CI 里加了一个简单的校验脚本检查所有模板的 frontmatter 是否完整、引用关系是否断裂、是否有冗余文件。这些措施执行之后团队内部模板的可持续性好多了不用天天担心谁又把模板改坏了。另外一点模板库中尽量用相对路径不要用绝对路径。不同成员的开发环境路径完全不同脚本里一旦写死路径换个人就崩。所有输入都通过参数传递脚本输出目录默认定位到当前仓库的相对路径这样在不同平台和环境下都能正常工作。4.4 应用场景扩展与安全边界模板库完全做好之后可以应用到很多场景不必局限在代码审查和重构。我目前已经扩展了几个场景CI 失败日志分析、依赖安全公告检查、API 契约变更检测、数据库迁移脚本评审。每个新场景的接入方式都是一样的写模板、做 CLI 封装、加 Agent 工作流。但在扩展过程中必须注意安全边界。首先要明确 AI 的操作权限边界模板中会调用 Claude Code 的能力去执行命令、修改文件如果模板写得不够严格AI 可能会擅自执行危险操作。我建议在AGENTS.md中写清楚哪些目录是只读的、哪些命令需要人工确认。其次妥善管理密钥和敏感信息永远不要在模板或脚本里硬编码 API Key 或数据库凭证所有敏感信息通过环境变量注入。第三对于 AI 自动生成的代码变更必须配合人工审查流程特别是数据库变更和生产环境相关的修改。说到底模板库起到的是“放大”作用它会放大 AI 的能力也会放大 AI 的错误。安全规则不是摆设而是刚需。5. 场景化模板示例从命令行到端到端工作流5.1 一个完整的重构工作流用“提取函数”这个最常见的重构场景展示模板库如何把端到端工作流串起来。需求是把某个大型函数拆成多个小函数同时保证逻辑不变。这个任务适合用 Agent 工作流来处理因为涉及读文件、分析依赖、修改代码、重新编译、对比行为等多个步骤。Agent 工作流文件如下# 提取函数 Agent 工作流 ## 输入 - 源文件: {{source_file}} - 函数名或行号范围: {{function_scope}} ## 步骤 1. 读取源文件定位目标函数分析函数内部依赖关系。 2. 识别可提取的独立逻辑块评估是否有共享变量或闭包依赖。 3. 向用户提交提取方案包括新函数名称、参数列表、返回值设计。 4. 用户确认后执行提取操作。 5. 修改完成后运行测试和编译命令确认无回归。 6. 输出 refactor 报告包括变更文件列表、变更行数、测试结果。这个 Agent 工作流结合了代码分析、方案确认、执行修改和验证测试。关键点是第三步的“向用户提交提取方案”这是一道人工确认关卡能有效避免 AI 大范围重构导致的不可控风险。我踩过不少次没有确认关卡、AI 直接大改代码的坑所以后来所有涉及代码修改的工作流都会加入一道确认步骤。5.2 从人工复制到模板库的转变过程一些读者可能会想我现在直接用 Claude Code 也能做这些任务为什么要花时间搭模板库我自己的答案是单次任务确实不需要但如果你一个月要执行几十次同一类任务模板库的时间投入很快就回本了。以测试生成为例以前我每次都要在对话框里描述“请帮我生成单元测试覆盖这些分支使用 Jest 框架遵循 AAA 模式”然后还要花时间纠正格式。有了模板之后只需运行./skulls/gen-test src/utils/format.tsAI 自动读取模板、自动生成符合团队标准的测试代码。生产效率和输出质量都稳定多了。一个值得留意的心得是模板库和 AI 的发展是相辅相成的。随着 AI 模型能力提升模板的写法也在演进。早期模板需要写很多约束性指令现在模型更聪明模板反而可以更注重“任务意图”的表达少写限制性话术。保持模板轻量、聚焦于意图本身实际效果反而比堆砌指令更好。我个人维护这套模板库的时间越长越发现它本质上是在“把自己的判断标准传给 AI”。团队协作里这是非常有价值的资产不是所有人都能清晰地表达什么叫“好的代码审查”但模板库能把这个标尺落地。所以如果你已经在用 Claude Code不妨从自己最高频的 3 个任务开始试着把每一次的输入整理成模板再用命令行封装起来你会明显感觉到效率的差别。