开发者设计出适配AI驱动开发的分层文档结构

这是一份 AI 驱动开发的文档：目前规格和计划已经超过 40 个文件、1 万行，已经无法总览整体。

AI 代理可以读写 Markdown，但对人类来说阅读太痛苦。但如果转成 HTML，就无法在 GitHub 上直接阅读。我和 Claude + Codex 讨论出了一个能同时满足两者需求的结构。

结论是分成三层：
1. Markdown 树是原始文件
2. 人工手写的内容只有顶层的 README.md 这一个文件 = 链接集合，不按文件夹列表排列，而是按产品结构排列，每个条目只保留指向原始文件的链接
3. 用 pandoc 生成和 Markdown 相同文件夹结构的镜像 HTML 树，然后把 HTML 加入 gitignore。人类阅读只看这里，入口是 README.md → index.html

针对内容不一致的应对方案，是用设计而非规则解决问题：README 只能写入「原始文件明确记载内容的压缩总结」= 不能添加独有的新内容。因此大部分对 Markdown 的细节修改都不需要更新 README。

剩下需要处理的只有 AGENTS.md 里的一行约定，以及检查链接失效、规格覆盖、标题格式的检查脚本（内容含义的同步不通过机器强制）。

我很喜欢这个设计的点在于角色完全分离：Markdown = 给 AI 代理、给 GitHub 使用，生成的 HTML = 给人类在本地阅读使用（自带自动目录），assets 文件夹存放通用的 css 和 js。

人类需要维护的只有 README 这一个文件，团队所有成员只需要在本地运行 pandoc 脚本即可。