AI 协作的双层文档架构原则
核心目标
让 AI 更快进入正确工作模式，而不是每次都重新理解项目。
文档不是越多越好，关键是 高密度、低歧义、可复用。
一、总原则
1. rules 不是越长越好
AI 上下文资产要追求 高密度，不是高篇幅。
关键不是少写，而是：
- 只保留稳定规则
- 不写解释性废话
- 不写代码导览
- 不写实现碎细节
- 不把“一次性阅读信息”和“长期协作规则”混在一起
一句话： 常驻上下文放规则，按需上下文放说明。
二、双层架构
第一层：常驻规则层
目标
每次都能喂给 AI，帮助它快速进入正确工作模式。
特点
- 短
- 硬
- 稳定
- 低歧义
- 高复用
第一层建议放 5 类内容
1. 全局通用规则
适用于整个项目的基础工程规则，例如：
- engineering principles
- 命名规范
- 分层原则
- 复用 / 抽象 / 扩展原则
- 通用 do / don’t
2. 项目级硬规则
不是所有项目通用，但在这个项目里长期成立的规则，例如：
- low-code 项目的系统边界
- renderer / metadata / schema / editor 的职责划分
- 哪些层不能乱串
- 哪些历史坑禁止继续沿用
3. 核心系统最小规则
针对 condition / directive / handle / source / action 这类核心系统，只保留最小规则骨架，例如：
- purpose
- core contracts
- boundary
- invariants
- canonical entry points
- do / don’t
4. 项目心智地图
这是 AI 的导航图，不是大而全说明文。
应回答：
- 这个项目的主链路是什么
- schema、metadata、renderer、editor 各处于哪一层
- 常见修改应该落在哪一层
- 系统之间怎么连接
5. 修改决策规则
这是第一层里非常关键但最容易缺的一层。
它回答的不是“项目是什么”，而是：
- 遇到需求应该改哪一层
- 什么时候改 metadata，不该改 renderer
- 什么时候该抽共享工具
- 什么时候先补 rules，不先动代码
- 什么时候应该做 canonical 收口
第二层：按需深入层
目标
只有在深入改某个系统时才加载。
特点
- 解释性
- 实现性
- 可变动
- 局部加载
第二层适合放
- 实现细节
- 文件位置
- 详细执行流程
- 历史演进说明
- gotchas
- 示例
- 技术债
- 重构计划
- 兼容逻辑
- 临时行为说明
一句话： 第二层服务深入实现，不服务快速进入工作模式。
三、第一层 / 第二层的判断标准
该放第一层的标准
满足 3 条里的 2 条就放第一层：
- 几乎每次协作都会用到
- 是稳定规则，不是当前实现偶然细节
- 不知道它，AI 很容易改错方向
该放第二层的标准
满足任意 1 条就下沉：
- 只有改到特定系统时才需要
- 主要是实现细节
- 可能随重构变化
- 更像说明，不像规则
- 例子、展开解释、历史背景偏多
四、写 rules 的取舍原则
应该写进 rules 的
- 系统目的
- 核心契约
- ownership boundary
- invariants
- canonical entry points
- editor vs runtime 职责差异
- 明确禁止事项
- 明确未实现、禁止依赖的点
不应该塞进 rules 的
- 大段背景说明
- 为什么这样设计的长解释
- 文件列表导览
- 过细的执行步骤
- 零散 gotchas
- 当前实现细节但不属于稳定规则的内容
五、第一层文档的理想结构
每份核心 rules 文档尽量控制在短小高密度范围内。
推荐结构：
- Purpose
- Core Contracts
- Ownership Boundary
- Invariants
- Canonical Entry Points
- Do / Don’t
- Related Systems
这就够了。
不要再额外堆背景、文件路径、长篇解释。
六、抽象时最关键的判断
1. 先区分“规则”还是“说明”
先问自己：
- 这是长期稳定规则，还是当前实现说明？
- 重构以后它还成立吗？
- 它是在指导未来修改，还是只是在解释今天的代码？
如果只是解释今天的代码，就不该放第一层。
2. 先区分“不变量”还是“当前行为”
不要把这两种东西混在一起。
不变量
- 改了就等于系统语义变了
- 应该长期稳定
- 应该明确写进 rules
当前行为
- 今天代码这样实现
- 以后可以调整
- 更适合放第二层 notes
3. 抽象只抽“稳定共性”
不是代码像，就该抽。
只有同时满足这些条件，才值得抽象：
- 重复出现
- 概念上是同一类问题
- 职责归属相同
- 抽完以后能减少未来判断成本
好的抽象结果应该是：
- 输入输出清晰
- 责任稳定
- 不隐藏语义
- 能成为 canonical entry point
七、最实用的一句话
第一层解决“AI 该怎么想”，第二层解决“AI 具体怎么做”。
八、最终原则
文档分层的目的，不是为了整理得漂亮，
而是为了让 AI：
- 更快进入正确语境
- 更少改错层
- 更少重复理解
- 更稳定复用已有规则
- 更容易形成统一风格
所以最终追求的不是“写更多”，而是：
把真正高价值、稳定、会影响决策的内容，放进第一层。
