1. 为什么我把模板看得比提示词更重要1.1 从每次重新交代到一次沉淀、长期复用大概半年前我开始重度使用 Claude Code最开始和大多数人一样每开一个新项目就往终端里粘贴一大段项目背景说明然后才开始让它干活。头几次还行项目一多就出问题了要么忘了贴要么贴得不全Claude 频繁问出一些我在文档里已经写过无数遍的基础问题。后来我意识到问题的核心不在怎么把提示词写得更长、更细而在怎么把协作规范沉淀下来。于是我开始整理 claude-code-templates 这套模板库——它不是一个提示词收藏夹而是一整套工作流的起点项目长期记忆、常用操作命令、自动化钩子、角色分工全都在模板层面固化下来。这篇文章会完整拆解这套模板里到底有什么、每部分背后的设计理由、从零搭建的具体步骤以及我实际用了几个月之后踩过的坑。适合两类人一类是已经在用 Claude Code、但对每次都要重复交代感到疲惫的开发者另一类是团队里想统一 AI 协作规范、却又不知道从哪儿下手的技术负责人。1.2 模板解决的三个真实痛点我总结下来模板至少解决三个层面的事。第一上下文一致性。同一个项目今天你让 Claude 按项目规范写代码明天忘了提它就按默认风格来。在 AI 辅助编码时代代码风格漂移会变得特别致命因为 AI 产出的速度太快一次漂移就是几百行。等人工 review 发现的时候重构成本已经很高了。第二新人上手成本。团队里来了新同事与其让人家读十篇 onboarding 文档不如把关键约定写进模板。新人只要打开 Claude CodeAI 会主动告诉他这个项目的构建命令、测试命令和代码规范相当于给 AI 装了一套入职培训。第三重复劳动自动化。每次提交前都要跑 lint、格式化、单元测试这类事情完全可以做成斜杠命令或者 hook让 Claude 一键完成而不是手动敲三遍指令。这是模板最直观的收益省时间而且省的是每天都会发生的时间。1.3 模板与提示词的本质区别很多人分不清这两者以为模板就是把提示词存起来下次复制粘贴。不是的。提示词是临时的模板是持久的。提示词靠人每次记得用模板靠文件在项目启动时自动加载。提示词的质量取决于你当天的心情和记忆力模板的质量取决于你迭代了多少次、踩过多少坑。打个比方提示词像是你出门前口头嘱咐一句记得买牛奶回来模板则是把家里所有常用物品的位置、采买清单、供应商联系方式都写在一本册子里放在门口鞋柜上每天出门自动看到。两者的信息密度不在一个量级。理解了这层区别你才会明白为什么值得花时间把模板打磨好——它是在给 AI 协作者建立肌肉记忆不是写一份用完就扔的便签。2. claude-code-templates 的核心构成2.1 CLAUDE.md项目的长期记忆整个模板体系里CLAUDE.md 是灵魂文件。它放在项目根目录Claude Code 每次启动、每个会话开始时都会自动读取它。换句话说你不需要在任何一次对话里重新介绍项目背景Claude 自己就会知道。我的经验是CLAUDE.md 至少覆盖五个方面项目简介与架构概览、常用命令build / test / lint / dev、代码风格与命名规范、目录结构说明、明确禁止的事项。这里最需要注意的一点是不要把它当成团队文档来写。CLAUDE.md 是给 AI 的行动指南不是给人看的项目百科。我见过有人把架构演进历史、会议决策记录全塞进去结果 Claude 反而更迷糊——它不知道哪些是当前必须遵守的哪些只是背景信息。判断标准很简单写进去的每一句话都必须能直接影响 Claude 的一个具体行为。影响不了的删掉。2.2 斜杠命令把有效提示词变成可复用资产斜杠命令定义在项目的.claude/commands/目录下每个 markdown 文件就是一个命令。你在对话里输入/reviewClaude 就会读取review.md按里面定义的流程执行完整的代码审查。这是模板里性价比最高的部分。原因在于每个人在和 Claude 协作的过程中都会积累一些这次效果特别好的提示词。比如你某次发现先看 git diff 再逐文件审查最后按严重程度排序输出报告这个流程特别有效——但如果你不把它固化下来下次还得重新组织语言而且组织出来的可能就不是最优版本。斜杠命令解决了这个问题。我目前常用的几个/review代码审查、/test补测试、/refactor重构、/commit生成提交信息并提交。每个命令文件通常不超过 30 行但都是经过实战验证的高质量指令。2.3 hooks让规范从口头约定变成自动执行hooks 配置在.claude/settings.json里可以监听 Claude Code 生命周期事件比如PreToolUse、PostToolUse。通俗地讲你可以在 Claude 调用某个工具之前或之后自动执行一段你自己的脚本。最典型的用法在 Claude 写完文件之后自动跑一遍格式化和 lint。这样它产出的代码从一开始就符合项目规范而不是等你最后人工兜底。hooks 的核心价值在于它把规范从被动约束变成了主动行为。CLAUDE.md 是告诉 Claude应该这么做斜杠命令是告诉 Claude可以这么做而 hooks 是让所有产出必须已经这么做。三层配合下来规范就不再是纸面文章。2.4 子代理与角色分工Claude Code 还支持定义子代理放在.claude/agents/目录下。每个子代理有自己的专属指令和工作目标你可以把它理解成一个有明确岗位职责的虚拟同事。我在模板库里定义了两个子代理一个是测试工程师专门负责分析代码、设计测试用例、补单元测试另一个是代码评审官专门从性能、安全、可维护性三个维度挑毛病。子代理的价值在于角色隔离。主对话负责统筹子代理负责专项。这比在同一个上下文里频繁切换角色要稳定得多——你不会因为现在请你当测试专家这句话说完之后、聊了三轮需求就把这个设定忘了因为子代理的指令是独立加载、独立维护的。3. 从零搭模板一份可直接照做的实操记录3.1 动手前先做的三件事不要一上来就追求大而全。先花半小时回答三个问题这个项目里你最常让 Claude 干的五件事是什么哪些事情是你每次都要重复交代、它还会时不时忘掉的项目里最容易出错、最不能让步的约定有哪些这三个问题的答案就是你模板第一版内容的全部来源。注意这三个问题的答案不需要一次想完整。第二版、第三版的内容会在你使用过程中自然长出来——每当你发现 Claude 犯了同一个错误两次就对应加一条约束。3.2 第一版 CLAUDE.md 怎么写到 100 行拿一个真实项目举例。假设这是一个 Next.js 项目TypeScript测试框架是 Vitest样式方案是 Tailwind。第一版 CLAUDE.md 可以长这样# 项目企业级 SaaS 控制台 ## 技术栈 - Next.js 14App Router - TypeScript严格模式 - Tailwind CSS - Vitest Testing Library - Prisma PostgreSQL ## 常用命令 - 开发npm run dev - 测试npm run test - Lintnpm run lint - 构建npm run build ## 代码规范 - 组件文件使用 kebab-case 命名 - 禁止使用 any确实无法推断类型时使用 unknown 并显式收窄 - 优先使用 Server Components需要交互才用 Client Components - 样式统一用 Tailwind禁止写内联 style - 错误处理统一用 Result 模式不抛裸 Error - API 路由的入参必须做运行时校验zod ## 目录结构 - app/ 路由与页面 - components/ui/ 基础 UI 组件 - components/features/ 业务组件 - lib/ 工具函数与通用逻辑 - server/ 服务端逻辑与数据访问 ## 禁止事项 - 不要修改 app/api 下既有接口的契约字段名、请求方式 - 不要引入新的 UI 依赖除非明确要求 - 不要提交包含 console.log 的调试代码写完之后自己读一遍用前面说的标准校验每一句话是否都能直接改变 Claude 的一个行为能就够了。不能删掉。我特别想强调的是CLAUDE.md 不是项目说明书它是行动准则。所以这个项目由哪个部门负责为什么选择 Next.js这类内容不要写写遇到什么问题用什么模式处理。3.3 把高频操作固化成三个斜杠命令CLAUDE.md 解决知道斜杠命令解决会做。以我的/review.md为例执行一次完整的代码审查。流程如下 1. 先用 git diff 查看当前分支相对主干的所有变更 2. 逐文件审查重点关注 - 类型安全是否有 any、是否存在不安全的类型断言 - 错误处理是否吞异常、是否丢失错误上下文 - 性能是否有重复计算、N1 查询、无意义的重渲染 - 安全是否有注入风险、敏感信息是否可能泄漏 3. 输出结构化审查报告按严重程度阻断 / 建议 / 可选排序 4. 对阻断级别问题直接给出修复方案这个命令文件本身不重复 CLAUDE.md 里的规范细节因为 Claude 已经通过长期记忆知道了。它只负责定义流程规范由记忆层提供。这也是模板保持简洁的关键——不要让文件之间大量重复内容否则维护起来会痛苦死。3.4 用 hooks 打通 lint 链路的配置示例hooks 配置我建议从最小可用的方案开始。以下是我在模板库里默认带的一段配置{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npx eslint --fix \$CLAUDE_FILE_EXTENSION\ } ] } ] } }这段配置的含义是每当 Claude 编辑或写入文件之后自动对对应文件跑一次eslint --fix。第一次配完之后你会看到一个明显的现象——Claude 产出的代码再也不会出现风格突然不一致的问题因为风格在生成那一刻就被修正了。要注意hooks 脚本要写得足够健壮尤其处理文件路径时要带引号防止路径里出现空格导致命令错误。而且脚本的退出码要可控格式化修复失败不应该阻塞整个任务但真正严重的问题需要让 Claude 知道。3.5 验证模板的两个标尺模板搭完之后找两个真实任务试跑一遍。我的验证标尺只有两个第一不提示能不能干活。开一个全新会话直接给任务看 Claude 是否已经知道项目结构、命令和规范。如果它还在问这个项目的测试命令是什么说明 CLAUDE.md 没写到位。第二产出是否符合规范。跑完一个任务检查代码风格、目录放置、错误处理方式是否和模板里约定的一致。不一致说明约束还不够强要么把语言改得更明确要么加 hook 做硬性约束。这两个标尺跑通了模板的第一版就算合格了。不要追求完美先让它能跑然后在真实使用中迭代。4. 实战中踩过的四个坑4.1 模板过度设计2000 行 CLAUDE.md 的反面教材我见过有人把 CLAUDE.md 写到两千行事无巨细全塞进去从命名规范到注释风格到 git commit 格式到发布流程。结果就是 Claude 在关键决策时反而更迷糊因为重要信息被淹没在海量细节里。后来我做了一次实验把项目里所有规范文档自动合并且精简对比效果。结论非常明确——精简版本的任务完成质量明显更高。原因不复杂Claude Code 的注意力分配受上下文长度影响模板越长关键约束的权重被稀释得越厉害。所有信息都重要就等于所有信息都不重要。我的经验是 CLAUDE.md 控制在 100200 行。超过这个量就该把内容拆分到斜杠命令、hooks 或子代理里各司其职不要挤在一个文件里。4.2 规范漂移模板文件也要走评审模板文件是代码的一部分必须纳入版本控制而且改动要走正常的代码评审流程。听起来像是废话但真做起来很容易忽略。我自己就翻过车一次在功能分支上顺手改了 CLAUDE.md 里的目录约定合入主干时没有代码冲突Git 没有报警我就合了。结果那个分支上特有的、还没经过团队确认的约定就静默地变成了主干规范。下一个读到的人以为这是评审过的正式规范照做了。好在后来发现的早否则就要带着错误的约定跑几个迭代。从那以后我把 CLAUDE.md 和.claude/目录的改动纳入和业务代码一样的评审流程。模板的变更和代码的变更是同等重要的变更不能因为只是个配置文件就放松。4.3 hooks 失败吞掉整个任务hooks 是所有功能里最需要谨慎的因为它在 Claude 的执行路径上插了一脚配置不当可能让整个任务卡死。我最惨的一次经历写了一个PostToolUsehook 跑 prettier结果 prettier 因为某个文件语法错误退出码非零Claude 误以为自己的操作失败了于是反复重试同一个编辑白白消耗了大量 token最后任务超时。那次之后我总结了 hooks 三原则脚本必须幂等重复执行结果一致失败必须静默除非是真正需要阻塞的错误优先用自动修复模式--fix而不是纯检查模式。这三个原则能避免大部分 hook 带来的意外中断。4.4 上下文窗口的隐性成本Claude Code 的上下文窗口不是无限的。CLAUDE.md 和子代理指令每次都会占用一定上下文模板越大留给实际代码分析的上下文就越少。我实测下来200 行的 CLAUDE.md 大约消耗几千 token这个量级通常可以接受。但如果你在模板里塞了大量示例代码块消耗会非常可观。有一版模板里我放了完整的一个组件示例光那一段就占了好几千 token。后来我把示例精简为核心模式的骨架信息密度高占用量小。建议定期检查模板里有没有冗余内容。模板是活文档每次迭代都要顺手清理让每一行都有存在价值。5. 模板库的进阶玩法5.1 按项目类型沉淀一套模板库当你积累了几个项目的模板之后会发现它们有很多共性。这时候可以把公共部分抽出来形成一套模板库。我现在维护的 claude-code-templates目录大概是这样的web-frontend/Next.js TS 项目的基础规范backend-service/Node.js 服务的规范python-tool/Python 工具类项目的规范docs-site/文档站点的规范common/跨项目公共的斜杠命令与 hooks新项目直接拷贝对应模板再根据项目特点微调。过去搭一个项目的 AI 协作规范需要半天现在十几分钟就能搞定而且质量有保障因为模板已经在真实项目中验证过。这就是 claude-code-templates 的核心价值——它不是某个项目的配置文件而是一套可以快速复制的工作流资产。每接一个新项目你继承的是自己过去所有项目的最佳实践。5.2 把模板接进 CI模板可以进一步与 CI 打通。我做了两件事第一在 CI 里加一个步骤验证 CLAUDE.md 里列出的命令是否都能正常运行。防止纸上谈兵的规范——比如模板里写了npm run test但如果测试跑不起来这个规范对 AI 就只是噪音。第二在 CI 中触发一次带模板的 AI review。当代码合入主干前CI 会调用 Claude Code 执行模板里的审查流程输出结构化报告。实测下来这确实能拦截一部分低级错误——比如异常被静默吞掉、类型断言使用不当。但它不是用来替代人工评审的而是把人工评审从找低级错误中解放出来让人专注于架构和业务逻辑。5.3 团队落地三步走一个人搭模板是效率工具一个团队都用模板就是工程规范。团队落地我建议分三步第一步技术负责人搭出第一版模板自己在一个项目里用两周。这两周里把任何它怎么又做错了的抱怨记下来这些就是模板需要改进的点。第二步选定一个试点项目全量推广。收集反馈时要注意大部分问题不是AI 不行而是模板没写清楚。每一条反馈都应该是模板迭代的线索而不是对工具的抱怨。第三步定期 review 模板本身像 review 代码一样。可以放在双周会的固定议程里十分钟快速过一遍有没有新的坑需要固化、有没有旧内容已经失效。5.4 模板是活文档持续迭代的机制最后说说我理解中最重要的原则模板的价值不在一次写得多完美而在于持续迭代。我的第一版 CLAUDE.md 可能只有二十行非常粗糙。到现在这个项目的模板已经迭代了几十次每一次的改动几乎都是同一个来源——Claude 在某个任务上犯了错而这个错误本来可以通过一条更明确的约束避免。所以我养成了一个习惯每次和 Claude 协作完如果过程中有任何不满意的地方立刻花两分钟判断这是不是模板缺失导致的问题。是就改模板不是一次性问题也值得记录。这个过程很像带新人——你永远写不出一份完美的说明书但你可以在一次次磨合中让协作越来越顺。这就是 claude-code-templates 真正想做的事情让 AI 协作的每一次摩擦都变成下一次更顺畅的台阶。