用 Claude Code 写代码大半年我最大的体会是它强是强但如果你每次都靠临时对话让它干活你会发现自己像在伺候一个记性差又话多的同事。直到我把常用任务都沉淀成一套 claude-code-templates把重复工作变成/review、/refactor、/commit这种斜杠命令整个效率才算真正起来。这篇文章就把这套东西的搭建思路、文件结构、命令模板和踩坑经验完整拆给你看。它本质上就是一批 Markdown 文件外加一个 JSON 配置文件放进~/.claude或项目根目录的.claude目录后Claude Code 会自动把它们识别成可调用的命令集。适合正在用 Claude Code、又觉得每次打一大段提示词很浪费的开发者也适合想在公司内部统一代码审查和编码规范的团队。聊模板之前先说一个判断模板不是用来给 Claude 立人设的而是用来定规矩的。人设给得再花哨指令不明确输出照样稀碎。所以我下面所有内容都围绕一个中心——怎么把话说清楚、把任务拆细、把输出格式锁死。这才是模板系统真正值钱的地方。1. 项目定位与模板设计思路——模板不是堆提示词是给 AI 定规矩1.1 先想清楚这套模板到底解决什么问题不使用模板的时候我每天的工作流是这样的打开 Claude Code敲一段帮我看看这段代码有什么问题它列几条泛泛的建议我再补一句重点看并发它重新分析一遍然后我再补充如果有问题直接给修改代码……一轮下来上下文里堆满了重复解释真正干活的时间没多少。这事本质上和带新人一样——你不会让他每次从零开始理解你的项目而是给他一份入职手册他不懂的再问。模板系统解决的三个核心痛点首先是重复劳动。代码审查、提交信息、注释翻译、错误排查这些任务每天都在发生形式高度相似值得固化成固定指令。其次是上下文浪费。你每重新开始一个会话Claude 对项目一无所知把背景信息放在模板里等于省掉了每次几十行环境说明。第三是经验无法沉淀。团队里有人发现了一个好用的审查方法口头传授容易失真写成模板文件放进 Git 仓库所有人就都能复用。我最终把模板体系分成四个层次全局上下文CLAUDE.md、自定义命令commands/*.md、权限与模型配置settings.json、以及可选的 hooks 自动化脚本。前面三个是基础日常使用已经覆盖 90% 的需求hooks 属于进阶玩法放到后面讲。1.2 设计原则按任务拆分不按语言拆分很多初玩模板的朋友上来就写Python 专家前端大神系统架构师这种角色模板我试过效果一般。原因是角色只是身份任务是动作。Claude Code 真正需要的不是一句你是资深专家而是你接下来要按这个流程把这段代码过一遍输出格式严格按表格来。身份描述写得再多不如把动作写清楚。我后来把所有模板按任务拆而不是按技术栈拆。比如我不会维护一个Vue 模板去覆盖所有 Vue 相关需求因为 Vue 场景里既有代码审查、又有样式调整、又有单元测试混在一起等于什么都没说。正确的粒度是一个模板只对应一种任务审查就是审查重构就是重构写提交信息就是写提交信息。具体设计时我遵守四条原则单一职责。一个模板只干一件事但把这件事做透。审查模板里不要顺手加上重构指令那会干扰主线。短模板优先。正文尽量控制在 30 行以内。模板太长Claude 会顾此失彼抓不住重点。少参数。需要传参的模板最多一两个参数参数越多输出越不可控。可组合。基础模板可以互相调用比如审查模板里可以要求先调用项目导读模板拿到项目背景。这套原则执行下来模板文件从看起来很全变成用起来很顺。一两周之后你会明显感觉到Claude 的输出越来越接近稳定同事的水平而不是随机实习生。1.3 标准目录结构社区约定俗成的产物形态Claude Code 对模板的识别有一套约定路径理解这个路径整个项目结构就清楚了~/.claude/ ├── CLAUDE.md # 全局上下文所有项目生效 ├── settings.json # 权限、模型、行为配置 └── commands/ # 自定义斜杠命令 ├── review.md # /review 代码审查 ├── refactor.md # /refactor 代码重构 ├── commit.md # /commit 生成提交信息 ├── doc.md # /doc 生成文档 └── explain.md # /explain 解释代码如果是单个项目专属的模板就放到项目根目录的.claude/下结构一样但只在那个项目里生效。社区里开源的 claude-code-templates 仓库基本都是这种形态。把模板做成 Git 仓库管理后团队成员 clone 下来用一条软链命令就能让所有人共享同一套命令集这个我放到 4.3 细说。2. 核心配置解析CLAUDE.md、settings 与命令文件的细节2.1 CLAUDE.md 是常驻空气项目上下文的一半都在这CLAUDE.md是 Claude Code 每次会话启动时自动加载的上下文文件本质上是一份 Markdown 格式的系统提示。它和命令模板最大的区别是命令模板是你主动调用的CLAUDE.md 是空气你不需要开口它就一直在影响 Claude 的行为。所以这个文件应该放永远不变的信息。我自己的项目 CLAUDE.md 长这样# 项目商城中后台管理系统 ## 技术栈 - 前端Vue3 TypeScript Pinia - 后端Node.js NestJS PostgreSQL - 部署Docker Nginx ## 常用命令 - 启动开发npm run dev - 跑测试npm run test - lint 检查npm run lint ## 代码风格约束 - 组件命名用 PascalCase变量用 camelCase - API 层统一 try/catch错误返回 { code, message } - 业务代码禁止 console.log统一用 src/utils/logger.ts - 注释统一中文函数注释写明参数与返回值写 CLAUDE.md 有一条重要原则只写事实清单不写形容词。别写请认真负责请遵守最佳实践这种话AI 无法从空洞的形容词里执行出具体行为。相反错误返回结构是{ code, message }这种信息Claude 会直接拿去用。另外要注意全局~/.claude/CLAUDE.md和项目.claude/CLAUDE.md是合并加载的同名主题下项目级优先。这意味着同类指令如果两边都写了最终以项目为准。所以我的经验是全局只写通用习惯比如代码注释用中文提交信息用 Conventional Commits项目里写业务特定规则比如订单状态流转必须走状态机。分开写才能避免互相覆盖。2.2 commands 的 YAML 头命令文件的门面和元信息commands/目录下的每个.md文件对应一个斜杠命令文件名就是命令名。比如review.md就是/review。文件开头有一段 YAML frontmatter用来给 Claude Code 提供命令的元信息--- description: 对当前分支改动做一轮代码审查 argument-hint: 审查重点例如并发性能 --- 你是一位拥有 10 年后端经验的代码审查者请对当前改动做 review。字段说明description必填。命令面板里显示的介绍文本也用于 Claude 自动选命令时的参考。argument-hint可选。告诉用户这个命令需要一个参数以及参数长什么样。allowed-tools可选。限定这个命令运行时 Claude 可以使用哪些工具比如只能读文件、不能执行命令。model可选。指定使用哪个模型执行本命令。YAML 头下面就是命令的正文。正文才是模板的灵魂。我写正文时固定包含五个部分角色定位、输入来源、执行步骤、输出格式、禁止事项。角色定位一句话够用输入来源说明分析对象是当前分支改动还是某个具体文件执行步骤要编号输出格式要具体到用表格列出 P0/P1/P2 问题禁止事项要放在最后因为它是对前面所有指令的补丁。2.3 settings.json 与 hooks模板系统的自动挡玩法settings.json是 Claude Code 的全局行为配置里面可以锁定默认模型、配置权限白名单甚至指定一些自动响应策略。我常用的配置大概是这样{ model: sonnet, permissions: { allow: [Bash(npm run *), Read(**) ], deny: [Bash(rm -rf *), Bash(git push *)] } }权限配置的意义在于给模板兜底。模板里如果写了需要跑测试的命令而权限不允许Claude 会卡住。反过来如果权限太松某些模板里的危险操作又可能被自动执行。我的习惯是读操作默认允许写操作和删除操作一律先询问。hooks 是更高级的玩法可以在工具调用前、会话开始、命令执行结束等时机触发脚本。比如在 PreToolUse 阶段判断用户输入了/deploy就自动拉取最新代码。但对于刚开始搭模板的人来说hooks 不是必需品先把命令模板跑通之后再考虑自动化。我一向建议先手动、后自动原因是 hooks 排查成本高出了问题你连模板在哪一步断掉都不好定位。3. 关键模板类型详解角色型、工作流型、任务型、风格约束型3.1 角色型模板给 Claude 一个明确官职和处事标准角色型模板的正文开头通常给定一个身份但关键是身份后面必须紧跟行为标准否则身份就是一个空壳。以我最常用的/review模板为例--- description: 双角度代码审查输出分级问题清单 argument-hint: 可选指定审查角度如并发安全 --- 你是一位有 10 年后端经验的代码审查者。请对当前分支相对 main 的改动做审查。 步骤 1. 先执行 git diff 查看改动文件列表 2. 逐个文件审查注意边界条件和异常处理 3. 输出审查报告 输出格式 | 级别 | 文件 | 行号 | 问题描述 | 修改建议 | | 严重程度按以下分级 - P0必然导致线上故障 - P1逻辑错误或严重缺陷 - P2可读性、可维护性问题 要求 - 不要输出代码整体质量不错这种空话 - 每个问题必须给到文件和行号 - 如果你认为没有发现 P0/P1直接说未发现 P0/P1 问题这个模板的核心不在10 年后端经验这句话而在后面的步骤、分级、格式约束。风险点在于审查范围默认是当前分支相对 main如果项目没有用 Git 或者分支模型不同模板就跑不动。所以我建议团队项目里把审查范围写清楚甚至可以在模板里加一句如果 git diff 无输出请提示用户检查分支和暂存区。同样属于角色型的还有/security-audit用来做安全巡检重点关注 SQL 注入、越权访问、敏感信息硬编码等问题输出格式也类似分级标准参照 OWASP Top 10 的分类思路。3.2 工作流型模板把分析、计划、编码、测试、总结串起来工作流型模板解决的是大任务怎么拆步的问题。我平时用得最多的/dev模板会指挥 Claude 走一套完整流程理解需求、产出方案、等确认、写代码、跑测试、输出总结。写出来大概是--- description: 从需求到代码的完整开发流程 argument-hint: 需求描述 --- 你是一名全栈工程师。用户将给出一段需求请严格按以下流程执行 第 1 步阅读项目根目录的 CLAUDE.md 和 README确认技术栈和代码规范。 第 2 步搜索相关代码理解需求涉及的模块。 第 3 步输出实现计划包括改动的文件列表和实现要点。 第 4 步等待用户确认确认后再开始写代码。 第 5 步写完代码后执行相关测试确保改动不影响已有功能。 第 6 步输出改动总结包含文件清单、关键逻辑说明和测试结果。第 4 步的等待确认是我踩过一次大坑之后加上的。没有确认环节时Claude 经常自作主张改了一堆相关文件导致 diff 巨大审查成本远高于收益。现在的模式是先计划后执行多一次交互但整体更稳。工作流模板的另一个典型是/commit-flow它会根据 diff 自动分析改动类型生成符合 Conventional Commits 规范的提交信息然后执行git add和git commit。注意这种模板涉及写入操作必须配合权限限制至少要在 settings 里禁止git push避免出问题。3.3 任务型模板围绕 argument-hint 的高效传参机制任务型模板的特点是可以接收用户传入的参数。Claude Code 规定命令正文里用$ARGUMENTS代表用户输入的内容。比如我写了/explain.md--- description: 解释指定代码文件或函数 argument-hint: 文件路径或函数名 --- 请解释用户传入的代码对象$ARGUMENTS 输出结构 1. 这个代码是做什么的用一句话概括 2. 核心逻辑拆解分点说明 3. 输入输出约定 4. 潜在风险和建议 如果是一个文件先说明文件整体职责再挑关键函数解释。使用方式就是/explain src/utils/date.ts或者/explain formatDate。参数传递是字符串替换所以你可以在模板里任意位置使用$ARGUMENTS但一个命令只保留一个参数位是最稳妥的。任务型模板还包括/translate专门做技术文档的中英互译要求保留代码块、保留 Markdown 结构、术语不随意改写。这类模板的输出格式约束比角色型模板更重要因为翻译任务最容易犯的毛病就是意译过头把专有名词改成了口语化描述。我的translate.md里明确写着API 名、变量名、框架名保留英文只翻译自然语言部分。3.4 风格约束型模板把编码规范变成可执行规则风格约束不是单一命令更像一个常驻规则集。除了放进 CLAUDE.md 之外我还会做一个/style-check模板用于定期批量扫描--- description: 按项目编码规范检查指定目录代码 argument-hint: 目录路径 --- 请扫描路径 $ARGUMENTS 下的代码对照以下规范逐条检查 1. 组件命名是否 PascalCase 2. 是否有裸 console.log 3. API 层是否有 try/catch错误是否统一返回 { code, message } 4. 是否存在超过 300 行的文件 5. 导入顺序是否规范 输出格式 - 合规项列一句通过 - 不合规项按文件路径 问题 修改建议列出 - 最后给一个合规率百分比风格约束模板有个好处它把团队在 Code Review 时靠人肉检查的事项提前机检了省下的时间可以用来讨论真正的逻辑问题。但要注意风格检查模板的输出依赖于 CLAUDE.md 中规范写得是否清楚如果规范本身模糊模板必然失灵。所以在推进风格模板之前先花半小时把 CLAUDE.md 的规范条款改成机器能判断的句子这是性价比最高的投资。4. 落地实操一步步搭建并调试一套自己的模板4.1 初始化目录与最小可用配置搭一套最小可用的模板系统其实三条命令就够了mkdir -p ~/.claude/commands touch ~/.claude/CLAUDE.md touch ~/.claude/settings.json第一次做的时候别贪多先放一个模板跑通整个链路。我建议第一个模板就写/review因为代码审查需求最普遍、效果最容易观察。写完模板文件之后重启 Claude Code 会话输入/看看命令列表里有没有出现review。能出现链路就通了。还有一个小细节命令文件名必须是英文小写中间可以用连字符比如security-audit.md。文件名会直接显示为命令名所以命名要直观。不要起checkcode.md这种含义模糊的名字宁可长一点写成code-review.md。4.2 从能用到好用以 /review 模板的迭代为例我第一次写/review模板时正文只有一句话你是一位资深的代码审查专家请认真审查代码帮我找出问题。结果输出效果惨不忍睹——列了一堆建议增加错误处理建议优化性能这种正确但没用的废话连文件的完整路径都不给。后来我在一周内迭代了三个版本每版只改一个变量第一版增加输出格式约束要求用表格列出文件、行号、问题、建议输出立刻变得可定位了。第二版增加严重程度分级要求区分 P0/P1/P2并且明确告诉 Claude如果没发现 P0/P1直接说未发现这一步把废话比例砍掉大半。第三版增加审查范围指定用git diff看当前改动让审查变得有边界。迭代的规律是不要试图一次把模板写完美先用最小版本跑起来再根据输出缺点逐个打补丁。每次补丁只加一条约束这样你能清楚知道哪条规则起了作用。现在这个模板已经稳定用了四个月输出质量远远超过大多数人工审查。4.3 全局模板与项目模板的分工以及用 Git 管理模板全局和项目模板的分工我按通用性切分目录适合放什么典型命令~/.claude/commands所有项目通用的任务/commit、/explain、/translate项目.claude/commands项目专属逻辑/api-client、/db-migration、/order-flow通用模板和项目模板混在一起容易造成冲突。比如全局有个/test模板跑 Jest项目里用的是 Vitest命令一执行就错。如果项目模板里也定义了同名命令以项目为准但最好还是从命名上就区分开项目专属命令加项目名前缀比如/shop-test。模板本身一定要纳入 Git 管理。我自己的做法是把模板仓库放在~/projects/claude-code-templates然后用软链把它变成全局命令目录# 备份现有目录如果有 mv ~/.claude/commands ~/.claude/commands.bak # 建立软链 ln -s ~/projects/claude-code-templates/commands ~/.claude/commands团队协作时每个人都走同一条软链命令模板更新后git pull即可生效。这个方案的坑在于如果你后续直接往~/.claude/commands里添加文件改的不是原仓库下次 pull 会混乱。所以规则很简单所有命令文件一律在模板仓库里修改再同步过来绝不在软链目录里原地编辑。4.4 我在调试时用的几张检查表调试模板不是玄学我总结了几条具备可操作性的检查方法第一开启 verbose 模式或者查看会话日志看 Claude 实际收到的提示词长什么样。很多时候你觉得模板写得挺清楚但 Claude 实际读到的上下文已经被 CLAUDE.md 和前面的对话污染了复核一下原始输入能找到 50% 以上的跑偏原因。第二一次只改一个变量。模板不好用最常见的错误是同时改了输出格式、步骤顺序、角色描述好几个地方然后发现问题更严重了却分不清是哪个改动导致的。把变量拆开每次只动一个定位速度快十倍。第三模板少用如果你觉得……可以……这种模糊授权。Claude 拿到这种句式会倾向于输出更多内容而不是收敛。把可选项改成硬性要求比如基本方案如果没有明显风险不要返回多个备选方案。第四明确禁止项写在模板末尾。我测试下来Claude 对文末的否定指令执行得比文初的肯定指令更稳这可能是上下文注意力分布导致的。所以不要输出无关建议不要逐行贴代码这些话统一放在模板最后一段。5. 高频问题与排查技巧实录5.1 命令不显示、找不到先查目录和后缀最常见的现象是输入/看不到自定义命令或者命令存在但提示 not found。排查顺序是先看路径。项目启动时要确认当前目录就是项目根目录.claude必须在这个根目录下才会被识别。全局命令确认在~/.claude/commands别手滑放进了.claude或者commands/commands。再看后缀。文件名必须以.md结尾全小写不能用.txt或者.markdown。最后看 frontmatter。YAML 头必须顶格写description前面不能有空格字段名不能拼错。改完任何一个文件记得重启 Claude Code 会话命令面板才会刷新。5.2 模板生效了但输出总跑偏是不是指令有内伤输出跑偏最常见的原因是模板内部自相矛盾。典型例子是模板开头写请详细说明结尾写保持简洁这两个指令同时存在时Claude 往往会折中成一种最尴尬的形态。我的经验是输出长度指令只写一次放在输出格式附近如果要求简洁就直接给输出模板比如只用表格输出每行不超过 20 字而不是写简洁这种形容词。另一个跑偏来源是角色设定过度。模板里写一大段你是拥有 20 年经验的全球顶尖架构师反而会诱导 Claude 生成夸张、不具体的表达。角色定级到资深工程师就够了剩余空间全部留给步骤和格式。还有一类问题是输入来源没定死。审查模板如果不写分析当前 git diff 改动Claude 可能把整个项目都扫一遍输出巨长且不聚焦。给模板圈定范围是控制输出长度最直接的手段。5.3 CLAUDE.md 指令冲突全局与项目级怎么协调如果把全局规则和项目规则写得重叠就会出现一种诡异的现场上午执行命令输出中文注释下午同样的命令输出英文注释因为某个项目的 CLAUDE.md 覆盖了全局设置。这是设计阶段就要避免的问题。我整理了一张冲突对照表方便自查冲突内容全局 CLAUDE.md项目 CLAUDE.md生效规则注释语言中文英文项目覆盖全局输出英文包管理器npmpnpm项目覆盖执行 pnpm 命令代码风格无要求强制 PascalCase两者合并项目规则额外生效文档语言中文中文无冲突同向叠加协调方法说透了就一条同名规则的冲突默认以项目 CLAUDE.md 为准因为项目离任务更近。所以全局文件尽量只放可被安全覆盖的习惯项目专属约束必须放项目文件里。如果你发现某个全局规则经常被项目覆盖说明它根本不该放在全局移到项目文件反而更清晰。5.4 argument-hint 不生效、参数传不进模板有时候敲/explain src/utils/date.tsClaude 好像完全没收到参数或用了一个奇怪的旧值。这通常不是命令本身的问题而是模板正文里没有正确使用$ARGUMENTS变量。记住命令正文中出现$ARGUMENTS的地方才会被用户输入替换如果模板里写的是用户将传入文件路径这种描述而没有实际引用变量Claude 只能靠猜。另外参数中如果包含空格命令面板里应该用引号包住比如/explain src/utils/date format.ts。参数传入后在模板里最好做一次第一步先确认参数内容的处理让 Claude 先复述它理解到的输入再去执行任务。这一步能避免大量因为参数理解错位导致的牛头不对马嘴。5.5 问题速查表把一路上的坑做一份速查表遇到问题直接对表找方向症状可能原因解决方案命令不在列表里文件放错目录或后缀错误检查~/.claude/commands/*.md重启会话命令存在但报错YAML frontmatter 格式错误检查顶格、字段名删除多余空行输出全是废话模板缺少格式约束增加文件行号问题建议表格输出要求输出过长不可控没有限定输入范围写明只分析当前 diff或指定一个文件参数不生效没在正文使用$ARGUMENTS直接替换文本不要用描述代替引用命令和期望行为不一致模板步骤模糊拆成编号步骤每步一个动作写明等待确认全局项目和项目行为冲突CLAUDE.md 规则重叠全局只放通用习惯项目规则放项目文件某命令自动执行危险操作权限配置过宽settings 的 deny 加上 rm -rf、git push 等最后再补充一个亲测有效的经验模板不是写完就完事的至少要经历一次真实任务实战才算验收。我每次新建模板都会立刻找一个真实任务跑一遍然后根据输出改三个地方——步骤边界、输出格式、禁止事项。这套循环下来模板会越用越薄因为很多前置说明写清楚之后冗余的字句就删掉了。现在我的/review模板只有 25 行输出稳定度却比最早 100 行的版本高得多。希望这套思路能让你少走点弯路早日攒出一套真正属于自己项目的模板库。
