你是不是也遇到过这种情况同一个项目里你让 Claude Code 处理一个重构任务结果它对项目背景一无所知先花几分钟把代码库翻一遍然后写出来的代码风格和你团队规范差得十万八千里。更别提每次开新会话都像面试一个新程序员什么都要重新交代。我之前也是这么过来的直到我把 claude-code-templates 这套思路真正落到项目里情况才彻底转变。所谓 Claude Code 模板说白了就是把 AI 协作时需要反复交代的信息、约定、命令、角色行为全部固化成一整套可复用的配置文件。它解决的不仅是“少打几行字”的问题而是让 AI 在一个项目里拥有稳定的“记忆”和“行为准则”——每次会话启动时它天然就知道项目在做什么、技术栈是什么、代码规范是什么、遇到什么情况该调用什么命令。这篇文章适合所有在用 Claude Code 但觉得“差点意思”的人也适合想让团队统一 AI 协作方式的工程负责人我会从模板体系的组成、写法、完整实操到常见坑位一次性讲透。1. 先搞清楚Claude Code 的模板到底解决什么问题1.1 默认配置与模板化的差距在哪里很多人刚接触 Claude Code 时觉得它已经挺聪明让改 bug 能改让写函数能写但用着用着就会发现两个特别难受的地方。第一个是“失忆感”。每次新开会话它对项目的了解几乎为零。你让它改一个模块它要先读文件、猜结构、试用例跑的路径一轮对话里至少三分之一的开销浪费在“重新认识项目”上。第二个是“风格漂移”。你昨天交代过错误处理要统一返回结构今天换一个会话它就忘了自己又发明一套代码注释该用中文还是英文它今天用中文明天用英文团队成员在不同会话里得到的产物完全是两种风格。模板化配置针对的就是这两个问题。你可以把项目的技术栈、目录结构、命令规范、代码风格、甚至团队偏好全部写进模板文件让 Claude Code 在每次会话开始时就自动加载这些上下文。这样它不再是“一个聪明的万能实习生”而是“一个熟悉你项目的专属工程师”。这中间的差距用过模板的人和没用过模板的人体感是完全不同的。1.2 模板体系的三个层级个人、项目、团队我先说一个基础认知Claude Code 的模板配置并不是单个文件而是一个分层体系理解了这个分层才能真正用好它。外层是用户级配置通常放在~/.claude/CLAUDE.md里它加载到你的所有项目会话中适合放一些跨项目通用的个人偏好比如你默认使用的语言风格、常用的工具链命令、不希望 AI 触碰的目录等。中间层是项目级配置放在项目根目录.claude/CLAUDE.md这是最核心的一层所有关于这个项目的技术背景、架构约定、启动方式、测试命令都应该放这里。最内层是命令、子代理和钩子它们是按需加载的比如你写了一个/commit命令平时不占任何上下文只有你主动敲斜杠触发它时才会加载子代理同理只有主模型判断需要调用或者你手动指定时它才进入上下文。这个“全局常驻、项目常驻、任务按需”的设计有它的内在逻辑。全局和项目级模板必须精简因为每次对话都会占用上下文命令和子代理可以内容丰富因为它们只在需要时才消耗 token。理解了这个层级关系你就知道模板不是越厚越好而是该常驻的精炼、该按需的具体。2. 摸清模板体系的四个核心组件2.1 CLAUDE.md给 AI 的“项目说明书”CLAUDE.md 是整个模板体系的心脏很多教程把它看成一个“规则文件”但我更愿意叫它“项目说明书”。它不是用来写一堆抽象口号的而是要把项目的关键信息以 AI 最容易理解和遵循的方式组织起来。一个高质量的 CLAUDE.md 应该包含三块内容。项目背景与全局约束是最基础的一块包括项目是做什么的、核心业务领域是什么、有没有必须遵守的技术限制比如必须兼容某个版本的运行环境、不能依赖某个第三方库。技术栈与架构信息是第二块写清楚前端用什么框架、后端用什么语言、代码仓库的目录结构如何、数据层怎么组织。工作约定与常用命令是第三块包括测试命令、构建命令、代码风格要求、命名规范、以及团队特有的工作流。我见过很多失败的 CLAUDE.md共同特征是写了太多“废话”。比如“请写出高质量的代码”“请遵循最佳实践”——这种话 AI 读了等于没读。真正有效的写法是给出可以机械执行的信息项目用 pnpm 还是 npm、测试跑npm run test还是pytest、新代码必须带类型定义、所有对外接口的返回值统一成{ code, data, message }这种结构。这些具体到可验证的规则AI 才能真正执行。2.2 自定义命令 /command把重复操作变成一句话Claude Code 支持在.claude/commands/目录下放一系列 Markdown 文件每个文件对应一个斜杠命令。这是所有组件里投入产出比最高的一个因为它的写法极其简单却能把高频重复的动作压缩成一个词。比如团队每个成员都要在提交代码前生成规范的 commit message传统做法是每次都要敲一长串 prompt“帮我看一下 git diff然后根据 Conventional Commits 规范生成一个提交信息……”有了模板命令你只需要写一个.claude/commands/commit.md里面写清楚你要 AI 做的事之后在终端里敲/commit它就自动扮演这个角色。类似的场景还有/review代码审查、/doc生成文档、/refactor重构助手等。命令文件的一个关键特性是支持$ARGUMENTS参数引用你可以用/commit 修复登录页样式问题这种带参数的方式调用AI 会把参数带入到命令逻辑中。我自己常用的场景是写一个/explain命令当我看不懂某段代码时敲一下就能让 AI 从用户视角、实现细节、潜在风险三个角度解释比我手动组织 prompt 快得多。2.3 子代理 Subagent给不同角色装上专业脑子如果说命令是“按场景触发的一次性专业动作”子代理就是“可以独立承担某类任务的专业角色”。Claude Code 支持在.claude/agents/目录下定义子代理每个子代理有自己的身份定义、能力范围、工具权限和工作方式。举个例子。我在一个中大型项目里配置了一个code-reviewer子代理它的身份是资深代码审查专家工具权限只开放文件读取和搜索不开放写入。主模型在接到“帮我把这段代码审查一下”的任务时会自动判断交给这个子代理更合适或者你也可以用code-reviewer直接指定。子代理的好处是专业聚焦——它不会在审查时顺手帮你改代码不会跑偏而且它的 prompt 本身就可以写得非常详细因为它是按需加载的不需要担心占用主会话的上下文空间。子代理文件的结构一般是 YAML 格式的 frontmatter 加上正文 promptfrontmatter 里写名字、描述、工具权限正文里写这个角色应该遵循的工作流程和输出要求。描述字段非常重要因为主模型靠它来判断“这个任务该不该交给这个子代理”描述写得越清晰调度的准确率越高。2.4 钩子 Hooks让模板在关键时刻自动生效钩子机制可以说是模板体系的“自动化开关”它允许你在特定事件发生时自动触发命令而不需要手动干预。Claude Code 的 hooks 配置写在.claude/settings.json里支持的事件类型包括工具调用前PreToolUse、工具调用后PostToolUse、会话开始等。举一个我实际在用的例子。我们团队要求任何文件写入后都要通过 lint 检查以前靠人工提醒总有人忘了。后来我在settings.json里配了一条 PostToolUse 钩子匹配 Edit 类工具文件写入后自动执行npm run lint发现问题当场报错。这一个配置就省掉了无数次代码评审会上为 lint 问题扯皮的场面。还有一类用法是给特定的命令执行前置校验比如在/deploy命令执行前钩子先检查当前分支是不是 main不是就拦下来。这类“规则自动化”让模板从“被动的资料”变成了“主动的监督者”大大减少了低级错误。不过要注意钩子的触发频率配得太激进会在每次文件修改时都跑一遍耗时命令反而拖慢效率阈值要自己调。3. 手把手搭一套项目模板完整实操过程3.1 先想清楚三个问题再动手写模板上手写模板之前先别急着建文件花十分钟想清楚三个问题。第一个问题你的项目里AI 最常被要求做哪些事是写业务代码、改 bug、做重构还是写测试和文档不同侧重决定你的模板重心。第二个问题这个项目的技术栈和工作流有哪些硬性约定比如框架版本、包管理器、测试工具、代码风格这些是必须写进模板的硬信息。第三个问题团队里最常出现的重复性操作是什么列出来这些就是最适合做成斜杠命令的候选。三个问题过完你会发现模板的结构基本浮出水面。我的习惯是把答案写在一张草稿纸上分成“常驻信息”和“按需信息”两列。常驻信息进 CLAUDE.md按需信息进 commands 或 agents。这个先后顺序很重要——先有需求后有模板而不是照着别人的模板抄一遍那样基本是浪费生命。3.2 初始化目录从零创建模板骨架好开始动手。打开你的项目终端先看一下现有目录里有没有.claude目录没有就创建一个。然后按下边的骨架把文件先建好mkdir -p .claude/commands .claude/agents touch .claude/CLAUDE.md .claude/settings.json建好后的目录结构大概长这样.claude/ ├── CLAUDE.md # 项目级主模板常驻上下文 ├── settings.json # 钩子、权限等配置 ├── commands/ # 斜杠命令按需加载 │ ├── commit.md │ ├── review.md │ └── explain.md └── agents/ # 子代理按需加载 └── code-reviewer.md再说一个很多人不知道的小细节Claude Code 也兼容项目根目录直接放一个CLAUDE.md的写法新项目我推荐统一放到.claude/CLAUDE.md因为这样所有和 AI 协作相关的配置都在一个目录里进不进版本库也更好控制。如果你是从老项目迁移过来把根目录的CLAUDE.md移到.claude/下就行功能是一样的。3.3 写主模板 CLAUDE.md一个可直接套用的示例主模板的核心原则是“简洁、具体、可验证”。我写一个通用示例你可以直接套到自己的项目上然后按需删改# 项目背景 - 项目名称shop-api - 一句话描述面向电商小程序的商品与订单服务端 API - 核心约束必须兼容 Node 18禁止引入重量级 ORM数据访问层统一走 repository 模式 # 技术栈 - 运行时Node.js 18 TypeScript - 框架Fastify - 包管理器pnpm - 测试Vitest supertest - 数据库PostgreSQL via pg # 常用命令 - 安装依赖pnpm install - 本地开发pnpm dev - 运行测试pnpm test - 类型检查pnpm typecheck - Lintpnpm lint # 代码约定 - 所有对外 API 的返回结构统一为 { code, data, message } - 错误处理必须使用统一异常过滤器禁止在路由内裸 catch - 新写的业务方法必须附带 JSDoc 注释说明入参、出参和异常场景 - 文件命名xxx.service.ts / xxx.controller.ts / xxx.repository.ts # 工作流要求 - 修改代码后必须跑 pnpm typecheck 和 pnpm test - 涉及数据库变更时优先给出迁移文件而非直接改表结构 - 如果任务跨多个模块先列出影响范围再动手改这一份下来大概在 600 字左右信息密度很高。你可能会问为什么没有大段的技术说明因为 Claude Code 本身就很懂技术它缺的不是“知识”而是“你这个项目的具体约定”。写模板的过程本质上就是把团队里散落在文档里、代码评审里、口头传承里的隐式知识显式地写出来。3.4 写两个高频命令/commit 和 /review命令文件写起来非常简单就是一个 Markdown 文件文件名的前缀就是命令名。我拿团队用的/commit举例在.claude/commands/commit.md里写上这些内容你是本项目的提交信息助手。请根据当前的 git diff 生成一个提交信息。 要求 1. 遵循 Conventional Commits 格式类型从 feat / fix / refactor / docs / test / chore 中选择 2. 用一句话概括主体变更必要时可以加 body 说明影响范围 3. 如果 diff 为空明确告诉用户没有可提交的变更 当前变更 git diff $ARGUMENTS /git diff写完之后你只需要在终端敲/commit它会自动拉取当前 diff 并按规则生成提交信息。如果你只想让它提交某个文件直接/commit src/xxx.ts 修复价格计算问题后面那段话会通过$ARGUMENTS注入进去。再看/review它适合做合并前的自检你是团队里的高级代码审查者现在对以下改动进行审查。 审查维度 1. 正确性逻辑是否完整有没有边界遗漏 2. 一致性命名、返回结构、错误处理是否符合项目约定 3. 性能是否存在明显的低效写法 4. 安全性有没有注入、敏感数据泄露等风险 输出格式 - 按问题严重程度分级列出blocker / major / minor / suggestion - 每个问题附上文件的相对路径和行号区间 - 如果没有问题简洁回复“LGTM” 改动内容 git diff $ARGUMENTS /git diff这个命令相当于给团队一个“低成本的 code review 预检”每次提交前跑一遍能挡掉不少低级问题。两个命令加起来不过十几行却能让日常操作效率翻一倍都不止。3.5 写一个代码审查子代理如果我预期一个角色会被频繁、独立地调用比如代码审查光靠命令可能不够因为它只能处理当前传入的参数而子代理可以在一次会话里自主地读文件、搜索上下文、串联多个文件来分析。下面是我在.claude/agents/code-reviewer.md里写的一个简化版--- name: code-reviewer description: 资深代码审查专家适合对跨文件的改动做系统性审查尤其是重构和新增模块。关注正确性、架构一致性、安全性和性能。 tools: Read, Grep, Glob --- 你是一位拥有十年经验的资深代码审查专家你的工作方式很固定 1. 先读取用户指明的改动文件或通过 Grep 搜索最近改动的关键符号 2. 理解改动涉及的业务链路而不是只盯着单文件 3. 审查时按这个顺序排查 - 正确性有没有明显的逻辑漏洞、并发问题、边界未处理 - 一致性命名、分层、错误处理是否符合项目 CLAUDE.md 里的约定 - 安全性用户输入是否被正确校验有没有注入风险 - 性能有没有明显的 N1 查询、循环内重复调用等 4. 输出时按 blocker / major / minor / suggestion 分级列出问题每条附带文件路径和修复建议 你的职责是审查和报告不要直接修改代码也不要用命令行运行任何会改变状态的命令。注意我在tools里只给了读取和搜索类工具不给写入权限这是有意为之——审查者应该只做审查顺手改代码看起来贴心实际上会打乱主任务流。描述里也写清楚了适用场景主模型在遇到类似需求时会自动派给它不需要手动指定也能工作。3.6 验证效果用三个测试任务验收模板模板写完了不能直接“感觉差不多”就上线建议用三个测试任务验收。第一个测试任务是上下文加载验收打开一个新会话先不写任何任务直接问 AI“基于当前项目的模板你知道这个项目的技术栈和代码约定吗”。如果它能准确说出 Fastify、pnpm、统一返回结构说明 CLAUDE.md 加载成功。第二个测试任务是命令触发验收随便改一行代码然后敲/commit看它能不能正确生成符合格式的提交信息再敲/review看它能不能基于当前 diff 给出分级意见。第三个测试任务是子代理调度验收给它一个跨文件的审查任务看主模型是否会自动调用code-reviewer子代理的分析结果是否靠谱。这三关过了模板基本就站稳了。我自己的经验是别一次追求完美先搭建一个够用的版本用起来然后在真实工作流里不断迭代——你今天觉得别扭的地方往往就是模板需要改的地方。4. 实战中的坑模板不生效、上下文爆掉、团队同步难4.1 模板明明写了却不生效八成是这几个原因我遇到过太多“模板写了但 AI 像没看见”的情况排查了一圈其实原因就那么几个。最常见的是路径不对。老版本的项目习惯把CLAUDE.md放在根目录新版本推荐放在.claude/CLAUDE.md下如果你两个位置同时存在可能会产生加载冲突或覆盖混乱。建议项目里只保留一个位置我统一用.claude/CLAUDE.md。还有一个坑是模板文件没有进版本库别人 clone 下来后发现.gitignore把.claude目录忽略了导致团队里只有本机有配置。如果你是 Windows 环境还要注意命令文件扩展名必须是.md写成.MD或.markdown都可能不识别。排查的时候直接点开一个会话问它“你能看到 CLAUDE.md 的哪些内容”会比反复改文件盲猜高效得多。4.2 模板越写越长结果 AI 反而变笨了这是我最想强调的一个坑。Claude Code 每次启动会话时会把用户级和项目级的 CLAUDE.md 加载进上下文窗口这部分空间是常驻开销。我见过有人把 CLAUDE.md 写到四五千字恨不得把公司 wiki 都粘进去结果就是每轮对话都白白消耗大量 token而且重要信息被淹没在一堆“背景知识”里AI 反而抓不住重点。判断模板是否过长一个简单标准是如果 CLAUDE.md 占到总上下文一个很大的比例对话没几轮就开始“忘事”那就需要瘦身。瘦身的思路不是删内容而是分层把大部分细节移到命令或子代理里让它们按需加载只把最精炼、最高频使用的约定留在 CLAUDE.md。我自己的经验是项目级 CLAUDE.md 控制在 500 到 800 字之间全局级控制在 200 字以内剩下的细节全部下沉。字少了AI 反而记得更牢。4.3 命令冲突与优先级同名命令到底听谁的当一个命令名在多个位置存在时有一个优先级规则需要留意。Claude Code 里项目级.claude/commands下的命令会覆盖用户级~/.claude/commands下的同名命令。如果你在全局配了一个/commit项目里又配了一个/commit实际生效的是项目级那个。这个设计的本意是让项目有自主定制能力但也容易引发困惑。我建议全局只放通用性极强的命令比如/explain、/doc而把和项目强相关的命令都放项目级比如/deploy、/migration。这样冲突概率小也符合“全局管通用、项目管具体”的分层原则。4.4 团队模板同步把模板当成工程代码来管理最后说说团队协作。模板文件本质上是代码资产应该像代码一样被管理。我的习惯是把.claude目录纳入 Git 仓库在合并请求里走 review 流程模板改动也要有人 review、有变更记录而不是某个人私自在本地改完就完事。有一点值得注意不要把敏感信息写进模板。模板是会跟着仓库分发的数据库连接串、密钥、内部 API 地址这类信息绝对不要出现在 CLAUDE.md 里可以用环境变量占位符让 AI 从环境里读取。还要定期做“模板体检”隔几周让团队成员反馈哪些规则形同虚设哪些新约定还没补进去让模板跟着项目一起演进。模板不是写一次就一劳永逸的东西它是需要维护的活文档。5. 一些踩过坑之后总结出的心得模板这套东西用到现在我个人最强烈的感受是它本质上是在帮 AI“划定工作边界”。很多人以为模板写得越详细 AI 越能干实际恰恰相反模板的核心价值是让 AI 知道“这个项目里什么是对的、什么是错的、什么该做什么不该做”边界清晰了它才能真正发挥能力。我早期踩过的最大一个坑就是什么都想往 CLAUDE.md 里塞结果每轮对话都在为冗长的背景信息买单后来狠心砍到 600 字左右AI 的表现反而上了一个台阶。最后再分享一个我一直在用的小技巧模板里的规则一定要写成“可验证”的形式。比如“代码质量要好”这种话毫无意义改成“所有对外接口必须返回 { code, data, message } 结构”才是模板该有的样子——AI 可以对照检查人可以快速 review大家都不靠猜。这套方法不仅适用于 Claude Code也适用于你使用任何编程智能体的过程把隐式约定显式化、把高频动作用例化、把团队共识文档化效率的提升是实打实的。