先说一个我被逼无奈整理模板库的真实场景。那阵子我手上同时有三四个项目技术栈不同、代码规范不同、commit信息风格也不同。每天开工第一件事就是在Claude Code里把这些项目差异重新解释一遍这个仓库用pnpm、测试是vitest、路由命名要kebab-case……解释完它确实听懂了但换个会话、换个终端窗口一切照旧。我意识到问题不在模型在于我没给它准备一套模板体系。claude-code-templates这个仓库起手方向通常不是给代码生成脚手架模板而是把AI协作者自己的工作方式模板化。你给Claude Code讲一遍团队规范、讲一遍review风格、讲一遍任务拆分套路它当场执行得很漂亮可是下一次会话你又要重新讲一遍。模板做的事情就是把讲一遍变成读一次文件。这篇文章我梳理一下自己搭模板库的完整思路从目录结构、指令文件、slash command到进阶的自维护工作流全部是基于实际项目反复调出来的经验适合已经把Claude Code用起来、但还没给它建立长期记忆的人。1. 在Claude Code里templates到底指什么先说破一个误区。很多人一听代码模板下意识想的是react-ts模板、node-api模板这类脚手架然后问Claude Code不是本来就会写代码吗我存一套模板有什么用确实你往对话里丢一句按Vite React TS的标准结构开一个新项目它立刻能搭出来。但那是一次性的是临时命令和模板没关系。真正值得沉淀的模板是给AI协作者的指令模板、约定模板和工作流模板。Claude Code本身有一套持久的上下文机制用来把这类信息固化常用的包括CLAUDE.md放在项目根目录或全局配置目录下每次对话自动加载相当于AI的入职手册。自定义slash command放在.claude/commands/目录下的Markdown文件你输入/命令名就是把一整段精心设计过的提示词喂给模型。Output Style定义模型输出的表达风格让它不管在哪个项目里产出的格式都符合你的偏好。Agents子代理把某类专职任务挂到特定角色上比如只做代码审查的senior reviewer。这四样东西合在一起才构成完整的claude-code-templates体系。它们解决的痛点是一致的把每次会话都要重复说的话变成文件把每次都要碰运气才能得到的高质量输出变成稳定的预期。1.1 模板的真正载体不是脚手架而是指令与约定我见过有团队把通用提示词写在一个自己维护的prompts/文件夹里每次要用了就打开文件复制粘贴。这当然也算模板但很笨。Claude Code的模板优势在于它是自动加载和命令触发的。自动加载的是CLAUDE.md。你只要把约定写在里面每次在这个目录里启动会话它就已经读过了你不需要再复述。命令触发的是slash command你把一段写好的提示词存成/review.md之后输入/review src/utils/date.ts就够了后面那一串参数会被映射为$ARGUMENTS注入到提示词里。所以构建templates的关键不是写Prompt而是设计这套文件的组织方式什么内容自动加载、什么内容按需触发、什么内容分配给专职Agent。组织方式对了模板库才有复用性否则就只是一个堆满Markdown的杂物间。1.2 三类模板仓库全局、项目、团队我用下来最顺手的划分是三层。全局模板放在~/.claude/下面服务的是我这个人的通用偏好我习惯commit信息用中文还是英文、我要求模型在动手前先列计划、我禁止它乱删文件等等。这些跟你写哪个项目无关放全局。项目模板放在project/.claude/下面服务的是这个仓库的专属事实数据库迁移脚本不能乱动、API路径前缀是/api/v2、测试要用哪套mock方案。内容可能不多但都是换个项目就完全不成立的信息。团队模板则是把项目模板里通用性较强的部分抽出来放进git仓库共享大家一起维护。三层之间会有覆盖和补充关系后面第5节我会专门讲怎么避免它们互相打架。2. 目录怎么搭文件怎么分一套能落地的模板结构很多人搭模板库的第一反应是写一个CLAUDE.md把什么内容都往里面塞。这是最朴素也最容易翻车的做法。我后来才意识到模板库的结构设计直接决定了AI能不能用上它。一个CLAUDE.md文件里塞了几十条碎片化的规则模型不是记不住而是不知道哪条规则在哪个场景下最重要。你让它写测试的时候它反而会优先执行排在文件开头的那条所有文件名用kebab-case而不是现在最该关注的测试文件里不要mock外部请求。信息没有分层、没有触发条件这就是典型的模板失效。我的做法是把模板库拆成不同目录让内容各就各位自动加载的只放最高频的约定按需执行的放进commands需要专职角色处理的放进agents影响输出观感的放进output-styles。2.1 全局模板目录的布局我本机的~/.claude/目录大致长这样~/.claude/ ├── CLAUDE.md # 全局指令跨项目的个人偏好 ├── settings.json # 权限、hooks、模型等配置 ├── commands/ │ ├── commit.md # /commit规范提交信息 │ ├── review.md # /review代码审查 │ ├── plan.md # /plan需求拆解成任务 │ ├── update-templates.md # /update-templates让AI自维护模板库 │ └── ... ├── output-styles/ │ ├── verbose-report.md # 详细报告风格 │ └── concise-review.md # 简洁审查风格 └── agents/ ├── senior-reviewer.md # 专职老手审查员 ├── docs-writer.md # 专职文档编写 └── test-architect.md # 专职测试设计CLAUDE.md保持精简只写没有争议的、跨项目都成立的内容比如回答中文问题用中文、动工前先展示执行计划、禁止用rm -rf这类危险命令除非用户明确要求。这类规则放全局没问题但数量要克制。2.2 项目级模板的接入方式每个项目下我习惯建一个.claude/目录project/ ├── .claude/ │ ├── CLAUDE.md # 项目专属约定自动加载 │ ├── commands/ │ │ ├── gen-api.md # /gen-api按接口文档生成调用代码 │ │ ├── db-check.md # /db-check检查迁移脚本安全性 │ │ └── ... │ ├── settings.local.json # 项目级权限与hooks │ └── agents/ │ └── backend-specialist.md项目级CLAUDE.md放的是这个仓库特有的死规矩。比方说这是每个会话都必须被提醒的不能改动migrations目录下已提交的文件API请求必须走统一的request封装新代码不引入moment.js。这些内容不在项目级文件里只放在commands里的原因是它们不是每次都要用而是触发某类任务时才需要。比如检查迁移脚本安全性这件事把它存在/db-check里需要的时候一条命令调出来比自动加载占用上下文更划算。2.3 一个CLAUDE.md的配料表很多人把CLAUDE.md当成聊天背景板想到什么写什么。我建议按照下面这个配料表往里放东西# 项目指令 ## 基础事实 - 主要语言TypeScript - 包管理器pnpm - 测试框架Vitest Testing Library - 目录结构src/features/...src/shared/... ## 代码约定 1. 新文件名一律 kebab-case 2. 后端接口返回结构保持 { code, data, message } 3. 提交信息格式feat(scope): description ## 必须避免 - 不要改动 database/migrations 下已合并的文件 - 不要在业务代码中直接使用 window.alert - 不要新增 axios 实例统一用 shared/request ## 当前上下文 - 主干分支为 main发布流程见 ops/README.md注意CLAUDE.md里写的是事实和禁区不是长篇大论的教学。模型本来就知道怎么写代码不需要你教它什么是防抖它需要的是知道这个仓库里防抖工具函数在哪、命名是什么。事实越精准指令越短执行越稳。3. 写Slash Command模板的完整实战CLAUDE.md是自动加载的适合放常态信息。但真正让模板库发挥威力的是slash command。它把一整段带有明确步骤的提示词封装成命令让AI在特定任务上保持稳定的输出质量。Slash command的文件本身就是一个Markdown模板放在.claude/commands/目录下文件名就是命令名。基础结构包含可选的frontmatter和正文。我拿三个实际在用的命令演示一下设计思路。3.1 最简单也最常用的commit信息模板虽然Claude Code有内置的提交信息能力但要做到符合团队规范、按scope归类、正文说清楚动机自定义模板依然更可靠。我在~/.claude/commands/commit.md里这样写--- description: 生成符合Conventional Commits规范的提交信息 --- 请阅读下面这些git diff生成一条符合项目规范的commit信息。 $ARGUMENTS 要求 1. 使用 Conventional Commits 格式type(scope): subject 2. type 限于 feat / fix / refactor / docs / test / chore 3. subject 不超过50个字符用中文概括改动意图 4. 正文逐条列出关键改动与原因不要逐行复述diff 5. 如果diff过大先总结主要模块再展开实际使用时先git diff复制进来再输入/commit它就会按这个标准生成。$ARGUMENTS是模板的核心占位符用户的输入会原样替换到那个位置。我这边的经验是模板里把不要做什么写清楚往往比要做什么更管用。第5条就是典型的例子diff一大模型容易陷入逐行翻译所以提前给一个兜底策略。3.2 代码审查模板把Checklist交给AI代码审查是我用Claude Code最重的场景。它的难点在于模型看代码的能力足够但经常会给出这行代码可以再封装一下这类没有信息量的意见。等我把它调教成能说人话以后我把整套标准固化成了/review命令--- description: 对指定文件或代码块做系统性代码审查 agent: senior-reviewer --- 请以团队资深审阅者的身份审查以下代码 $ARGUMENTS 审查流程 1. 先阅读相关上下文文件理解改动意图不急于下结论 2. 按严重级别输出问题列表P0阻塞合并、P1应修复、P2建议优化 3. 每个问题必须标注文件路径、行号、问题描述、修复思路 4. 关注真实缺陷边界条件、并发安全、错误处理遗漏、性能风险 5. 不要输出风格偏好类意见如这里换个写法更好除非影响可维护性 6. 审查结束后给出合并建议批准 / 需修改 / 需重新设计三个设计要点。其一用agent字段把审查任务交给专职子代理后面第4.2节细说。其二第4条明确了什么才是需要输出的内容把模型的注意力从到处找茬拉回到找真实缺陷上。其三第6条强制它给出结论避免给一堆意见却没有倾向性。3.3 复杂工作流模板需求拆分与任务规划还有一类模板是针对半结构化工作流的。比如拿到一段含糊的需求描述我不要它立刻写代码而是先拆任务。这个模板长这样--- description: 将一段需求描述拆解为可执行的任务清单 --- 请基于下面这段需求描述完成任务拆解 $ARGUMENTS 处理步骤 Step 1提取需求的硬性约束时间、性能、兼容性、数据安全 Step 2识别涉及的技术模块标注不确定点 Step 3按数据层 - 业务层 - 展示层输出任务清单 Step 4每个任务标注依赖关系和验收标准 Step 5输出风险项与需要我确认的决策点这个模板的价值在于我把我自己拆需求时的思考顺序写成了流程让AI照着走而不是直接给一个结果。实际用下来Step 5特别有用。模型如果对需求理解有偏差之前会悄悄绕过去现在它会明确列出这几个决策点需要你确认把歧义暴露出来避免后期返工。4. 模板进阶输出风格、子代理与模板自维护基础模板建好以后你会很快进入一个阶段命令是好用了但输出的样貌还不够统一。比如让它写缺陷报告它一会儿用表格一会儿用段落一会儿又突然变成口语。这种问题靠slash command解决不了因为它横跨所有任务。这时候要引入两个进阶机制Output Style和Agents。4.1 Output Styles定义怎么说Output Style的思路是在output-styles目录下存放描述文件定义模型在回复时的表达方式。它不是写什么而是怎么说。我在~/.claude/output-styles/code-review.md里写了这样一套约束--- name: code-review-style --- 当你在输出代码审查结果时遵循以下风格 - 问题列表使用紧凑表格严重级别 | 文件 | 行号 | 一句话描述 - 每行问题描述不超过30个字 - 修复建议放在表格后的独立小节 - 全程使用祈使句不用敬语和寒暄这个机制非常适合让团队里所有成员共享同一种输出风格。把风格文件放进git仓库新人拉下来一放AI产出的报告格式就和老员工的一致了。项目模板库如果只能做一件事我建议先做output styles见效最快。4.2 Agents把模板挂到专职角色上Agents是比slash command更重一层的封装。slash command是调用一段流程Agent是起用一个人设。我定义了一个专职的审查者存在~/.claude/agents/senior-reviewer.md里--- name: senior-reviewer description: 以资深后端工程师视角审查代码 --- 你是一名有10年后端经验的工程师在分布式系统和高并发场景上有丰富积累。 你的审查风格 - 优先寻找数据一致性、并发边界、错误恢复等深层次问题 - 不会因为代码风格与你的偏好不同而给出意见 - 每一条意见必须有明确的行为后果说明 你擅长的领域事务边界、缓存一致性、分布式锁、幂等设计。然后回到第3.2节的/review命令frontmatter里用agent: senior-reviewer指向它。效果很明显模型在整个审查对话里都保持这个角色而不是每次打开会话都回到通用助手。如果你有多个专职Agent建议把它们的定义文件都放进模板库统一管理。4.3 让Claude Code自己维护模板库模板库最大的维护成本不是建而是改。规则过时了怎么办命令不好用怎么办手动改所有markdown文件太累。我的做法是写一个slash command让Claude Code自己管理自己的模板。这个/update-templates命令大约长这样--- description: 根据最近对话记录优化commands与CLAUDE.md --- 请检查以下模板文件并根据要求优化 $ARGUMENTS 优化目标 1. 删除不再使用的规则合并重复条目 2. 将每次会话重新解释过的偏好吗补入合适的CLAUDE.md 3. 如果你发现某个command经常需要额外补充说明说明模板遗漏了关键约束 4. 输出修改前后的diff等我确认后再写入命令的正文没有写死具体文件名单我用$ARGUMENTS传入必要时让它自己扫描~/.claude/目录。第4条是安全阀AI自我修改模板库是有风险的我做一次确认再落盘。这个自维护机制运行一段时间后模板库会越来越贴合你的真实习惯。说到底模板是给AI用的启动配置也是给人看的团队文档它必须保持呼吸。5. 模板设计中的坑以及我现在的取舍原则前面讲的都是搭建方法最后专门说说坑。我在迭代模板库的过程中犯过不少错有些是逻辑上的有些是使用习惯上的。写出来你能少走几个星期弯路。5.1 模板膨胀什么该放什么不该放最常见的翻车方式是CLAUDE.md越写越长最后变成一本300行的团队Wiki。模型读取时确实全部能看到但注意力会被稀释。它看到文件名规范、技术栈、部署流程、测试约定、代码风格……真正该在当前任务中执行的那几条反而淹没在噪声里。我的经验是三层过滤全局CLAUDE.md只放铁律比如禁止危险命令中文回答项目CLAUDE.md只放事实比如包管理器是pnpm接口返回结构固定可做可不做的建议一律放commands用的时候临时调出来。模板是给AI减压的不是给它加记忆负担的。5.2 优先级冲突与夺权式模板模板库覆盖范围变广以后一定会有内容冲突。全局说commit信息用中文某个项目说commit信息必须纯英文便于生成changelog。模型遇到这种冲突不会自己仲裁它只会随机选择或问你要答案。我的解决办法是在全局CLAUDE.md里明确写一条优先级顺序规则。- 当冲突出现时按以下优先级执行 1. 用户当前对话中的明确指令 2. 项目级 .claude/CLAUDE.md 3. 全局 ~/.claude/CLAUDE.md 4. 模型默认行为这样全局默认虽然是中文commit但项目级文件里写了纯英文模型就能明确识别当前场景的优先级不会摇摆。另一个坑是夺权式模板。我见过有人为了让AI严格按照规范执行写了极其庞大的条件分支要求它在所有场景下按流程走。结果模型不再有基本判断力连用户就是想快速改个变量名都要先跑一遍完整需求拆解流程。模板应该提供边界和行为预期不应该剥夺用户的临场控制权。所以我现在写命令模板时总是留一句如果任务非常简单可以跳过Step 2和Step 3直接给出结果给模型一条逃生通道。5.3 我踩过的坑和当前推荐做法最后分享三个具体教训。第一参数占位符一定要写清边界。最初我在review模板里只写审查以下代码$ARGUMENTS结果用户粘贴一段代码后模型可能顺着代码里的小问题扯远。后来我在模板里写仅审查$ARGUMENTS中出现的范围不要扩展到调用链以外的部分误判少了很多。第二命令名和内置命令撞车。我最早建了一个/new命令用来生成新组件模板但Claude Code本身有类似的创建功能结果经常触发错命令。给自定义命令起名时我建议要么加前缀/gcommit要么选有业务含义的词/gen-api、/db-check避开通用动词。第三模板也要做定期清理。一个项目用了半年早期写的某些规则可能早就失效了比如测试文件统一放__tests__目录后来已经改成co-located写法。我现在每两到三周跑一次专门清理任务让模型找出模板中与当前项目结构不符的条目我确认后删掉。这套机制比人工维护靠谱得多。还有一点想提醒模板库不是一次建完就结束的它本身就是代码需要Refactor。我的建议是所有模板文件都纳入git管理每次调整都留提交记录。这样你的模板库会慢慢从几条零散规则进化成一套能描述团队协作方式的工作流协议。以后不管是你自己开新项目还是新人加入项目把模板库一铺Claude Code就知道该怎么用正确的姿势干活了。