仓库即知识系统：给 Agent 一张地图

Agent 无法访问的信息等于不存在。仓库是 Agent 的唯一真实来源。

"一个大 AGENTS.md" 为什么失败

OpenAI 团队最初尝试把所有指导塞进一个巨大的指令文件，结果四个问题同时爆发：

问题	原因
上下文被挤占	巨大文件占据了任务和代码的空间
一切重要 = 没有重要	Agent 局部模式匹配，而非有意导航
瞬间腐化	人类停止维护，规则变成过期陷阱
无法验证	单一文件无法做机械化检查

正确做法：目录，不是百科全书

AGENTS.md ≈ 100 行，只做一件事：指向更深的信息源。

ARCHITECTURE.md
├── design-docs/         # 设计文档，含验证状态
├── exec-plans/          # 执行计划（活跃 / 完成 / 技术债）
├── product-specs/       # 产品规格
├── references/          # 外部技术参考
├── generated/           # 自动生成的文档（如 DB schema）
├── DESIGN.md
├── FRONTEND.md
├── QUALITY_SCORE.md     # 按领域评分，追踪差距
└── SECURITY.md

渐进式披露 (Progressive Disclosure)

Agent 从稳定的小入口开始
被引导到需要时才访问的深层文档
而非一上来就被淹没

机械化维护

Linter + CI：验证知识库的时效性、交叉链接、结构正确性
"文档园丁" Agent：定期扫描过时文档，自动开 PR 修复

关键原则

Agent 看不到的 = 不存在的

Slack 讨论、会议决策 → 必须沉淀到仓库
像为新员工做 onboarding 一样组织信息
偏好"无聊"技术：可组合性好、API 稳定、训练数据覆盖充分
有时自己实现功能，优于依赖行为不透明的第三方库