AGENTS.md 终极写法：让 AI 真正「读懂你」

💡 看完这一篇，你再也不需要第二篇 Codex 入门教程

——AGENTS.md 终极写法：让 AI 真正「读懂你」

🪝

过去两篇我们搭好了骨架，避开了坑。

但我有一件事一直没说透：

为什么同样一套 Codex + Obsidian，有人用起来像开了外挂，有人用起来还是觉得「也没什么特别的」？

我问过身边用这套系统的朋友，把他们的 AGENTS.md 截图发给我看。

结论几乎是一样的：用得好的人，AGENTS.md 写得很具体；用得不好的人，AGENTS.md 要么空着，要么只有两行废话。

4 AGENTS.md 是 Codex 执行任何工作之前首先读取的文件，通过「全局配置 + 项目级覆写」的层级机制，让每次任务都能继承一致的工作约定，无论你打开的是哪个仓库。

它是整个系统的大脑里的「操作系统」。

而大多数人装了操作系统，却没有设置自己的用户偏好。

这篇文章，我把我迭代了 5 个版本、用了 3 个月 的 AGENTS.md 全部公开，带你逐行搞懂每个字段为什么这样写。

读完这篇，你不需要再看任何其他 Codex 入门教程。

「工具认识你，才能替你工作。AGENTS.md 是你和 AI 之间最重要的那份自我介绍。」

📖 先理解 AGENTS.md 的运作机制

很多人把 AGENTS.md 当成一个「配置文件」，觉得它是技术性的东西，和自己没关系。

其实不是。

你可以把它想象成两个角色之间的一份「工作协议」：

text

你（知识库的主人）
    ↕
  AGENTS.md
（你们之间的规则文件）
    ↕
Codex（你的 AI 助理）

每次你打开 Codex 开始工作，它做的第一件事，就是读 AGENTS.md。

它从这里知道：你是谁，你的知识库长什么样，你喜欢什么风格的输出，什么时候需要问你确认，什么时候可以直接执行。

写得越具体，它出错的概率越低，越「懂你」。

AGENTS.md 一共支持两个层级：

建议两个都写：全局写你的基础身份和通用偏好，项目级写知识库的具体规则。项目级的规则会覆盖全局规则。

🔧 AGENTS.md 完整模板（第 5 版，可直接复用）

下面是我目前在用的版本，按模块逐一解释每个字段的作用：

模块 1：身份定义

Markdown

# 关于我
## 我是谁
- 身份：内容创作者 + 知识工作者
- 核心关注领域：个人成长、AI 工具、PKM（个人知识管理）
- 当前主要项目：
  - 系列文章：Codex + Obsidian 知识库搭建教程
  - 个人成长记录：100天认知复盘
  - 读书系统：年度 50 本读书计划
## 我的输出目标
- 公众号长文（2000-3500字，深度方法论向）
- B站视频脚本（8-15分钟，保姆教程向）
- Obsidian 知识页（成熟概念，可被引用）

为什么这样写：

告诉 Codex 你是谁，它在帮你整理知识时会优先考虑「这对内容创作有没有用」，而不是泛泛地给你学术式的总结。

模块 2：知识库结构规范

Markdown

# 知识库结构
## 文件夹说明
- `Inbox/`：原始输入区
  - 所有新内容先放这里
  - 不要求格式，允许凌乱
  - 超过 3 天未处理的笔记需要提醒我
- `raw/`：整理层
  - 经过一次结构化处理的资料
  - 必须有 frontmatter
  - status 字段标记处理进度
- `wiki/`：成熟知识层
  - 可以被其他笔记直接引用的成熟概念页
  - 修改前必须告知我，获得确认
  - 鼓励双向链接
- `daily/`：每日笔记
  - 每天的随手记、复盘、待办
  - 格式：YYYY-MM-DD.md
## Frontmatter 规范
所有 raw/ 和 wiki/ 下的笔记必须包含：
---
date: YYYY-MM-DD
tags: [标签1, 标签2]
status: draft | reviewing | published
source: 来源（书名/URL/个人思考）
related: 相关笔记1, 相关笔记2
---

为什么这样写：

结构规范是让 AI 能够「系统性工作」的前提。如果它不知道你的文件夹代表什么，它就只能猜。猜出来的结果，你会觉得「感觉没什么用」。

模块 3：工作规则（最重要）

Markdown

# 工作规则
## 必须遵守的红线（不得违反）
1. 未经我明确确认，不删除任何已有笔记内容
2. 未经我确认，不修改 wiki/ 下已标记为 published 的笔记
3. 任何批量操作（超过 10 个文件）执行前，先列出操作清单等我确认
## 鼓励主动做的事
1. 在整理笔记时，主动发现可以添加的双向链接，并告知我
2. 如果发现 raw/ 下某篇笔记的质量已经可以晋升到 wiki/，主动提醒我
3. 发现知识库里的「孤立节点」（没有任何链接的笔记），定期报告给我
## 什么时候需要问我
- 发现笔记内容有明显矛盾或过时信息时
- 不确定某篇笔记应该归档到 raw/ 还是 wiki/ 时
- 一个任务需要超出授权范围操作时
## 默认行为
- 如果我没有特别说明输出格式，默认用 Markdown
- 如果我没有说明语言，默认用中文
- 如果任务模糊，先问清楚再执行，不要猜测

为什么这样写：

工作规则是「防错机制」。越清晰的规则，AI 自作主张的空间越小，你的笔记越安全。

「不是 AI 不够聪明，是规则写得不够清楚，给了它太大的猜测空间。」

模块 4：输出偏好

Markdown

# 我的输出偏好
## 风格
- 语气：像一个靠谱的朋友在分享，不要居高临下
- 句式：短句为主，节奏明快
- 避免：过度使用"您"，避免"请注意"这种机器感强的措辞
## 结构偏好
- 先给结论/一句话总结，再展开论据
- 复杂概念给我两个版本：「一句话版本」+ 「详细版本」
- 步骤类内容用有序列表，并列内容用无序列表
## 知识整理偏好
- 每次整理资料，给我提炼 3-5 个「可以直接使用的核心观点」
- 如果原文有可以单独传播的金句，单独标注出来
- 概念解释时，优先用类比和隐喻帮我理解
## 我不喜欢的表达方式
- 「你应该...」→ 改为「一种方式是...」
- 「值得注意的是...」→ 直接说内容
- 「综上所述...」→ 不要这样的套话结尾

为什么这样写：

这个模块决定了 Codex 输出的「味道」。写清楚你的偏好，你会发现它的回复越来越像「你的风格」，而不是一个通用 AI 助理的感觉。

模块 5：常用任务快捷定义

Markdown

# 常用任务说明
## 当我说「处理 Inbox」时，你要做：
1. 读取 Inbox/ 下所有新笔记
2. 为每篇笔记提炼 3 个核心观点
3. 在 raw/ 下创建结构化摘要页（加上 frontmatter）
4. 检查 wiki/ 下是否有可以关联的已有笔记
5. 如有关联，在摘要页结尾加上 related 链接
6. 把处理完的原始笔记移到 raw/processed/ 文件夹归档
## 当我说「做周复盘」时，你要做：
1. 读取本周 daily/ 下所有日记
2. 提炼本周核心事件、主要收获、未完成事项
3. 生成一份「周复盘报告」存入 daily/weekly/
4. 检查本周 raw/ 下新增的笔记，推荐 3 篇晋升到 wiki/
## 当我说「知识库体检」时，你要做：
1. 列出 Inbox/ 下超过 3 天未处理的笔记
2. 列出 raw/ 下 status=draft 且超过 2 周未更新的笔记
3. 列出 wiki/ 下没有任何入链的孤立页面
4. 输出一份「知识库健康报告」
## 当我说「整理这篇」+ 附上内容时，你要做：
1. 提炼核心观点（3-5条）
2. 找出可独立传播的金句（如有）
3. 在 raw/ 创建结构化摘要页
4. 推荐关联的 wiki/ 页面

为什么这样写：

这是「快捷指令」的概念。把你最常用的任务预先定义好，以后一句话就能触发完整的工作流，不需要每次都写一大段指令。

「把你的经验沉淀为可复用的规则——这不只是知识管理的方式，也是个人 IP 的护城河。」

模块 6：我的知识框架参考

Markdown

# 我正在构建的知识框架
## 核心概念体系
（这里放你正在深耕的核心概念，让 AI 整理资料时优先向这些方向关联）
- PKM - 个人知识管理体系
- 第二大脑 - AI 辅助知识库的概念
- 长期主义 - 时间维度的价值思考
- 认知进化 - 思维方式的迭代记录
- 知识复利 - 知识积累的复利效应
## 我在追踪的问题
（这些是你正在思考的开放问题，AI 在整理新资料时会主动与这些问题关联）
- 如何让知识库从「存档工具」变成「思考参与者」？
- 个人成长的哪些维度是可以被量化和追踪的？
- 一套知识管理系统如何能够「自生长」而不依赖纪律维护？

为什么这样写：

这个模块是最高级的设置，也是最多人忽略的。

5 当知识库开始吸收新问题而不只是吸收新资料，这才是一个系统会持续长起来的信号。

告诉 AI 你在追踪的问题，它在整理每一篇新资料时，都会自动检查「这和我的问题有没有关系」——这才是「第二大脑」真正参与你思考的方式。

📊 5 个版本的迭代对比

✅ 三步写出你自己的 AGENTS.md

第一步：复制我的模板框架 把上面的模块全部复制进去，先不要改内容。

第二步：替换成你自己的信息 逐个模块，把我的内容换成你真实的情况——你的身份、你的文件夹结构、你的输出偏好。

第三步：跑通之后开始迭代 用一周之后，看看哪些地方 Codex 还是「猜错了」，把那个场景加进规则里。AGENTS.md 是一个活的文件，它应该随着你对系统的理解一起成长。

❓ 常见问题

Q：AGENTS.md 写多长合适？ A：没有上限，但也不要为了写而写。我现在的版本大约 600 字，5 个模块。建议从 3 个核心模块开始（结构规范 + 工作规则 + 常用任务），后面慢慢补充。

Q：AGENTS.md 写了但感觉 Codex 没有遵守？ A：检查文件是否放在正确路径，以及 Codex 版本是否支持 AGENTS.md（v0.135.0+ 以上版本完整支持）。

Q：全局 AGENTS.md 和项目级 AGENTS.md 冲突了怎么办？ A：项目级覆盖全局，优先级更高。如果两者有矛盾，Codex 会遵循项目级的规则。

🔮 下一步

你现在已经有了：

• ✅ 一个搭好的 Codex + Obsidian 知识库骨架（第 1 篇）
• ✅ 7 大踩坑已经全部避开（第 2 篇）
• ✅ 一份让 AI 真正「懂你」的 AGENTS.md（本篇）

接下来缺的最后一块拼图，是让整个系统开始「自动运转」。

下一篇，我会带你搭建一个完整的「一个下午，陪你成长 10 年」的知识系统架构——从顶层设计到具体路径，把这套系统的长期主义逻辑彻底讲清楚。

「AGENTS.md 不是一次性配置，它是你和 AI 之间持续进化的工作协议——你对自己的理解越深，它就越懂你。」