如果你跟我一样整天跟 Claude Code 在终端里打交道大概率早就发现一个现象同一个工具放在不同人手里完全是两种生产力。有人能用它十几分钟完成一次跨模块的代码梳理有人聊到第五轮就开始跑偏、改错文件、反复返工。差距往往不在模型而在模板。“Claude Code 模板”听起来不像什么炫技概念但它才是决定工具上限的隐形杠杆。说白了模板就是一套预先写好的规则、上下文和流程让 Claude Code 在动手之前就知道“你是谁、要做什么、按什么标准做、哪些事千万别碰”。没有这套东西它就像刚入职三天的新同事聪明但缺乏方向有了它你相当于给这个新同事发了一本工作手册、一堆审批表单和一条自动质检流水线。这篇文章就来把模板这件事掰开揉碎讲清楚底层有哪些模板块、怎么写才能不踩坑、如何从零到一搭一套能直接复用的模板包以及我实战中踩过的几个典型问题。适合刚接触 Claude Code 的初学者也适合已经用了很久但总觉得“不够聪明”的老用户。1. 模板体系从“一次性提示”到“团队资产”1.1 拆开看Claude Code 里的模板到底指什么很多人以为模板就是“把一段提示词存成文件”这只是其中一层。Claude Code 的模板体系至少包含四类东西对应四种不同的用途。第一类是项目记忆文件 CLAUDE.md。它相当于项目级的工作手册放在仓库根目录Claude Code 启动时会自动读取。内容是项目的目标、架构、技术栈、编码约定、常用命令、容易犯的错误。它解决的核心问题是“让 AI 在动手前了解全局”。没有 CLAUDE.md 的情况下Claude Code 只能靠在对话里临时问东问西或者凭通用知识猜你的项目结构自然容易跑偏。第二类是自定义斜杠命令。默认的/clear、/init之外Claude Code 允许你把常用操作固化成自己的斜杠命令比如/review做代码审查、/test生成测试、/fix处理特定类型的报错。斜杠命令本质上是精心设计的提示模板加上参数入口和工具权限控制。比起每次手动输一大段要求命令能保证每次执行的提示质量稳定。第三类是 Hooks 自动化钩子。你可以配置一个钩子让某些动作自动触发比如每次 Claude Code 写完文件后自动跑一次格式化或 lint每次调用某些危险工具前先自动拦截检查。这属于流程模板把“人工提醒”变成“自动化规则”。第四类是 Agent 子代理定义模板。Claude Code 支持创建具备不同职责的子代理比如“前端专家”“测试工程师”“安全审查员”每个子代理由一份单独的 Markdown 文件定义内含角色定位、能力边界、可使用的工具列表和输出要求。这就像给 AI 团队里每个岗位都写好了岗位说明书。1.2 为什么模板能带来质的改变我一直觉得模板最大的价值不是“省几个字”而是把隐性经验固化下来。你用了半年 Claude Code一定积累了不少技巧哪些要素它容易漏哪种描述方式它最容易理解哪些命令它经常在错误的目录下执行。这些经验如果没有写进模板就是一次性的写进去之后每次会话都会继承。更关键的是稳定性。我观察过不少团队的使用情况同一个仓库上午让 Claude Code 重构一个小模块效果很好下午换个同事继续聊效果突然变差。原因很可能是上午的会话里积累了详细上下文下午新会话从零开始。项目模板就是把“上午的有效上下文”沉淀下来让每个新会话都站在同一个起点。还有一点容易被忽略模板是团队协作的接口。多人用 Claude Code 时如果每个人都有自己的一套描述习惯AI 的行为会非常分裂。有了统一模板大家默认遵循同一套规则AI 产出的风格、格式、质量标准也会收敛代码评审时就少了很多“这到底按谁的标准写的”的争议。2. CLAUDE.md 项目记忆模板给 Claude Code 一本员工手册2.1 骨架怎么搭最合理CLAUDE.md 不是写得越多越好。它像新员工入职手册要让对方快速理解核心信息而不是把公司制度全文背下来。我个人推荐的骨架是七块项目一句话定位、技术栈清单、常用命令、项目目录导航、核心架构说明、编码约定、禁忌清单。项目定位最好用一句话讲清楚“这个系统是干什么的、给谁用”。别小看这句话它决定了 Claude Code 后续判断优先级的方向。一个给内部运营人员用的后台管理系统和一个给外部用户用的高并发 API 服务同样是“改一个接口”取舍逻辑完全不同。技术栈清单要具体到版本和关键框架。不是简单写“Python Django”而是写清楚 Python 版本、ORM 用什么、数据库连接走哪个库、有没有使用消息队列。这样 AI 在生成代码时才不会“自以为是”地引入你根本没安装的依赖。目录导航部分很多人会漏掉。Claude Code 虽然能自己搜索文件但你直接告诉它核心代码在哪几个目录、测试在哪、静态资源在哪、部署脚本在哪能省掉大量无效搜索。尤其对大型仓库这一步收益极高。架构说明要写清模块之间的依赖方向和关键数据流。别写太细重点是让 AI 知道“改 A 模块时可能连带影响 B 模块”避免改了一个函数就以为万事大吉。编码约定是模板里最有“钱”的部分。把你团队真正在乎的规则列出来命名风格、错误处理方式、日志格式、数据库迁移规范、接口返回结构。这里尽量避免罗列网上能找到的通用规范而是要写“咱们项目里特有”的约定。比如你们约定所有日期字段统一存时间戳还是字符串错误码前两位表示模块禁止在业务层直接拼 SQL这些信息通用文档里根本没有才是模板的含金量所在。最后是禁忌清单。每个项目都有自己的雷区某个生产环境配置绝对不能改、某个老模块欠了大量技术债不能顺手重构、某些测试稳定但很慢不能乱删。把这些明确写进 CLAUDE.md能避免 AI 在一通正常操作里突然踩爆一个隐形地雷。2.2 一个可以直接用的 CLAUDE.md 模板示例下面这个例子是我在某中等规模 Web 项目里实际使用过的结构你可以按自己的项目改。# 项目指南 ## 项目定位 本项目是订单履约系统中的发货模块负责将订单推送到仓配系统并回传物流轨迹。 面向内部运营和仓配同事使用日均处理订单量约为 20 万。 ## 技术栈 - Node.js 18 TypeScript 5.x - 框架NestJS 10 - 数据库PostgreSQL 15通过 Prisma ORM 访问 - 缓存Redis 7使用 ioredis 客户端 - 消息队列RabbitMQ使用 amqplib ## 常用命令 - 安装依赖npm install - 本地启动npm run start:dev - 运行测试npm test - 数据库迁移npx prisma migrate dev - 代码检查npm run lint ## 目录导航 - src/modules/shipping发货核心业务 - src/modules/oms订单管理相关适配 - src/common公共类型与工具函数 - test集成测试用例 - infra部署与容器配置 ## 核心架构 发货模块通过 RabbitMQ 消费订单消息组装发货请求后调用仓配系统 HTTP 接口。 回调接口负责接收物流轨迹写入本地数据库后通过 WebSocket 推送给前端。 依赖方向shipping - oms/common禁止反向引用。 ## 编码约定 - 所有接口入参必须通过 DTO 校验禁止直接用 any - 返回结构统一为 { code, data, message }code0 表示成功 - 错误码前两位表示模块shipping 模块使用 14 开头 - 日期字段统一存 ISO 字符串禁止存本地时间戳 - 异步任务必须走 RabbitMQ不要直接使用 setTimeout ## 禁忌 - 不要修改 infra/ 下的生产部署配置 - 不要重构 src/modules/oms/legacy 目录该目录为老系统临时适配 - 不要删除 test/integration 中带 SLOW 标记的用例看到没这份 CLAUDE.md 里的内容九成是通用 AI 知识库里查不到的只有在这个仓库里干过活的人才知道。写清楚后Claude Code 再处理发货模块的改动时会天然按照这套规则来生成的代码风格一下子就“像自己人写的了”。2.3 内容取舍与三个反模式CLAUDE.md 最常见的反模式是“写成文档库”。有人把整个项目的设计文档、接口文档全塞进去结果 Claude Code 的上下文窗口被大量低频信息挤占反而降低了核心指令的注意力。记住CLAUDE.md 是工作手册不是文档中心。那些偶尔才需要的信息应该放到仓库里让模型按需搜索而不是一股脑嵌入上下文。第二个反模式是“用不痛不痒的套话凑数”。像“请写出高质量代码”这种话看起来没问题实际毫无信息量因为它没有给出可执行的判断标准。宁可写“函数行数不要超过 80 行”“所有外部接口调用必须做超时处理”也不要写虚的。第三个反模式是“只写规则不给原因”。模型不是人它记不住没有逻辑关联的规则。比如你写“不要使用 lodash”它下次很可能还是会用因为它不理解为什么。但如果你写“不要使用 lodash本项目运行在边缘环境包体积每增加 1KB 都会影响冷启动速度”模型就会意识到这是硬约束。给规则附上理由遵从率会显著提高。3. 自定义斜杠命令把常用操作做成“一键脚本”3.1 命令模板的结构自定义斜杠命令存放在两个位置的其中之一项目级.claude/commands/目录或者用户级~/.claude/commands/目录。项目级的命令只对当前仓库生效适合沉淀业务相关的操作用户级命令对所有项目生效适合放通用的审查、重构动作。每个命令是一个 Markdown 文件文件名就是斜杠命令名例如review.md对应/review。文件最顶部用 YAML 写元信息下面写真正的提示内容。--- description: 执行一次完整的代码审查 argument-hint: [可选的审查范围如 src/modules/shipping] allowed-tools: Read, Grep, Glob, Bash ---元信息里最重要的是 description它会在斜杠命令列表里展示给用户。argument-hint 是给用户看的参数提示比如告诉它可以传一个文件路径或目录范围。allowed-tools 限制该命令执行时可调用的工具这非常关键它防止某些高风险操作被命令触发。正文部分就是你写给 Claude Code 的提示词里面可以引用用户输入的参数。当用户输入/review src/modules/shipping时src/modules/shipping就会被注入到命令模板中实现带参数的命令。3.2 三个可以直接抄的命令模板我先分享一个代码审查命令这也是我日常使用频率最高的。它解决了“让 AI 主动去找问题”的核心需求而不是简单问一句“代码有什么问题”。--- description: 执行一次完整代码审查按模块输出问题清单 argument-hint: [目标路径] allowed-tools: Read, Grep, Glob, Bash --- 对目标范围执行一次严格代码审查重点检查以下维度 1. 正确性是否存在逻辑漏洞、边界条件遗漏、并发问题 2. 可维护性是否违反项目 CLAUDE.md 中的编码约定 3. 性能是否有明显的性能隐患N1 查询、循环内部 I/O 等 4. 安全隐患是否有注入口、敏感信息泄露、越权访问 目标范围{{$ARGUMENTS:全部代码}} 输出格式要求 - 按严重程度分组分组为致命 / 需修复 / 建议优化 - 每个问题给出文件路径、行号、问题描述、修复建议 - 如未发现问题明确输出“本次审查未发现问题” 注意审查逻辑类问题时要查看相关测试用例不要只读实现代码。再看一个测试生成命令。直接让 AI “写测试”很容易产出只覆盖正常路径的无效用例所以模板里必须强制它先分析代码路径再设计用例。--- description: 根据目标函数或模块生成单元测试 argument-hint: [目标文件或函数名] allowed-tools: Read, Grep, Glob, Bash, Write --- 为目标代码生成单元测试流程如下 1. 先阅读源代码梳理所有出口路径、异常分支、边界条件 2. 检查现有测试避免重复覆盖 3. 设计用例时遵循“正常路径 边界条件 异常输入”三组结构 4. 使用项目现有的测试框架和断言风格不要引入新依赖 目标{{$ARGUMENTS}} 额外要求 - mock 外部依赖禁止真实网络请求 - 每个测试必须带明确的中文用例名说明验证的行为 - 测试数据用工厂函数生成不要硬编码一堆魔法数字最后一个是我处理遗留项目的利器——清理命令。老代码库里经常有“看着没用但不敢删”的代码用这个命令可以低风险地做一次存活度体检。--- description: 检查代码的引用情况输出可安全删除的疑似死代码清单 argument-hint: [目录或文件] allowed-tools: Read, Grep, Glob, Bash --- 对目标范围检查疑似死代码规则如下 1. 搜索所有符号的引用点区分直接引用、字符串引用、动态引用 2. 动态引用或反射场景下就算没有静态引用也要标记为“需人工确认” 3. 公共 API 定义即使无内部引用也要标记为“对外不可删” 4. 输出表格文件名、符号名、引用数量、删除建议可安全删除/需人工确认 目标范围{{$ARGUMENTS}}写好这些命令文件后在 Claude Code 会话里输入/就能看到命令列表输入/review src/modules/shipping就能直接触发。整个过程从“告诉 AI 一堆细节”简化为“敲一条命令”这就是模板落地后最直观的体验提升。4. Hooks 自动化模板让流程自己跑起来4.1 Hooks 能解决什么问题Hooks 是 Claude Code 里的自动化触发机制它在特定事件发生时自动执行一段命令或脚本。我只提三个最常用的场景写完代码后自动格式化、危险操作前自动拦截、每次会话结束前自动输出变更摘要。写完代码后自动格式化这个场景很实际。Claude Code 生成的代码风格再接近团队规范也会有缩进、引号、分号这类细节问题。与其每次都花额外轮次让它改格式不如配置一个 PostToolUse Hook只要模型执行了 Write 或 Edit 工具就自动对相关文件跑一次 Prettier。危险操作拦截属于 PreToolUse Hook 的典型用法。比如你规定“禁止使用 Bash 工具执行DROP TABLE”就可以在工具调用前设置一个检查脚本发现危险命令时直接拦截并提醒。这相当于给 AI 的越权操作加了一道门禁。会话摘要输出则适合多人协作用的场景。每次会话结束前让 Claude Code 自动总结这次改了哪些文件、新增了什么命令、是否留下了待办事项写入一个变更日志文件。这样后续接手的人不用猜上次讨论了什么。4.2 配置模板与避坑提示Hooks 的配置写在.claude/settings.json里。我直接给一个可用的示例。{ hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: npx prettier --write \$CLAUDE_FILE_PATHS\ } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: bash .claude/hooks/check-dangerous-command.sh \$CLAUDE_TOOL_INPUT\ } ] } ] } }matcher 字段用来匹配工具名Write|Edit 表示在模型执行这两个工具后触发。钩子脚本里可以通过$CLAUDE_FILE_PATHS这类内置变量拿到当前操作的文件列表。上面对应的拦截脚本可以写成这样#!/usr/bin/env bash input$1 if echo $input | grep -qE DROP TABLE|rm -rf /|git push --force; then echo 拦截检测到危险命令已阻止执行 exit 2 fi exit 0这个脚本的逻辑很简单检查输入是否有高危命令发现就直接返回非零退出码让 Claude Code 停止当前操作。用 Hooks 最容易踩的坑有两个。一是钩子脚本本身报错会导致流程中断所以脚本里所有命令都要考虑“没有输出”和“执行失败”的情况。二是 PostToolUse 里如果再触发文件修改有可能引发新的 Hook 事件形成连锁循环。我建议给所有 Hook 脚本加上“自身只跑一次”的标记比如判断环境变量或入口参数避免无限套娃。5. Agent 工作流模板从单兵作战到小团队协作5.1 子代理定义文件怎么写Claude Code 的 Agent 功能允许你定义多个有独立职责的子代理每个子代理有自己的一套提示、工具列表和行为边界。它在复杂任务中特别好用把一个大任务拆给不同角色的子代理避免单个对话里职责混乱。子代理定义放在.claude/agents/目录下每个文件同样以 YAML 元信息开头。我以一个“测试工程师”子代理为例。--- name: tester description: 负责编写单元测试与集成测试运行测试套件并分析失败原因 tools: Read, Grep, Glob, Bash, Write --- 你是一名资深测试工程师专职负责自动化测试。 工作原则 1. 开始写测试前必须先阅读目标代码列举所有需要覆盖的分支 2. 遵循项目中已有的测试风格优先复用现有工具函数 3. 运行测试时如果出现失败先分析失败原因再修改代码禁止盲目重试 4. 测试用例命名必须说清楚验证场景例如“订单金额为负数时应拒绝创建” 质量标准 - 分支覆盖率不低于 85%关键异常路径必须有用例 - mock 必须最小化只 mock 真正的外部依赖 - 测试运行时间超过 5 秒的在用例名前加 SLOW 标记 注意事项 - 不要为了覆盖率而生成无意义的断言 - 不要修改测试目标代码的逻辑只允许修复测试本身的问题description 是子代理最关键的字段它决定了主代理在什么情况下会选择这个子代理。因此 description 里要写清楚职责边界和适用场景不要写成笼统的“负责测试相关事务”而要写成“负责编写单元测试与集成测试运行测试套件并分析失败原因”。tools 列表控制子代理能使用的工具这是权限隔离的核心。子代理能用的工具越少越不容易造成失控操作。子代理目录在生产环境部署时建议只给 Write 和 Read 类工具禁止直接执行会影响生产环境的命令。5.2 主代理与子代理的编排模板定义好子代理后还需要一个编排提示模板告诉主代理什么时候该把任务拆给谁、怎么整合结果。这个模板我习惯放在 CLAUDE.md 里或者单独做成一个命令。## Agent 编排规则 - 当任务涉及大规模测试补全或测试排障时优先委托给 tester 子代理 - 当任务涉及前端组件实现或样式修复时优先委托给 frontend 子代理 - 每个子代理返回结果后主代理必须复核关键代码与测试结果不能直接照搬 - 子代理之间的任务必须通过上下文传递文件路径不要传递大段代码块这条编排规则本身也是模板的一部分它解决的是“Leader 如何调度专家”的问题。没有编排规则时主代理偶尔会用子代理、偶尔自己硬扛行为不可预测。有了规则复杂任务会被稳定地拆解流转协作质量会明显更稳定。一个常见的错误是把所有任务都甩给子代理导致上下文切割过度。子代理之间共享的信息有限如果任务强依赖全局上下文强行拆给多个子代理反而会降低效果。我的经验是强耦合、需要全局视野的任务主代理自己做弱耦合、可独立完成的任务才拆给子代理。6. 从 0 到 1一套最小可用模板包的完整落地6.1 最小模板包包含哪些文件如果你是第一次搭模板不用一上来就搞 Agent、Hook 全家桶。我建议按下面这个最小组合起步总共四个文件覆盖八成收益。项目根目录/ ├── CLAUDE.md └── .claude/ ├── settings.json ├── commands/ │ ├── review.md │ └── test.md └── agents/ └── tester.md第一份 CLAUDE.md 是必选项用来固化项目背景和规则。没有它后面所有模板的效果都会打折扣。第二份 settings.json 可以先只配置一个 PostToolUse 格式化钩子解决代码风格问题。第三份 review.md 命令把代码审查工作标准化。第四份 tester.md 子代理把测试类任务隔离到一个角色里。这套组合覆盖了“了解项目、规范操作、审查结果、质量保障”四个环节对一个中等复杂度的仓库来说已经能明显感受到差异。6.2 我自己的演进记录从 v1 到 v3第一次搭模板时我犯过的最大错误就是贪多。那时候我在 CLAUDE.md 里写了整整八十行编码规则几乎把团队规范文档全文搬运进去了。结果 Claude Code 确实记住了一部分但上下文占用暴增基础指令的响应质量反而下降。这是模板 v1 的典型问题把上下文当仓库用。v2 我做了减法。只保留三块项目定位、关键路径、禁忌清单。作息一下清晰了很多。但后来又发现少了点什么——AI 经常在细节决策上不一致这里的“不一致”指的是同一天前后几次修改看待同一问题的角度明显漂移。于是在 v2.5 我加入了“决策偏好”一节写明“面对不确定需求时优先选择兼容性更好的方案不要追求过度设计”。这类原则性信息信息密度高且不占太多空间效果很立竿见影。v3 开始模块化。我把 CLAUDE.md 压到最精简把大量可选的详细规范挪到.claude/commands和agents里。这样核心上下文负担小详细规则又能在特定任务场景被精准加载。这个结构一直用到现在也是我推荐给大家的模板组织方式。所以别指望一步到位。模板是活的东西要根据实际使用反馈不断裁剪、搬移、重写。每用一两周就回顾一次哪些指令真正影响了行为哪些只是自我感动然后果断删掉后者。7. 常见问题速查我踩过的那些坑7.1 上下文爆炸怎么办症状是对话越往后 Claude Code 越“迟钝”甚至早期说过的重要约束它也会忘。原因通常是 CLAUDE.md 或命令模板塞了过多内容也可能是某次会话让模型读取了超长文件并长时间保留在上下文中。我的解决办法分两层。第一层把 CLAUDE.md 控制在 150 行以内超过的部分拆出去让模型按需用 Grep 或 Read 自己去找。第二层遇到特别大的重构任务时主动分阶段处理不要试图在单个会话里把所有上下文都堆进去。模板的职责是告诉模型“信息在哪”而不是替模型把所有信息都背下来。7.2 模板指令冲突时谁说了算Claude Code 会同时读取 CLAUDE.md、命令模板、Agent 定义和用户对话中的即时指令。当这些来源里的要求相互矛盾时优先级通常是即时对话指令最高其次是特定任务模板再次是 Agent 定义最后是 CLAUDE.md 里的通用规则。这就带来一个有意思的实践如果你想让某个规则“绝对不可违反”把它写进即时指令中是不够的还要同时在多个层级重复强化。比如“绝对不要修改生产配置文件”这句话CLAUDE.md 里写一遍、相关命令模板里写一遍、Agent 工具权限里直接移除 Edit 工具三重保险才能确保不翻车。7.3 Hook 脚本导致的意外中断Hook 脚本返回非零退出码时Claude Code 会认为当前操作失败并中断流程。我第一次配格式化钩子时脚本里直接用npx prettier结果某个文件路径带了空格命令执行失败整个 Write 操作被回滚CI 一度红成一片。排查了一圈才发现是路径空格问题。修复方法是把所有文件路径都用双引号包好并且在脚本开头加一个简单的参数校验遇到异常输入直接跳过而不是终止操作。Hook 脚本在正式使用前一定要手工模拟各种输入测试一遍别等到实际运行再暴露问题。7.4 斜杠命令没有生效或参数注入失败出现这种情况优先检查 YAML 元信息是否写错。YAML 里description:后面必须紧跟一个空格任何缩进错误都会导致整个文件无法解析。参数注入方面不同版本对占位符的写法略有差异最稳妥的做法是先跑一次不带参数的版本确认正常后再加参数模板逐步调试。另外一个隐蔽问题是命令文件命名。文件名里的字母会直接成为命令名的一部分不支持大写或特殊符号命名规则最好统一成小写连字符比如new-feature.md。改了文件名后如果在会话里看不到新命令先确认文件权限是否可读再确认是否放在了当前项目识别的.claude/commands目录下。7.5 模板更新后行为没变化有些人以为改完 CLAUDE.md 和命令模板下一次对话就会自动生效。实际情况是正在进行的会话里Claude Code 可能已经缓存了旧的模板内容。最可靠的做法是更新模板后开始一个全新会话或者主动让模型重新读取对应文件。当模板文件比较多时我习惯在改动后用/init触发一次重新加载再手动抽查几个关键指令是否按新规则执行。这比直接开聊要稳妥可以提前发现模板格式错误或路径引用失效的问题。回到最开始的问题——为什么同一个 Claude Code在不同人手里差距这么大我的答案始终是模板就是那个差距。它不是一把万能钥匙但它是一支能沉淀经验、统一行为、减少返工的杠杆。别再羡慕别人的 AI 编码效率了把你脑子里的隐性规则写出来让模板替你干活效果不会让你失望。 Claude Code模板实战：从CLAUDE.md到Agent工作流提升AI编程效率
如果你跟我一样整天跟 Claude Code 在终端里打交道大概率早就发现一个现象同一个工具放在不同人手里完全是两种生产力。有人能用它十几分钟完成一次跨模块的代码梳理有人聊到第五轮就开始跑偏、改错文件、反复返工。差距往往不在模型而在模板。“Claude Code 模板”听起来不像什么炫技概念但它才是决定工具上限的隐形杠杆。说白了模板就是一套预先写好的规则、上下文和流程让 Claude Code 在动手之前就知道“你是谁、要做什么、按什么标准做、哪些事千万别碰”。没有这套东西它就像刚入职三天的新同事聪明但缺乏方向有了它你相当于给这个新同事发了一本工作手册、一堆审批表单和一条自动质检流水线。这篇文章就来把模板这件事掰开揉碎讲清楚底层有哪些模板块、怎么写才能不踩坑、如何从零到一搭一套能直接复用的模板包以及我实战中踩过的几个典型问题。适合刚接触 Claude Code 的初学者也适合已经用了很久但总觉得“不够聪明”的老用户。1. 模板体系从“一次性提示”到“团队资产”1.1 拆开看Claude Code 里的模板到底指什么很多人以为模板就是“把一段提示词存成文件”这只是其中一层。Claude Code 的模板体系至少包含四类东西对应四种不同的用途。第一类是项目记忆文件 CLAUDE.md。它相当于项目级的工作手册放在仓库根目录Claude Code 启动时会自动读取。内容是项目的目标、架构、技术栈、编码约定、常用命令、容易犯的错误。它解决的核心问题是“让 AI 在动手前了解全局”。没有 CLAUDE.md 的情况下Claude Code 只能靠在对话里临时问东问西或者凭通用知识猜你的项目结构自然容易跑偏。第二类是自定义斜杠命令。默认的/clear、/init之外Claude Code 允许你把常用操作固化成自己的斜杠命令比如/review做代码审查、/test生成测试、/fix处理特定类型的报错。斜杠命令本质上是精心设计的提示模板加上参数入口和工具权限控制。比起每次手动输一大段要求命令能保证每次执行的提示质量稳定。第三类是 Hooks 自动化钩子。你可以配置一个钩子让某些动作自动触发比如每次 Claude Code 写完文件后自动跑一次格式化或 lint每次调用某些危险工具前先自动拦截检查。这属于流程模板把“人工提醒”变成“自动化规则”。第四类是 Agent 子代理定义模板。Claude Code 支持创建具备不同职责的子代理比如“前端专家”“测试工程师”“安全审查员”每个子代理由一份单独的 Markdown 文件定义内含角色定位、能力边界、可使用的工具列表和输出要求。这就像给 AI 团队里每个岗位都写好了岗位说明书。1.2 为什么模板能带来质的改变我一直觉得模板最大的价值不是“省几个字”而是把隐性经验固化下来。你用了半年 Claude Code一定积累了不少技巧哪些要素它容易漏哪种描述方式它最容易理解哪些命令它经常在错误的目录下执行。这些经验如果没有写进模板就是一次性的写进去之后每次会话都会继承。更关键的是稳定性。我观察过不少团队的使用情况同一个仓库上午让 Claude Code 重构一个小模块效果很好下午换个同事继续聊效果突然变差。原因很可能是上午的会话里积累了详细上下文下午新会话从零开始。项目模板就是把“上午的有效上下文”沉淀下来让每个新会话都站在同一个起点。还有一点容易被忽略模板是团队协作的接口。多人用 Claude Code 时如果每个人都有自己的一套描述习惯AI 的行为会非常分裂。有了统一模板大家默认遵循同一套规则AI 产出的风格、格式、质量标准也会收敛代码评审时就少了很多“这到底按谁的标准写的”的争议。2. CLAUDE.md 项目记忆模板给 Claude Code 一本员工手册2.1 骨架怎么搭最合理CLAUDE.md 不是写得越多越好。它像新员工入职手册要让对方快速理解核心信息而不是把公司制度全文背下来。我个人推荐的骨架是七块项目一句话定位、技术栈清单、常用命令、项目目录导航、核心架构说明、编码约定、禁忌清单。项目定位最好用一句话讲清楚“这个系统是干什么的、给谁用”。别小看这句话它决定了 Claude Code 后续判断优先级的方向。一个给内部运营人员用的后台管理系统和一个给外部用户用的高并发 API 服务同样是“改一个接口”取舍逻辑完全不同。技术栈清单要具体到版本和关键框架。不是简单写“Python Django”而是写清楚 Python 版本、ORM 用什么、数据库连接走哪个库、有没有使用消息队列。这样 AI 在生成代码时才不会“自以为是”地引入你根本没安装的依赖。目录导航部分很多人会漏掉。Claude Code 虽然能自己搜索文件但你直接告诉它核心代码在哪几个目录、测试在哪、静态资源在哪、部署脚本在哪能省掉大量无效搜索。尤其对大型仓库这一步收益极高。架构说明要写清模块之间的依赖方向和关键数据流。别写太细重点是让 AI 知道“改 A 模块时可能连带影响 B 模块”避免改了一个函数就以为万事大吉。编码约定是模板里最有“钱”的部分。把你团队真正在乎的规则列出来命名风格、错误处理方式、日志格式、数据库迁移规范、接口返回结构。这里尽量避免罗列网上能找到的通用规范而是要写“咱们项目里特有”的约定。比如你们约定所有日期字段统一存时间戳还是字符串错误码前两位表示模块禁止在业务层直接拼 SQL这些信息通用文档里根本没有才是模板的含金量所在。最后是禁忌清单。每个项目都有自己的雷区某个生产环境配置绝对不能改、某个老模块欠了大量技术债不能顺手重构、某些测试稳定但很慢不能乱删。把这些明确写进 CLAUDE.md能避免 AI 在一通正常操作里突然踩爆一个隐形地雷。2.2 一个可以直接用的 CLAUDE.md 模板示例下面这个例子是我在某中等规模 Web 项目里实际使用过的结构你可以按自己的项目改。# 项目指南 ## 项目定位 本项目是订单履约系统中的发货模块负责将订单推送到仓配系统并回传物流轨迹。 面向内部运营和仓配同事使用日均处理订单量约为 20 万。 ## 技术栈 - Node.js 18 TypeScript 5.x - 框架NestJS 10 - 数据库PostgreSQL 15通过 Prisma ORM 访问 - 缓存Redis 7使用 ioredis 客户端 - 消息队列RabbitMQ使用 amqplib ## 常用命令 - 安装依赖npm install - 本地启动npm run start:dev - 运行测试npm test - 数据库迁移npx prisma migrate dev - 代码检查npm run lint ## 目录导航 - src/modules/shipping发货核心业务 - src/modules/oms订单管理相关适配 - src/common公共类型与工具函数 - test集成测试用例 - infra部署与容器配置 ## 核心架构 发货模块通过 RabbitMQ 消费订单消息组装发货请求后调用仓配系统 HTTP 接口。 回调接口负责接收物流轨迹写入本地数据库后通过 WebSocket 推送给前端。 依赖方向shipping - oms/common禁止反向引用。 ## 编码约定 - 所有接口入参必须通过 DTO 校验禁止直接用 any - 返回结构统一为 { code, data, message }code0 表示成功 - 错误码前两位表示模块shipping 模块使用 14 开头 - 日期字段统一存 ISO 字符串禁止存本地时间戳 - 异步任务必须走 RabbitMQ不要直接使用 setTimeout ## 禁忌 - 不要修改 infra/ 下的生产部署配置 - 不要重构 src/modules/oms/legacy 目录该目录为老系统临时适配 - 不要删除 test/integration 中带 SLOW 标记的用例看到没这份 CLAUDE.md 里的内容九成是通用 AI 知识库里查不到的只有在这个仓库里干过活的人才知道。写清楚后Claude Code 再处理发货模块的改动时会天然按照这套规则来生成的代码风格一下子就“像自己人写的了”。2.3 内容取舍与三个反模式CLAUDE.md 最常见的反模式是“写成文档库”。有人把整个项目的设计文档、接口文档全塞进去结果 Claude Code 的上下文窗口被大量低频信息挤占反而降低了核心指令的注意力。记住CLAUDE.md 是工作手册不是文档中心。那些偶尔才需要的信息应该放到仓库里让模型按需搜索而不是一股脑嵌入上下文。第二个反模式是“用不痛不痒的套话凑数”。像“请写出高质量代码”这种话看起来没问题实际毫无信息量因为它没有给出可执行的判断标准。宁可写“函数行数不要超过 80 行”“所有外部接口调用必须做超时处理”也不要写虚的。第三个反模式是“只写规则不给原因”。模型不是人它记不住没有逻辑关联的规则。比如你写“不要使用 lodash”它下次很可能还是会用因为它不理解为什么。但如果你写“不要使用 lodash本项目运行在边缘环境包体积每增加 1KB 都会影响冷启动速度”模型就会意识到这是硬约束。给规则附上理由遵从率会显著提高。3. 自定义斜杠命令把常用操作做成“一键脚本”3.1 命令模板的结构自定义斜杠命令存放在两个位置的其中之一项目级.claude/commands/目录或者用户级~/.claude/commands/目录。项目级的命令只对当前仓库生效适合沉淀业务相关的操作用户级命令对所有项目生效适合放通用的审查、重构动作。每个命令是一个 Markdown 文件文件名就是斜杠命令名例如review.md对应/review。文件最顶部用 YAML 写元信息下面写真正的提示内容。--- description: 执行一次完整的代码审查 argument-hint: [可选的审查范围如 src/modules/shipping] allowed-tools: Read, Grep, Glob, Bash ---元信息里最重要的是 description它会在斜杠命令列表里展示给用户。argument-hint 是给用户看的参数提示比如告诉它可以传一个文件路径或目录范围。allowed-tools 限制该命令执行时可调用的工具这非常关键它防止某些高风险操作被命令触发。正文部分就是你写给 Claude Code 的提示词里面可以引用用户输入的参数。当用户输入/review src/modules/shipping时src/modules/shipping就会被注入到命令模板中实现带参数的命令。3.2 三个可以直接抄的命令模板我先分享一个代码审查命令这也是我日常使用频率最高的。它解决了“让 AI 主动去找问题”的核心需求而不是简单问一句“代码有什么问题”。--- description: 执行一次完整代码审查按模块输出问题清单 argument-hint: [目标路径] allowed-tools: Read, Grep, Glob, Bash --- 对目标范围执行一次严格代码审查重点检查以下维度 1. 正确性是否存在逻辑漏洞、边界条件遗漏、并发问题 2. 可维护性是否违反项目 CLAUDE.md 中的编码约定 3. 性能是否有明显的性能隐患N1 查询、循环内部 I/O 等 4. 安全隐患是否有注入口、敏感信息泄露、越权访问 目标范围{{$ARGUMENTS:全部代码}} 输出格式要求 - 按严重程度分组分组为致命 / 需修复 / 建议优化 - 每个问题给出文件路径、行号、问题描述、修复建议 - 如未发现问题明确输出“本次审查未发现问题” 注意审查逻辑类问题时要查看相关测试用例不要只读实现代码。再看一个测试生成命令。直接让 AI “写测试”很容易产出只覆盖正常路径的无效用例所以模板里必须强制它先分析代码路径再设计用例。--- description: 根据目标函数或模块生成单元测试 argument-hint: [目标文件或函数名] allowed-tools: Read, Grep, Glob, Bash, Write --- 为目标代码生成单元测试流程如下 1. 先阅读源代码梳理所有出口路径、异常分支、边界条件 2. 检查现有测试避免重复覆盖 3. 设计用例时遵循“正常路径 边界条件 异常输入”三组结构 4. 使用项目现有的测试框架和断言风格不要引入新依赖 目标{{$ARGUMENTS}} 额外要求 - mock 外部依赖禁止真实网络请求 - 每个测试必须带明确的中文用例名说明验证的行为 - 测试数据用工厂函数生成不要硬编码一堆魔法数字最后一个是我处理遗留项目的利器——清理命令。老代码库里经常有“看着没用但不敢删”的代码用这个命令可以低风险地做一次存活度体检。--- description: 检查代码的引用情况输出可安全删除的疑似死代码清单 argument-hint: [目录或文件] allowed-tools: Read, Grep, Glob, Bash --- 对目标范围检查疑似死代码规则如下 1. 搜索所有符号的引用点区分直接引用、字符串引用、动态引用 2. 动态引用或反射场景下就算没有静态引用也要标记为“需人工确认” 3. 公共 API 定义即使无内部引用也要标记为“对外不可删” 4. 输出表格文件名、符号名、引用数量、删除建议可安全删除/需人工确认 目标范围{{$ARGUMENTS}}写好这些命令文件后在 Claude Code 会话里输入/就能看到命令列表输入/review src/modules/shipping就能直接触发。整个过程从“告诉 AI 一堆细节”简化为“敲一条命令”这就是模板落地后最直观的体验提升。4. Hooks 自动化模板让流程自己跑起来4.1 Hooks 能解决什么问题Hooks 是 Claude Code 里的自动化触发机制它在特定事件发生时自动执行一段命令或脚本。我只提三个最常用的场景写完代码后自动格式化、危险操作前自动拦截、每次会话结束前自动输出变更摘要。写完代码后自动格式化这个场景很实际。Claude Code 生成的代码风格再接近团队规范也会有缩进、引号、分号这类细节问题。与其每次都花额外轮次让它改格式不如配置一个 PostToolUse Hook只要模型执行了 Write 或 Edit 工具就自动对相关文件跑一次 Prettier。危险操作拦截属于 PreToolUse Hook 的典型用法。比如你规定“禁止使用 Bash 工具执行DROP TABLE”就可以在工具调用前设置一个检查脚本发现危险命令时直接拦截并提醒。这相当于给 AI 的越权操作加了一道门禁。会话摘要输出则适合多人协作用的场景。每次会话结束前让 Claude Code 自动总结这次改了哪些文件、新增了什么命令、是否留下了待办事项写入一个变更日志文件。这样后续接手的人不用猜上次讨论了什么。4.2 配置模板与避坑提示Hooks 的配置写在.claude/settings.json里。我直接给一个可用的示例。{ hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: npx prettier --write \$CLAUDE_FILE_PATHS\ } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: bash .claude/hooks/check-dangerous-command.sh \$CLAUDE_TOOL_INPUT\ } ] } ] } }matcher 字段用来匹配工具名Write|Edit 表示在模型执行这两个工具后触发。钩子脚本里可以通过$CLAUDE_FILE_PATHS这类内置变量拿到当前操作的文件列表。上面对应的拦截脚本可以写成这样#!/usr/bin/env bash input$1 if echo $input | grep -qE DROP TABLE|rm -rf /|git push --force; then echo 拦截检测到危险命令已阻止执行 exit 2 fi exit 0这个脚本的逻辑很简单检查输入是否有高危命令发现就直接返回非零退出码让 Claude Code 停止当前操作。用 Hooks 最容易踩的坑有两个。一是钩子脚本本身报错会导致流程中断所以脚本里所有命令都要考虑“没有输出”和“执行失败”的情况。二是 PostToolUse 里如果再触发文件修改有可能引发新的 Hook 事件形成连锁循环。我建议给所有 Hook 脚本加上“自身只跑一次”的标记比如判断环境变量或入口参数避免无限套娃。5. Agent 工作流模板从单兵作战到小团队协作5.1 子代理定义文件怎么写Claude Code 的 Agent 功能允许你定义多个有独立职责的子代理每个子代理有自己的一套提示、工具列表和行为边界。它在复杂任务中特别好用把一个大任务拆给不同角色的子代理避免单个对话里职责混乱。子代理定义放在.claude/agents/目录下每个文件同样以 YAML 元信息开头。我以一个“测试工程师”子代理为例。--- name: tester description: 负责编写单元测试与集成测试运行测试套件并分析失败原因 tools: Read, Grep, Glob, Bash, Write --- 你是一名资深测试工程师专职负责自动化测试。 工作原则 1. 开始写测试前必须先阅读目标代码列举所有需要覆盖的分支 2. 遵循项目中已有的测试风格优先复用现有工具函数 3. 运行测试时如果出现失败先分析失败原因再修改代码禁止盲目重试 4. 测试用例命名必须说清楚验证场景例如“订单金额为负数时应拒绝创建” 质量标准 - 分支覆盖率不低于 85%关键异常路径必须有用例 - mock 必须最小化只 mock 真正的外部依赖 - 测试运行时间超过 5 秒的在用例名前加 SLOW 标记 注意事项 - 不要为了覆盖率而生成无意义的断言 - 不要修改测试目标代码的逻辑只允许修复测试本身的问题description 是子代理最关键的字段它决定了主代理在什么情况下会选择这个子代理。因此 description 里要写清楚职责边界和适用场景不要写成笼统的“负责测试相关事务”而要写成“负责编写单元测试与集成测试运行测试套件并分析失败原因”。tools 列表控制子代理能使用的工具这是权限隔离的核心。子代理能用的工具越少越不容易造成失控操作。子代理目录在生产环境部署时建议只给 Write 和 Read 类工具禁止直接执行会影响生产环境的命令。5.2 主代理与子代理的编排模板定义好子代理后还需要一个编排提示模板告诉主代理什么时候该把任务拆给谁、怎么整合结果。这个模板我习惯放在 CLAUDE.md 里或者单独做成一个命令。## Agent 编排规则 - 当任务涉及大规模测试补全或测试排障时优先委托给 tester 子代理 - 当任务涉及前端组件实现或样式修复时优先委托给 frontend 子代理 - 每个子代理返回结果后主代理必须复核关键代码与测试结果不能直接照搬 - 子代理之间的任务必须通过上下文传递文件路径不要传递大段代码块这条编排规则本身也是模板的一部分它解决的是“Leader 如何调度专家”的问题。没有编排规则时主代理偶尔会用子代理、偶尔自己硬扛行为不可预测。有了规则复杂任务会被稳定地拆解流转协作质量会明显更稳定。一个常见的错误是把所有任务都甩给子代理导致上下文切割过度。子代理之间共享的信息有限如果任务强依赖全局上下文强行拆给多个子代理反而会降低效果。我的经验是强耦合、需要全局视野的任务主代理自己做弱耦合、可独立完成的任务才拆给子代理。6. 从 0 到 1一套最小可用模板包的完整落地6.1 最小模板包包含哪些文件如果你是第一次搭模板不用一上来就搞 Agent、Hook 全家桶。我建议按下面这个最小组合起步总共四个文件覆盖八成收益。项目根目录/ ├── CLAUDE.md └── .claude/ ├── settings.json ├── commands/ │ ├── review.md │ └── test.md └── agents/ └── tester.md第一份 CLAUDE.md 是必选项用来固化项目背景和规则。没有它后面所有模板的效果都会打折扣。第二份 settings.json 可以先只配置一个 PostToolUse 格式化钩子解决代码风格问题。第三份 review.md 命令把代码审查工作标准化。第四份 tester.md 子代理把测试类任务隔离到一个角色里。这套组合覆盖了“了解项目、规范操作、审查结果、质量保障”四个环节对一个中等复杂度的仓库来说已经能明显感受到差异。6.2 我自己的演进记录从 v1 到 v3第一次搭模板时我犯过的最大错误就是贪多。那时候我在 CLAUDE.md 里写了整整八十行编码规则几乎把团队规范文档全文搬运进去了。结果 Claude Code 确实记住了一部分但上下文占用暴增基础指令的响应质量反而下降。这是模板 v1 的典型问题把上下文当仓库用。v2 我做了减法。只保留三块项目定位、关键路径、禁忌清单。作息一下清晰了很多。但后来又发现少了点什么——AI 经常在细节决策上不一致这里的“不一致”指的是同一天前后几次修改看待同一问题的角度明显漂移。于是在 v2.5 我加入了“决策偏好”一节写明“面对不确定需求时优先选择兼容性更好的方案不要追求过度设计”。这类原则性信息信息密度高且不占太多空间效果很立竿见影。v3 开始模块化。我把 CLAUDE.md 压到最精简把大量可选的详细规范挪到.claude/commands和agents里。这样核心上下文负担小详细规则又能在特定任务场景被精准加载。这个结构一直用到现在也是我推荐给大家的模板组织方式。所以别指望一步到位。模板是活的东西要根据实际使用反馈不断裁剪、搬移、重写。每用一两周就回顾一次哪些指令真正影响了行为哪些只是自我感动然后果断删掉后者。7. 常见问题速查我踩过的那些坑7.1 上下文爆炸怎么办症状是对话越往后 Claude Code 越“迟钝”甚至早期说过的重要约束它也会忘。原因通常是 CLAUDE.md 或命令模板塞了过多内容也可能是某次会话让模型读取了超长文件并长时间保留在上下文中。我的解决办法分两层。第一层把 CLAUDE.md 控制在 150 行以内超过的部分拆出去让模型按需用 Grep 或 Read 自己去找。第二层遇到特别大的重构任务时主动分阶段处理不要试图在单个会话里把所有上下文都堆进去。模板的职责是告诉模型“信息在哪”而不是替模型把所有信息都背下来。7.2 模板指令冲突时谁说了算Claude Code 会同时读取 CLAUDE.md、命令模板、Agent 定义和用户对话中的即时指令。当这些来源里的要求相互矛盾时优先级通常是即时对话指令最高其次是特定任务模板再次是 Agent 定义最后是 CLAUDE.md 里的通用规则。这就带来一个有意思的实践如果你想让某个规则“绝对不可违反”把它写进即时指令中是不够的还要同时在多个层级重复强化。比如“绝对不要修改生产配置文件”这句话CLAUDE.md 里写一遍、相关命令模板里写一遍、Agent 工具权限里直接移除 Edit 工具三重保险才能确保不翻车。7.3 Hook 脚本导致的意外中断Hook 脚本返回非零退出码时Claude Code 会认为当前操作失败并中断流程。我第一次配格式化钩子时脚本里直接用npx prettier结果某个文件路径带了空格命令执行失败整个 Write 操作被回滚CI 一度红成一片。排查了一圈才发现是路径空格问题。修复方法是把所有文件路径都用双引号包好并且在脚本开头加一个简单的参数校验遇到异常输入直接跳过而不是终止操作。Hook 脚本在正式使用前一定要手工模拟各种输入测试一遍别等到实际运行再暴露问题。7.4 斜杠命令没有生效或参数注入失败出现这种情况优先检查 YAML 元信息是否写错。YAML 里description:后面必须紧跟一个空格任何缩进错误都会导致整个文件无法解析。参数注入方面不同版本对占位符的写法略有差异最稳妥的做法是先跑一次不带参数的版本确认正常后再加参数模板逐步调试。另外一个隐蔽问题是命令文件命名。文件名里的字母会直接成为命令名的一部分不支持大写或特殊符号命名规则最好统一成小写连字符比如new-feature.md。改了文件名后如果在会话里看不到新命令先确认文件权限是否可读再确认是否放在了当前项目识别的.claude/commands目录下。7.5 模板更新后行为没变化有些人以为改完 CLAUDE.md 和命令模板下一次对话就会自动生效。实际情况是正在进行的会话里Claude Code 可能已经缓存了旧的模板内容。最可靠的做法是更新模板后开始一个全新会话或者主动让模型重新读取对应文件。当模板文件比较多时我习惯在改动后用/init触发一次重新加载再手动抽查几个关键指令是否按新规则执行。这比直接开聊要稳妥可以提前发现模板格式错误或路径引用失效的问题。回到最开始的问题——为什么同一个 Claude Code在不同人手里差距这么大我的答案始终是模板就是那个差距。它不是一把万能钥匙但它是一支能沉淀经验、统一行为、减少返工的杠杆。别再羡慕别人的 AI 编码效率了把你脑子里的隐性规则写出来让模板替你干活效果不会让你失望。