1. 为什么我会专门维护一整套 Claude Code 模板我先说一个大多数人的真实状态下载了 Claude Code装好之后第一件事就是开个终端直接拿自然语言开始写代码。我也这么干过而且这样用了大概两三个星期。问题不是出在能不能用而是出在每天都要重复说一遍同样的话。每次开一个新仓库我得重新介绍项目背景、技术栈、目录结构、代码风格每次让它做代码审查我得临时写一大段审查标准每次生成测试我的提示词质量波动很大有时候生成的测试很到位有时候完全不能看。于是我开始考虑一件事这些工作流能不能像代码模板一样固定下来。claude-code-templates 这个想法就是从这里来的。它不是一个插件也不是某种需要编译安装的框架它本质上是一套给 Claude Code 用的可复用配置与提示词资产包括 CLAUDE.md 项目指令、.claude/commands 目录下的自定义斜杠命令、hooks 自动触发脚本以及配套的目录规范和命名约定。你把它放进一个独立仓库维护然后在需要的项目里以合适的方式引入就能让 Claude Code 的表现从随机游走的助手变成知道你们团队规矩的固定协作者。写这篇内容是想把我在搭建这套模板过程中的完整思考、目录结构、命令写法、以及连着踩了三周坑才总结出来的教训一次性讲清楚。内容不会只停留在教你写一个命令文件而是会回答几个更关键的问题模板应该怎么分类才不会过时哪些配置该放模板里哪些配置放模板里反而是负资产为什么同样的模板有人用了觉得变笨有人用了觉得效率翻倍适合谁来读我说直白一点如果你是个人开发者手上同时有三四个项目在跑每天跟 Claude Code 打交道的时间超过一个小时那你应该读如果你要带小组想把 AI 协作的标准做法统一起来那你更该读。如果只是偶尔用一下其实不需要模板直接对话反而更灵活。2. 模板分类的第一性原则按工作流切不按语言切很多人的第一个反应是搞一套模板库先按Python 模板JavaScript 模板Go 模板这样的维度去分。这个直觉很容易理解因为我第一次也是这么分的。但用了一个月之后我发现按语言维度建模板有非常大的问题第一每个语言的模板里会有 80% 的内容是重复的比如项目上下文说明代码风格要求输出格式约定。第二一旦某个通用规则要改你得同步改所有语言模板维护成本直线上升。第三真正决定项目差异的往往不是语言而是你在那个项目里要干的活。所以我后来把整个模板库推翻重新设计改成按工作流维度切分。所谓工作流就是你在 Claude Code 里反复要做的那几类动作。对我来说排在前几位的是新项目初始化、代码审查、测试生成、重构迁移、以及需求梳理。每一类动作都可以做成一个独立的命令或一个独立的配置块然后在具体项目里组合使用。2.1 初始化类模板把项目背景一次说清初始化类模板的核心目的只有一个让 Claude Code 在第一次打开某个仓库时就能自动知道这个项目的背景信息而不是等你一句一句地告诉它。这部分主要落地在 CLAUDE.md 里。我给每个项目写的 CLAUDE.md 一般分五块项目一句话简介和技术栈清单目录结构地图包含关键目录的作用代码风格约定包括命名、格式化、提交信息规范高频命令速查比如启动方式、测试命令、构建命令禁止事项比如不要改动某个自动生成的目录不要在没确认的情况下批量替换 API。这里有个关键经验CLAUDE.md 不是越长越好。我最早的时候想既然它能被自动读取那我多写点信息它不就更懂我吗。结果写了一份接近三千字的 CLAUDE.md实际跑下来发现 Claude Code 在长上下文上的损耗非常明显——它会在无关紧要的细节上消耗注意力有时候甚至为了迎合你写的规则而过度设计。后来我把这份文件压到 800 字以内信息密度提上去反而准确率更高了。压缩手法也很简单只保留新成员第一天入职需要知道的事情其余一律删掉或者移入按需调用的命令模板。2.2 审查类模板让检查规则从感觉变成清单代码审查是最适合做模板的场景。如果你用自然语言让 Claude Code 审查代码它大概率会给你输出一堆这段代码看起来不错但可以注意以下几点这样泛泛的评论。问题在于你没有给它审查的依据。审查工作流模板就是要解决这个把好代码的标准固定成显式清单并要求它逐条对照输出。我用的审查类命令长这样/review --scopelogin --depthfull命令内部会引导 Claude Code 先读取变更文件再对照清单逐项检查安全边界是否完整、错误处理路径是否存在、是否引入循环依赖、命名是否跟项目现有习惯一致、是否存在悄悄改动的无关行为。每条检查结果必须给出定位文件和行号不能只给建议。这个必须给证据的约束很关键否则 AI 审查就会退化成一个形容词生成器看起来什么都说了实际上什么都没说。2.3 测试生成类模板减少提示词波动测试生成是我看到的人与人之间差异最大的一类场景。同样一句帮我给这个函数写测试有人能得到完整的边界测试有人只能得到三个 happy path。区别不在模型而在提示词里有没有说清楚测试的约束条件。模板把这个约束固定下来之后输出质量就稳定了。我的测试模板会要求先列出被测函数的输入输出维度再列出边界条件然后才生成测试代码测试命名必须遵循项目既有风格不允许为了通过测试而修改被测试代码如果发现被测试代码存在 bug必须以注释形式报告不能直接改。这四条规则写进命令之后我生成测试的可接受率明显上升尤其是面对那些有大量历史遗留代码的模块模板能强制 AI 不要自作主张去碰业务逻辑。3. 模板的物理结构CLAUDE.md、commands 和 hooks 各自该放什么说清楚分类思路接下来看落地到目录里到底长什么样。Claude Code 本身支持几类自定义机制claude-code-templates 把这套机制组合成一个统一结构。3.1 CLAUDE.md项目级默认上下文CLAUDE.md 是项目根目录下的一个 Markdown 文件Claude Code 在项目里启动时会把它自动作为上下文的一部分读取。你可以再加 CLAUDE.local.md 做本地私有配置也可以针对子目录放 CLAUDE.md 实现局部覆盖。我把 CLAUDE.md 视作模板库的默认脸面。在 claude-code-templates 里我维护了一份通用版 CLAUDE.md任何项目复制过去之后只需要修改项目简介和技术栈部分就能用。这看起来很简单但恰恰是很多人忽略的地方他们让 Claude Code 裸奔的原因就是觉得写 CLAUDE.md 很麻烦。其实一份能用的最小 CLAUDE.md十分钟就能写完收益远远大于投入。很多人的误解是 CLAUDE.md 只能写项目说明其实它还承担着给 AI 定边界的作用。比如我经常在里面写一句话当用户提出与当前项目无关的问题时先提醒用户这偏离了项目上下文而不是硬答。这看起来像废话但实际上能明显减少 AI 跑偏的概率。3.2 commands 目录自定义斜杠命令的核心自定义斜杠命令放在 .claude/commands/ 目录下每个命令对应一个 Markdown 文件文件名就是命令名。文件可以带 YAML frontmatter 来设置元信息比如命令的说明、参数定义。不带 frontmatter 的纯 Markdown 文件也能被识别为命令这是最小可用形态。我重点想讲的是命令文件的组织技巧。一个命令文件不只是一段提示词更准确说它是一条有输入输出的工作流脚本。所以我的命令文件有固定结构开头一段说明何时使用中间是分步执行逻辑结尾是输出格式要求。模板库里不应该出现那种只有一句话的命令文件那种文件用了一次你就会发现跟直接对话没什么区别因为它缺少约束。下面给一个我在模板库里实际在用的 review 命令文件骨架你可以直接抄--- description: 按项目规范对指定范围代码进行审查输出结构化报告 argument-hint: 指定审查范围如 login、pkg/oss 或全部 --- 你是本项目的资深代码审查负责人。你熟悉 {{ $CLAUDE_PROJECT_DIR }}/CLAUDE.md 中约定的代码规范。 请按以下步骤执行审查 1. 使用 git diff 或读取目标目录明确本次审查涉及的变更范围 2. 逐文件对照规范清单安全边界、错误处理、依赖方向、命名一致性、无头行为 3. 对每个问题给出文件路径与行号 4. 输出问题清单按严重级别排序不输出泛泛赞美 注意如果目标范围过大先输出文件清单等用户确认后再逐文件审查。这个命令用起来比直接说review 一下我的代码可靠得多因为它把审查时到底要查什么固定下来了。你不需要在每次审查前重新描述一遍项目规范命令文件会自动读取 CLAUDE.md 里的约定。3.3 hooks少用但用对了很值hooks 是 Claude Code 在特定事件发生时自动触发外部脚本的机制比如在 Claude 执行某个工具之前或之后运行一段检查脚本。模板库里我没有放很多 hooks因为 hooks 的风险比命令高它自动触发一旦脚本写错容易造成误操作或者不断打断对话流程。我只在两种情况下建议用 hooks。第一种是安全护栏比如禁止在未确认的情况下执行删除操作可以在相关的工具调用事件里挂一个检查脚本。第二种是质量门禁比如生成的代码必须通过 lint 才能落地可以在工具调用后自动跑一遍。除此之外大多数你想用 hooks 做的事情用命令模板反而更可控因为命令是你主动触发的具备明确的意图上下文。我给一个安全护栏类 hook 的配置思路{ hooks: { PreToolUse: [ { matcher: Bash(rm|mv|git reset --hard), hooks: [ { type: command, command: echo 检测到高风险操作请确认后手动放行 exit 1 } ] } ] } }这个 hook 的作用就是在 Claude Code 准备执行删除、强制移动或重置操作时先拦一道。这种宁可多确认一次也不误杀的思路适合所有团队成员一起用的场景。4. 从空仓库到一个可用模板库完整落地流程这部分写给你照着做不搞抽象。我假设你已经装好了 Claude Code也知道怎么在终端里启动它接下来只需要把一个空目录变成能用的模板库。4.1 先把目录结构搭好我的 claude-code-templates 仓库目录大概是这个形状claude-code-templates/ ├── README.md ├── base/ │ ├── CLAUDE.md │ └── commands/ │ ├── review.md │ ├── plan.md │ ├── test.md │ ├── refactor.md │ └── explain.md ├── stacks/ │ ├── python-fastapi/ │ └── typescript-nextjs/ └── scripts/ └── install.shbase 目录放通用资产不跟具体技术栈绑定stacks 目录放特定技术栈的补充配置scripts 目录放安装脚本。这个划分对应前面说的分层覆盖原则任何项目都可以先拿 base再根据需要叠加 stacks。比如 python-fastapi 这个 stack 里我只会放跟这个技术栈强相关的内容# Python FastAPI 项目补充约定 - API 路由统一放在 app/routers/ 下模块命名为 xxx_router.py - 数据校验使用 Pydantic禁止在路由函数里手写 if 判断参数 - 数据库会话通过依赖注入获取禁止直接 import session 全局对象 - 测试文件放在 tests/ 下文件名对应被测模块名加 _test 后缀这样 project 拿到 base 之后如果恰好是 FastAPI 项目再拷一份 stack 配置就能得到一个非常贴合实际项目的环境。stack 与 base 分离的价值在于你新增一个技术栈时不需要动通用部分你改进通用部分时也不会碰坏技术栈特有的规则。4.2 第一个模板如何封装一个需求梳理命令如果你之前没写过任何一个模板我建议第一个先做需求梳理或开会前置这种零风险命令而不要上来就做自动生成代码的模板。因为这种命令写错了也无所谓顶多输出一段话不会动你的代码。需求梳理命令的目标是当你拿到一个模糊的 feature 需求时让 Claude Code 通过和你问答的方式产出一份可执行的结构化需求说明。我管它叫 /plan。它的实现思路是命令文件里定义一系列必须确认的问题链每轮只问两三个问题把用户回答逐步收集最后按固定格式输出需求文档、任务拆解、以及风险点。我的 plan 命令核心逻辑大概长这样--- description: 通过问题链梳理需求输出可执行开发计划 argument-hint: 粘贴原始需求描述或说明要启动的功能 --- 请把用户给出的原始需求拆解为问题链每轮最多问 3 个问题所有问题确认完毕后输出 1. 需求一句话版本 2. 功能拆解按用户视角不按技术视角 3. 边界情况清单失败时行为、兼容性要求、数据量级预估 4. 技术影响面涉及哪些现有模块 5. 建议实施顺序 规则不要在第 1 轮就给出完整方案如果原始需求里已经有明确信息不要重复提问所有问题只与需求本身有关。实际执行效果是从我不知道这个功能怎么做到我有一份任务清单的时间大概能压缩一半。关键是它强制你思考边界条件——模板里的问题链会问这个功能失败时应该怎么表现兼容旧的调用方吗数据量级预估是多少这些问题是人类开会时最容易漏掉的。我经常发现跑完一次 plan 命令之后原本以为很简单的一个需求实际存在着三四个我根本没想过的边界问题。4.3 引入到现有项目两种方式模板库本身是一个仓库怎么把一个模板引入到你在开发的项目里我试过两种方式。第一种是手动复制简单粗暴把 base 目录下的 CLAUDE.md 和 commands 复制到目标项目的根目录和 .claude/ 目录下。第二种是脚本化安装我在 scripts/install.sh 里写了复制逻辑支持如下用法bash scripts/install.sh /path/to/your/project --stack python-fastapi脚本会先检查目标目录有没有已存在的 CLAUDE.md 或 .claude/commands有的话会先备份再覆盖避免误伤。这里特别提醒直接覆盖是危险的你原来的配置可能是调过很久的结果一个 install 脚本清掉你会想骂人。所以我在脚本里始终保留备份逻辑这是踩过一次坑之后才加的。安装脚本的核心逻辑可以简化成#!/usr/bin/env bash PROJECT_DIR$1 STACK$2 BACKUP_DIR${PROJECT_DIR}/.claude-backup-$(date %Y%m%d%H%M%S) if [ -f ${PROJECT_DIR}/CLAUDE.md ]; then mkdir -p ${BACKUP_DIR} cp ${PROJECT_DIR}/CLAUDE.md ${BACKUP_DIR}/ echo [备份] 已备份原有 CLAUDE.md 到 ${BACKUP_DIR} fi cp base/CLAUDE.md ${PROJECT_DIR}/CLAUDE.md mkdir -p ${PROJECT_DIR}/.claude/commands cp base/commands/*.md ${PROJECT_DIR}/.claude/commands/ if [ -n $STACK ]; then cp stacks/${STACK}/CLAUDE.md ${PROJECT_DIR}/CLAUDE.local.md fi你可以根据自己的实际目录调整路径但核心思想一致先备份再覆盖最后输出一份安装报告。这比纯手复制要可靠得多。4.4 用 tree 或 ls 验证安装结果装完之后别急着开始对话先验证一下。我会在项目里跑一条命令ls -la CLAUDE.md CLAUDE.local.md .claude/commands/确认几个文件都到位了再启动 Claude Code输入/看命令列表里有没有新命令出现。如果命令没出现大概率是 frontmatter 写错了或者目录名不对直接排查这两块就行。5. 这三周踩过的坑比官方文档教我的都多最后想集中写一写我在真实项目里遇到的高频坑。这些内容你翻官方文档翻不到基本上只能靠实际使用攒出来。5.1 最大的坑模板太肥上下文被吃光我最早做出来的第一版模板库里面有一份巨详细的 CLAUDE.md还有十几个命令文件。结果在实际项目里Claude Code 经常出现上下文被塞满聊着聊着开始忘事的问题。排查之后发现问题出在两条机制上一条是 CLAUDE.md 是每次会话自动加载的所以它的体量直接决定每次对话的起步开销另一条是 .claude/commands 里的所有命令元信息也会被加载命令数量太多同样会占空间。解决方式是我后来反复提到的那句话CLAUDE.md 控制字数commands 控制数量。CLAUDE.md 我压到 1000 字以内只保留新成员入职须知commands 我只保留真正高频使用的四五个其余冷门命令放到一个子目录归档用的时候再手动引入。改完之后明显感觉到对话的记忆窗口宽了最后解决问题的成功率也高了。5.2 frontmatter 写错命令静默消失这个坑发生率非常高写了一个命令文件斜杠命令却怎么都加载不出来。我一开始以为是文件名有没有对齐、目录名有没有搞错结果都没问题。后来仔细排查才发现是 YAML frontmatter 里的字段名写错了。比如把 description 写成 describe或者 argument-hint 写成了 arguments那么 Claude Code 就可能不把这个文件识别为有效命令。诡异的是它不会给你任何报错只是命令列表里不出现你还在那研究是不是路径错了。我的经验是每新建一个命令文件先用最简单的形式验证只有一行 # 标题没有 frontmatter确认能加载出来再加 frontmatter。少量增量的方式能帮你快速定位到底是内容问题还是格式问题。另外frontmatter 里的描述建议控制在一两句话内太长的描述同样会占用上下文。5.3 hooks 的误触发比想象的更常见前面我说 hooks 要少用那次教训就是从一次误触发来的。我当时想加一个代码修改后自动跑测试的 hook逻辑很简单但真正在项目里跑起来就会发现它会在你只想改一行注释的时候也触发测试甚至在某些工具调用前后连续触发多次整个对话节奏被打乱。最后我把 hook 改成命令模板需要跑测试的时候手动执行反而更顺手。这里面的本质问题是hooks 缺少意图判断它只能根据事件类型和工具匹配条件去触发但它判断不了你是不是真的想跑测试。在你专心改代码的时候莫名其妙跑一轮全量测试这种打断非常伤。5.4 模板需要版本管理也需要反版本管理还有一个容易被忽略的点模板库本身要有版本记录但模板里的内容不要追求频繁更新。你不需要为模板的每次改动都写长篇 changelog但至少要保留一个逐条增删的清单否则三个月后你根本不知道某个命令当初是为什么加进来的。我在 README 里维护了一个很短的历史记录类似v0.3 增加 plan 命令原 init 命令拆分v0.2 精简 CLAUDE.md删除过长目录说明v0.1 初始版本包含 review/test/refactor 三个命令这种记录看起来不起眼等你想做新一轮调整的时候它就是你最好的决策依据。另一个反直觉的体会是不要急着把第一次写的模板立刻推给全团队用。先在自己日常项目里用两周改掉至少一轮再说。团队协作场景下一个设计得不舒服的模板会放大所有人的挫败感而你自己先试用则可以过滤掉大部分问题。6. 模板的持续演进从能用到好用的两次关键迭代模板库不是写完就完了它需要持续演进。我把它拆成三个具体维度命中率、容错率、可解释性。6.1 命中率模板是否真的解决了你的高频需求判断一个模板值不值得保留标准很简单它是否让你的使用频率提高了如果一个命令你连续两周都没用过那它大概率不是真实需求。我在 claude-code-templates 里保留的命令全部是在过去一个季度里至少用过五次的。那些看起来很酷但实际不常用的命令我宁可删掉也不保留因为它们会变成上下文里的噪音。有一个典型的例子是我早期做过的commit message 生成模板。当时觉得很好用但后来发现我直接让 Claude Code 看 git diff 再提交反而更快模板反而成了一个多余步骤。删除模板不是否定当初的工作而是承认它已经被更自然的交互方式取代了。6.2 容错率模板在出错时如何表现模板的作用不只是输出好结果更关键的是在情况不明确的时候它知道该怎么表现。我见过很多模板的毛病是假设条件写得太满一旦现实跟假设不一致AI 就开始硬编。比如 review 模板假设所有代码都在 git diff 里但实际项目里有人直接改完没提交这时候模板会不知所措。我的改进方式是给模板加前置检查步骤。比如 review 命令的第一步被设计为先检查 git diff 是否有内容如果没有就提示用户代码是否已暂存plan 命令会在第一步检查原始需求里是否已有明确的技术方案如果有就直接跳到方案评估阶段。这个先判断状态再决定路径的思路比那种一条路走到底的模板稳定得多。6.3 可解释性模板里的每个指令都要能回答为什么最后一条是我自己在迭代过程中沉淀的原则模板里的每一条规则都要能回答为什么这条规则存在。如果某条规则连你自己都说不出原因那就删掉。因为 AI 会严格执行模板里的指令哪怕这条指令不合理。你写下的每一句话都会被当成权威约定去执行。举个例子我在模板里写过所有函数都要有 docstring后来发现这个项目里的 util 脚本有一些内部小函数写 docstring 纯属浪费。于是我把这条规则改成了公共导出函数必须写 docstring内部临时函数不强制。修改之后那个项目里生成的代码明显更符合实际团队的代码风格了。模板不是用来约束 AI 的模板是用来让 AI 跟你的团队标准对齐的所以它必须精确。差不多就是这些。如果你也维护着类似的 claude-code-templates 项目或者正打算从零开始做一套希望这内容能让你少走点弯路。模板的价值不在生成的那一刻而在于你把它当作一套持续演进的工程资产去对待的那种心态。真正用起来之后你会发现自己越来越不喜欢从空白对话开始的开发方式——那种每次重新解释一遍背景的时间才是被悄悄浪费掉的最大成本。