如果你最近逛技术社区应该总能看到claude-code-templates这个关键词。乍一看它像是某个抢手的 GitHub 仓库其实它更像是一类正在快速蔓延的实践把 Claude Code 这个终端里的 AI 编程代理从“每次现场组织 prompt 的裸奔状态”变成一套有目录、有版本、能团队共享的模板资产。我第一次意识到这件事是在一个朋友的 dotfiles 仓库里看到.claude/commands目录里面躺着十几个 markdown 文件每个文件名就是一种常见任务review、commit、refactor、test……那一刻我才明白拉开 AI 编程效率差距的往往不是谁更会聊天而是谁更会沉淀 prompt。这篇文章不聊安装教程重点讲讲怎么从零搭一套属于自己的claude-code-templates体系覆盖项目指令、slash command、参数传递和常见坑都是实际跑过之后沉淀下来的东西。1. 为什么需要一套 Claude Code 模板体系1.1 工具只是起点稳定输出靠的是稳定输入Claude Code 的能力很强它可以读项目文件、改代码、跑测试、执行命令甚至跨文件重构。但你有没有发现同一个任务不同人用它效果天差地别。让 Claude Code“帮我修 bug”它能给你列出一堆可能性让它“根据失败用例、错误堆栈和相关模块定位根因并给出改动方案”结果质量就完全不一样。这里的差距不是模型能力而是上下文组织能力。一个复杂工程任务需要先读哪些文件、按什么顺序读、什么算完成、什么算失败如果不提前固化成模板AI 每次都要盲猜。claude-code-templates的核心就是把优秀工程师拿到需求后的思考过程固化下来不是一段简单的祈使句而是一整套带工作流、检查清单、输出约束的指令。可以把这个思路理解成“上下文工程”。Prompt engineering 解决单轮对话里的表达问题上下文工程解决一个完整任务周期里的信息供给问题。模板的价值在于它保证了每一次系统调用的输入质量都稳定。输入稳输出才会稳。1.2 少写废话本质上是省 token、省时间很多人对模板有个误解觉得模板就是越长越细越好。我在实际使用中的经验是模板要长在“方法论”上而不是长在“废话描述”上。比如你写“请以一名资深运维专家的身份认真分析这个项目的部署问题注意要全面、深入、不要遗漏任何细节”这句话看着有道理其实什么约束都没给。AI 输出会非常发散而且极不稳定。相比之下“先看docker-compose.yml再查最近 100 行日志按FAILED、TIMEOUT、RETRY三个维度归类”这种指令信息密度显然更高。模板化还有一个额外收益减少每轮任务的 token 占用。Slash command 相当于把一大段反复粘贴的任务描述压缩成一个命令名。命令内部可以引用项目的CLAUDE.md让 Claude 自动补齐项目背景不用你手动复制粘贴一屏背景资料。长期跑下来省下的 token 和时间非常可观。2. 模板体系的分层设计从命令到项目指令2.1 第一层Slash Command 通用模板我最先开始整理的就是 slash command。在 Claude Code 里你可以在.claude/commands/目录下放 markdown 文件文件名就是命令名。比如新建一个review.md在对话中输入/reviewClaude 就会把文件内容作为指令来处理。这一层的定位是“与项目无关的通用方法论”。比如代码审查、提交信息生成、单元测试补写、重构脚手架这类任务不管项目是 React 还是 Python方法论都差不多。通用模板里不应该出现具体业务名词而是写清楚工作流和判断规则。写文件时我习惯在顶部给一段 frontmatter至少包含命令描述和参数提示。例如--- description: Review changed files on the current branch argument-hint: [optional commit range] ---需要注意不同版本对 frontmatter 字段的支持度不一样description和argument-hint是相对稳定的基础字段。更多高级字段以你当前版本的官方文档为准。frontmatter 下面才是正文正文就是一段结构清晰的指令。2.2 第二层CLAUDE.md 项目记忆模板Slash command 之所以能做到通用是因为它把“项目背景”和“工作方法”做了分离。项目背景不应该塞进命令模板里而应该放进CLAUDE.md。CLAUDE.md是 Claude Code 在进入项目后会自动读取的说明文件。它适合放这些内容项目架构图或者核心目录说明常用命令开发、构建、测试、类型检查代码规范命名、目录组织、错误处理偏好禁止事项不要改哪些目录、不要往哪个接口里加字段我的经验是CLAUDE.md必须保持精简。见过有人把几百行的历史决策都写进去结果每轮对话都被这些冗余信息占用模型反而抓不住重点。理想状态是读一遍就能在脑子里形成项目地图的程度。命令模板和CLAUDE.md配合起来效果才会好模板讲“怎么做”项目文件讲“这个项目特殊在哪”。2.3 第三层Agent 角色模板当任务需要连续多步、切换不同上下文时普通命令模板就不太够用。比如“先定位问题再写测试再重构最后跑回归”如果所有步骤都在同一个上下文里完成模型很容易看到后面忘了前面。这时候我会把一些命令模板升级成独立的 agent 角色。Claude Code 的 agent 本质上就是一段带角色的系统指令它拥有更聚焦的工作目标和工具使用边界。你可以把“资深前后端分离审查员”“测试用例强迫症患者”“性能优化侦探”这种人设沉淀成独立的 agent 模板。不过要说明agent 的具体配置方式和目录位置在不同版本变化较快不必一开始就追求这个层级。先把手动 slash command 用熟练等真正做到“一个命令反复用仍然觉得不够”时再升级也不迟。我在团队里推广的顺序是先有命令模板再有项目记忆最后才往 agent 方向演进。3. 手把手搭建你的第一个 claude-code-templates 仓库3.1 目录结构与命名规范我推荐把模板单独建一个仓库或目录维护而不是只散落在单个项目里。这样你在任何新项目里都能快速复用。我的默认目录结构长这样~/.claude/ ├── CLAUDE.md ├── commands/ │ ├── review.md │ ├── commit.md │ ├── test.md │ └── scaffold.md └── agents/ └── senior-reviewer.md用户级目录放在~/.claude/下对所有项目生效项目级目录放在仓库根目录的.claude/下随项目走。我更建议把真正通用、稳定的模板放在用户级项目专属的约定放进项目级。命名上单词小写、用连字符分隔类似code-review、write-test、fix-style。不要用空格、中文、大写字母因为命令名需要被 Claude Code 和终端脚本同时识别符号越少越不容易出错。3.2 编写一个“提交信息生成”模板拿最常用的提交信息模板举例。文件路径是.claude/commands/commit.md内容我通常会写得很具体--- description: Generate a conventional commit message from staged changes argument-hint: [optional context] --- You are helping me write a Git commit message. First run git diff --cached --stat to see staged changes. Then run git diff --cached --diff-algorithmminimal to read the full diff. Rules: - Use Conventional Commits format: type(scope): subject - Types: feat, fix, refactor, docs, test, chore, perf - First line under 72 characters - Explain the why in the body, not just the what - Do not mention file names unless they are essential If no changes are staged, tell me and stop. Output: 1. Commit message in a code block 2. A short bullet list explaining your reasoning这个模板好在哪里它没有让 Claude 凭空脑补 diff而是先要求执行命令读取真实状态再按格式产出。模板里没有塞任何项目特有信息所以它在任何 Git 仓库里都能用。实际运行时我在 Claude Code 输入框敲/commit它就会依次执行命令、读 diff、生成 commit message。如果你只在终端里跑也可以把这段内容喂给 headless 模式后面会讲到参数化方式。3.3 安装、调用与版本注意事项把commit.md放进~/.claude/commands/后重新启动 Claude Code输入/commit就能看到对应命令。如果你放了文件但命令没有出现优先检查扩展名是不是.md以及文件名是否符合命令命名规则。需要提醒的一点是全局目录和项目目录如果出现同名命令行为并不是“两边合并”而是一方覆盖另一方。为了避免团队里出现“我在项目内改了/review你本地全局也有一个/review大家行为不一致”的情况我通常只保留一处。团队协作时项目内.claude/commands/review.md作为唯一事实来源全局同名命令一律移除。模板和 Claude Code 版本是有一定耦合的。不建议在一个很老的版本里尝试最新的 frontmatter 字段。我一般的做法是先写最朴素的纯文本指令模板不依赖任何高级字段等确认它在我手头版本上稳定工作再逐步叠加特性。3.4 变量与参数传递的几种方法早期我把模板当纯文本文件用里面写死一个文件路径或一个具体任务结果每次都要复制一个新文件非常低效。后来开始做变量化处理。最简单的做法是在模板里留占位符比如{{PATH}}、{{FEATURE}}然后用一个小脚本把占位符替换成真实值再传给 Claude Code 的 headless 模式。例如#!/usr/bin/env bash set -euo pipefail template_file$HOME/.claude/commands/review.md target${1:?usage: review.sh path} sed s|{{PATH}}|$target|g $template_file | claude -p这里的claude -p是 headless/print 模式直接输出结果适合脚本集成和 CI 场景。需要注意如果文件路径里包含|、这类符号sed替换可能出问题所以更稳妥的做法是用 Python 脚本或envsubst。我个人更倾向于在 shell 里少做高级处理遇到复杂路径直接改用 Python 一行式替换否则调试“为什么模板没有渲染”特别浪费时间。如果你的 Claude Code 版本自带命令参数引用优先用内置方案。输入/review src/components/UserCard.tsx模板内部按当前版本支持的变量名取用参数比外部脚本更干净。但作为模板仓库设计占位符 脚本有一个额外好处这套模板不绑定 Claude Code以后换工具也能复用这是我喜欢保留它作为基础方案的原因。4. 模板内容怎么写才不会被 AI 读废掉4.1 上下文先行先给模型一张地图很多人写模板第一句就是命令式祈使句“找出所有内存泄漏。”模型高效工作的前提是知道自己是谁、面对什么、边界在哪。你不是在训练它而是在给它画地图。我通常按角色、背景、目标、约束这四个顺序写。先交代角色例如“你是一名负责任的后端工程师”再交代背景例如“这个项目是一个使用 PostgreSQL 的订单服务近期出现慢查询但不确定是否由数据库层引起”接着给目标最后给约束。不要把背景塞到十几行的公司历史里三到五句话足够。AI 不是记不住长文本而是长文本里如果大部分内容和任务无关它会分不清优先级。上下文地图越精简行为越可控。4.2 指令去模糊用行为约束代替愿望描述“请优化代码”是我见过最无效的指令。什么叫优化压缩了行数算吗把回调改成 async/await 算吗在没有判定标准的情况下AI 只能猜。更好的方式是写出行为边界只有在存在明显重复逻辑时才抽函数否则不要强行重构改动必须保持对外 API 完全兼容如果无法复现问题停下来向用户提问不允许引入新的第三方依赖这就是所谓的“否定清单”。肯定清单告诉模型该做什么否定清单告诉它绝对不能做什么。对于 Claude Code 这样会主动改文件、执行命令的工具否定清单尤其重要。我见过不少模板没有写“不要运行数据库迁移”这类约束结果 AI 在分析代码时顺手改了 schema。一次操作越界带来的返工成本远超省下的 prompt token。4.3 输出结构化方便回填与二次加工模板除了解读现况还有一个重要功能是规范输出。同一个 review 任务如果没有输出格式约定有人得到三行总结有人得到论文级报告很难统一消费。我偏好要求模型按固定结构输出比如## Summary ## BLOCKER 级别问题 ## SHOULD-FIX 级别问题 ## NIT 级别问题又比如测试模板要求输出“测试文件路径、测试场景描述、断言点列表”。这样产出的内容可以直接贴进 PR 描述或者被脚本继续处理。结构化输出还隐藏着一个好处它迫使模型在思考阶段就把问题进行分级。一个能区分“必须改”和“可以不改”的模型比一个只会给清单的模型可靠得多。模板里写清楚输出格式实际上是在做思维链引导而不是只在控制格式。5. 实操实录给 React 仓库落地 review 模板5.1 场景与需求我们团队维护一个 React TypeScript 项目PR 合并前需要做代码审查。人工看一遍很容易遗漏状态更新和依赖数组问题于是希望 Claude Code 先做一轮机械检查人工在此基础上复核。需求听起来很明确但第一版完全不是那么回事。我把这个踩坑过程原原本本写出来因为大部分人第一次做模板都会经历类似路径。5.2 第一版模板的失败第一版只写了一句Review the current branch for issues.跑起来后发现Claude 确实“review”了但输出像博客文章的开头段概括了分支改了什么说了一些“代码质量较高”“逻辑清晰”的废话几乎没有给出可执行的问题点。它甚至没有主动去读 diff也没有跑类型检查因为模板里根本没提这些动作。现在复盘问题非常明显没有指定工作流没有给出检查清单没有定义“什么是问题”。模型只能按它对“review”这个词的默认理解来自由发挥。自由发挥在闲聊里是优点在代码审查里就是灾难。5.3 变成可用版本的 v0.2我重新写了一版带完整工作流的模板内容如下--- description: Review changed files on the current branch against project conventions argument-hint: [optional commit range] --- You are acting as a senior engineer doing a pull request review. Workflow: 1. Run git diff main...HEAD --stat to map the change set. 2. Run git diff main...HEAD -- *.ts *.tsx to read the source changes. 3. Run git diff --name-only main...HEAD | xargs grep -n TODO\|FIXME to find leftover markers. 4. If type errors are suspected, run npx tsc --noEmit from the project root. Rules: - Only comment on code in the change set, do not review unrelated files. - Block the merge if a new TODO/FIXME was added, if a new any type was introduced, or if changed behavior has no test. - Keep each comment to one sentence with a concrete fix suggestion. - Use severity labels: BLOCKER, SHOULD-FIX, NIT. Output: ## Summary ## BLOCKER ## SHOULD-FIX ## NIT这版模板的进步在于它先把“如何审查”变成流程再通过规则约束模型不过度激进最后用输出格式固定结果形态。跑起来后输出里终于会出现“UserCard.tsx:37 的useEffect依赖缺失”这种可以直接定位的问题而不是结论式废话。不过它也不是完美的。模板里的npx tsc --noEmit和 grep 命令在不同项目里有差异所以这类项目专属信息我会迁移到CLAUDE.md里。模板要尽量保持通用只描述“先看 diff再做类型检查再查标记”具体命令从项目记忆里读这样才能跨项目复用。6. 常见问题与排查技巧实录6.1 命令不生效或找不到模板我遇到最多的问题是路径错了。很多新手把模板放在templates/、prompts/这种自定义目录下然后期待 Claude Code 能自动扫描。Claude Code 只认它约定好的配置目录不是所有 markdown 都能被当成 slash command。检查步骤很简单确认文件在.claude/commands/下文件扩展名是.md文件名没有空格和异常符号frontmatter 没有语法错误。还有一种情况是修改完模板后没有重启会话命令列表没有刷新。先重启再检查路径九十的问题都能解决。如果还不行可能是全局和项目级命令冲突。同名命令存在时以项目内为准这一点团队成员一定要对齐。6.2 模板总是答非所问模板输出跑偏大概率不是模型变笨了而是你的模板给的目标不够具体。我有个自查方法把模板交给一个完全不了解这个项目的人读一遍看他读完能不能说出“第一步做什么、什么情况下停下、最终输出长什么样”。如果这个人做不到模型大概率也做不到。另一个常见原因是模板信息过多且顺序混乱。项目规范、示例代码、历史决策全堆在一起模型抓不住关键路径。解决办法是按“角色背景 → 执行步骤 → 规则约束 → 输出格式”重组内容把扩展知识放进外部文件需要时让模型按需读取而不是一次性全塞进来。6.3 模板太长上下文窗口被撑爆我见过有的模板洋洋洒洒上千行里面包含完整的代码规范、公司内网链接、几十个示例。这样做的后果是真正执行任务时上下文窗口被大量与当前改动无关的信息占据模型的反应质量反而下降。模板长度应该控制在“能背下来”的程度。我的经验是核心命令模板尽量控制在 300 词以内最长不超过 600 词。如果确实有大量规范需要遵守把它拆成CLAUDE.md或独立文档在模板里用一句“遵守项目根目录下CLAUDE.md中的规范”来引用让模型需要时再读。6.4 团队协作时模板漂移团队里最难管理的不是代码而是模板版本。有人本地全局模板是旧版有人项目模板是新版导致同一个/review在不同人机器上行为不同review 结论自然也不一致。我建议把模板仓库化并且用 git 管理。对于真正需要统一的团队项目仓库里维护一份.claude/commands/并在 README 里写明“请删掉全局同名命令”。如果你的工具版本支持模板变量或配置引用尽量把动态信息参数化避免团队修改模板正文来适配自己。模板越统一协作成本越低。6.5 变量替换脚本出现莫名 bug最后说一个外部脚本替换的坑。如果模板里留了{{PATH}}你用sed做替换路径里一旦出现/没关系但出现或|就会炸。我踩过几次坑之后不再用sed处理路径类变量改用一个 10 行的 Python 小脚本做精确替换或者在模板里提示 Claude“把{{PATH}}视作用户输入的文件路径”让模型自己在对话里识别参数。这里有个原则宁可让模型多一步解析也不要在 shell 层做脆弱的文本替换。因为模型解析错了你还能修正对话脚本替换坏了连原始模板都看不清了。最后分享一点个人体会我前前后后整理过几十套模板最大的感受是模板不是一次写成的而是每一次让 AI 犯错之后把它的“错因”翻译成一条新规则补进claude-code-templates里。今天它忘了读 diff明天你就把“先跑git diff”写进模板今天它把 NIT 当 BLOCKER 报明天你就把严重级别定义写清。模板本质上是一个人机协作的日志积累得越久AI 的行为越接近你期望中的那个“好同事”。另外别贪多。第一次整理模板不要几十个命令一次铺开。从三个最高频的动作开始commit、review、test。把这三个打磨到看到输出就想复制粘贴的程度再往下扩展。这样做虽然起步慢但每一个模板都是真金白银跑出来的不是摆样子的文档。
