★ FEATURED ARTICLE 最近我一直在折腾一个挺有意思的开源项目claude-code-templates。说白了这个项目做的一件事是把 Claude Code 的提示词、CLAUDE.md 配置、自定义斜杠命令按场景打包成模板方便你开新项目时直接套用。Claude Code 本身就是个终端里的 AI 编程代理你用自然语言给它下指令它能帮你读代码、改代码、跑测试、查问题。但用久了你会发现如果不做约束和沉淀每次对话都得重新交代一堆背景回答质量全看临场发挥。模板这个东西就是把你反复要说的那些话固化成一套规则让 AI 每次都从一个更高的起点开始干活。这篇内容适合正在用或准备用 Claude Code 做日常开发的朋友也适合那些想把 AI 编程工具从“能用”推到“好用”的团队。我会从模板仓库的整体设计讲起逐个拆解 CLAUDE.md、自定义命令、子代理配置这些核心文件然后走一遍从零创建模板到实际调用的完整流程最后把我在真实项目里踩过的坑和排查经验一并整理出来。1. 模板项目到底在解决什么问题1.1 没有模板时Claude Code 用起来有多别扭先说一个很现实的场景。你打开终端敲claude进入交互模式然后告诉它“帮我看看这个模块的测试覆盖率为什么上不去”。它会开始读代码、分析问题给出建议。这事本身没问题但如果你换一个项目换一套技术栈换一批约定同样的问法得到的答案可能完全不一样。根源在于 Claude Code 对项目一无所知它只知道你当前说了什么以及它能从文件系统里看到什么。我最早用 Claude Code 的时候每个项目都要花大量时间在“喂背景”上。比如项目用的是 pnpm 还是 npm测试框架是 Vitest 还是 Jest代码风格有没有 eslint 规则提交信息要不要带 type 前缀构建产物放在哪个目录这些信息如果不提前说明AI 就会按它的默认习惯来猜。猜对了还好猜错了就得反复纠正一来二去效率反而比纯手写代码还低。这就是模板项目存在的核心价值把项目背景、团队约定、个人偏好从“每次对话临时说”变成“开机自动加载”。你在仓库里放一份结构化的模板文件Claude Code 启动时自动读进去之后每一次交互都带着这份上下文。省掉的不是几行字而是大量来回拉扯的沟通成本。1.2 一个模板仓库里通常装着什么以我实际维护的 claude-code-templates 项目为例它的目录结构大概长这样. ├── CLAUDE.md # 根级项目记忆自动加载 ├── .claude/ │ ├── commands/ # 自定义斜杠命令按场景分组 │ │ ├── review.md │ │ ├── commit.md │ │ ├── refactor.md │ │ ├── test.md │ │ └── agentic.md │ ├── agents/ # 子代理定义按角色分工 │ │ ├── backend-dev.md │ │ ├── frontend-dev.md │ │ └── debugger.md │ ├── hooks/ # 生命周期钩子 │ │ └── preCommand.sh │ └── settings.json # 编辑器与运行参数 └── templates/ # 按技术栈或项目类型拆分的子模板 ├── node-ts/ │ ├── CLAUDE.md │ └── commands/ ├── python/ └── go/这里我想解释一下为什么要分层。根目录的CLAUDE.md是全局记忆适合放所有项目通用的约定比如“代码里不要出现魔法数字”“修改前先画影响面分析”。templates/下的子模板则按技术栈拆分Node.js 项目有自己的测试命令Python 项目有自己的虚拟环境路径Go 项目有自己的格式化工具这些不适合混在一起。.claude/commands里放的是动作型指令类似快捷键一键触发某个工作流。四层各管各的互不干扰。这种结构化设计不是拍脑袋想出来的。Claude Code 的上下文窗口虽然大但塞满无关信息同样会稀释注意力。分层的好处是通用规则永远在场技术栈相关规则按需读取动作型指令只在主动调用时生效。上下文干净了回答质量自然稳定。2. 核心文件逐个拆解CLAUDE.md、命令、子代理2.1 CLAUDE.md项目记忆的载体CLAUDE.md是这个模板体系里最基础也最关键的文件。它的加载机制很简单Claude Code 启动时会自动读取当前目录以及上级目录里的CLAUDE.md把里面的内容作为初始上下文的一部分。你不需要输入任何指令它天然就在那儿。但很多人会把这份文件写成项目说明书“本项目基于 React 18 Vite TypeScript”两句话就完了。这其实浪费了它的能力。真正好用的CLAUDE.md应该包含四类内容项目结构速览、命令速查表、代码约定、常见陷阱。以我在一个 Node.js 全栈项目里用的模板为例# Node.js Fullstack Template ## 项目技术栈 - 前端React 18 Vite TypeScript - 后端Fastify Prisma - 测试Vitest Testing Library - 包管理pnpm ## 常用命令 - 启动开发服务: pnpm dev - 执行测试: pnpm test - 单测watch: pnpm test -- --watch - 类型检查: pnpm typecheck - 数据库迁移: pnpm prisma migrate dev ## 代码约定 - API 错误统一返回 { code, message, details } 结构 - 组件文件名使用 PascalCasehook 文件使用 camelCase 并以 use 开头 - 禁止在业务代码中使用 any如确有需要必须归档到 types/ 并写注释 - 新功能必须有对应的测试文件测试描述用中文 ## 常见陷阱 - 修改 schema.prisma 后必须执行 pnpm prisma generate否则类型不生效 - 不要在 useEffect 里直接使用 async 函数统一用自定义 hook 包裹 - 本地联调时后端默认跑在 8787 端口不要硬编码到前端代码里写这份文件时要注意密度。前四条技术栈信息是给 AI 定位用的让它知道当前世界的坐标系。命令速查表要让 AI 在跑脚本时不靠猜直接查表执行。代码约定是行为准则直接影响生成的代码风格。常见陷阱则是负向清单把容易犯的错提前标记出来。还有一个不太显眼但很实用的功能CLAUDE.md支持依赖引用。你可以在根目录的文件里写templates/node-ts/CLAUDE.md用这种语法把子模板的内容引入主文件。这样既避免了复制粘贴导致的信息不一致又能让通用模板和具体项目解耦。2.2 自定义斜杠命令把常用工作流固化成一条指令如果说CLAUDE.md解决的是“背景知识”问题那么.claude/commands/里的自定义命令解决的是“操作流程”问题。每个.md文件对应一个斜杠命令文件名就是命令名。比如你创建一个review.md就能在对话里输入/review直接触发生效。这里有个非常重要的机制斜杠命令文件里的$ARGUMENTS变量可以捕获用户输入。你可以在命令里写请对 $ARGUMENTS 指向的代码进行审查重点检查以下方面 1. 潜在的内存泄漏和资源未释放问题 2. 错误处理链路是否完整 3. 并发访问是否存在竞态条件 4. 是否符合项目 CLAUDE.md 中的代码约定这样用户输入/review src/utils/cache.ts时$ARGUMENTS就会被替换成src/utils/cache.ts直接对目标文件进行审查。这个设计把“模板的复用性”和“指令的灵活性”结合得很好。我的经验是按照任务的“重复频率”和“复杂度”来分类创建命令。高频且步骤固定的比如生成提交信息、跑全量测试、更新版本号做成短命令。低频但流程长的比如架构评审、数据库迁移检查、发布前安全排查做成带完整检查清单的长命令。以提交信息生成为例我常用的是这样一个命令请基于当前 git diffgit diff --staged生成提交信息要求 1. 信息格式遵循 Conventional Commits即 type(scope): description 2. type 选项feat / fix / refactor / chore / test / docs 3. 描述控制在 60 字以内使用中文 4. 如果改动涉及多个模块只提炼最重要的两条不要列流水账 5. 直接输出提交信息不要附带说明文字这个命令的妙处在于它把“信息格式”和“内容提炼”两个决策都交由 AI 完成而人只需要扫描一遍确认结果然后git commit -m $(claude -p ...)一条命令走完。整个流程从原来五分钟的纠结变成半分钟。2.3 子代理配置把不同角色拆开让每个任务更聚焦agents这个概念对于刚开始接触 Claude Code 的同学可能有点陌生。简单说子代理是带着特定角色设定的独立任务单元你可以把一个大任务交给多个子代理并行或分步处理而不是让一个 AI 从头干到尾。在.claude/agents/下创建backend-dev.md这样的文件里面就是纯 Markdown 的“角色说明书”。# backend-dev 你是一名资深后端开发工程师专注 Node.js 与 API 设计。 技能特点: - 熟悉 Fastify、Prisma、PostgreSQL - 擅长接口设计与数据库建模 - 注重错误处理、日志可观测性和测试覆盖 工作方式: - 先概括问题再拆解实现方案最后写代码 - 每个 API 变更必须同步考虑对现有调用方的影响 - 新增依赖前要确认理由并检查是否有更轻量的替代方案这个配置文件的意义在于当你需要深度开发某个模块时可以切到一个“专家模式”让 AI 站在专门角色上思考而不是什么都用默认的通用助手。在我的实际使用中这种角色限定对输出质量的提升非常明显尤其在代码细节和规范遵守层面。另外一个小技巧子代理之间可以互相交互。比如先让 backend-dev 设计 API再让前端开发子代理基于这个设计生成调用代码。你不需要一次性把所有细节都讲完只要让它们按顺序接力各自输出自己职责范围内的成果。3. 从零搭建一套可复用的模板3.1 安装与初始化把官方骨架拉到本地不论你是要使用 claude-code-templates 这个仓库本身还是要按它的思路创建自己的模板第一步都是把项目骨架初始化好。Claude Code 提供了官方初始化命令claude --init执行之后会在当前目录生成一份基础的CLAUDE.md里面通常包含几个空白的章节块比如项目概览、命令、代码风格。这个文件可以看作一个起点但你大概率需要在里面填上真实内容。如果你不想从零开始写也可以直接把 claude-code-templates 仓库克隆下来然后用自己的项目内容替换模板里的示例。我倾向于的动作是克隆仓库 → 删掉示例的 history → 逐个打开每个文件把技术栈、命令、约定改成当前项目实际情况。这样做的好处是不会漏掉目录结构里的任何重要文件。初始化之后建议立刻在终端里跑两条命令确认环境正常claude claude -p 请读取 CLAUDE.md并用三句话概括项目定位第一条验证交互模式能正常启动第二条用非交互模式测试文件加载。如果第二条返回的是“项目定位是……”说明CLAUDE.md已经生效。如果它说“我没有足够信息”说明文件路径写错了或者权限有问题。3.2 按实际需求编写模板内容以测试生成命令为例现在假设我们要给一个 TypeScript 项目写一个测试生成模板。这个场景很有代表性因为它既涉及命令设计又涉及项目约定的遵守。先建命令文件.claude/commands/add-test.md请为 $ARGUMENTS 中的文件或模块生成单元测试要求 1. 测试框架使用 Vitest断言风格使用 expect 2. 测试文件输出到同目录下的 __tests__/ 文件夹 3. 测试命名采用中文描述格式为 xxx 时应该 xxx 4. 优先覆盖核心业务逻辑不追求行覆盖率 5. 涉及异步请求时使用 mocked 数据禁止在单测中发起真实网络请求 6. 生成完成后运行 pnpm vitest run file --reporterverbose 自检并粘贴测试结果这个模板有几个细节值得注意。第 2 条解决了“测试文件放哪”的问题否则 AI 可能把测试放在根目录或 src 外面。第 3 条是团队风格约束中文命名对后续维护和 review 都友好。第 5 条是常见的网络请求污染问题提前声明能避免生成一批不可重复的脆弱测试。第 6 条是闭环操作让 AI 生成完代码后自己跑一遍验证而不是把“跑通”这件事留给用户。在实际调用时我会写/add-test src/services/order-service.tsAI 会读那个文件理解业务逻辑然后按模板生成配套测试并自动执行自检。整个流程完全可复现换一个人来操作得到的结果风格基本一致。3.3 让模板在项目里生效目录、命名与加载机制模板文件写好了如果不生效等于白写。这里把加载机制最关键的几条规则列出来。第一条CLAUDE.md的查找是自动的。Claude Code 会从当前目录向父级目录逐级查找找到就加载。所以你放在项目根目录的全局规则在任何子目录打开交互模式时都能生效。反之如果你在某子目录里单独放一个CLAUDE.md这条优先级会更高适合存放某模块特有的规则。第二条斜杠命令的命名要谨慎。文件名就是命令名所以review-code.md对应的命令是/review-code。要注意不要跟 Claude Code 内置命令冲突比如clear、help这类就别用了。我的习惯是所有自定义命令都带前缀或明确动词比如review、commit、add-test既好记又不容易冲突。第三条子代理的调用方式。创建完.claude/agents/backend-dev.md之后在交互模式里输入Agent: backend-dev就能切换到对应角色。如果想在一条指令里直接指定可以用claude -p Agent: backend-dev\n请实现 ...。还有一条容易被忽略的.claude/settings.json的配置。里面可以设置权限白名单比如允许哪些命令自动执行、禁止哪些目录被修改这对安全性和可控性很有价值。一个基础配置长这样{ permissions: { allow: [ pnpm test, pnpm lint, git diff, git status ], deny: [ rm -rf, git push --force ] } }有了权限白名单你就敢让 AI 在本地随意跑命令因为真正有破坏性的动作已经被拦截了。这套机制用熟之后模板系统才算是真正进入可生产状态。4. 避坑指南与常见问题排查4.1 模板不生效、命令报错、上下文混乱的典型原因先说最常碰到的问题模板文件明明写了但 AI 好像完全没在读。这个我排查过好几次绝大多数情况是CLAUDE.md文件命名大小写搞错了或者放在了被.gitignore忽略的目录里。还有一个隐蔽原因同时存在多个CLAUDE.md子目录的规则覆盖了根目录的预期。按我的经验先执行claude -p 你的项目定位是什么做快速验证如果答案不对就逐级检查文件名和目录结构。第二个常见问题是斜杠命令被报“未找到”。通常是因为文件没有放在.claude/commands/下而是放在commands/或者别的自定义目录里。Claude Code 对目录名有严格要求.claude必须带点前缀不能改名。如果确认目录没放错再看一眼文件后缀是不是.md有时在 Windows 下新建文件会自动加上隐藏扩展名导致匹配失败。第三个问题更隐蔽涉及上下文污染。当你把大量命令、代理定义、子模板一股脑写进CLAUDE.md之后AI 的上下文虽然能承载这些信息但权重分布会被稀释核心指令反而得不到足够关注。我的处理方法是区分“常驻记忆”和“按需加载”。真正关键的约束只保留在根级CLAUDE.md里而细分的操作手册、技术栈说明全部放进templates/子目录用时再通过引用。这样既保持加载轻量又不丢失细节。第四个典型坑是命令文件里的$ARGUMENTS传参异常。我在导入别人写的模板时遇到过这种写法请审查 $1 这个文件但在 Claude Code 的命令模板里$1并不是预期参数正确写法是$ARGUMENTS。这个变量会把用户输入的全部内容当作字符串替换进去。如果用户输入里带了引号或空格替换结果可能和预期不一致所以命令模板里最好预估参数格式必要时加一句“如果传入了多个文件路径请逐个处理”。第五个问题跟 hooks 有关。.claude/hooks/下的脚本可以在命令执行前或后触发但默认情况下脚本报错会静默失败导致你根本不知道 hook 有没有跑。排查方法是在脚本开头加一行输出到日志文件比如echo $(date) hook called /tmp/claude_hook.log。确认能触发之后再逐步增加逻辑。4.2 让模板真正好用的几条底层心得摸索了大半年我慢慢意识到模板项目的重点不在模板本身而在“维护节奏”。模板不是一次性写完就完事的它需要跟随项目演进持续更新。每次发现 AI 在某个问题上反复出错我就把这个错误记一条进CLAUDE.md的陷阱区。每次评审代码时发现风格不一致我就补一条约定。模板文件本质上是从错误中沉淀出来的知识库而不是开工前一次性写完的摆设。关于“什么时候该建新命令”我的判断标准很简单一件事如果我在一周内手把手教过 Claude 三次以上它就值得变成一个命令。反过来如果某个命令创建之后一次都没用过那就不惜删掉别让目录里堆满僵尸文件。命令越少越精调用的确定性就越高。我见过有人一口气建了四十多个命令结果自己都记不住哪些有哪些最终用的还是那三五个。还要提醒一点任何模板都只能约束输出的“形式”框不住真实工程里的所有边界。遇到极端场景时最好的做法不是继续堆规则而是直接在当前对话里补充一次性指令临时打通问题之后再把解决方案沉淀到模板里。这种闭环迭代的方式比我最初追求“一次性设计完美方案”要靠谱得多。最后分享一个让我受益最多的细节Claude Code 支持语法直接引用任意文件路径。在模板里写好引用路径后实际工作中遇到同类任务我可以直接输入/review src/service/user.ts src/service/order.ts让 AI 同时读取几个关键文件再执行审查。结合模板里预设的检查清单这个组合用顺手之后代码 review 和测试生成的效率提升不是一点半点我在几个中大型项目里都已经把这一套固化为日常流程了。
阅读完成 · 觉得有帮助？
