Claude Code模板实战：用CLAUDE.md构建AI协作约定

如果你和我一样过去大半年把 Claude Code 当日常开发主力那你大概率遇到过这种场景每开一个新项目都得重新把项目背景、技术栈、代码规范、哪些事不能做跟 AI 从头到尾交代一遍一旦会话断开或者隔几天再继续它又把之前的约定忘得干干净净。我一开始也以为多写几句提示词就能解决直到把这一整套交代抽成可复用的模板也就是 claude-code-templates才算真正找到解法。这个项目本质上是一组 Claude Code 的配置模板集合CLAUDE.md、斜杠命令定义、hooks 脚本、按项目类型区分的规则包。它能解决的问题很具体——让 AI 在会话开始的第一秒就知道项目背景、代码风格、该做什么和不该做什么而不是靠你每次临时复制粘贴说明。适合三类人天天用 Claude Code 写代码的个人开发者想让团队统一 AI 协作方式的工程负责人以及刚接触这个工具、想少走弯路的初学者。接下来我会把这个项目从设计思路到实际落地完整拆开来讲。1. 为什么需要模板从日常重复交代到一次配置复用1.1 会话上下文丢失AI 编程助手的隐形瓶颈用过 Claude Code 的人应该都有这种感受单次会话里它理解力在线改动也利落。但一旦会话断开或者换一个新项目它就完全不记得你昨天说过的技术栈偏好、目录结构、命名规范。这不是模型能力的问题而是机制决定的每次会话启动时AI 能看到的项目上下文是有限的。它在里面找不到你想让它遵守的约定就只能基于通用经验猜测。猜测的结果就是代码风格飘忽不定昨天定好的架构规约今天换个会话又没了。这个问题的本质是工作记忆太短而人的期望是长期记忆。我们平时写代码时脑子里装着整个项目的历史决策、边界条件、模块之间的依赖关系AI 编程助手如果没有一个外部文件把这些信息固定下来那就只能靠你每次在对话里重新强调。一件事重复 20 次你自然想把它变成一份固化文档——这就是 claude-code-templates 最开始诞生的动机。1.2 模板解决的三个具体痛点我把用过的人反馈和自己踩过的坑汇总了一下模板化主要解决三个层面的问题。第一是上下文连续性问题。CLAUDE.md 这种机制相当于给 AI 一个开机自检清单它一旦被项目接住每次新会话都会主动加载不用你开口。单是这一点就能省掉大量重复描述。第二是协作风格一致性问题。团队里每个人用 AI 的方式都不一样有人喜欢让它先写测试再写实现有人习惯让它改完直接跑 lint还有人完全依赖 AI 重构但要求每个改动都解释。如果这些偏好没有写进统一的模板文件代码提交历史里就会出现风格撕裂这次提交是 TDD 留下的测试下次提交又是先写代码后补测试。模板把这些偏好固化等于给团队立了一个AI 协作公约。第三是新人上手成本问题。新同学 clone 一个仓库后打开 CLAUDE.md 就能看到项目背景、常用命令、目录陷阱比翻几十页 README 和人肉问答高效得多。我见过不少团队把 CLAUDE.md 当AI 版新人文档来用效果意外地好。2. 模板骨架拆解CLAUDE.md 之外还需要哪些关键文件2.1 一个典型模板仓库的文件结构很多人以为模板就是一份 CLAUDE.md其实完整的模板是一组文件的组合。我建议按下面这种结构组织claude-code-templates/ ├── README.md ├── CLAUDE.md ├── commands/ │ ├── review.md │ ├── commit.md │ └── test.md ├── hooks/ │ ├── pre-tool-use.sh │ └── post-tool-use.sh ├── project-types/ │ ├── web-frontend.CLAUDE.md │ ├── backend-service.CLAUDE.md │ └── cli-tool.CLAUDE.md └── shared/ ├── code-style.md └── security-practices.md这里每一层的职责是分开的CLAUDE.md入口文件把 shared 和 project-types 里的规则按需引用进来也可以直接写当前项目最核心的约定。commands/定义斜杠命令。比如/review代表帮我检查当前分支的改动输出问题清单/commit代表按团队约定格式生成提交信息。它让高频操作变成一条命令不用每次描述场景。hooks/Claude Code 的 hooks 机制可以在 AI 调用工具前后执行脚本。比如在写文件之前自动格式化或者在执行危险命令前弹出确认。project-types/按项目类型区分的规则包。Web 前端项目关注组件目录、状态管理、样式方案后端服务更多关注接口规范、数据库访问、错误处理。把这些拆开是为了避免一份模板里堆满互相冲突的规则。shared/跨项目通用的规则比如缩进风格、命名习惯、敏感信息处理方式。2.2 CLAUDE.md 的核心配置逻辑CLAUDE.md 这个文件名不是凭空起的它是 Claude Code 启动时自动读取的项目级说明文件。它的定位和 README 完全不同README 是给人类看的CLAUDE.md 是给 AI 看的任务简报。我在写模板时会把内容控制在几个固定板块。开头用两到三行说明这个项目是什么让 AI 立刻建立背景认知然后写技术栈和关键依赖避免它推荐一个项目里根本没有的框架接着写代码风格和目录约定这是最容易出分歧的地方最后写禁止事项和常用命令明确告诉它哪些事不要做、哪些操作可以直接执行。下面是一个简化示例# Project: user-auth-service ## 项目概述 - 基于 Node.js TypeScript 的用户认证服务 - 提供登录、注册、token 刷新、权限校验四个核心接口 ## 技术栈 - 运行时: Node.js 20 - 框架: Fastify - 数据库: PostgreSQL 15使用 Prisma ORM ## 代码风格 - 使用 TypeScript strict 模式 - 函数返回值必须显式标注类型 - 数据库查询通过 repository 层封装禁止在 controller 中直接调用 Prisma ## 目录约定 - src/routes: 路由定义 - src/controllers: 业务逻辑入口 - src/repositories: 数据库访问层 ## 常用命令 - pnpm dev: 启动开发服务 - pnpm lint: 跑 ESLint - pnpm test: 跑单元测试 ## 禁止事项 - 不要修改已有数据库迁移文件 - 不要在请求处理路径中使用 any 类型 - 不要引入未在 package.json 中声明的依赖这个模板看起来不复杂但它把 AI 最容易跑偏的几个点全钉死了。实际使用中我发现只要 CLAUDE.md 里写清楚了禁止事项AI 在动手改代码时就会明显更收敛不再是自由发挥的状态。2.3 斜杠命令把高频操作封装成一句指令斜杠命令是模板里回报率很高的一个组件。它的本质是预设好的 prompt 模板把它放在commands/目录下Claude Code 就能在对话中输入/review来触发。比如commands/review.md可以写成你是一名资深的代码审查者。请按以下步骤检查当前分支的改动 1. 先列出本次改动的文件清单和diff统计 2. 逐文件检查重点关注: - 是否存在未处理的错误分支 - 是否引入类型安全隐患 - 是否遵循项目 CLAUDE.md 中定义的代码风格 3. 输出审查报告包含: - 问题清单按严重程度排序 - 每个问题的文件位置和建议修复方式 4. 如果改动涉及测试文件请额外检查测试覆盖是否充分 注意: 只提出问题不要直接修改代码。有了这个文件团队里任何人都能一键触发结构化的代码审查不用自己组织提示词。而且它天然和 CLAUDE.md 联动——审查规则里写明了要参考项目约定AI 执行时会把两份文件都读进去。2.4 全局规则与项目级规则的边界模板里最容易犯的错是想把所有东西都塞进一份文件。实际上规则应该分层全局规则放~/.claude/CLAUDE.md只写所有项目都适用的内容比如通用编码风格、敏感信息处理、禁用不安全操作项目级规则放仓库内的 CLAUDE.md写这个项目特有的约定。为什么这么分因为全局规则一旦写得太多会稀释 AI 的注意力。想象一个人同时被十条跨项目规则和二十条项目规则夹击他大概率会优先处理最新、最具体的指示然后把那些放之四海而准的废话忽略掉。AI 也有类似的行为倾向。我在早期版本里把使用语义化提交信息这种通用规则写进了每个项目模板后来发现它对某个本来就没打算按 SemVer 发版的项目造成了困扰——AI 频繁要求我把版本号升上去。把它移到全局规则后这个问题就消失了。3. 从零搭建一套可复用的 Claude Code 模板3.1 先想清楚服务哪类项目搭建模板前第一件事不是写文件而是确定模板的服务范围。你可以问自己三个问题。第一个问题我日常最多接触的项目类型是什么如果你的主力是前端开发却花大量精力写后端规则模板那收益就有限。我在 claude-code-templates 里拆了三个初版类型web-frontend、backend-service、cli-tool这基本覆盖了我平时工作的全部场景。第二个问题哪些规则是反复吃过的亏比如我曾经在一个 TypeScript 项目里被 AI 连续三次引入ts-ignore注释来绕过类型检查。这就是一条值得写进禁止事项的规则——因为它反复发生说明默认行为就是会往这个方向跑。第三个问题哪些环节最需要 AI 的创造力哪些环节最需要约束模板不是越严越好。如果你所有代码都要求 AI 严格按某种模板生成它发挥空间就小改起来反而别扭。我自己的经验是目录结构和命名规范要严算法实现和代码组织方式要给自由度。3.2 编写第一版模板的具体步骤定好范围后我建议按下面四步写第一版不要一上来就追求大而全。第一步写项目概述。两百字以内说明这个项目干什么、技术栈是什么、主要模块有哪些。这一段是给 AI 建立背景认知的不需要写细节。第二步写禁止事项。这是收益最高的一步。把你在过往会话里反复纠正 AI 的事情列出来比如不要在 reducer 里写副作用不要修改公共 API 的返回结构不要使用已废弃的 SDK 方法。禁止事项写得越具体AI 的判断越稳定。第三步写目录结构和常用命令。如果你在一个 monorepo 里这一步尤其重要否则 AI 经常不知道该在哪个 package 下创建文件。常用命令最好带一句说明比如pnpm dev是启动本地开发服务pnpm build是打包产物验证。第四步写斜杠命令和 hooks。先挑最高频的一两个操作比如/review和/commit用之前提到的格式写好。hooks 也可以从最简单的开始这里有一个 bash 脚本示例作用是让 AI 在修改文件后自动跑格式化#!/bin/bash # hooks/pre-tool-use.sh # 在 AI 执行 Write 工具前触发自动对目标文件做格式校验 target_file$1 if [[ $target_file *.ts || $target_file *.tsx ]]; then pnpm exec eslint --fix $target_file --quiet /dev/null 21 if [[ $? -ne 0 ]]; then echo WARNING: ESLint found issues in $target_file. Please fix them before committing. fi fi exit 0这个脚本不会直接拦截 AI 的行为而是给它一个格式问题的反馈信号。实际用下来比在 CLAUDE.md 里写十句注意代码格式更管用。3.3 模板的验证与迭代别写完就以为结束了好多人的模板写完就丢仓库里吃灰这是最大的浪费。模板是需要持续迭代的我建议每两周做一次模板回顾把最近两周和 AI 协作过程中反复纠正过的问题对照模板看是否已经覆盖如果发现 AI 频繁违反某条规则要么是规则没写清楚要么是规则写得不够具体。我自己给 claude-code-templates 做过一个简单的验证办法拿模板开一个新项目然后用同一个任务分别测试有模板和无模板两种情况。比如让 AI 实现一个带鉴权的 REST API对比它的第一次输出质量。有模板时它大概率会直接按项目目录约定创建文件、按既定风格写代码无模板时它可能先跟你确认一堆技术选型甚至直接用一个你没提到的框架。这个对比非常直观也是我说服团队引入模板的常用手段。4. 按项目类型切换模板大型工程、脚本工具与团队协作场景4.1 大型代码库模板约束要强规则要细大型代码库的模板关键词是强约束。原因很简单代码库越大AI 可选的实现路径越多越容易走偏。比如一个前端 monorepo可能包含多个应用和共享组件库如果模板不写清楚公共组件放哪个包、样式变量在哪定义、状态请求走哪个封装AI 完全可能随手新建一个目录放共享逻辑导致后续维护成本飙升。我在 web-frontend 模板里会专门加一个模块归属板块## 模块归属 - 所有 UI 组件按业务域放在 apps/admin、apps/portal 下的 components 目录 - 跨应用共享的组件放入 packages/ui禁止在 app 内部直接创建共享组件目录 - API 请求统一封装在 packages/api/src/endpoints 下按服务划分文件这种规则比注意代码组织结构这种空话有效得多。它给了明确的操作边界AI 不用猜。另一个大库场景的服务端项目模板我会额外强调数据库访问规则和错误处理规范因为它们出问题的成本最高。4.2 小型脚本和一次性任务模板给 AI 留足自由度和大型工程相反小工具、脚本类项目的模板要轻。你写一个数据迁移脚本、一个日志分析工具、一个 mock 服务根本不需要二十条规则。这类项目的特点是生命周期短、结构简单、AI 的临时判断通常足够好。在小项目模板里我只保留四样东西项目一句话说明、运行方式、依赖约束、禁止暴力操作比如不要直接操作生产环境数据。斜杠命令也可以精简留一个/commit和/explain就够了。多余的规则只会拖慢 AI 的响应速度让它花时间读那些和当前任务无关的条款。4.3 团队共享模板约定比工具更重要如果模板要在团队里共享重点就不再是文件内容本身而是怎么维护和怎么达成共识。首先是维护方式。我见过最顺畅的做法是模板仓库单独建一个 git 仓库每次改动走 PR 评审。改 CLAUDE.md 和我们改代码是一个流程这样才能确保每一步变更被记录和讨论过。没有评审机制的模板很容易变成某个人的私有偏好集合别人用起来很别扭。然后是迭代节奏。建议每个迭代结束时团队用五分钟回顾这个迭代里 AI 帮我们干活时有哪些地方明显不舒服。把这些问题提到模板评审里看是不是规则盲区。这个习惯坚持三个月模板就从一个空壳长成团队的协作知识库了。最后是冲突处理。多个人用模板时一定会有对 AI 行为的不同期望。比如有人希望 AI 写注释有人认为代码自解释不需要注释。这种分歧不该靠模板里的某一方压制另一方更好的方式是把注释规则细化成场景对外暴露的 API 需要注释内部实现不强制。把分歧转化为可操作的场景规则是模板设计里比技术更微妙的部分。5. 实战中踩过的坑与对应的调整策略5.1 指令太长反而失焦模板也有边际效应递减我刚开始搞 claude-code-templates 时有个版本写了将近两百行覆盖了从代码风格到提交信息格式的所有细节。结果毫不意外AI 开始在对话里频繁地读规则而不是写代码响应速度明显变慢而且有些规则之间开始互相打架。那些放在后面的规则经常被忽略因为它们和前文某条规则存在轻微的语义重叠。后来我做了减负把模板压到 80 行以内每条规则必须满足具体、可判断、不与其他规则重叠三个条件。凡是感觉模糊的规则一律删掉以后真踩坑再加回来。事实证明这个策略是对的精简后 AI 的正确率反而上升了。模板不是写越多越好它是写的每一条都应该在关键时刻拦得住错。5.2 规则冲突的优先级处理全局和项目级叠加时怎么办全局 CLAUDE.md 和项目级 CLAUDE.md 会被同时加载一旦说互相冲突的话AI 的表现就会像两个老板给了相反指令的下属。我之前遇到过一个案例全局规则写所有代码必须使用函数式编程风格而某个项目模板里写在这个模块中允许使用类因为现有代码大量使用类承载状态。结果 AI 在生成代码时一会儿遵循项目模板用类一会儿又切回全局规则改用函数行为非常不稳定。解决方式很直接明确优先级。我的模板里固定加一条说明——项目级 CLAUDE.md 优先于全局规则发生冲突时以项目级为准。同时在全局模板里少写那些容易和具体项目冲突的风格偏好把函数式还是类这种判断留给项目模板决定。经过这个调整AI 的决策稳定度提高了不少。5.3 模板的版本管理与回滚把模板当代码管模板文件本质上是代码的元代码它影响 AI 如何生成代码所以它本身也该走版本管理。我维护 claude-code-templates 时给模板仓库加了 tag 和 changelog。每次改模板都必须写清楚为什么改是因为某次会话里 AI 反复出错还是因为项目结构发生了变化回滚场景也很实际。有一次我给某个项目模板加了自动生成 README 更新内容的规则结果 AI 在每次改动代码后都去大改 README产生了大量无意义 diff。我回滚到上一个 tag 后马上恢复了正常。如果不做版本管理这种问题只能靠人肉回忆之前模板的内容再手改回去效率极低。5.4 别把模板写成束缚给 AI 留出合理的判断空间最后一个坑也是我把这篇笔记写到这里的最大心得模板的边界一定要画得清楚。模板是给 AI 一个工作约定不是一份行为实现手册。如果把所有事都规定死AI 会变成一台只会执行指令的机器遇到模棱两可的场景反而不愿意做决定动不动就停下来问你请确认是否允许我这样做。这种体验让我一度觉得模板是负担。后来我在模板里加了一句软性规则遇到模板未覆盖的场景根据项目背景做出合理默认选择并在汇报中说明你做了什么假设。这句看起来不起眼的规则从根本上改变了协作节奏。AI 不再频繁请示而是主动做决定并附带说明我只需在 review 时留意那些假设。合理设置默认行为和异常上报机制才是模板真正顺手的形态。6. 一些实际操作中的体会6.1 hook 脚本作为模板的延伸Claude Code 模板的边界实际上比 CLAUDE.md 大很多。hooks 机制可以把很多预设动作变成自动化流程。我目前在模板里内置了三个 hooks修改文件后跑格式化、执行测试前检查是否安装了依赖、记录每次命令执行结果到日志文件。前两个直接改善了代码质量第三个则为我做模板回顾提供了数据支撑。6.2 模板的最佳复现方式菜谱而非合同如果你要为某个项目定制模板最好先别急着参考别人的完整配置而是自己动手从最小版本开始。最理想的模板应该像一份菜谱食材项目背景和约束、步骤命令和流程、禁忌不能做的事都清清楚楚但具体怎么炒留给 AI 自己发挥。从这个意义上讲模板是辅助工具不是管理手段。我也希望大家拿到 claude-code-templates 后不是原样复制我的项目而是把它当一份自查清单项目背景写得够不够清楚禁止事项能不能覆盖到你最常踩的坑目录约定是否具体到 AI 不需要猜这些问题答完了你的模板才真正算你自己的东西。