# 文档分层约定

> 

本文档约束 Dujie 语言文档的分层方式，避免设计讨论、实现细则和用户指南混写。

## 目标

<steps level="4">

#### 将语言设计与用户说明分离

#### 让设计讨论有固定落点

#### 让用户文档只呈现收敛后的规则

#### 降低 README 和各类文档之间的漂移

</steps>

## 文档分工

### `00.guide`

面向语言使用者。

适合写：

- 稳定语法
- 已确认的语义
- 用法示例
- 最佳实践
- 常见限制和注意事项

不适合写：

- 尚未定案的设计讨论
- 多个备选方案的比较
- 编译器内部实现细节
- 语义仍在调整中的规则

### `01.design`

面向语言设计者和编译器开发者。

适合写：

- 新语法提案
- 语义定义和边界条件
- 设计动机与取舍
- CST / AST / 类型系统 / 代码生成影响
- 与既有设计的兼容性分析
- 未决问题和后续实现计划

## 工作流程

### 1. 新设计先进入 `01.design`

凡是新增或修改语言规则，包括但不限于：

- 语法
- 语义
- 类型规则
- 约束系统
- 模块规则
- 运行时行为

都先在 `01.design` 中编写设计文档和细则。

### 2. 设计收敛后再同步到 `00.guide`

当设计已经明确到足以对外说明时，再将结果整理为用户文档：

- 去掉内部推导过程
- 去掉未定方案
- 保留稳定语法和清晰示例

### 3. 用户文档不抢先定义规则

`00.guide` 不应该先于 `01.design` 独立引入新的语言规则。

如果发现某条规则只写在 `00.guide`，而没有对应设计依据，应当回补到 `01.design`，再决定是否保留。

## 设计文档建议结构

每篇设计文档尽量包含以下内容：

<steps level="4">

#### 问题定义

#### 设计目标

#### 语法规则

#### 语义规则

#### 示例与反例

#### 与现有规则的关系

#### 实现影响

#### 未决问题

</steps>

## 维护约定

- 讨论中的规则，以 `01.design` 为主
- 对外说明中的规则，以 `00.guide` 为主
- 如果两边出现冲突，先修正 `01.design`，再同步更新 `00.guide`
- README 保持概览性质，不承担完整语言规范的职责