在 claude code 中自定义指令模板

上个月，有个前端团队的Tech Lead在深夜给我发消息：“我把ESLint规则写进了CLAUDE.md，结果Claude Code连续三次生成代码都忽略了no-console规则，第四次我在对话里吼了一句‘不许用console.log’，它才改过来。这指令模板到底他妈管不管用？”

我看完他的CLAUDE.md，问题很明确：他写的是“请帮我的项目写代码”，没写“你在这个项目里的角色边界是什么”。

这就是这篇文章要解决的核心问题：大多数人在 Claude Code 里用的“指令模板”，本质上和发短信没什么区别，告诉模型你要什么，却没告诉模型你是谁、你的底线在哪、你希望什么事情必须先问过你再动手。

CLAUDE.md 的核心价值不在于“给模型下指令”，而在于建立人机协作的项目级共识。

过去三个月，我和5个技术团队在CLAUDE.md的指令设计上踩了足够多的坑，验证了多条反直觉的规律。这篇文章不会教你怎么创建文件，那种基础操作大多数开发者做完一遍就忘了。我会讲的是：在你真正投入使用三个月后，什么指令会失效、什么指令会让模型变“笨”、什么指令能真正让Claude Code从“执行者”变成“协作者”。

一、先把结论摆在这

在写指令模板之前，你需要接受三个反直觉的事实：

事实一：指令越具体，模型越容易在边缘场景失败。 很多人把CLAUDE.md写成了20页的需求文档，精确描述每一个输出格式。实测结果是：遇到文档未覆盖的场景时，Claude Code的自我纠错能力反而下降，因为它被训练成“严格按照约束来”，而不是“根据第一性原则判断”。这是Anthropic官方研究团队在Constitutional AI相关论文中反复强调过的规律：过约束会导致模型放弃推理。

事实二：CLAUDE.md中写“禁止事项”比“必须事项”更稳定。 在我们的测试中，用“你不应该直接修改已有的接口签名”替代“修改接口前必须先和我确认”，前者的遵守率高出23个百分点（测试场景：5个项目，各100次指令，统计接口修改正确率）。原因很简单：否定指令留给模型的推理空间更大，模型可以判断各种“看起来像修改接口”的行为模式，而肯定指令容易让模型落入“路径依赖”。

事实三：CLAUDE.md需要随着项目阶段演化，静态模板在Sprint 5之后一定会失效。 早期项目（Sprint 1-3）适合约束行为模式（“先问再做”）；中期项目（Sprint 4-8）适合约束架构边界（“不许碰infrastructure层”）；后期项目（Sprint 8+）适合约束变更安全（“任何涉及鉴权的改动必须先读JWT相关代码”）。三套模板不可混用。我见过最典型的失败案例是：项目都快上线了，CLAUDE.md还在写“请先确认技术方案”，导致Claude Code每次生成代码前都发一堆确认问题，严重影响效率。

二、CLAUDE.md到底是什么，一个被误解的“配置文件”

要理解指令模板为什么经常失效，必须回到最早对CLAUDE.md的设计意图。这不是一个“提示词文件”，它是一个项目级别的配置声明。

提示词文件（Prompt File）和配置文件（Configuration File）之间的区别，决定了你写CLAUDE.md的思路：

配置声明思维的一个典型例子：不要写“请用TypeScript写代码”，而要写“本项目是一个TypeScript项目（strict mode开启），所有新增代码应遵循项目根目录下的tsconfig.json配置”。前者是一条指令，后者是一个事实陈述，它告诉Claude Code“你是谁”，让模型自行推断“应该怎么做”。

我们团队的实测结果是：当CLAUDE.md从“指令列表”改为“事实声明”时，Claude Code在边缘场景下的自主判断准确率提升了约34%（统计口径：50个边界场景任务中，需要人工二次确认的次数从37次降至24次）。

这种写法的本质是，让模型用自己的推理能力去做决策，而不是用你的规则去做填空。

三、最常见的三种失败模板：为什么你写下它的时候就注定失效

三种指令模式在实际工程中反复出现，且屡屡失效。我逐一拆解原因。

3.1 “请遵循业界最佳实践”

这是CLAUDE.md中最常见的废话。失效原因极其简单：你的“最佳实践”和模型训练数据中的“最佳实践”大概率是冲突的。 比如你的团队遵循的是Airbnb的React编码规范，但Claude Code训练集中大量数据的代码风格可能是Google开源项目的风格（偏好函数式组件+TypeScript泛型约束）或者Facebook内部风格。当你说“请遵循最佳实践”时，模型会在多个“最佳实践”之间摇摆，最终输出一个“折衷方案”，而这个方案往往哪个团队的规范都不完全符合。

正确写法：不要提“最佳实践”，直接将你的编码规范的具体要点列出来。例如：“组件导出方式：prefer named export over default export; Props类型定义：使用interface而非type(除非必须使用联合类型); …”

这不是在教模型“怎么做”，而是在告诉模型“这个项目的约定是什么”。

3.2 “请确保代码质量”

这句和上面那条类似，但更隐蔽的危害在于：它让模型更倾向于过度工程化。 观察数据：当CLAUDE.md中包含“确保代码质量”这一模糊指令时，Claude Code在生成简单功能时增加异常处理分支、类型守卫、日志埋点的概率上升约41%（统计来源：我们团队对60个等价任务的对比生成结果审查）。

原因是Claude Code的RLHF训练强化了对“高质量代码”的评分偏好，而这个偏好通常对应“健壮性强+边界处理完善”的代码。当你再额外强调“确保质量”，相当于给这个偏好加了一个放大器，导致模型输出的代码徒增复杂度。

正确写法：明确指出你的团队对“质量”的定义是什么。比如“本项目对代码质量的定义：测试覆盖率达到85%+，所有API调用有错误处理，组件拆分粒度不低于单一职责。除上述三项外，不额外增加抽象层。”

3.3 “保持代码简洁”

这是另一个高频失效指令，失效原因是：模型根本不知道什么叫“简洁”。 Claude Code训练数据中的代码很多是教学类、文档类、开源项目示例类代码。这些代码为了可读性，往往会增加注释、类型标注、中间变量。但当你强调“简洁”时，模型可能走向另一个极端：省略必要的类型标注、合并过长的链式调用、减少变量命名导致语义不清。

正确写法：不要用“简洁”这种主观形容词。改用可操作的约束：“若无特殊原因，单个函数不超过50行、单文件不超过300行、组件propos数量不超过8个；对于可读性优于简短性的场景，优先保证可读性。”

四、重新理解“指令”，从行为约束到上下文构建

上面三点解释了“为什么你的指令会失效”。但更深层的问题是：你是不是从一开始就用错了CLAUDE.md的功能定位？

我调研了5个使用Claude Code超过300小时的开发者，询问他们对CLAUDE.md的理解。结果是5个人给出了3个完全不同版本的答案：

• 版本A：CLAUDE.md就是Prompt Engineering，告诉模型怎么做任务。
• 版本B：CLAUDE.md是System Prompt，约束模型的行为边界。
• 版本C：CLAUDE.md是项目上下文，提供背景信息。

这三个版本都对，但都漏掉了最重要的一个维度：CLAUDE.md同时作用于模型的推理链路，而不只是输入层。

当你写“本项目使用React 18 + TypeScript”时，这句话不仅是一个信息输入，它还会影响Claude Code在选择代码模式时的概率分布，模型在你的声明基础上，会给React 18 + TypeScript相关的代码模式赋予更高的权重，给Vue或JavaScript代码模式赋予更低的权重（甚至直接排除）。

这意味着CLAUDE.md具备一个没说出口的能力：它是你控制模型“候选方案池”的入口。 你不需要告诉模型“不要用Vue写代码”，你只需告诉它“这是React项目”，模型自然会排除Vue模式。这个机制比我见过的任何Prompt技巧都更稳定，因为它作用于模型内部的表示层而非表面输出层。

基于这个理解，好的CLAUDE.md应该做三件事：

1. 声明事实：“这个项目用的是哪些技术栈、遵循什么规范、部署在什么环境。”
2. 定义边界：“哪些事情需要先问我、哪些事情可以自己决定、哪些事情绝对不能做。”
3. 强化约束：“遇到以下特定场景时，优先采用这些策略（而非其他策略）。”

这三件事中，第一件最重要，第二件次之，第三件只是补丁。大部分人的CLAUDE.md做反了，大量精力花在写“具体策略”上，忽略了“声明事实”这个地基。

五、实际案例：一个前端团队的CLAUDE.md演化史

拿我深度参与观察的一个前端团队举例（React + TypeScript + Ant Design，规模3人前端+2人后端，项目周期12周）。他们的CLAUDE.md经历了三个版本的迭代，每一次失败的教训都很有参考价值。

V1.0 阶段（第1周）

原始CLAUDE.md内容（节选）：

你是项目的前端开发助手，请帮助你生成符合规范的代码。
请遵循Airbnb React编码规范，使用TypeScript，UI组件使用Ant Design。

请确保代码质量，保持简洁易读。

问题暴露（第2周）：

1. Claude Code生成的组件风格不一致：有时是class组件，有时是函数组件。
2. 对于简单表单，生成了过度复杂的表单验证逻辑。
3. 组件拆分粒度混乱：有时一个组件300+行，有时拆得过细导致3个文件各只有30行。
4. 最关键的问题：Claude Code在修改已有代码时，多次忽略了项目中已经存在自定义Hook（如useRequest），重复造轮子。

这个阶段的根本问题：CLAUDE.md没有告诉模型“你是谁”，所以模型每一次生成代码都是在“独自从头理解项目”。

V2.0 阶段（第3-4周）

改版后的CLAUDE.md（节选）：

项目上下文：

本项目是一个B端管理后台，技术栈：React 18 + TypeScript 4.9 (strict: true) + Ant Design 5

状态管理使用ahooks的useRequest模式，项目自定义hooks存放在src/hooks/目录

组件目录结构：src/components/下按业务模块分组，公共组件放在src/components/common/

本项目遵循的代码约定：优先使用函数组件+hooks；API请求使用src/utils/request.ts封装的request方法；表单使用Ant Design Form组件搭配自定义useForm hooks。

行为边界：

添加新功能前，先检查src/hooks/和src/utils/中是否有可复用的工具或hooks

修改已有组件时，保持组件的导出方式不变（default export vs named export）

如需引入新的npm包，必须先询问

不要删除或修改现有的测试文件

关键约定：

所有API请求需处理loading和error状态，并在UI层展示

组件props超过6个时考虑拆分组件的必要性

每个组件文件不超过250行，超过则考虑拆分

改善效果（第5周观察）：

1. 代码风格一致性明显提升，class组件出现率从21%降至3%。
2. 重复造轮子现象减少，useRequest和自定义Hook的复用率提升。
3. 生成代码前主动检查hooks目录的频率显著增加。

新出现的问题（第6-7周）：

1. Claude Code在生成表单时变得过于模板化，所有表单都用同一个模式，导致简单表单写得很冗长。
2. 组件行数限制250行这条规则导致了奇怪的拆分：有些逻辑高度内聚的组件被强行拆分，增加了理解成本。
3. 当用户明确要求“快速实现”时，Claude Code仍然坚持先检查hooks和utils，效率反而下降。

这个阶段暴露的核心问题：指令是静态的，但开发场景是动态的。第3-4周的指令在稳定期（第5周）表现优异，但在迭代加速期（第6-7周）开始成为障碍。

V3.0 阶段（第8周开始）

第三次改版，结构调整为三个模块：

[声明层] 项目事实（Claude Code需要知道的抽象层级判断依据）

技术栈：React 18 + TypeScript 4.9 (strict) + Ant Design 5

状态管理：ahooks useRequest模式，项目级自定义hooks位于src/hooks/

API请求：使用src/utils/request.ts

部署环境：内网部署，不需要考虑浏览器兼容性（无需polyfill）

本项目阶段：迭代加速期，功能交付效率优先于代码整洁度（本周期会动态调整）

[边界层] 不可逾越的红线（无论任何场景都必须遵守）

绝不修改src/utils/request.ts（这是鉴权和拦截器的核心）

绝不删除已有测试文件或已有的自定义hooks

绝不引入未确认的第三方npm包

绝不直接修改tsconfig.json（由Tech Lead负责）

[策略层] 推荐行为（可根据实际场景由开发者对话调整优先级）

建议在生成新功能前检查src/hooks/和src/utils/目录（非强制，快速场景可跳过）

建议组件不超过300行（为明确约束，允许内聚性强的组件超过）

建议API请求处理loading/error状态（在快速原型阶段可暂不处理）

V3.0带来的根本性变化：

1. 声明层给了模型“阶段判断”的依据。当模型知道项目处于“迭代加速期”，它在代码生成的简洁性 vs 健壮性抉择中会偏向简洁性。实测中，同一任务在V2.0和V3.0下的平均代码行数减少了约28%，同时未引入新的bug（因为核心边界层的约束保证了安全性）。
2. 边界层用“绝不”替代了“尽量”。这是V3.0最重要的改进。在后来的3周内，CLAUDE.md中的4条“绝不”指令的遵守率达到100%（28个任务中零违反），而同期的“建议”指令遵守率在78%-93%之间波动。否定表述的稳定性优势在实际项目中得到了清晰验证。
3. 策略层明确标注了“非强制性”。这解决了V2.0阶段“所有规则等权重”的问题，模型不清楚哪些规则可以打折扣、哪些不可以。当策略层明确说了“非强制”“快速场景可跳过”，模型反而能在正确的时候做出正确取舍。

六、构建你自己的CLAUDE.md：一套可复用的框架

结合上述案例，我总结出一套在你自己的项目中可以直接套用的框架。但先提醒一点：不要直接复制某个团队的模板，因为每个团队的项目阶段、架构复杂度、团队规模和对模型的行为预期都不同。你的CLAUDE.md应该在这些维度上做出适配。

6.1 声明层：告诉模型“你正在一个什么样的项目里”

声明层的核心作用是缩小模型的候选方案空间。你不需要告诉模型“别这么做”，你只需要告诉它“我们这边的情况是这样的”，它自然会排除不相关的方案。

以下8个维度构成了声明层的骨架：

技术栈维度

• 语言及版本：TypeScript 4.9 / Python 3.11 / Go 1.21
• 框架及版本：React 18 / Django 4.2 / Gin
• 关键依赖库：Ant Design 5 / ahooks / pandas
• 运行时环境：Node 18 LTS / Docker / 内网部署

项目结构维度

• 目录组织逻辑：按业务模块 / 按功能分层 / 领域驱动
• 关键文件路径：自定义hooks位于src/hooks/，API封装位于src/utils/request.ts
• 配置文件位置：tsconfig.json / .eslintrc.js / Dockerfile

开发约定维度

• 编码规范来源：Airbnb React规范 + 团队补充规则 / Google Python Style Guide
• 命名约定：文件名kebab-case，组件名PascalCase，变量名camelCase
• 导出方式：prefer named export
• 类型定义风格：interface优先于type（除非需要联合类型）

项目阶段维度（这个大多数人会忽略）

• 当前阶段：启动期/稳定开发期/迭代加速期/发布候选期/维护期
• 阶段偏向：代码健壮性优先/交付效率优先/可维护性优先
• 调整周期：此声明预计在多长时间内有效（例如“本周有效，下周可能调整”）

声明层的写法技巧是：不要用“建议”“推荐”这类词，而是用陈述句直接陈述事实。 这不是下指令，而是在建立共识背景。

6.2 边界层：定义不可逾越的红线

边界层是CLAUDE.md中最稳定、最容易遵守的部分。原理在于：否定指令给模型留下了推理空间。 当你说“永远不要修改X文件”，模型在处理各种任务时，都能在推理链路中识别“这个操作是否会影响X文件”，而不用去匹配一个复杂的“何时可以修改X”的规则集。

边界层的规则需要满足三个标准：

1. 绝对性：必须是“绝不”，不能是“尽量”。
2. 可验证性：Claude Code在执行前能够判断一个操作是否会触发这条规则。
3. 稳定性：这条规则在项目的当前阶段不会改变。

以下是高价值边界规则的四个来源：

高危害性操作

• 绝不删除或修改已有的测试文件
• 绝不修改鉴权相关代码（auth / middleware / interceptor）
• 绝不修改数据库schema（由后端负责）
• 绝不引入未授权的第三方依赖

高影响面操作

• 绝不修改tsconfig.json、.eslintrc.js、webpack/vite配置
• 绝不修改CI/CD配置文件（.github/workflows / Dockerfile）
• 绝不修改.gitignore（除非明确要求）

团队分工边界

• 样式文件由专人负责，不要修改任何.styl/.less/.scss文件（除非明确要求）
• 国际化文案由产品提供，不要自行编撰i18n key对应的内容
• API接口定义以后端OpenAPI文档为准，不要自行修改接口签名

业务安全边界

• 绝不将测试环境的API地址用于生产代码
• 绝不硬编码密钥、token、密码
• 绝不修改SQL查询中的WHERE条件（除非明确告知原因）

边界层的维护规律是：只增不减。 当一个新边界被发现时（例如“某个第三方库的升级导致了兼容性问题”），加入边界层；但已有的边界除非项目阶段发生根本性变化，否则不删除。我们的经验是，边界层的内容在12周周期内通常只增加2-3条，几乎不会删除。

6.3 策略层：给出推荐行为，明确可协商性

策略层是CLAUDE.md中最灵活的部分，也是最容易被滥用和过度设计的部分。策略层的核心原则是：明确每一条策略的优先级、适用场景、以及是否可以跳过。

推荐的策略层结构：

默认策略（比声明层更具体的操作指引，但注意不要和声明层的“事实陈述”混淆）

• 建议优先使用项目已有的custom hooks（如useRequest、useForm）
• 建议组件超过300行时考虑拆分（非强制）
• 建议所有API请求处理loading/error状态
• 建议新增类型定义统一放在src/types/目录

场景差异策略

• 快速原型场景：可忽略loading/error状态处理、可压缩组件拆分标准
• 生产交付场景：必须处理所有异常分支、必须编写单元测试、必须进行可访问性检查

冲突解决策略（当多条策略冲突时，哪条优先）

• 可维护性 vs 效率：在迭代加速期，效率优先；在稳定开发期，可维护性优先
• 复用已有方案 vs 引入新方案：如果已有方案覆盖90%以上需求，必须复用；否则可评估新方案
• 代码行数限制 vs 内聚性要求：高内聚组件可超过行数限制，低内聚组件即使行数少也应提示拆分

策略层的写法技巧是：明确定义“什么时候不用遵守这条策略”。 这让模型在场景切换时不会僵化执行所有规则。

七、指令失效的深层原因：不只是写得不好，而是用错了工具

这个判断来自于过去半年对多个使用Claude Code团队的经验观察：指令失效有一半以上的原因不在“怎么写指令”，而在于我们期待CLAUDE.md完成的任务，根本不该由CLAUDE.md来完成。

7.1 CLAUDE.md不是代码审查工具

很多团队在CLAUDE.md中写了大量代码审查规则：“请检查变量命名是否符合规范”“请检查是否有未处理的Promise”“请检查是否有重复代码”。结果是：Claude Code在生成代码时确实会进行这些检查，但同时让每一次代码生成都变得极其缓慢（推理链路被审查逻辑拖长），而且生成的代码会带上大量防御性注释（如“此处已进行空值检查”“此处确保Promise被处理”）。

这本质上是用错了工具。 代码审查应该由ESLint、Prettier、SonarQube或Code Review机制来完成，而不是让Claude Code在推理时来做。CLAUDE.md不应该成为“Lint规则的提示词版”。

7.2 CLAUDE.md不是文档生成器

另一类常见误用是：在CLAUDE.md中写“每次生成代码时，请附带详细的JSDoc注释”“请在所有函数上方写清楚参数说明和返回值说明”。这导致两个问题：

1. Claude Code生成的注释质量参差不齐，且很多是“显而易见式注释”（如“@param {string} name – 姓名”），污染代码。
2. 过量的注释指令会挤占CLAUDE.md的“事实声明”和“边界”空间，让真正重要的上下文信息被稀释。

建议做法：不要在CLAUDE.md中写文档相关的指令。如果需要强制生成注释，配置ESLint的require-jsdoc规则即可，这比在推理层约束更稳定且零额外推理成本。

7.3 CLAUDE.md不能替代团队沟通

最隐蔽的误用是：在CLAUDE.md中写入“本项目的技术决策依据”“为什么选择React而非Vue”“为什么使用ahooks而不是redux”。这些信息对Claude Code的代码生成几乎没有任何帮助（模型不需要知道“为什么选择React”来决定如何写React代码），而且对团队成员来说，这类信息应该存放在项目Wiki或Architecture Decision Record中，而不是藏在CLAUDE.md里。

一个干净的CLAUDE.md应该只包含对Claude Code生成决策有直接影响的上下文信息。任何“给人看但AI不需要看”的信息，都应该移出CLAUDE.md。

八、不同项目阶段的CLAUDE.md模板策略

基于对多个项目的观察，不同阶段适用的CLAUDE.md策略差异很大。以下是我总结的分阶段策略，附带实际可行的模板要点。

8.1 项目启动期（第1-3周）

特征：技术选型还在调整，目录结构可能变动，编码规范尚未最终确定。

CLAUDE.md策略：声明层和策略层从简，边界层尽快建立。

声明层重点关注：

• 明确技术栈（即使后续可能调整）
• 明确指出当前阶段为启动期，允许快速试错

边界层重点关注：

• 给基础设施文件（tsconfig.json、package.json、vite/webpack配置）加“绝不修改”边界
• 给数据库Schema和API接口定义加边界

策略层可简化：启动期不建议在策略层投入太多精力，因为大量约定会变。

启动期模板示例（声明层核心片段）：

本项目阶段：启动期（快速验证技术方案，编码规范未最终确定）
技术栈：React 18 + TypeScript 4.9 (strict) + 暂未确定UI库

关键约束：tsconfig.json、package.json、vite.config.ts不要修改（由项目初始化者负责）

这个阶段的典型错误：有人在项目启动期就写了一大堆策略层规则（如“组件必须有多少行”“必须怎么写注释”），结果两周后技术选型调整，所有规则都需要重写。

8.2 稳定开发期（第4-8周）

特征：技术栈稳定，编码规范确定，项目结构成型。

CLAUDE.md策略：三层的投入都在同步增加，策略层开始发力。

声明层应补充：

• 完整的项目结构描述（关键目录及用途）
• 完整的依赖库清单及使用场景

边界层应补充：

• 根据前期踩坑经验，增加高危害性操作边界（如“某个库的升级会导致兼容性问题”）
• 补充团队分工边界（前端/后端/测试的责任划分）

策略层应重点建立：

• 代码生成风格约束（组件拆分标准、hooks复用策略）
• 场景差异策略（正常开发vs快速修复）

稳定期模板示例（策略层核心片段）：

[策略层 - 稳定开发期]
默认策略：

生成新功能前检查src/hooks/和src/utils/中是否存在可复用逻辑

组件超过250行时，发出建议拆分提醒

API请求默认处理loading/error状态

快速修复场景（当用户明确标注为热修复/紧急修复时）：

可跳过上述检查

优先保证修改的安全性而非代码整洁度

修复完成后，在回复末尾提醒需要进行代码重构

这个阶段最大的坑是策略层写得过多。建议稳定期策略不超过8条，超过则考虑：哪些可以合并、哪些其实是声明层的内容、哪些是多余的。

8.3 迭代加速期（第8周以后，需求密集到达）

特征：功能需求频繁，交付压力大，团队对规范的容忍度上升。

CLAUDE.md策略：声明层需要频繁更新（特别是项目阶段声明和阶段偏向），策略层应适当收缩以提升生成效率。

声明层关键变更：

• 明确标注“迭代加速期，效率优先”
• 移除对编码整洁度的过度约束
• 快速原型场景：可跳过loading/error状态处理等

边界层保持不变：这是底线。无论交付压力多大，核心边界不能松动。

策略层收缩原则：

• 将“必需”类策略改为“建议”类策略
• 明确声明哪些策略可以在快速场景下跳过
• 保留安全隐患相关策略（如“不要硬编码密钥”），但这是边界层的事

迭代加速期最容易出现的错误：忘记在CLAUDE.md中声明阶段切换。 结果是团队在快速迭代，但Claude Code还按照稳定期的策略一丝不苟地检查hooks、建议拆分组件、要求写类型守卫，最终开发者不得不频繁在对话中追加“快速实现，不用太严谨”这类指令，抵消了CLAUDE.md的效果。

九、当你需要“临时覆盖”CLAUDE.md时

无论指令设计得多好，总会出现需要临时突破规则的场景。这时候怎么做能最小化对模型行为稳定性的影响？

9.1 在对话中覆盖：明确“本次例外”

当你在单次对话中需要Claude Code忽略某条策略时，正确的表述方式是：

错误做法：“这次不用管组件行数限制了，直接写就行。”

正确做法：“本次任务中，忽略CLAUDE.md中‘组件不超过300行’的策略，该策略不适用于本场景。其他策略照常遵守。”

区别在于：前者让模型陷入模糊判断，“不管行数限制，那其他限制还要管吗？”后者明确指明了覆盖范围和生效范围（“本次任务”“仅该策略”）。

9.2 临时修改CLAUDE.md的风险

有人选择在CLAUDE.md中临时注释掉某些规则。这种做法有风险：

• 注释掉规则后，一旦忘记恢复，后续所有对话都会在新规则下运行。
• 多人协作时，A注释掉规则，B并不知道，导致B的对话在不可预期的规则下运行。

推荐做法：如果需要长期放宽某条规则（例如整个迭代周期内允许组件超过300行），直接修改CLAUDE.md并注明有效期；如果只是单次例外，在对话中临时覆盖，不要改CLAUDE.md。

9.3 多个开发者对同一个CLAUDE.md的覆盖冲突

这是我们团队遇到的最棘手的问题之一。场景是：开发者A在对话中说“忽略组件拆分建议”，开发者B在同一项目的另一对话中说“请严格遵循组件拆分建议”。两个对话基于同一个CLAUDE.md，但各自产生了不同的临时规则。

解决方案取决于Claude Code的上下文隔离机制：如果每个对话是独立上下文（目前的实际情况），那么A和B的临时覆盖仅在自己对话中生效，互不影响。但如果未来Claude Code引入了跨对话的规则学习机制（目前没有，但技术上可行），就需要在CLAUDE.md中明确声明“临时覆盖的作用域仅限于当前对话，不对其他对话产生持久影响”。

十、CLAUDE.md的迭代策略：什么时候该改、什么时候不该动

CLAUDE.md需要经常调整吗？我的回答是：声明层和边界层保持稳定，策略层按需调整，但调整周期不应该短于一个迭代。

10.1 触发CLAUDE.md更新的信号

以下信号出现时，说明CLAUDE.md需要审视：

1. 同一类规则被开发者反复在对话中覆盖（说明该规则的实际价值已经降低，或者当前阶段不需要它）。
2. Claude Code连续3次以上在同一个业务场景中做出了不符合预期的判断（可能是指令冲突，或者声明层信息不足）。
3. 技术选型或项目结构发生重大变化（声明层必须同步更新，否则Claude Code会基于过时信息做判断）。
4. 新的高危害性操作边界被识别（必须立即加入边界层）。

10.2 不应该频繁修改CLAUDE.md的理由

每修改一次CLAUDE.md，Claude Code都需要在后续对话中重新理解你的项目上下文。虽然模型本身不存储状态，但频繁修改CLAUDE.md会让长对话上下文中的行为不稳定（前面的对话基于旧规则，后面的基于新规则）。

我们的经验数据：修改CLAUDE.md后，紧接着的2-3次对话中，Claude Code的行为偏差率会上升约15%-20%（表现为忘记某些已有约定、过度依赖新规则、在旧规则和新规则之间摇摆），之后才逐渐稳定。因此，修改CLAUDE.md的节奏建议控制在每两周一次（除非出现紧急的安全边界需要立刻更新）。

十一、三个即刻可以落地的优化建议

说了这么多理论和案例，这里给三条你读完就可以在项目里实施的优化：

11.1 用“事实陈述”重写声明层

打开你的CLAUDE.md，找到所有以“请”“建议”“必须”开头的句子。尝试把它们改写为陈述句。例如：

• 原句：“请使用TypeScript strict mode”
• 改写：“本项目TypeScript配置启用strict mode”

• 原句：“建议遵循Airbnb React编码规范”
• 改写：“本项目编码规范基于Airbnb React规范，补充规则见.eslintrc.js”

• 原句：“请优先使用项目已有的hooks”
• 改写：“项目级自定义hooks位于src/hooks/目录，已有hooks包括useRequest、useForm、useAuth”

这条优化的效果应该在1-2天内就能观察到，Claude Code在代码生成的一致性上会有明显改善。

11.2 拆分“边界”和“策略”，用不同强度的语言表述

把CLAUDE.md分成三段，分别标注[声明层][边界层][策略层]。边界层只用“绝不”和“永远”，策略层可以保留“建议”“推荐”，但必须注明场景差异和可跳过条件。

这个做法的核心价值在于：让模型清楚知道哪些规则不能妥协、哪些规则可以根据场景灵活调整。很多指令失效的根源就是“把策略当成了边界”，导致模型在正确的时候打破了规则（因为场景确实需要打破），然后开发者在对话中纠正，导致规则混乱。

11.3 加上“项目阶段声明”

这是最简单的动作，也是90%的CLAUDE.md缺少的内容。只需加一行：

本项目当前阶段：稳定开发期（可通过原型快速验证方案，编码规范已确定，交付周期为2周一迭代）

这行命令给Claude Code提供了最关键的信息，它在和什么样的开发节奏配合。在“迭代加速期”它会降低对整洁度的要求，在“发布候选期”它会更谨慎地处理修改，在“维护期”它会减少引入新依赖的倾向。

十二、总结：CLAUDE.md的本质是“人机协作的项目共识协议”

回过头看这篇文章开头那个深夜的问题，“指令模板到底他妈管不管用”，答案是：写对了就管用，写不对就可能让Claude Code在关键时刻掉链子。

CLAUDE.md不应该只是一个提示词文件，它应该是一份经过设计的“项目共识协议”，内容包括：

• 声明层：告诉模型“这个项目的事实是什么”，缩小候选方案空间。
• 边界层：告诉模型“哪些事绝对不能做”，保障安全底线。
• 策略层：告诉模型“多数情况下这样做效果更好”，提供行为指引。

这三层从稳定到灵活、从不可妥协到可协商，构成了一个完整的指令体系。

下一步你可以做的事情：

1. 打开你项目中的CLAUDE.md，检查它是否包含了这三层。
2. 删掉所有模糊形容词（“简洁”“高质量”“良好”），用事实陈述或可衡量标准替代。
3. 加上项目阶段声明，让模型知道现在该快还是该稳。
4. 检查边界层的指令是不是都用“绝不”表述，是不是每一条都真正不可妥协。

最后重复一句本文的核心结论：CLAUDE.md的目标不是让AI学会按照你的规则答题，而是让AI学会在正确的场景下问对的问题。 做到这一点，你的CLAUDE.md就不再是一个“指令模板”，而是一份让你和AI真正搭档起来的协议。