TL;DR大仓库的解法不是把 AGENTS.md 写厚，而是拆薄：根目录放地图与全局约定，子目录放模块细节。r/codex 实战帖走通了这条路，这篇把做法拆成七步。
来源信号 SOURCES
以下内容整理自社区公开讨论，本页只做拆解与核实，不搬运原帖；观点归属原作者。
Reddit r/codex ·「My AGENTS.md file」实战帖 · 静态仓库分析与上下文拆分查看原帖 ↗Codersera · AGENTS.md Complete Guide 2026 · 规范与示例查看原帖 ↗
事实性知识 FACTS
这些是讨论中被多方印证、或可对照官方文档核实的事实。
- AGENTS.md 是 Linux Foundation 开放的纯 Markdown 标准，可以在仓库内按目录分层放置。
- r/codex 实战帖的做法有两步：先让代理做静态仓库分析产出仓库地图，再把上下文按层拆进多份 AGENTS.md。
- 官方最佳实践支持这个方向：长期有效的指令沉淀进 AGENTS.md——放常驻约定，不放一次性任务。
- 社区指南（Codersera 等）系统整理过 AGENTS.md 的规范与示例，分层拆分在规范层面站得住。
概念性知识 CONCEPTS
社区讨论里的概念不全是事实——每条都标注了它的性质，读之前先看标签。
静态仓库分析已验证事实
让代理只读不改，产出目录职责、入口文件与依赖关系的仓库地图。r/codex 实战帖的起点动作。
分层指令已验证事实
全局约定放根目录，模块特有约定放子目录，让指令跟着模块走。实战帖采用、社区指南支持的做法。
大仓库迷路个人观点
社区对「代理在大型代码库里读错文件、改错模块」现象的统称。现象被广泛报告，但成因分析与解法效果多为个人经验。
拆分命中率待验证假设
「分层之后代理首次命中正确文件的比例明显提高」这类断言，目前以单点经验为主，缺公开对照数据。
场景 SOP STEP BY STEP
目标把一个大仓库改造成 Codex 能自助导航的形态：一层地图、多层模块说明，新会话不再从零摸。
前提仓库较大（多模块或多目录）；有根目录 AGENTS.md 或准备从零建。
- 01只读分析
启动
codex，第一句声明「本轮只读不改」，让它产出仓库地图：目录职责、入口文件、模块依赖。 - 02人工核图
对照你自己的理解改正错漏。代理猜错的模块关系留在地图里，以后每次都会被带偏。
- 03根目录放地图层
把核好的总览与目录索引写进根 AGENTS.md，外加全局约定：命令、规范、禁区。
- 04子目录放模块层
核心模块各放一份简短的 AGENTS.md，只写该模块特有的约定，不重复全局内容。
- 05开工指路
新任务开场点名「先读根目录与某某模块的 AGENTS.md」，把导航主动权留给自己。
- 06换模块验收
去一个没改过的模块提小需求，看它能否找对文件、用对约定。
- 07随重构更新
大重构合并后，同步更新受影响模块的地图与模块层，地图过期比没有更危险。
结果根目录一份地图、核心模块各一份说明；换模块提需求时 Codex 能自行定位，不再从头摸起。
看完之后 NEXT
想知道今天的重置判定？回到 首页实时雷达。