一句话: CLAUDE.md / MEMORY.md 写得好不好，决定了新窗口读一句就能写代码还是读完五个文件才能开始。本文用一个真实的改造案例讲清楚怎么写——"开箱即用"四个字是唯一的标准。

适合谁读：正在用 Claude Code、Cursor 等 AI 编程工具写代码，想让助手少犯错的开发者。

问题：新窗口读完五个文件才开始写代码

我有个嵌入式 C 项目，用 Claude Code 写代码。项目的入口文件是 CLAUDE.md——Agent 打开新窗口先读它，了解项目结构和规范。

但原来的 CLAUDE.md 长这样：

# 嵌入式固件项目

## 详细参考
- [编码规范](coding-style.md)
- [构建流程](build-workflow.md)
- [硬件抽象层](hal-guide.md)
- [测试规则](test-rules.md)

没了。核心信息全在四个链接里。Agent 打开新窗口 → 读 CLAUDE.md → 发现是目录 → 读 coding-style.md → 读 build-workflow.md → 读 hal-guide.md → 读 test-rules.md → 五个文件读完，总算知道怎么写了。

每开一次新窗口，重复一遍这个过程。每次都要纠正同样的错误。

改：读第一段就能写代码

网上找了一圈 CLAUDE.md 最佳实践，核心原则就一条：自包含。

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

Agent 的疑问	原来的回答	改完后的回答
我是谁？	没说	"你是固件开发助手，用 C 语言，Keil MDK"
干什么？	没说	"写驱动→编测试→跑仿真，编译用 armcc"
怎么开始？	读五个文件才知道	"立即开始"代码块，三条命令

"绝对禁止"从散落各处集中到 CLAUDE.md 第四段——不改 HAL 层、不动链接脚本、不碰 bootloader。Agent 不用翻五个文件才能凑齐禁区清单。

详细的编码规范、构建流程保留在链接文件里，Agent 需要时才翻。但不是一上来就要翻。

改造前后对比

	改之前	改之后
CLAUDE.md	链接目录	自包含，第一段能写代码
启动速度	不知道从哪开始	"立即开始"代码块，三条命令
错误反馈	没有纠错机制	"犯错后立刻更新 CLAUDE.md"
"禁区"规则	散落各处	集中在一个段落
代码风格	没写	"变量加 s_ 前缀，函数判 NULL"

五个关键设计

1. 第一段就回答"三个什么"

你是谁 → 干什么 → 有什么约束

Agent 读完第一段就知道自己的角色、要完成什么任务、什么不能碰。不需要翻页。

2. "立即开始"代码块

直接给可复制的命令，不是描述。Agent 看到就能执行。

# 编译
armcc -c --cpu Cortex-M3 -g main.c

# 跑测试
make test

# 烧录
openocd -f board/stm32f4discovery.cfg -c "program build/firmware.elf verify reset"

3. "绝对禁止"集中放

不要分散到各个文件。Agent 一次读完就知道什么不能碰。

典型的代码项目禁区：

• 不改 HAL 层自动生成的代码
• 不动链接脚本（.ld/.sct）
• 不碰 bootloader 目录
• 不提交 .env 和密钥文件
• 不自己加第三方库（先问）

4. "犯错后立刻更新记忆"

这是最重要的机制。每次 AI 犯了一个会重复犯的错，立刻写到 CLAUDE.md 里。

例子：

• Agent 每次都在函数里不判 NULL → 加"所有公开函数第一行判 NULL"
• Agent 总把结构体名泄漏到代码里 → 加"项目结构体名用通用名替代"
• Agent 写的注释又臭又长 → 加"注释一行说完，不写多行文档注释"

不做这一步，同一个坑踩十次。

5. 新窗口的打开语写进项目

很多人换了新窗口不知道怎么跟 Agent 说。把标准打开语写在项目 README 里：

打开 CLAUDE.md，然后帮我写 XXX 模块的驱动。

或者项目配置了 CLAUDE.md 自动加载，直接说需求就行。

CLAUDE.md vs MEMORY.md vs AGENTS.md

	CLAUDE.md	MEMORY.md	AGENTS.md
加载方式	Claude Code 自动读取	需手动让 Agent 读	Cursor/Copilot 自动读取
作用域	全局→项目→子目录逐级合并	自定义目录	单文件，仓库根目录
适合场景	Claude Code 用户	项目专属持久化记忆	多工具团队统一配置

如果你的团队有人用 Cursor 有人用 Claude Code，建一个 AGENTS.md 再软链接：

ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md .cursorrules

一份内容，所有工具都能读。

怎么检查你的文件写得好不好

打开一个新窗口，让 Agent 开始写代码，看它第一轮输出：

• 好：Agent 直接开始写，风格对、约束对、没踩禁区
• 差：Agent 问"这个项目是干什么的？""用什么编译？"——入口文件没写清楚
• 很差：Agent 开始翻文件、读目录结构、探索项目——你的入口文件就是个目录，它在自己找路

用这个标准检查一遍，改到 Agent 第一段代码就写对为止。

---

实测对比：改之前: 新窗口读 5 个文件才能干活 | 改之后: 读 1 段就开始

有用的话点个收藏，下次调试直接用。有问题欢迎评论区交流，看到了都会回。

下一篇：一天学完15个源文件——DeepSeek看图、AI当老师、AI审查代码、省Token技巧——用AI加速嵌入式开发