给 Agent 做代码库说明文件，我用的三个层次

第一层：全局 CLAUDE.md
项目是什么、怎么跑、目录干什么、硬约束。控制在 100 行内。

第二层：模块说明（每个主要目录一个）
这个模块的职责边界、对外接口、内部结构、已知的坑。每份 30 行左右。

第三层：文件头注释
每个复杂文件顶部写三行：这个文件解决什么问题、依赖谁、被谁依赖。

三层的好处是渐进式加载。简单任务只读第一层，深入某个模块再读第二层，改具体文件看第三层。

维护成本主要在第三层，但它对新人和 Agent 的价值最大。