一句话: CLAUDE.md 写得好不好，决定了新窗口读一句就能干活还是翻完一堆文件才能开始。核心原则：自包含——第一段回答"我是谁、干什么、怎么开始"，禁区集中放，详细规则需要时才翻。

适合谁读：用 Claude Code、Cursor 写代码，想让 AI 少犯错的开发者。

问题

项目的 CLAUDE.md 原来长这样：

# 项目

## 参考
- [编码规范](style.md)
- [构建流程](build.md)
- [架构指南](arch.md)
- [测试规则](test.md)

核心信息全在四个链接里。Agent 打开新窗口 → 读 CLAUDE.md → 发现是目录 → 翻四个文件 → 终于知道要干什么。每开一次窗口重复一遍。

改：自包含

改完后的 CLAUDE.md 第一段回答三个问题：

禁区集中放一个段落——不改 HAL 层、不动链接脚本、不碰 bootloader。Agent 一次读完就知道什么不能碰。

五个设计

第一段回答"三个什么"——你是谁、干什么、有什么约束。Agent 读完就干活。

"立即开始"代码块——给可执行的命令，不是文字描述。

# 编译
make build
# 测试
make test

禁区集中放——不改自动生成代码、不动链接脚本、不自己加第三方库。

犯错立刻更新——每次 AI 犯会重复的错，立刻写进 CLAUDE.md。不做这一步同一个坑踩十次。

新窗口打开语写进项目——"读 CLAUDE.md，然后帮我写 XXX 模块"。

CLAUDE.md vs AGENTS.md

怎么检查

打开新窗口看 Agent 第一轮输出：直接干活 = 好；问"项目是干什么的" = 差；开始翻目录探索 = 入口文件就是个目录。

有用的话点个收藏，下次调入口文件直接查。有问题欢迎评论区交流。