# .mdd 工作区布局

模块驱动开发的所有产物都放在项目根下的 `.mdd/` 目录。布局如下：

```
.mdd/
├── manifest.md          # 模块树总表（唯一入口）
├── designs/             # 每模块一份设计文档：designs/<module-id>.md
├── code/                # 每模块一个代码目录：code/<module-id>/
├── change-requests/     # 需求变更请求：change-requests/<seq>-<slug>.md
├── archive/             # 设计变更时的旧代码归档：archive/<module-id>/rev-<n>/
└── logs/                # 调度与报告：
    ├── schedule.md              # 主 agent 的派单流水（谁/何时/结果）
    ├── impact-<seq>.md          # 变更分析师的受影响模块分析
    └── <module-id>/report.md    # 每个模块实现 agent 的交付报告
```

## 1. manifest.md（模块树总表）

每个模块一行，字段（用 Markdown 表格或 YAML 均可，但**整份文件保持一种格式**）：

| 字段 | 含义 | 取值示例 |
|------|------|----------|
| id | 模块唯一 id（kebab-case 路径） | `auth/oauth` |
| name | 职责短语 | `OAuth 登录` |
| parent | 父模块 id（根模块为空） | `auth` |
| depends_on | 依赖的模块 id 列表 | `common/contracts, data/users-store` |
| status | 生命周期状态 | `planned / designed / implemented / integrated / changed` |
| revision | 对应 design 文档的最新修订号 | `2` |

维护规则：

- manifest 是唯一入口：新模块先登记，再设计，再派单；
- 每完成一个阶段就更新对应模块的 status；
- 设计变更走完 P6 后，revision 必须等于 design.md 修订历史中的最新号；
- code/ 下只允许存在 manifest 中登记的模块目录。

## 2. designs/<module-id>.md

每模块一份，用 `templates/module-design.md` 模板。设计文档是唯一事实来源：

- 对外契约（接口、数据结构、事件）以这里为准，代码必须与之一致；
- 修订历史记录每次变更（revision 递增），作为"重新生成"的触发依据。

## 3. code/<module-id>/

模块实现 agent 的全部输出。结构由模块设计决定（如 `src/`、`tests/`、配置文件）。

- 只允许该模块的 owner 写入；
- 设计变更时整目录移入 archive，原目录从零重建。

## 4. change-requests/<seq>-<slug>.md

需求调整的正式记录（模板见 `templates/change-request.md`）。seq 从 1 递增。

## 5. archive/<module-id>/rev-<n>/

设计变更时旧代码的快照。命名含被替换的 revision 号，例如 `archive/auth/rev-1/`。

- 用途：查阅参考、追溯历史；
- 纪律：归档代码**不得**被复制为新实现的基础（新代码必须从新设计重新生成）。

## 6. logs/

- `schedule.md`：主 agent 的派单流水，追加式记录：时间 / 目标模块 / agent 任务 / 结果（成功、失败原因、重派次数、去向）。
- `impact-<seq>.md`：变更分析师输出，对应第 <seq> 份 change-request。
- `<module-id>/report.md`：模块实现 agent 的交付报告（做了什么、怎么运行、自测结论、遗留问题）。