claude-code 现在已经是不少人的日常开发伙伴了但很多人用它的方式其实很有问题——打开终端问一个问题得到答案完事。这样用不是不行只是 claude-code 的能力完全没被释放出来。我之前在建完成了好几个小工具和内部系统之后慢慢意识到一件事真正让 claude-code 从聊天机器人变成项目协作者的关键不是它本身有多聪明而是你喂给它的上下文和约束有多清晰。这个 claude-code-templates 项目就是把这些上下文固化成模板放在项目的 CLAUDE.md 里让每次会话都在同一套规则下工作。这篇东西是我基于自己折腾小半年的经验整理出来的适合所有在用 claude-code 或类似 AI 编程助手的开发者里面讲的东西可以直接抄。1. 为什么要给 claude-code 做模板1.1 claude-code 的原生问题每一分钟都在重新开始很多人第一次用 claude-code 的体验是这样的在项目目录下输入claude它确实能读你的代码也能理解你的问题但每次你说完需求它给出来的代码风格、命名习惯、对测试的态度跟你自己写的对不上。最头疼的是同一个问题换个说法问它它可能给出两种完全不同的方案。这不是 claude-code 笨也不是模型能力不够。问题在于 claude-code 虽然是编码助手但它仍然是无状态的——每次会话开始它对你的项目应该怎么写只有通用认知没有项目专属认知。它不知道你的团队习惯在函数名前面加get还是fetch不知道你把数据库连接统一放在哪个目录更不知道你之前已经踩过某个第三方 SDK 的坑。这就好比你招了一个能力很强的外包但他第一周上班什么都要重新讲一遍第二周你讲烦了他也做不对。模板的作用就在这儿把重新讲一遍的内容固化下来写进项目根目录的 CLAUDE.md让 claude-code 每次启动都自动加载这些规则。它不是让 claude-code 变得更聪明而是让它把精力集中在真正需要思考的问题上而不是反复猜你的偏好。1.2 没有模板的时候工作流低效在哪里我实测下来没有模板的工作流大致是这种节奏先跟 claude-code 说帮我看一下这段代码有没有问题它看完给你反馈你再补充这是个 React 项目你按函数组件的写法来改它改了然后你再提醒测试不要用 mock 库我们统一用 vitest它又调整一轮。一个下午下来光是在对齐规则上就花了一半时间。最典型的是代码风格不一致的问题。比如有个项目里既有 4 空格缩进的老代码也有 2 空格缩进的新代码claude-code 在修改老文件时经常自作主张把整个文件重新格式化结果是它觉得自己顺手整理了一下在你的 code review 里却成了一堆噪音。还有依赖管理它在不确定某个库是否已经安装的时候会直接在 package.json 里塞一个它认为应该可以的版本往往跟项目里实际用的版本冲突。我自己统计过在没有写 CLAUDE.md 的项目里claude-code 生成的代码有三成左右需要人工调整风格或架构位置写了模板之后这个比例降到一成左右。这个对比非常明显模板的投入产出比极高写一份项目通用的规则文件可能只需要小半天但之后每一次会话都在受益。1.3 这个模板适合给谁用如果你只是偶尔拿 claude-code 补一段正则表达式或者让它解释某个报错那模板的价值确实不大CLAUDE.md 对这种轻量使用反而显得啰嗦。但如果你满足下面任一条件模板基本就是刚需你把 claude-code 用在真实项目上而且不是一次性的修改而是连续几周、几个迭代的开发你有团队协作的需求希望每个人用 claude-code 时输出的代码风格没有太大差异你反复在做同一类项目比如 Vue 后台、Python 数据处理、Node 脚本发现每次都是从零跟它解释项目结构你遇到过它的错误决策比如误删了不该删的代码、改了不该改的配置想通过规则把它拦在门外。我知道有些人听到写模板第一反应是又要搞一套流程文档觉得很重。但 claude-code 的这个模板其实非常轻它就是一个 Markdown 文件你完全可以在某个项目里先写三五行试试觉得有用了再加内容。它不是一次性交付的全量方案而是一个可以逐周迭代的活文档。2. 模板体系怎么搭整体设计思路2.1 三层结构全局、项目、任务我给模板体系定的设计原则是分三层各管各的。这个想法借鉴了编程里的分层职责避免所有东西都塞在一个大文件里到后面连自己都懒得看。第一层是全局偏好层。存放在用户机器上的约 ~/.claude/CLAUDE.md这一层写的是你个人的通用编码偏好——比如你写 Python 时习惯用 type hints写前端时坚持函数组件不用 class 组件希望 claude-code 在改动代码之前先展示 diff。这些规则跟具体项目无关是你这个人的偏好。用 claude-code 的时候它会自动读取这个全局文件所以任何项目打开都带着你的个人基线。第二层是项目约束层。存放在各项目根目录的 CLAUDE.md这一层写的是当前项目的特殊性——技术栈、目录结构、命令、架构约定、禁止事项。这是模板体系里最核心的一层因为项目特殊性正是 claude-code 最容易忽略的部分。比如某个项目虽然用了 webpack 但希望你别动这项配置某个服务必须走特定的 header 鉴权这类信息必须放在项目级文件里全局文件不应该知道也不应该管这些。第三层是任务指令层。当你需要处理某个特定任务时比如做一次代码评审、迁移一个旧模块、修一个棘手的 bug你可以在会话里用--append或直接在对话中附上本次任务的约束。这一层不适合放到前两层因为它是临时的、一次性的写进全局和项目文件反而会污染长期规则。这个分层的好处是权责清晰。全局层稳定不动项目层随项目演进任务层用完即走。我在实践中最怕遇到的情况就是大家把这三个层级混在一起比如把个人偏好写进项目的 CLAUDE.md导致换个人来协作时一堆规则对他并不适用反而干扰判断。2.2 模板仓库的目录怎么组织因为 claude-code 的模板最终要落到 CLAUDE.md 里所以一个专门维护模板内容的仓库目录设计要按场景来分而不是按语言或框架来分。我见过有人按 JavaScript、Python、Go 这样分目录结果一份前后端项目模板要拆到好几个文件里维护成本高复制也不方便。更实用的组织方式是按项目类型来组织。比如我的模板仓库长这样claude-code-templates/ ├── README.md ├── web-frontend/ │ ├── CLAUDE.md │ ├── react-vite.md │ └── vue-element.md ├── backend-api/ │ ├── CLAUDE.md │ ├── node-express.md │ └── python-fastapi.md ├──># 项目claude-code-templates ## 项目概览 这是一个维护 claude-code 项目模板的仓库。 技术栈JavaScript、Node.js、Markdown。 主要用途为不同项目场景生成 CLAUDE.md 模板。 ## 常用命令 - 安装依赖npm install - 运行测试npm test - 类型检查npx tsc --noEmit ## 代码风格 - 使用 2 空格缩进不使用分号。 - async/await 优先避免 .then 链。 - 变量名使用 camelCase常量使用 SCREAMING_SNAKE_CASE。 - 所有公共函数写 JSDoc 注释。 ## 架构约定 - 模板内容按场景目录存放避免跨场景耦合。 - 模板中的占位符统一用 {{项目名称}} 风格便于替换。 - 新增模板时先检查是否与已有模板存在内容重叠。 ## 禁止事项 - 不要修改 README.md 中的项目介绍部分。 - 不要引入额外的构建工具。 - 不要在模板仓库中放真实项目的敏感配置。 ## 版本记录 - 2025-03初始模板。这份模板看着挺简单的但它已经把项目概览、命令、风格、架构、红线、版本六个维度的信息都覆盖了。claude-code 有了这些信息之后它知道你项目是干嘛的知道测试要跑哪个命令知道代码写成什么样算合格也知道哪些事碰不得。这些信息在没有任何模板时是需要你在无数个对话里反复人工强调的。3.2 逐段拆解模板的每个部分先说说项目概览这一段。很多人觉得 claude-code 自己能读代码为什么还要在模板里写项目简介我的经验是虽然它能读代码但它判断项目性质的方式是扫描依赖和目录结构这个过程不总是准确。你直接在模板里写清楚这是干什么的、用什么技术栈它就能更快地理解整个项目的上下文不会出现把 Node 项目当成纯前端项目来给建议的情况。常用命令这段的价值在于减少它瞎猜。没有命令信息时claude-code 在需要跑测试的时候可能会自己猜那应该是 npm test 吧运气好能猜对但像某些项目测试命令是pnpm test:unit这样的它就完全猜不到。在命令缺失的情况下它甚至会尝试安装一个新的测试框架来帮你运行测试这种行为在真实项目里后果是灾难性的。把命令写进模板之后它便不会去猜也不会去安装无关依赖。代码风格是模板里最直接影响生成结果的部分。claude-code 默认的代码风格接近市面上常见项目的平均风格但它不知道你自己的偏好。比如我一份代码里习惯不用分号但 claude-code 每次补全都会在行尾加分号看起来非常别扭。在模板里明确声明不使用分号之后这个问题立刻解决。风格规则要写得具体像代码要清晰这种话等于没说变量命名用 camelCase这类的才有约束力。架构约定这段是给 claude-code 的地图。一个大型项目里claude-code 常常会迷茫在哪里放新代码、该遵循什么模式。模板里写明复用的组件放在 src/components/ 下页面文件放在 src/pages/ 下它生成的新代码就会自动落到正确的位置而不是突然在根目录新建一个文件。项目结构越复杂这一段的价值就越明显。禁止事项是最能防止事故的内容。claude-code 的主动性有时候是灾难的根源——它可能看到某个代码冗余就主动删除看到配置不合理就自动修改。这类行为在你不注意的时候可能已经改变了项目的关键逻辑。模板里用一条不要修改 xxx的规则就能把这类事故挡在发生之前。红线规则一定要写得小而明确不要写不要做出不合理的修改这种它无法判断的话。3.3 验证模板有没有生效写完模板之后需要验证它确实被 claude-code 读到并且发挥作用这个过程不能省。虽然 claude-code 正常情况下会自动加载 CLAUDE.md但还是建议手动确认特别是第一次写模板或者修改了文件名的时候。最简单的验证方式是在项目目录下启动 claude-code然后问它根据项目的 CLAUDE.md我这个项目的测试命令是什么 如果它引用文件并正确回答npm test说明加载链路没问题。如果回答我看一下项目的 package.json 再告诉你说明文件没有加载成功这时检查文件名、所在目录和 claude-code 的启动位置。第二个验证方式是让它做一次小任务观察它是否遵守了模板里的风格约束。比如故意让它补全一个函数如果它主动使用了 JSDoc、保持了 2 空格缩进、没有加分号那这些规则就真的生效了。如果它写出来的代码跟模板要求的不一致可能是模板里的措辞不够强比如写了尽量、可以这类含混词需要改成必须使用这样的强指令。我踩过一个教训模板里写了尽可能避免使用 any 类型结果 claude-code 还是时不时用 any因为它认为类型定义太复杂、用 any 是合理的权衡。改成禁止使用 any 类型除非有理由并在注释中说明之后行为就明显收敛了。这里面有个原理AI 编程助手对避免这类弱约束的重视程度远低于禁止这类强约束所以写规则的时候该硬的地方一定要硬。4. 场景化模板示例从通用到专项4.1 前端项目模板前端项目是 claude-code 最常用的场景之一但也是模板需求最复杂的场景。因为前端项目的技术栈组合很多React、Vue、Angular 各有各的写法构建工具又有 Vite、Webpack、Next.js 的差异。通用模板里写的规则到了具体的前端项目里往往不够用。我常用的前端模板里除了通用规则外还会追加这样几条## 前端项目特定规范 - 组件统一使用函数组件 Hooks禁止使用 class 组件。 - 全局状态统一使用 zustand不要引入 Redux。 - 样式方案Tailwind CSS禁止引入 CSS Modules。 - 路由配置统一放在 src/router/index.ts不要在页面内自定义路由跳转逻辑。 - 组件文件命名采用 PascalCase样式类名采用 kebab-case。 - 运行代码检查npm run lint -- --fix提交前必须执行为什么这些规则必须在模板里明确举个例子一个本来用 zustand 的小项目claude-code 在一个状态管理场景里可能直接生成一段 Redux 代码因为 Redux 在它的训练数据里最经典它默认成熟方案比轻量方案更稳妥。可实际上你的项目根本不需要也没打算引入 Redux。模板里的这条规则既防止它引入新依赖也避免项目里同时出现两套状态管理模式。样式方案也是容易出分歧的地方。Tailwind 和 CSS Modules 都在用claude-code 如果看到项目里有几个 .module.css 文件可能沿用这个模式也可能根据你一句加个样式就在 Tailwind 的写法上即兴发挥。在模板里把方案定死它是不会私自开新路线的。4.2 后端 API 项目模板后端项目的重点不在代码风格而在架构边界和数据安全。claude-code 在后端项目里最危险的时刻是它主动造轮子——自己实现一段认证逻辑、自己封装数据库操作而不是复用项目已有的公共模块。我的后端模板通常会包含这些约束## 后端项目特定规范 - 所有数据库访问必须通过 repository 层禁止在控制器中直接操作数据库。 - 鉴权统一走 authMiddleware新接口禁止写内联的 token 校验逻辑。 - API 响应格式统一为 { code, message, data }禁止直接返回原始数据。 - 新增依赖必须先检查 package.json 是否已有对应能力否则需说明理由。 - 不要打印完整请求体或响应体日志避免敏感信息泄漏。 - 所有接口必须有入参校验禁止信任前端传入值。这里最值得讨论的是禁止在控制器中直接操作数据库这条。从模板角度来说它是架构层面的约束不是语法层面的约束。claude-code 只看一段代码的语法正确性判断不出这句话写在 controller 里是不是分层错误只有明确的规则能拦住它。没有这个规则时我确实见它生成过把数据库查询直接写在路由回调里的代码功能是能跑但后续要改事务、加缓存就非常困难。日志与安全相关的内容也要提前写死。claude-code 为了帮你调试可能会在代码里加 console.log 打印完整参数对象这在开发环境还好但很容易被一起提交到生产代码里。模板里明确禁止打印完整请求体这类代码就不会出现了。4.3 测试与重构模板测试场景的模板跟日常开发不太一样它更多是任务型的。因为写测试的时候claude-code 需要理解的是项目的测试策略比如某些模块已经覆盖率很高不需要重测某些极端边界是需要重点覆盖的。测试模板的示例## 测试任务规则 - 单元测试文件与被测文件放在同一目录下命名为 *.test.ts。 - 只使用 vitest 作为测试框架不要引入 jest。 - Mock 原则优先 mock 网络请求不要 mock 被测函数内部实现细节。 - 测试应描述行为而非实现测试 add 函数输出而不是测试 add 函数内部调用了 binarySearch。 - 新测试跑通后运行 npm test 确保全量通过不要只跑单个文件。这种模板最直接的价值是避免 claude-code 在测试里使用过度 mock。它生成单元测试时有个坏习惯喜欢把被测模块内部的依赖函数全部 mock 掉导致测试跑通但完全失效——你改了函数内部逻辑测试还是通过等于没测。模板里写明不要 mock 内部实现细节生成的测试就耐看多了。重构类模板则更强调步骤和验证。claude-code 做重构时容易一次改动太多你很难评审。我一般会在模板里限定重构步骤每次只重构一个函数完成后运行类型检查和测试确认通过后再继续下一项。 这能让整个重构过程变得可追踪出问题也能快速定位到是哪一步引入的。5. 常见问题与排查技巧实录5.1 模板写了却不生效这是我最常被问到的问题而且大多数时候原因都很简单。首先检查文件名必须是 CLAUDE.md大小写都对不能是 CLAUDE.txt。其次检查位置它必须在当前会话启动目录下。如果你在项目根目录启动了 claude-code但 CLAUDE.md 放在 src/ 里那是不会被加载的。还有一种隐蔽的情况如果你用了全局目录比如 ~/.claude/CLAUDE.md 和项目目录的 CLAUDE.md 同时存在项目目录的规则会叠加到全局规则之上而不是替换。如果全局规则跟项目规则内容冲突以哪个为准实测下来项目级声明往往更具针对性但最稳妥的做法还是避免在两个层级写互相矛盾的规则。我自己会定期全局检查一遍全局 CLAUDE.md把已经过时或者跟所有项目都冲突的内容清理掉。另外CLAUDE.md 的改动不需要重启任何服务但如果你当前正在一个长时间会话里它可能不会重新扫描文件。遇到这种情况直接退出会话重新启动 claude-code规则就会重新加载了。5.2 规则冲突了怎么办规则冲突一般发生在三层模板合并的时候。最常见的冲突是全局说统一使用 4 空格缩进项目模板说统一使用 2 空格缩进claude-code 不知道听谁的。我的处理原则是项目规则优先于全局规则。因为全局规则服务于你这个人的通用偏好而项目规则服务于这个项目的实际需要项目代码长期保持一致性比你的个人偏好更重要。但 claude-code 本身不一定总是这样裁决所以更保险的做法是项目模板里显式写一句本项目使用 2 空格缩进此规则优先于全局配置。这样明确声明之后就基本没有歧义了。如果发现它还是用了旧规则可能是全局文件里的措辞太强比如写了必须始终使用 4 空格可以同步改弱全局文件的语气把必须改成默认。还有一类规则冲突是模板里自相矛盾。比如某条说禁止使用 any另一条又说第三方库缺失类型时可以直接使用 any。这种矛盾会让 claude-code 选择困难通常在生成代码时会优先执行更具体的规则但有时候也会犹豫。所以写模板要避免把特殊情况写进去特殊情况用任务层的临时指令去处理不要长期放在模板里制造冲突。5.3 模板越写越肥怎么办模板刚建立的时候大家都喜欢往里加内容今天加一条规则明天加一条约束几周之后就变成一个几十 KB 的大文件。这时候 claude-code 的表现反而变差因为有用的规则被淹没在大量重复的、低价值的文本里了。它处理长上下文时注意力是会被稀释的。我给自己的原则是超过 150 行之后就必须做减法。操作方法很简单把模板里所有规则过一遍标出哪些在过去两周会话里确实让 claude-code 改进了行为的留着那些写上去之后从来没观察到它违反过的删掉或者至少降级为注释。不是每条规则都有必要让 claude-code 遵守有些规则只是你自己心理安慰它们并不会被违反也就不需要占用上下文空间。另外一个思路把对 AI 的规则和给人看的说明分开。CLAUDE.md 只放对 claude-code 行为的约束项目背景介绍这些给团队成员看的信息放在 README 里不要让模板文件承担文档职责。模板文件越聚焦效率越高。5.4 模板要不要进版本控制要而且必须在版本控制里。claude-code 的模板直接决定代码提交质量它本身就是一种项目资产。但这里有一个隐藏的坑如果你在模板里写了本地的绝对路径、团队成员的个人信息或者本地数据库连接串这些内容进 Git 仓库会产生风险。我的处理方式是在模板里只放占位符比如项目根目录位于 {{项目根目录路径}}具体路径等团队成员克隆到本地后自行替换。其实大部分内容不需要占位符——技术栈、命令、代码风格都是通用的只有极少数配置才涉及个人环境差异。模板进版本控制之后模板的变更历史天然就是一份团队 AI 协作规范的演进记录哪个迭代我们开始强制 lint、哪个项目我们决定不用 Redux都看得清清楚楚比口头通知靠谱得多。团队协作时还要注意模板更新要跟成员沟通。我自己遇到过一次在 CI 重命名之后更新了模板里的运行命令但另一个同事的本地分支还跑着旧模板他让 claude-code 根据旧命令跑 CI结果 claude-code 反复报错。这时候不用慌把这个分支的 CLAUDE.md 拉到最新版就能解决。团队里同一仓库的 CLAUDE.md 有版本差异是常态合并分支时注意处理这个文件就好。5.5 一些执行层面的细节经验最后分享几个我在大量使用中总结的执行细节这些不是模板语法问题但直接影响使用体验。第一CLAUDE.md 文件的编码要用 UTF-8特别是要写中文注释或规则说明时。我之前在一个 Windows 环境下的项目模板里写过中文规则因为文件保存成了 GBK 编码claude-code 读出来的是一些乱码规则自然就失效了。现在我的所有模板都强制用 UTF-8 保存问题再没出现过。第二模板里的命令要放到对应的「场景」里。比如项目里大多数人都在用 Bun 而不是 npm那模板里所有的命令都写bun install、bun test不要写 npm。claude-code 有个倾向是使用最常见的包管理器如果模板里不写清楚它很可能在用了 bun 的项目里生成 npm 命令虽然也能跑但会额外引入一个 lockfile造成冲突。第三别忽视禁止事项的威力。我发现很多人写 CLAUDE.md 时只写正面规则比如应该怎么做很少写负面清单。但 claude-code 出错时基本都是越界而不是做得不够。所以每次它做了一件你不希望它做的事别急着改代码先想想能不能把这件事写进禁止项里。用这样的方式迭代模板模板的进化速度会非常快因为每一版都是基于真实事故修正出来的。基于我自己的实操经验claude-code 的价值真的在模板之外已经被定了一大半我见过太多人把时间浪费在和它重复解释项目背景上。如果你也正在用 claude-code我真建议你从今天起花二十分钟列一个最简 CLAUDE.md只写项目路径、常用命令和三条红线然后跑一周看看差异。体验过它第一次就知道你的规矩之后你就再也回不去那种从零解释的开发方式了。