一句话: 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加速嵌入式开发
