Claude Code不按指令执行？写出让Agent精准执行的共识协议

数码系统

相机 win10

测评 win11

手机智车

华为 Tesla

小米理想

苹果蔚来

游戏软件

LOL 抖音

原神微信

当前位置：首页

业界动态

Claude Code不按指令执行？写出让Agent精准执行的共识协议

热心网友时间：2026-06-29

转载

上周在技术交流群里，有人提了一个常见困惑：“为什么我的 Claude Code 总是不按指令执行？明明已经详细写进 CLAUDE.md 了。”

我打开他的 CLAUDE.md 一看——整整 482 行，从项目背景到编码标准、Git 提交格式、部署流程，几乎把整个团队 Wiki 搬了进去。

问题根源在哪？不是内容写多了，而是写的全是 Claude 能够直接从代码中自行分析出来的信息。

真正需要写入的——那些它无法自行推断的构建命令、那些与默认行为相悖的项目规范——反而淹没在大量冗余信息里了。

CLAUDE.md 不是项目文档，不是 README，也不是给人阅读的说明。它是你与 AI Agent 之间建立的协作契约——就像分布式系统中各个节点之间协商的通信协议，写对了，所有 Agent 遵循同一套规则执行；写错了，每次对话都在重复纠正同样的错误。

这篇文章是我基于实际项目对 CLAUDE.md 的深度实战总结。从底层加载机制讲到文件组织结构，从该写入什么讲到绝不能写什么，最后提供一套拿来即用的完整模板。

概览: "CLAUDE.md 是你与 AI Agent 之间的协作契约。本文从加载机制、优先级顺序、文件组织到常见误区，手把手教你写出能让 Claude Code 精准执行的项目指令，附完整配置示例与踩坑经验"

keywords: ["CLAUDE.md配置", "Claude Code指令优化", "AI编程助手规范", "Agent协作协议", "prompt engineering实践", "项目级AI指令文件"]

先搞清楚 CLAUDE.md 是怎么被加载的

在动手编写 CLAUDE.md 之前，必须深入理解它的加载机制。否则你很难判断为什么某些指令生效了，另一些却没有。

Claude Code 启动时，会从四个层级收集指令，优先级从高到低——类似于分布式系统中的配置层叠结构，层级越高，覆盖能力越强：

claude-md-loading-hierarchy claude-md加载层级示意图

第一层：企业策略（Managed Policy）。这是组织管理员通过 /etc/claude/ 下发的全局性策略，个人开发者通常用不到。优先级最高，能够覆盖所有其他配置。

第二层：项目级（Project）。即你项目根目录下的 CLAUDE.md 文件。这是最常用的方式，也是本文探讨的重点。它随代码一起提交，团队成员共享同一份配置。

第三层：用户级（User）。存放在 ~/.claude/CLAUDE.md，仅对你自己生效。适合用来定义个人偏好——比如你更习惯中文回复、偏好简洁风格等。

第四层：本地覆盖（Local Override）。放在项目根目录下的 .claude/CLAUDE.md（注意是 .claude 目录），通常被加入 .gitignore，不提交到代码库。适合存放本地特有的环境变量路径、调试参数等个性化配置。

关键点来了：Claude Code 会沿目录树向上递归收集所有 CLAUDE.md。这是什么意思？假设你的项目结构如下：

my-monorepo/
├── CLAUDE.md                    # 顶层：通用规范
├── backend/
│   ├── CLAUDE.md                # 后端子项目规范
│   └── src/
└── frontend/
    ├── CLAUDE.md                # 前端子项目规范
    └── src/

当 Claude Code 在 backend/ 目录下工作时，它会同时加载 backend/CLAUDE.md 和顶层的 CLAUDE.md，然后将两者拼接后送入上下文。这个机制与分布式系统中的配置层叠覆盖完全一致——全局配置作为基础，局部配置进行覆盖。

踩坑记录：如果你在子目录和根目录的 CLAUDE.md 里写了互相矛盾的指令（比如根目录说「用 ESLint」，子目录说「用 Biome」），Claude 会优先遵循离当前工作目录更近的那个。但如果指令只是「不同」而非「矛盾」，两者会合并生效。这个行为在官方文档中没有明确说明，是实际踩坑发现的。

该写什么：那些 Agent 猜不到的东西

这是整篇文章最核心的部分。最新版文档给出了一个非常精准的判断标准：

写进 CLAUDE.md 的应该是 Claude 无法从代码本身推断出来的信息。

具体来说，有四类内容必须写进去：

1. 构建和测试命令

这是最高优先级。Claude 能读懂你的代码，但它猜不到你的构建系统该怎么运行。

## 构建命令
- 构建整个项目：`mvn clean install -DskipTests`
- 构建单个模块：`mvn clean install -DskipTests -pl dlm-framework/dlm-rule`
- 运行测试：`mvn test -pl dlm-framework/dlm-rule`
- 本地启动：`./scripts/dev-start.sh`（需要先启动 ZooKeeper 和 Redis）
> 首次构建多模块项目时，先注释掉父 POM 的  段，构建完成后恢复。

注意最后那行踩坑提示——这种信息 Claude 绝对猜不到，写进去能省掉每次手动解释的时间。

2. 违反默认习惯的编码规范

Claude 默认会按照业界最常见的规范写代码。如果你的项目有不同的约定，必须明确告知。

## 编码规范
- Ja va 版本：Ja va 8（不要使用 var、stream 的 toList()、records 等高版本特性）
- 缩进：4 空格（不是 2 空格）
- 测试框架：JUnit 4 + Mockito（不是 JUnit 5）
- 日志：使用 @Slf4j 注解，不要手动创建 Logger 实例
- 异常处理：业务异常用 BizException，不要用 RuntimeException

这里的关键是「不是什么」比「是什么」更重要。Claude 可能默认用 JUnit 5 写测试——如果你不说「用 JUnit 4」，它就会按自己的判断来。

3. 架构约定和模块边界

Claude 能读懂单个文件，但它不一定理解你项目的整体架构意图。

## 架构约定
本项目采用微内核 + 插件架构：
- `dlm-framework/` 是纯框架层，不允许包含任何业务逻辑
- `dlm-app/` 是业务服务层，每个服务遵循 api / service / web 三子模块模式
- 新增协议适配器放在 `dlm-protocol/`，实现 `IProtocolDispatcher` 接口
- RPC 调用通过 Dubbo，不要引入 Feign 或 RestTemplate 做服务间调用

4. 工作流程和提交规范

## Git 规范
- 提交信息格式：`(): `，type 包括 feat/fix/refactor/docs/test
- 不要用 --no-verify 跳过 pre-commit hook
- PR 标题不超过 70 字符
- 每个 PR 只做一件事，不要混合功能开发和代码重构

千万别写什么：Agent 自己能搞定的事

写 CLAUDE.md 最常见的错误是信息过载。最新建议控制在 500 行以内——不是因为有硬性限制，而是因为每次对话启动时 CLAUDE.md 的内容都会被注入 context window，写太多等于每次都在浪费 token 预算。

以下内容不要写进 CLAUDE.md：

项目目录结构说明。Claude 可以自己跑 ls 和 find，不需要你在 CLAUDE.md 里画 ASCII 目录树。
语言基础知识。不需要写「Ja va 是一种面向对象的编程语言」或者「Spring Boot 是一个微服务框架」。Claude 知道。
通用编码规范。如果你的规范和业界标准一致（比如 Go 用 gofmt、Python 用 Black），不需要重复写。只写不同的地方。
大段解释性文本。CLAUDE.md 不是技术文档。Claude 需要的是可执行的指令，不是背景介绍。比较一下：

# ❌ 错误示范：解释性文本
我们的项目使用了微内核架构，这种架构的核心思想是将系统分为核心框架和插件模块。核心框架提供基础的运行时环境和扩展点，而插件模块则通过实现这些扩展点来添加具体功能。这种设计的好处是...（后面还有 200 字）

# ✅ 正确示范：可执行指令
## 架构规则
- framework/ 层不允许 import app/ 层的任何类
- 新插件必须实现 IPlugin 接口并注册到 PluginRegistry
- 跨模块依赖通过 SPI 机制，不要直接 new

write-vs-not-write 该写与不该写的内容对比

用 `.claude/rules/` 做路径级精准控制

CLAUDE.md 是全局生效的。但有些规则只在特定文件上才有意义——比如「测试文件必须用 Given-When-Then 命名」这条规则，你不希望它在改 README 的时候也蹦出来。

.claude/rules/ 目录就是干这个的。每个 .md 文件可以通过 frontmatter 指定生效范围：

---
description: "测试文件编码规范"
globs: ["**/test/**/*.ja va", "**/*Test.ja va"]
---
- 测试方法命名：should*预期行为\_when*前置条件
- 每个测试方法只测一件事
- Mock 使用 @Mock 注解 + @InjectMocks，不要手动 new
- 断言用 assertThat()（Hamcrest），不要用 assertEquals()

当 Claude 编辑匹配 glob 模式的文件时，这些规则会自动注入上下文。编辑其他文件时，这些规则不会出现。

这个机制的好处是精准投放，节省 token。你可以这样组织：

.claude/
└── rules/
    ├── testing.md          # globs: ["**/test/**"]
    ├── api-design.md       # globs: ["**/controller/**", "**/api/**"]
    ├── database.md         # globs: ["**/mapper/**", "**/repository/**"]
    └── frontend.md         # globs: ["src/components/**/*.tsx"]

踩坑记录：如果一个 rule 文件没有 globs 字段（或者 globs 为空），它会始终生效，等价于写在 CLAUDE.md 里。用这个特性可以把一些「总是需要但又不想塞进 CLAUDE.md」的规则外置。

`@import` 语法：CLAUDE.md 的模块化

当项目规模大到 CLAUDE.md 超过 200 行时，拆分是唯一的出路。@import 语法让你可以把 CLAUDE.md 拆成多个文件：

# CLAUDE.md
## 通用规范
@docs/coding-standards.md
@docs/git-conventions.md

## 构建指南
@docs/build-guide.md

## 架构说明
@docs/architecture-rules.md

被引用的文件内容会在加载时展开，效果等同于直接写在 CLAUDE.md 里。

这个语法的价值在于关注点分离。编码规范变了，你只需要改 coding-standards.md，不需要在一个巨大的 CLAUDE.md 里翻找。团队中负责不同模块的人可以各自维护自己的规则文件。

但有一个需要注意的地方：import 的文件也计入总 token 消耗。拆分是为了可维护性，不是为了绕过长度限制。最终注入上下文的内容量是一样的。

验证策略：让 Agent 自证正确

写 CLAUDE.md 最容易忽略的一点是：光告诉 Agent「怎么做」不够，还要告诉它「做完之后怎么验证自己做对了」。

这就像分布式系统里的心跳检测——你不能只下发指令然后祈祷节点正确执行，你需要一个反馈机制。

## 验证清单
改完代码之后，按顺序执行以下检查：
1. `mvn compile -pl <修改的模块>` — 确保编译通过
2. `mvn test -pl <修改的模块>` — 确保测试通过
3. 检查是否有新增的编译警告
4. 如果修改了 API 接口，确保 Dubbo 的 api 模块也同步更新了 DTO

agent-verify-feedback-loop Agent验证与反馈循环

更高级的做法是在 CLAUDE.md 里引导 Claude 使用 Plan Mode：

## 复杂任务处理
对于涉及 3 个以上文件的修改：
1. 先进入 Plan Mode（/plan），列出所有要改的文件和改动点
2. 等我确认后再开始执行
3. 每改完一个文件就运行一次编译检查
4. 全部改完后跑完整测试套件

这相当于在共识协议里加了一个两阶段提交（2PC）：先 prepare（列计划），再 commit（执行修改）。如果 prepare 阶段发现计划不对，abort 的成本几乎为零。

多 Agent 场景下的共识问题

如果你用了 Claude Code 的 Sub-agent 或 Agent Teams 功能，CLAUDE.md 的作用就更关键了——它是所有 Agent 共享的唯一配置源。

每个被 spawn 出来的 Sub-agent 都会独立加载当前目录的 CLAUDE.md。这意味着：

好处：所有 Agent 天然遵守同一套规则，不需要额外的同步机制。这就是分布式系统里「配置中心」的作用。
风险：如果 CLAUDE.md 里的指令有歧义，不同 Agent 可能做出不同的解读——就像拜占庭将军问题里，同一条命令被不同节点解读出不同含义。

所以在多 Agent 场景下，CLAUDE.md 的指令必须做到无歧义、可执行、可验证：

# ❌ 有歧义的指令
- 代码要写得简洁
- 变量命名要有意义
- 适当添加注释

# ✅ 无歧义的指令
- 方法体不超过 30 行，超过就提取子方法
- 变量命名用 camelCase，布尔变量以 is/has/can 开头
- 只在「为什么这样做」不明显时添加注释，不要注释「做了什么」

如果你还配置了自定义 Sub-agent（放在 .claude/agents/ 目录），每个 agent 可以有自己的 system prompt 和工具白名单。但它们仍然会继承 CLAUDE.md 的全局规则。层级关系是：

CLAUDE.md（全局共识）
  └── .claude/agents/reviewer.md（agent 专属指令）
       └── 运行时 context（当前任务 + 对话历史）

?[技术配图：架构图 - 多 Agent 配置继承关系] Excalidraw 文件：images/claude-md-writing-guide-consensus-protocol/multi-agent-config-inheritance.excalidraw 渲染后替换为 ![多 Agent 配置继承关系](images/claude-md-writing-guide-consensus-protocol/multi-agent-config-inheritance.png)

五个常见反模式（以及怎么修）

Anthropic 最新文档里列出了几个高频踩坑模式，加上一些实战经验，总结如下：

反模式 1：厨房水槽式（Kitchen Sink）

症状：CLAUDE.md 超过 500 行，啥都往里塞。后果：context window 被大量低价值信息占用，真正重要的指令被稀释。修法：砍到 200 行以内。用「如果我删掉这行，Claude 会做错吗？」来判断每一行的去留。不会做错的就删。

反模式 2：过度指定（Over-Specified）

症状：把 Claude 能自己推断的东西也写进去。比如在一个 TypeScript 项目里写「使用 TypeScript 开发」。后果：噪声，而且容易和实际代码脱节——你 CLAUDE.md 里写的规范可能和代码库实际用的不一致。修法：只写差异项。问自己：「一个熟悉这个技术栈的高级工程师，看到代码后还需要被告知什么？」需要被告知的那些，才值得写。

反模式 3：反复纠正不记录（Correct-and-Forget）

症状：每次 Claude 犯同样的错误，你都在对话里纠正它，但从来不更新 CLAUDE.md。后果：下次新对话又犯。因为 CLAUDE.md 是跨对话持久化的，对话内的纠正不是。修法：第二次纠正同一个问题时，立刻写进 CLAUDE.md 或 .claude/rules/。这是一条铁律。

反模式 4：信任-验证缺口（Trust-then-Verify Gap）

症状：在 CLAUDE.md 里写了详细的指令，但没有写验证步骤。Claude 执行完了你才发现不对。后果：返工。尤其在多文件修改场景下，返工成本很高。修法：每个关键指令后面跟一条验证命令。参考上面「验证策略」章节。

反模式 5：无限探索（Infinite Exploration）

症状：没有告诉 Claude 项目的边界在哪里，它花大量 token 去读无关的文件。后果：token 浪费，执行慢，还可能被无关信息误导。修法：在 CLAUDE.md 里明确标注「不需要关注」的目录：

## 项目边界
- 忽略 `legacy/` 目录，这是已弃用的旧代码
- 忽略 `vendor/` 和 `node_modules/`
- 只关注 `src/main/ja va/` 下的业务代码和 `src/test/` 下的测试代码

一个可以直接抄的模板

把上面所有实践汇总，一个 CLAUDE.md 的推荐结构长这样：

# CLAUDE.md

## 构建命令
[必须：构建、测试、启动命令，含前置条件和踩坑提示]

## 编码规范
[只写和默认不同的约定，越具体越好]

## 架构规则
[模块边界、依赖方向、禁止的做法]

## Git 规范
[提交格式、分支策略、PR 要求]

## 验证清单
[改完代码后的自动检查步骤]

## 项目边界
[哪些目录要关注，哪些要忽略]

配合 .claude/rules/ 做路径级细化：

.claude/
├── CLAUDE.md              # 本地覆盖（不提交）
├── agents/
│   └── reviewer.md        # 代码审查专用 agent
└── rules/
    ├── testing.md          # 测试文件专用规则
    ├── api-design.md       # API 层专用规则
    └── database.md         # 数据访问层专用规则

常见问题

Q：CLAUDE.md 和 AGENTS.md 是什么关系？

AGENTS.md 是行业通用的 agent 指令文件名，多家 AI 编程工具都支持。Claude Code 同时读取 CLAUDE.md 和 AGENTS.md，两者内容会合并。如果你的项目要兼容多个 AI 工具（比如同时用 Claude Code 和 Cursor），可以把通用规范放 AGENTS.md，Claude 专属配置放 CLAUDE.md。