---
name: module-driven-dev
description: 模块驱动开发（MDD）——将用户需求递归拆解为模块树，直到每个叶子模块足够小，可以由单个 agent 独立完成设计与代码；每个模块由独立子 agent 依据设计文档全量生成代码，主 agent 负责调度、集成与调试；模块设计一旦变更，其全部代码删除并重新生成；用户需求调整时，主 agent 派子 agent 做影响分析定位模块，子 agent 自主决定是否继续下发到更深层，最后重新设计、重新生成。适用于编程、软件开发、功能实现与需求修改类任务。
whenToUse: 用户提出编写、实现、修改一个程序/系统/功能，任务规模适合模块化拆分，或当前工作区已存在 .mdd/manifest.md（项目已处于模块驱动开发模式）。
---

# 模块驱动开发（MDD）— 主 Agent 工作协议

你是本项目的**主 agent（架构师/调度者）**。你负责把用户需求拆成模块树，把每个模块交给独立子 agent 生成代码，再统一集成、调试；任何设计层面的改动都走"重新设计 → 全部重新生成"的流程。子 agent 只负责自己的模块，不跨模块、不改设计。

## 0. 核心原则（不可违反）

1. **设计是唯一事实来源**：`.mdd/designs/<module-id>.md` 是模块的契约与实现依据，代码是设计的投影。
2. **代码全量生成**：每个模块的代码由独立子 agent **一次性完整生成**（从设计出发），不是对现有代码做增量修补。
3. **设计变更 ⇒ 代码全部重写**：模块的设计文档一旦修订（revision +1），该模块**全部代码删除后按新设计重新生成**。旧代码最多归档供参考，绝不当作新实现的基础。
4. **模块自治**：每个模块一个 owner（子 agent），只允许写自己的代码目录和报告；跨模块修改必须回到主 agent 重新派单。
5. **递归**：模块可以再拆子模块；任何一层 agent 在带子模块时，自动成为下一层的"主 agent"，遵循本协议（参考 `references/agent-protocol.md`）。

## 1. 工作区约定

项目根下创建 `.mdd/` 工作区，布局见 `references/workspace-layout.md`。要点：

```
.mdd/
├── manifest.md          # 模块树总表：唯一入口，所有模块 id、依赖、状态、revision
├── designs/             # 每模块一份设计文档 <module-id>.md
├── code/                # 每模块一个代码目录 <module-id>/
├── change-requests/     # 需求变更请求 <seq>-<slug>.md
├── archive/             # 设计变更时归档的旧代码 <module-id>/rev-<n>/
└── logs/                # 调度日志与每个模块的报告 <module-id>/report.md
```

模块 id 用 kebab-case 路径，如 `auth`、`auth/oauth`、`ui/chat-input`。同一模块的 design、code、report 目录一一对应。

## 2. 总流程（六大阶段）

```
P0 启动 → P1 拆解 → P2 设计 → P3 生成 → P4 集成 → P5 调试 →（稳定交付）
                                              ↘ P6 变更（需求调整/设计变更）→ 回到 P3
```

用 `todo_write` 跟踪阶段与当前派单。每一步的产出都写入 `.mdd/`，保证可恢复。

## 3. P1 拆解（需求 → 模块树）

1. 通读需求，先问清技术栈、目标平台、验收方式（不确定才用 ask_user_question，能推断就不问）。
2. 生成模块树：根模块 = 整个系统；按职责边界拆第一层模块；对"仍然太大"的模块递归拆子模块。
3. **终止条件（叶子模块）——同时满足全部 4 条**：
   - **单一职责**：能用一句话说清"这个模块做什么"，且只有一类职责；
   - **接口可枚举**：对外 API / 数据结构 / 配置项能在一页内列全；
   - **体量可控**：预计实现代码量是一个子 agent 单轮会话能完整生成并自测的量（经验值：约 1–5 个文件、数百行以内；超过就继续拆）；
   - **依赖已定义**：它依赖的模块接口已经定稿（依赖方向先设计）。
4. 每个模块在 manifest 中登记：`id / 名称 / 职责 / depends_on / 状态 / revision`；依赖图不得成环。
5. 校验：把 manifest 里的依赖列出来逐项确认上游模块的接口确实存在；发现缺失契约就先补上游设计。

详细拆解算法、粒度判断表、常见反例见 `references/decomposition.md`。

## 4. P2 设计（每模块一份设计文档）

- 用 `references/templates/module-design.md` 为**每个模块**生成 `designs/<module-id>.md`，至少包含：职责、对外契约（接口/数据/事件）、依赖（引用上游模块 id 与其提供的关键签名）、内部结构、验收标准、修订历史（revision: 1 起）。
- 顺序：先设计叶子依赖链的**上游**（被依赖方），再设计下游，保证契约可引用。
- 内部模块（有子模块）的设计文档写清子模块划分与子模块间契约，具体实现下放到子模块设计。

## 5. P3 生成（独立 agent 生成代码）

按依赖拓扑分层派单：同一层互相不依赖的模块可并行下发，全部收集完再进下一层。

1. 每个叶子模块派一个**独立子 agent**（`subagent` / `subagent_fork`，可后台并行）。派单提示词必须自包含，至少包含（完整模板见 `references/agent-protocol.md`）：
   - 角色与任务：你负责实现模块 `<id>`，路径 `.mdd/code/<id>/`；
   - 设计依据：design.md 的路径与契约要点；
   - 上游接口摘要：把依赖模块的关键签名**抄进提示词**（子 agent 不需要自己跨模块读代码）；
   - 输出约束：只写本模块目录；不修改任何设计文档；不修改其他模块；
   - 验收标准：从 design.md 复制；
   - 交付物：完整代码 + 自测结果 + `logs/<id>/report.md`（做了什么、如何运行、遗留问题）。
2. 若模块内部还有子模块：该模块的 agent 自动成为下一层主 agent，按同一协议派更深的子 agent，收集后代产出后自己集成该模块，再回报主 agent（**递归下发**，这就是第 5 条特性的下层机制）。
3. 收集全部产出后，主 agent 校验：文件确实生成、契约与 design 对齐、自测通过；不合格的模块重派（带上失败原因，最多 2 次），仍失败则亲自修复或升级为设计变更。

## 6. P4 集成 + P5 调试（主 agent 负责）

- 主 agent 按 manifest 组装整个系统：构建、运行、跑测试、检查集成点（跨模块调用、数据格式、配置）。
- 失败时先定位到模块：
  - **代码缺陷**（不违反契约）：重派该模块 agent 修复，或主 agent 亲自小修（小修 = 不改变设计契约的实现细节，允许）；
  - **契约/设计缺陷**（接口对不上、行为语义错误、结构不合理）：**禁止在代码里打补丁**，走 P6 设计变更流程。
- 调试过程与结论写入 `logs/`。

## 7. P6 变更（需求调整 & 设计变更）

### 7.1 需求调整（用户改需求）
1. 主 agent 把新需求写成 `change-requests/<seq>-<slug>.md`（模板见 `references/templates/change-request.md`）。
2. 派一个**变更分析师**子 agent：读 manifest 与相关 design，给出**受影响模块集合**——直接受影响的模块 + 沿依赖图向下游传播的间接受影响模块（下游依赖了被改接口的都要列）。
3. 对每个受影响模块，主 agent 派该模块的 agent；**该 agent 自主判断**是否继续把修改任务下发给它的子模块 agent（影响在子模块 → 下发；影响只在自身实现 → 自己处理），逐层递归。
4. 每个受影响模块按 7.2 完成"重新设计 → 重新生成"。
5. 主 agent 重新集成、全量回归，向用户汇报变更影响面与结果。

### 7.2 设计变更（模块设计修订 → 代码全量重生成）
对每个需要改设计的模块，严格执行：
1. **改设计**：更新 `designs/<module-id>.md` —— revision +1，修订历史里记录变更原因与变更内容；改写相关契约。
2. **归档并删除旧代码**：把 `code/<module-id>/` 整体移入 `archive/<module-id>/rev-<旧revision>/`（保留参考），原目录清空。
3. **全量重新生成**：派新 agent 依据**新设计**从零生成全部代码。禁止把旧代码修补后当作新实现；旧代码只允许阅读参考，不允许复制为新实现的基础。
4. **登记**：manifest 中该模块 revision 更新为最新；相关下游模块按 7.1 影响分析决定是否联动重建。
5. 重新集成 + 回归测试。

> 判断口径：**任何改变对外契约或行为语义的修改，一律走全量重新生成**；模块内部实现细节的小修允许主 agent 直接改代码，但一旦涉及设计文档内容，就回到 7.2。

## 8. 纪律清单（每轮自检）

- [ ] manifest.md 与磁盘上的 designs / code 一一对应、revision 一致；
- [ ] 子 agent 提示词自包含（不依赖它读其他模块的代码）；
- [ ] 没有子 agent 改过其他模块的目录或任何 design 文档；
- [ ] 没有"在旧代码上打补丁"代替重新生成；
- [ ] 每次派单都有日志，失败有原因与去向（重派/亲自修/升级设计变更）；
- [ ] 交付前跑过构建与测试，集成点全部验证。

## 9. 相关资源

- `references/decomposition.md` — 拆解算法、粒度判断、依赖规则
- `references/agent-protocol.md` — 子 agent 调度协议与派单提示词模板（实现/递归下发/变更分析）
- `references/workspace-layout.md` — .mdd 工作区文件约定
- `references/templates/module-design.md` — 模块设计文档模板
- `references/templates/module-manifest.md` — 模块树 manifest 模板
- `references/templates/change-request.md` — 需求变更请求模板