★ FEATURED ARTICLE 小半年时间里我用 Claude Code 反复建的项目加起来大概有二十多个。刚开始每开一个新项目都是从一个空白目录开始先手写一段大而全的系统提示把技术栈、编码习惯、禁止事项一股脑丢进去然后祈祷它在后面几周里不会跑偏。结果自然是时好时坏——同一个模型换一个项目、换一个会话发挥水平就像开盲盒。后来我专门花了一周时间整理 claude-code-templates 这套工作流模板把所有重复的配置、提示、命令和规则全部固化下来。效果立竿见影新项目从重新教育模型变成了直接应用已有规范团队同事接手时也不用再从零摸索。这篇文章会把整个整理过程、模板骨架、命令设计思路和踩过的坑都摊开讲希望能给你一个可以直接抄作业的起点。1. 先搞清楚模板到底在解决什么问题很多人第一次接触 Claude Code 模板会下意识认为它就是一堆提示词模板无非是把系统提示写得更长一点。这个理解差得很远。1.1 真正的问题是每次都重新解释我观察到的普遍现象是大多数人用 Claude Code 的前三天效率极高之后开始断崖式下降。原因不是模型变笨了而是上下文里那些约定俗成的信息在不断丢失。举个例子你做一个 TypeScript 项目定了三条规矩组件用函数式写法、测试文件必须放在__tests__目录下、错误处理统一用 Result 模式。第一天你花了几句话把这些写进对话模型执行得很好。第二天新开会话模型不记得这些了你又得重新说一遍。到了第三个项目你发现同样的话已经重复了十几遍每次还都说得不太一样。模板要解决的核心问题就是这件事把散落在对话里、脑子和 PR 评论中的隐性知识沉淀成项目目录里的一份显性文件。Claude Code 启动时会自动读取项目根目录下的CLAUDE.md把它当作默认的项目背景信息。这意味着只要模板到位新会话第一次开口就已经知道全部规矩不需要人类重新教一遍。1.2 模板经济的三个层次从价值角度我习惯把模板分成三个层次层次内容解决什么问题投入产出比第一层CLAUDE.md项目记忆文件代码规范、架构说明、常用命令中但要持续维护第二层.claude/目录工程化配置权限、命令、钩子、子代理最高一次配置长期受益第三层整仓模板骨架新项目初始化、团队标准化高适合多人协作只做第一层的人占大多数这也是为什么很多人觉得模板也就那样。真正让模板值钱的是第二层和第三层的工程化组合。后面几个章节我会把这几个层次逐一拆开。1.3 你该不该现在就做模板当然也不是所有人都需要建一套完整的模板体系。我的判断标准很简单如果你只是拿 Claude Code 做些一次性脚本、临时探索模板纯属过度设计手写几句提示就够了。如果你在一个代码库上长期迭代至少需要一份CLAUDE.md。如果你的团队有多个人用同一个代码库或者你会频繁开新项目那模板体系就值得认真搭。最难的不是搭模板而是持续维护。很多人的模板建完两周就过期了最后变成一坨没人愿意碰的死文件。这一点我在最后一节会展开讲。2. 模板的根基一张高质量的 CLAUDE.md无论模板体系做得多复杂根基永远是CLAUDE.md。它被 Claude Code 自动加载是你和模型之间最稳定的共同记忆。2.1 CLAUDE.md 在上下文里的位置先说清楚它的读取机制这决定了你该怎么写。Claude Code 加载记忆文件的顺序大致是系统内置提示 → 用户全局配置~/.claude/CLAUDE.md→ 项目根目录CLAUDE.md→ 子目录里的CLAUDE.md。加载顺序意味着越靠后的文件在具体场景下优先级越高但同时也离用户明确指示越远。这意味着两件事第一全局配置只写所有项目通用的偏好比如回答用中文、每次改动前先列执行计划这类个人习惯千万别写某个项目的专属内容。第二项目级CLAUDE.md是每个项目的主战场要覆盖的是这个仓库特有的信息。2.2 一份结构合理的 CLAUDE.md 骨架我花了很多版本迭代最后收敛成下面这个结构。你可以直接拿来当模板# 项目概述 - 项目定位一句话说清楚这是什么给谁用 - 技术栈清单语言、框架、关键库及版本 - 目录结构速览src、tests、scripts それぞれ干什么 # 常用命令 - 启动开发环境npm run dev - 运行测试npm test - 代码检查npm run lint - 构建产物npm run build - 注意命令必须从项目根目录执行遇到子目录请先 cd 回根目录 # 代码规范 - 语言/框架约定TypeScript 严格模式、函数式组件、命名规则 - 目录约定组件放 src/components页面放 src/pages - 错误处理统一使用 Result 模式禁止直接 throw 裸对象 - 样式方案Tailwind CSS Modules 分层使用 # 架构注意事项 - 数据流向展示层 → 业务层 → 基础设施层禁止反向依赖 - 状态管理全局状态只放跨页面共享数据局部状态用组件内 state - 接口规范所有后端调用统一走 api/ 目录下的封装 # 工作流规则 - 修改文件前先说明改动的文件和原因 - 涉及数据库结构变更时先询问再动手 - 提交代码前必须跑一遍 lint 和对应模块的测试 - 不确定的需求点直接提问不要自行假设 # 禁止事项 - 不要修改 auto-generated 目录下的文件 - 不要使用 console.log 做调试输出统一用 logger - 不要在业务代码里写死环境相关的配置这个结构的关键在于只写模型不知道的事。技术栈是 React 这种常识可以不写但这个项目的目录约定、数据流的强制方向、提交前必须跑哪些命令这类只有在这个仓库里才成立的信息一定要写清楚。2.3 别把 CLAUDE.md 写成百科全书我见过最离谱的项目CLAUDE.md有九百多行事无巨细连缩进用几个空格都写了。模型不是每句话都会百分百执行文件太长时注意力会被稀释反而最关键的规则被忽略了。经验准则是一个文件重点规则控制在二十条以内只保留违反就会出大问题的内容。次要内容拆到.claude/commands里的命令模板或者子代理的系统提示里需要时再调出来而不是一股脑塞进主记忆文件。另外CLAUDE.md写多了之后一定要自己通读一遍很多看似明确的规则站在模型的角度其实是自相矛盾的。3. 比 CLAUDE.md 更值钱的.claude 目录里的工程化配置CLAUDE.md只是解决了模型知道规矩的问题而.claude/目录解决的是模型能按规矩行动的问题。这才是模板体系里最容易被低估的部分。3.1 settings.json把权限与行为固化下来项目级配置文件是.claude/settings.json它控制 Claude Code 在这个项目里的权限范围和自动化行为。一个典型的配置是这样{ permissions: { allow: [ Bash(npm test), Bash(npm run lint), Bash(npm run build), Read(**) ], deny: [ Bash(git push --force), Bash(rm -rf *) ] }, hooks: { PostToolUse: [ { matcher: Edit, hooks: [ { type: command, command: npx prettier --check CHANGED_FILES } ] } ] }, model: 按团队统一选用的模型版本填写 }权限配置的意义是双向的。对模型来说明确的 allow 列表意味着它可以放手执行测试、构建这些高频操作不需要每次弹窗向你确认对团队来说deny 列表是底线防止模型顺手执行危险命令。3.2 hooks让模型的行为可校验hooks 是模板里自动化程度最高的部分。Claude Code 会在特定事件触发时执行你配置的命令让每次改动都被校验。最实用的两个场景PostToolUse配合Edit匹配器模型每改完一个文件自动跑一遍代码格式化检查或 lint把问题当场暴露。PreToolUse配合Bash匹配器在模型准备执行敏感命令前做一次拦截。写 hooks 时有个关键点容易被忽略hook 脚本本身要稳、要快。如果你的格式化工具需要两三秒才能跑完模型每改一个文件都要等这么久整体效率会非常糟糕。所以我会把耗时长的检查放在Stop事件里做汇总报告而不是放在每个Edit之后。3.3 settings 的作用域划分Claude Code 的配置有多个层级我强烈建议按这套规则来划分~/.claude/settings.json个人全局偏好比如通用权限、个人风格的输出格式。.claude/settings.json项目级配置提交到仓库团队共享。.claude/settings.local.json个人针对本项目覆盖的配置不提交仓库比如你本地测试用的特殊环境变量。把这三者分开是模板可以跨人复用的前提。很多团队模板推不下去就是因为在项目级配置里混入了某个人的个人习惯其他人一上来全是弹窗和冲突。4. 把高频动作固化成命令模板如果说CLAUDE.md是知识commands 就是动作的快捷键。这一步做完模板的使用体验会有质的飞跃。4.1 什么是命令模板在.claude/commands/目录下每个 Markdown 文件对应一个斜杠命令。比如.claude/commands/review.md对应/review。一个命令模板包含两部分文件开头的 YAML 元信息和正文的指令--- description: 对当前改动做一次结构化 Code Review argument-hint: [可选] 指定文件或模块 allowed-tools: Read, Grep, Glob model: 与项目主模型一致或使用更强推理模型 --- 你是一位严格的资深代码评审者。请对本次改动的代码进行结构化审查重点检查 1. 逻辑正确性是否存在边界条件遗漏、并发问题或明显的逻辑错误 2. 安全性是否引入了注入、越权、敏感信息泄露等风险 3. 可维护性命名、函数长度、模块职责是否合理 4. 与项目规范的符合度对照 CLAUDE.md 里的代码规范逐条核对 输出格式 - 问题列表按严重程度排序标注所在文件和行号 - 每个问题给出修复建议并注明是否必须修改 - 最后给一个总体结论通过 / 有条件通过 / 不通过元信息里的description是给模型理解命令用途的allowed-tools限定了这条命令能调用哪些工具argument-hint提示用户跟在该命令后面的是什么参数。4.2 我沉淀下来的一套高频命令集用几个月下来我的模板仓库里常驻这几条命令几乎适配所有项目命令触发场景解决的核心痛点/review提 PR 前或改动完成后让模型以评审者身份重新审视代码而不是顺着写作思路自夸/fix-lint收到 lint 错误时统一修复格式问题不改变业务逻辑/test-case加新功能时根据函数签名自动补测试用例覆盖边界条件/commit准备提交代码时生成规范且符合团队 Commit Message 格式的提交信息/explain接手不熟悉的模块按调用链由外向内拆解模块职责输出架构笔记这里特别说一下/review的设计思路。很多人让模型做代码审查结果是模型把自己的思路又夸了一遍。原因很简单写代码和审代码是同一个会话模型天然倾向于维护自己之前的产出。把审查单独做成一条命令等于明确切断了作者视角让模型切换成独立的评审者角色效果完全两样。4.3 命令模板与 CLAUDE.md 的分工命令模板和CLAUDE.md的边界在哪里我一开始也处理得很乱。后来总结出一句话CLAUDE.md写被动规则commands 写主动任务。CLAUDE.md里的规则是每时每刻都生效的约束比如不要改自动生成的文件而命令模板是用户主动发起的工作流比如帮我审查这次改动。如果一条复杂的流程被写进CLAUDE.md模型反而因为指令太长而失去重点把流程放在命令里只有你主动召唤时它才需要理解和执行。5. 搭一个能沉淀、能传给团队的模板仓库当你把单项目的模板玩顺之后下一步的自然需求是能不能把它抽成一套可复用、可分发的东西我的做法是维护一个独立的模板仓库所有公共资产都放在里面。5.1 仓库结构与设计原则我的claude-code-templates仓库结构大致是claude-code-templates/ ├── README.md ├── templates/ │ ├── nextjs-ts/ │ │ ├── CLAUDE.md │ │ ├── .claude/ │ │ │ ├── settings.json │ │ │ ├── commands/ │ │ │ │ ├── review.md │ │ │ │ ├── commit.md │ │ │ │ └── test-case.md │ │ │ └── agents/ │ │ └── .gitignore │ ├── python-api/ │ └── go-service/ ├── scripts/ │ ├── apply.sh │ └── init.py └── CHANGELOG.md设计上我坚持三条原则。第一条按技术栈分模板而不是按项目分模板。同一个技术栈的项目约定往往高度相似合并维护成本最低每个具体项目的业务差异通过项目里的CLAUDE.md补充。第二条每个模板目录自包含。一份CLAUDE.md、一套.claude配置配套齐全可以直接复制到任何空目录里用。不要让使用者在多个目录之间手动拼装拼装过程一定会出错。第三条模板仓库必须有一个 CHANGELOG。模板和普通代码一样会演化改了哪个通用规则、为什么改都要留痕。否则三个月后没人知道之前为什么那样定也不敢动它。5.2 落地到新项目的两种方式把模板应用到新项目两种方式我都用过。第一种是最朴素的复制粘贴手动把模板目录里的文件拷过去。优点是零依赖缺点是容易漏文件。第二种是写一个初始化脚本。比如scripts/apply.sh接收一个模板名和目标目录参数自动把对应目录下的文件复制过去并替换模板里的占位符例如项目名、模块名。GitHub 上的模板仓库大多用这种方式。我用 Python 写了个init.py还加了一个交互式问答问用户项目名、包管理器偏好、是否需要 ESLint 严格模式等然后把回答写进生成的CLAUDE.md。脚本化的价值不只是方便更重要的是它强制模板在可用状态下被维护。复制粘贴时你可能会容忍某些过期的片段但脚本一旦跑不通你当天就得修。5.3 团队推广中最容易忽略的一件事模板推给团队技术难度从来不是瓶颈瓶颈在于每个人的使用习惯不同。有人喜欢让模型多问问题有人喜欢它闷头干活有人用 default 模型有人切了更强的推理模型。所以我的建议是模板仓库里只放团队共识部分个人偏好部分一律用settings.local.json覆盖。同时在 README 里明确写清楚哪些文件必须用模板的、哪些可以本地覆盖把改模板的流程变成一次正式的 code review 而不是谁想改就改。6. 折腾大半年后踩过的坑和想明白的事最后这部分写我最想分享的几段真实教训。模板这件事光看理论永远觉得简单踩过坑才知道边界在哪里。6.1 CLAUDE.md 越长模型越记不住这是我最开始犯的错。总担心模型不了解项目背景于是什么细节都往CLAUDE.md里塞最长的一个版本写了三百多行。结果实测发现模型在执行到一半时经常把早期写在CLAUDE.md里的规则忘掉我不得不反复提醒。后来我把文件压到一百行以内并用负面清单的方式写规则——不写应该怎么做只写禁止怎么做。实测效果反而好很多模型对否定式约束的遵守率明显更高。6.2 hook 脚本失败不等于流程失败我踩过最隐蔽的坑是 hooks 的静默失败。有一版模板里我在PostToolUse中挂了一个 ESLint 检查脚本但脚本依赖的 Node 版本在某个同事机器上不对hook 抛错了。诡异的是Claude Code 并不会因此中断整个流程错误只在日志里出现一行不主动看根本发现不了。从那之后我给自己立了一条规矩hook 脚本必须内部兜底命令本身要写|| true之类的容错同时把失败信息输出到固定的日志文件。脚本的正确性要单独测试不能依赖模型每次帮你发现问题。6.3 模型知道但不遵守≠模板写得不对还有一种经常让人沮丧的情况CLAUDE.md里明明写了提交前必须跑测试模型还是偶尔跳过。我一度以为是模板不行反复调整措辞。后来才想明白模板负责的是把信息传达给模型但模型的实时决策还会被上下文中的其他因素影响比如用户当前的指令语气和正在进行的操作流。换句话说模板不是代码没有一个确定的执行路径。它更像一份入职培训手册能显著提升表现的下限但不能保证每一次行为都严格一致。所以对于真正零容忍的规则不要只依赖提示要用 hooks 和权限控制从机制上拦截。6.4 定期体检比一次性建设重要得多模板维护有个残酷的现实它和代码一样会腐化。技术栈升级、团队规范调整、新踩的坑要补充任何一个环节没跟上模板就会逐渐变成误导人的历史文档。我现在每两个礼拜做一次模板体检拿当前模板初始化一个临时项目跑几个标准场景看看模型是否能按预期工作。整个过程二十分钟能提前发现很多问题。6.5 几个我反复验证过的实操心得最后分享几个零散但实用的经验全局 CLAUDE.md 只写稳定偏好。比如默认用中文回答复杂操作前先说计划。凡是可能为某个项目定制的条目一律下沉到项目级文件。命令模板里加参数示例。argument-hint里写清楚例如/review src/utils实际使用率和正确率会明显提高团队里的新手拿到就知道怎么用。把模板当作代码来 review。每次改通用模板走正常的变更流程、更新 CHANGELOG、同步给团队。一旦走了非正式流程模板改起来没有记录过两个月就没人知道它怎么变成现在这样了。我对claude-code-templates这套工作流的最终体会是它的核心不是把规则写得多完美而是建立一条从经验到资产的管道。单个项目里偶然发现的好规则是经验沉淀进模板后它就是资产能跨项目、跨人地复用。只要你不把模板当成一次性产出而是当成一个需要持续维护的项目它带来的回报会远远超出搭建时那点成本。
阅读完成 · 觉得有帮助？
