AGENTS.md 只当目录，细节放 docs/index.md
主文件只教怎么找上下文。架构、领域和跨目录概念放到带 index.md 和 @tag 的文档树。
AGENTS.md 适合当入口，不适合当百科。社区里一套可执行的拆法：
AGENTS.md只写导航：先搜哪、必读哪份、完成后要不要回写文档- 结构化说明进
docs/，每个有意义的目录放index.md，用一两句话指向子页 - 跨目录概念用
@tag:auth-bootstrap这类记号同时标在文档和代码注释里 - 用一份短的
docs/tags.md给每个 tag 一个含义，避免同名乱飘
这仍然是 Markdown + 文本搜索，不依赖某家 IDE 的向量索引。Codex、人类和 rg 走同一层。
不要把临时环境状态写进这棵树。瞬时事实让它开工时自己探测。