1. 先把这个标题拆明白看到“claude-code-templates”这个项目名估计大部分人都能猜个大概这是给Claude Code用的模板集合。但真正用过Claude Code的人会知道模板这两个字背后藏的东西远比想象中多——它不是简单的几段提示词而是一整套让AI助手在项目里“懂规矩、按套路出牌”的机制。我最早接触Claude Code的时候跟很多人一样觉得这玩意儿就是个放在终端里的聊天窗口。你让它改bug它给你改你让它写测试它给你写。但用久了就发现一个问题同样的需求今天让它写出来的代码跟明天写的代码风格、结构、注释习惯完全是两个人。更头疼的是我明明在对话里强调过“数据库操作必须走事务”隔了几个小时它就忘了。后来我才意识到Claude Code这种带记忆的终端Agent跟普通的ChatGPT聊天窗口有本质区别。它可以在项目目录下读取你的约定文件可以挂载自定义命令甚至能在特定时机自动执行脚本。这些东西组合起来就是“模板”的真正含义——把团队规范、个人偏好、重复性工作流程全部固化成一堆可复用的配置文件。这篇文章我准备从实际落地角度把我自己维护的这套claude-code-templates完整拆开讲。包括CLAUDE.md怎么写、自定义斜杠命令怎么挂、hooks怎么配、以及踩过的那些坑。适合已经把Claude Code跑起来、但觉得它在真实项目里“不够听话”的人读。2. Claude Code模板系统的核心构成2.1 CLAUDE.md项目的“永久记忆”很多人把CLAUDE.md当成一个给Claude看的技术文档写两句“这是一个基于Python的后端项目”就完了。这其实大材小用了。CLAUDE.md是Claude Code在启动时会自动读取的项目级上下文文件它最大的价值在于让每一次会话都能继承项目的约定即使你关掉终端、隔了一周再回来它依然记得应该用什么风格写代码。我在自己项目的CLAUDE.md里一般分这么几块# 项目订单服务 ## 技术栈 - Python 3.11 FastAPI PostgreSQL - 包管理用 uv不要用 pip ## 代码规范 - 所有数据库查询必须走 repository 层禁止在路由里直接写 SQL - 型号名称用单数表名用复数 - 异常统一抛 domain_error不允许裸抛 ValueError ## 提交规范 - commit message 格式feat|fix|refactor|test(模块): 描述 - 提交前必须跑 ruff 和 pytest ## 环境变量 - 所有配置从 pydantic-settings 读取禁止硬编码 - 本地开发默认端口 8000你别小看这几行字。Claude Code读进去之后写代码时就会不自觉地去遵守。我实测过同一个项目写了CLAUDE.md跟没写它生成的代码风格一致性差距非常大。没写的时候它有时候给你带类型标注有时候不带有时候用f-string有时候用format写了之后基本能做到按规范输出。不过有个细节要注意CLAUDE.md不是越长越好。Claude Code每次会话启动都会把整个文件作为上下文加载太长会挤占有限的上下文窗口。我建议控制在100行以内只放“必须遵守”的内容那些偶尔提醒一下就行的事情就别往里面塞了。2.2 自定义斜杠命令把重复劳动交给模板这才是我觉得模板体系里最实用的部分。Claude Code支持在项目下建一个.claude/commands/目录里面每个Markdown文件对应一个斜杠命令。比如你创建一个review.md然后就可以在对话里输入/reviewClaude会立刻按你写好的指令执行。这个机制特别像给AI装上了“快捷键”。我其实最早被这个东西打动是因为一个很琐碎的场景——code review。以前我每次让Claude帮我检查代码都要不厌其烦地描述“请从安全性、性能、代码风格三个角度检查这段代码注意数据库N1查询注意越权判断输出格式是问题列表修改建议”。后来我把它做成了模板--- name: review description: 审查当前工作区代码 --- 请对当前分支的改动进行代码审查重点检查 1. 安全性越权、注入、敏感信息泄露 2. 性能N1查询、循环内IO、缺少索引的查询 3. 可维护性函数过长、重复代码、命名混乱 输出要求 - 按严重程度分组阻塞/建议/可选优化 - 每项必须给到具体文件和行号 - 建议修复方式要给出代码片段从此以后我只需要敲/review它就会按这个标准执行。同样思路我还做了/gen-test——给选中文件生成单测/explain——用金字塔原理解释一段复杂逻辑/changelog——根据git log生成变更日志。这些东西本质上都是“命令行式提示词”但体验完全不一样因为不需要每次重新组织语言也不会漏提要求。2.3 Hooks在关键时刻自动触发规矩Hooks这块可能很多人没接触过但它是把模板从“被动遵守”变“主动执行”的关键一环。Claude Code支持配置事件钩子比如在工具调用前、在会话启动时、在AI提交消息前等时机触发外部脚本。我开发环境里最常用的两个PreToolUse钩子监听Edit工具。脚本判断AI改动的文件路径如果命中“禁止修改”的白名单目录直接拦截并返回错误信息。Stop钩子在对话轮次结束时检查工作区状态如果发现未提交的TODO标记提醒我一声。钩子的配置写在.claude/settings.json里语法类似{ hooks: { PreToolUse: [ { matcher: Edit, hooks: [ { type: command, command: python .claude/hooks/check_edit.py, timeout: 10 } ] } ] } }如果你跟我一样是Python项目写个hook脚本并不难。比如我那个拦截脚本的逻辑就是解析传入的JSON参数取file_path字段判断是否以migrations/开头是的话就打印特定前缀的错误返回非零退出码。整个脚本不到30行。hooks真正有意思的地方在于它把模板从“建议”变成了“强制”。CLAUDE.md写得再好也总有疏漏的时候钩子就像装了红绿灯的路口哪怕AI想闯红灯也会被物理拦下来。3. 实操从零搭一套自己的模板3.1 目录结构设计网上开源的claude-code-templates仓库有很多我自己参考过好几个最后沉淀出来的目录是这样.claude/ ├── CLAUDE.md ├── settings.json ├── commands/ │ ├── review.md │ ├── gen-test.md │ ├── commit.md │ └── explain.md └── hooks/ ├── check_edit.py └── stop_check.py这个布局是我迭代了挺久才定的。起初我把CLAUDE.md放在项目根目录后来发现它如果每个子目录都有自己的一套上下文约定根目录那份会被“覆盖”于是改成了现在这样根目录放全局规范子目录再按需放各自的补充约定。Commands目录是模板的主战场。我强烈建议给每个命令都加上frontmatter块也就是文件开头那段用三横线包起来的元信息--- name: commit description: 根据当前改动生成规范的commit message ---这个description字段特别重要因为Claude Code在斜杠菜单里显示的就是它而且你必须让description足够有辨识度否则你装了十几个命令之后连自己都分不清哪个是哪个。3.2 命令模板的写法细节写自定义命令模板一开始最容易犯的错误就是“写作文”。有些人会把命令写成几大段描述巴不得把背景、目标、注意事项全部讲一遍。但实际用下来效果反而不理想。Claude Code的模型能力足够强你只需要“定框架、给标准、提约束”剩下的它会自己发挥。举一个我写commit命令的模板--- name: commit description: 用规范格式生成commit message --- 根据当前git diff生成符合规范的commit message。 要求 - 类型限定为 feat、fix、refactor、test、docs、chore 六种 - 格式type(scope): 摘要 - 摘要不超过50个字符 - 正文按“为什么改/怎么改/影响范围”三段写 最后输出命令git commit -m ... -m ... 不要实际执行注意到玄机没有最后一句非常关键——“不要实际执行”。我特意让Claude只输出命令、不执行。原因很现实AI自动提交偶尔会出幺蛾子要么把没写完的代码提交了要么commit message里带进去莫名其妙的内容。让它生成命令给我看我来手动执行比让它直接动手要稳妥得多。这和编程里的一个原则很像让自动化尽量做单向动作涉及写操作的地方留一手人工确认。Claude Code虽然支持会话内授权执行命令但把提交这种敏感行为交给AI自动做出了事后悔都来不及。3.3 模板里如何控制输出质量有些命令模板在执行完任务后输出会是一大坨杂乱的文本。你原本只想让它总结重点结果它把整个代码文件都抄给你看。对付这个问题我的经验是在模板里显式定义“输出格式”。比如review命令我要求它按三级列表输出### 阻塞级 - [文件路径:行号] 问题描述 ### 建议级 - [文件路径:行号] 问题描述 ### 可选优化 - [文件路径:行号] 问题描述这样输出出来一目了然直接可以贴给团队群。类似地gen-test这个命令我要求它输出“测试用例清单测试代码块”不允许输出额外解释。最开始的版本它每写一个测试用例就加一段“这个测试用例的目的是xxx”看着烦死了。另外一个技巧是给命令模板加负面约束。比如禁止事项 - 不要改动除目标文件之外的任何文件 - 不要在输出中展示全部代码文件内容 - 不要使用 正如我前面提到的 这类废话开头这些负面约束虽然写起来像废话但实测非常管用。大模型的生成逻辑里明确禁止的东西大概率会被避开而不写禁止项的内容它反而可能自由发挥跑偏。3.4 多项目管理自己的模板等你的模板体系在一两个项目里跑通了接下来会遇到一个现实问题每个项目都拷贝一份.claude/目录改起来很痛苦我今天改进一下review命令难道要同步到五六个项目里去我现在的做法是把通用模板单独放一个Git仓库管理各个项目通过工具拉取最新版。最简单的方案是直接软链接将全局模板目录链接到项目里ln -s ~/dotfiles/claude-templates/.claude/commands /your/project/.claude/commands但如果嫌软链接麻烦也可以写一个两三行的同步脚本用rsync把公共目录同步到各项目下。唯一需要注意的就是项目特有的命令不要放公共仓库否则会出现A项目的命令跑到B项目里执行引发各种不可预期行为。我把公共模板仓库里的命令都默认设计成“不依赖特定技术栈”。比如review命令它不会假设你用Python还是Node而某个项目独有的“检查数据库迁移是否规范”这种命令就只留在这个项目的.claude目录里不放进公共模板。分得越清楚后期维护越省心。4. 运行中的典型问题与排查实录4.1 命令出现了但什么都没发生这个坑我印象很深。有一阵子我创建了一个/refactor命令重启Claude Code之后输入命令它确实匹配到了但只回了一句类似“好的”的话然后没有执行任何操作。后来排查半天才发现问题出在frontmatter上。Claude Code的命令系统对frontmatter里的name字段特别敏感如果字段名写错比如误写成title命令虽然能被菜单列出来但不会触发对应的内容模板。我那会儿正好是把name写成了Name大小写不一致导致的。解决办法很简单严格按Od白皮书格式写frontmatter三个字段一个都不能少name用小写开头:--- name: refactor description: 对指定文件执行安全重构 ---另外还有一个常见坑命令文件的编码格式。如果你在Windows下用记事本编辑存成了UTF-8 with BOMClaude Code解析时可能读不出前几行。建议一律用无BOM的UTF-8保存最好直接在编辑器里设置默认编码。4.2 CLAUDE.md内容太多挤占上下文窗口上下文窗口是Claude Code最宝贵的资源而CLAUDE.md每次会话都会加载等于白占一块空间。我有个项目前期工程化做得特别重CLAUDE.md写到了两百多行结果后来发现Claude的响应质量明显下降——不是模型变笨了而是大部分上下文都用在读规范上留给任务的余量不够了。后来我做了两件事一是把CLAUDE.md砍到只剩硬性规范凡是“建议”“最好”级别的内容全部挪到命令模板里只在需要时按斜杠命令触达二是把一些长篇幅的参考文档移到单独文件里比如AGENTS.md、DETAILED_STANDARDS.md然后在CLAUDE.md里用一句话引导Claude“需要详细规范时读对应文件”。经过调整之后CLAUDE.md从两百多行压缩到六十行单次会话的上下文占用明显降下来了。有一次我拿同一个任务对比压缩前后Claude的推理表现差距还真不小后者明显“更聪明”。4.3 Hook脚本不生效但没有任何报错Hooks机制隐蔽的坑就更多了。有一回我配置了PreToolUse钩子脚本路径、JSON格式都觉得没问题但它就是不触发。后来发现是matcher写得太宽泛监听的是全部工具而脚本内部判断的是文件路径问题出在我脚本解析参数时字段名写错了。Claude Code的hook事件会给脚本传一段JSON里面包含工具调用的详细信息。不同版本、不同事件类型字段名可能会略有差异。所以写hook脚本时第一行最好先把传入的JSON打印到日志里看一眼确认结构再往下写#!/usr/bin/env python3 import sys, json payload json.loads(sys.stdin.read()) with open(.claude/hooks/debug.log, a) as f: f.write(json.dumps(payload, indent2))也别迷信官方文档版本更新后字段可能变。用这种调试方式把真实数据打出来是最靠谱的排查手段。另外还要注意退出码的语义。Hook脚本返回非零表示“阻止本次工具调用”。这是设计好的行为但如果你在脚本深处抛了个异常被解释成非零退出结果就是“明明没让它拦它却给拦了”。所以脚本内部异常建议显式捕获成功路径一律返回0。4.4 多项目模板冲突问题如果你同时打开多个项目每个项目都有各自的.claude目录这时候跨项目的命令是会串的。比如我在A项目敲/review它可能加载的是B项目的模板因为Claude Code对工作区的判断是以当前打开路径为准的。建议的做法是模板同步只做“公共层”项目特有模板坚决不进公共仓库。前面提到的同步脚本也要加排除规则把项目独有的命令文件排除掉。我吃过一次亏公共模板里放了个只适用于某个旧项目的命令结果新项目里误触发后生成了跟技术栈完全不匹配的代码。5. 最后分享两个小技巧模板这套东西看着简单真正用好还是需要花时间迭代的。我自己的体会是别一开始就追求“大而全”先从一个高频场景做起比如commit或review用顺手了再慢慢加。还有个小技巧我估计很多人没注意到Claude Code支持在对话里输入/commands查看所有可用命令在每个命令文件里你也可以在frontmatter中加一个argument_hint字段这样输入命令时它会提示应该带什么参数--- name: gen-test description: 为目标文件生成单元测试 argument_hint: 目标文件路径 ---试着用起来吧。模板的价值不在于“写得多漂亮”而在于“每天真正会用到”。先把一个命令打磨到自己满意为止再复制到其他项目里你会发现这套体系越用越顺手越用越离不开。