# 三轨文档体系 + 五层设计哲学

> 本文件定义了文档系统的核心理论基础。技能的所有推导和生成工作都基于此哲学。
> 当需要向用户解释"为什么这样设计文档系统"时，读取本文件。

---

## 三轨文档体系

任何软件项目都存在三类不同的"真相"，对应三轨：

### 🔴 Intent 轨（意图轨）

| 属性 | 值 |
|------|---|
| 回答的问题 | "最初打算怎么做" / "为什么要这样设计" |
| 真相源 | 人类意图 |
| 时间属性 | 冻结——编码前创建后冻结 |
| 对齐方向 | 不对齐——忠实记录原始设计意图 |
| 维护时机 | 编码前创建，只通过新的变更流程修改 |
| 典型读者 | 人类（理解设计动机） |
| 模板倾向 | 固定模板或全结构统一 |

**核心原则**：Intent 轨文档不试图与代码保持一致，而是忠实地记录编码前的设计意图。如果实现偏离了设计，不是修改 Intent 轨，而是通过新的变更流程记录偏离。

**存放位置建议**：`openspec/specs/`、`docs/design/`、`specs/`、或项目已有的设计文档目录。

### 🟢 Contract 轨（合同轨）

| 属性 | 值 |
|------|---|
| 回答的问题 | "代码现在是什么样" |
| 真相源 | 代码 |
| 时间属性 | 实时跟随——代码变了文档跟着变 |
| 对齐方向 | 代码→文档 |
| 维护时机 | 代码变更时立即更新 |
| 典型读者 | 人类+AI（API/配置参考） |
| 模板倾向 | 取决于分组 |

**核心原则**：Contract 轨文档的真相源是代码。当代码变更时，文档必须同步更新。

**存放位置建议**：`docs/modules/`、`docs/architecture/`、`docs/api/`、或项目已有的参考文档目录。

### 🔵 Constraint 轨（约束轨）

| 属性 | 值 |
|------|---|
| 回答的问题 | "代码应该遵守什么规则" |
| 真相源 | 团队共识 |
| 时间属性 | 阶段性——规则变更时更新 |
| 对齐方向 | 文档→代码 |
| 维护时机 | 约束变更时更新 |
| 典型读者 | AI（可执行规则） |
| 模板倾向 | 外壳统一 |

**核心原则**：Constraint 轨文档驱动代码。新代码必须遵守文档中定义的规则。

**存放位置建议**：`docs/conventions/`、`docs/standards/`、`docs/guidelines/`、或项目已有的规范目录。

---

## 三轨的区分标准

| 区分维度 | Intent | Contract | Constraint |
|---------|--------|----------|------------|
| 时间维度 | 编码前 | 编码后 | 持续 |
| 方向维度 | 不对齐 | 代码→文档 | 文档→代码 |
| 变更频率 | 极低（冻结） | 高（跟随代码） | 低（规则变更） |
| 维护者 | 👤 人类 | 🤖/🤖👤 | 🤖👤 |

### 快速判定流程

```
这份文档的内容能直接从代码推断吗？
├── 能 → 它是代码的真相吗？
│        ├── 是 → Contract 轨（代码→文档）
│        └── 否 → 它在约束代码吗？
│                 └── 是 → Constraint 轨（文档→代码）
└── 不能 → 它记录设计意图吗？
          └── 是 → Intent 轨（冻结）
```

---

## 五层设计哲学

与技术栈无关的五个原则：

### 哲学一：信息论——"每份文档只说一件事"

每份文档有且仅有一个职责，能用一句话概括。如果两份文档回答同一个问题，合并或重新切分。

**验证**：读完文档标题后，能否用一句话概括这份文档在说什么？

### 哲学二：时间论——"真相源有时间维度"

设计文档（编码前）和参考文档（编码后）有不同的时间属性。参见三轨体系。

### 哲学三：方向论——"对齐有方向性"

Contract 是代码→文档（代码变了文档跟着变），Constraint 是文档→代码（规则定了代码必须遵守）。

方向决定了：谁是对的（真相源）、什么时候更新（触发时机）、怎么验证（漂移检测方式）。

### 哲学四：确定性论——"维护有确定程度"

```
能从代码/配置直接推断？ ── 是 ──▶ 🤖 AI 自主
     │
     否
     ↓
需要理解业务/设计意图？ ── 是 ──▶ 🤖👤 AI 提议，人类确认
     │
     否
     ↓
需要原创思考/团队共识？ ── 是 ──▶ 👤 人类主导
```

### 哲学五：读者论——"文档有不同的读者"

| 读者 | 需求 | 文档风格 |
|------|------|---------|
| AI Agent | 精确规则，步骤可闭环 | 编号步骤 + 代码示例 + 检查清单 |
| 人类开发者 | 充足上下文，可理解 | Mermaid 图 + 段落说明 + 对比表格 |

---

## 跨领域验证

三轨+五层哲学已在 16+ 领域验证通过：Java Web、React/Vue SPA、Next.js、C++ 系统编程、Unity/Unreal 游戏开发、STM32 嵌入式、Electron/Qt 桌面应用、微服务集群、DevOps/Infra、数据工程、ML/AI、CLI 工具、移动端、区块链、内核开发、IoT、编译器、RTOS、FPGA/HDL、数据库内核。

核心原因：任何软件项目都存在三类真相（"为什么要这样设计"、"代码现在是什么样"、"代码应该遵守什么"），与具体技术栈无关。