module-boundary-design

name	module-boundary-design
description	模块边界设计。基于已完成的功能设计（SR-design），识别受影响模块，逐模块定义边界（职责、上游依赖、下游暴露），绘制模块交互时序，并通过对抗式审查发现边界冲突（职责泄漏、循环依赖、边界破坏、重复能力）。输出 module-boundary-design.md。用于AAW工作流步骤3。Use when the user asks for 模块边界设计、module-boundary-design。
version	2

Module Boundary Design

设计理念

本 skill 假设功能设计（SR-design）已完成。有了功能设计之后，模块边界设计的核心价值不是"穷举所有模块看看谁受影响"（这已在功能设计中隐含），而是：

1. 从功能设计中提取受影响模块 —— 不遍历全局，只提取涉及的
2. 对照架构文档交叉验证 —— 以 software_architecture.md 为准，补全功能设计可能遗漏的模块
3. 逐模块定义边界 —— 职责、上游依赖、下游暴露
4. 绘制模块交互时序 —— 将功能流翻译为模块调用流
5. 对抗式审查边界冲突 —— 职责泄漏、循环依赖、边界破坏、重复造轮子

问题管理工具

你可使用以下 MCP 工具辅助管理问题状态：

• add_questions – 批量添加待确认问题
• answer_question – 记录用户答案，并返回是否需要分析新问题的指示
• update_answer – 修改已记录问题的答案，用于用户纠正或补充
• get_status – 查看所有问题及状态（含已回答问题的答案），用于回顾已知信息
• finalize_questions – 检查所有问题是否已回答，并返回问答摘要

工作流执行流程

工作流全景：'确认输入' → '提取受影响模块 + 架构交叉验证' → '逐模块边界定义 + 交互时序' → '对抗式审查边界冲突' → '闭环问题' → '输出确认'

---

步骤 1: 确认输入

1. 明确当前工作目录
2. 确认 SR-design.md 存在（必须。上一步 SR 设计已保证）
3. 确认 AR-clarify.md 是否存在：
   • 存在 → 当前为 AR 模式，输出路径为 ./.sdd/{SR}/{AR}/module-boundary-design.md（与 AR-clarify.md 同目录），功能设计以 AR-clarify.md 为准
   • 不存在 → 当前为 SR 模式（免拆分），功能设计以 SR-design.md 为准；若由 aaw-workflow 编排调用，输出路径以工作单 output 为准，当前临时约定为 ./.sdd/{SR}/ALL/module-boundary-design.md
4. 确认 .sdd/software_architecture.md 存在（必须，获取模块定义和现有依赖关系）

向用户确认以当前工作目录继续，告知用户将基于以下文档：

• 功能设计：SR-design.md（SR 模式）或 AR-clarify.md（AR 模式）
• 架构参考：.sdd/software_architecture.md

---

步骤 2: 提取受影响模块 + 边界定义 + 交互时序

启动一个 subagent，执行以下分析：

**拷贝模板：**
- AR 模式：拷贝`<skill-dir>/references/module-boundary-design-template.md` 到 `./.sdd/{SR}/{AR}/module-boundary-design.md`
- SR 模式（免拆分）：若由 `aaw-workflow` 编排调用，拷贝到工作单 `output` 指定路径，当前临时约定为 `./.sdd/{SR}/ALL/module-boundary-design.md`；非编排场景可使用 `./.sdd/{SR}/module-boundary-design.md`

请读取以下文件完成模块边界设计：

1. 功能设计文档：如果存在`AR-clarify.md`则读取它，否则读取`SR-design.md`。
   - `AR-clarify`存在时不要参考`SR-design.md`——AR-clarify 是 SR-design 的切片。
2. 软件架构文档：`.sdd/software_architecture.md`，获取模块定义表和现有模块依赖关系。

请按以下顺序填充模板占位符`{{xxx}}`：

---

### Part A: 受影响模块提取 + 架构交叉验证

**第一轮：从功能设计提取**

基于功能设计文档（AR-clarify.md 优先，不存在则用 SR-design.md），**从功能设计中直接提取**涉及哪些模块。

对每个受影响模块，填写：
- 模块名称（必须与 software_architecture.md 中一致）
- 本需求中该模块承担的功能
- 是否新增模块（功能需求超出已有模块职责范围时标记为新增）
- 来源：标注 `AR-clarify提取`（优先使用）或 `SR-design提取`（无 AR-clarify 时）

**要求：**
- 不列举未被此需求影响的模块
- 不遍历 software_architecture.md 做全量高/中/低/无评级
- 只列出功能设计中明确涉及、或功能流程必然触及的模块

**第二轮：架构交叉验证**

功能设计是从功能视角编写的，可能遗漏某些架构层面必然被波及的模块。

请对照 `software_architecture.md` 中定义的模块清单，逐一检查：

> "这个模块在功能设计中没有出现，但根据它的职责定义，这个需求是否必然触达它？"

典型遗漏场景：
- 功能涉及的数据，其数据主权模块未被列出（如修改了用户数据但未列出用户模块）
- 功能流程必经的通路模块未被列出（如所有请求经过的网关/认证模块）
- 功能触发的事件，其消费方模块未被列出
- 功能涉及的配置项，其管理模块未被列出

如果发现遗漏，补入 Part A 并标注来源为 `架构验证补全`。
如果确认无遗漏，在 Part A 表后注明："已对照 software_architecture.md 完成交叉验证，无遗漏。"

### Part B: 模块边界定义

对 Part A 中的每个模块，逐一定义边界。边界包含五个维度：

1. **职责（做什么）** —— 按 `输入 → 处理 → 产出` 结构描述本模块在此需求中承担的具体职责，并标注**职责边界**（与相邻模块的分工：哪些功能本模块不负责，由哪个模块承担）
2. **数据主权（持有什么）** —— 本模块持有/管理的核心数据资产（表、缓存 key、文件等），其他模块不应绕过本模块直接访问
3. **上游依赖（依赖谁）** —— 本模块需要调用/依赖哪些其他模块、外部服务、中间件，**必须拆为子表**逐条列出（依赖方、具体接口/资源、协议、新增/已有）
4. **下游暴露（暴露什么）** —— 本模块向其他模块/外部系统提供什么接口，**必须拆为子表**逐条列出（接口、协议、入参、出参、新增/变更）
5. **模块内变更范围（改哪里）** —— 本需求涉及变更的文件/类/组件路径列表

**边界判断准则：**
- 当功能需要的数据由某模块持有，该模块即为数据主权方，其他模块不应绕过它直接访问该数据
- 当功能流程跨越模块职责边界，需要明确谁调用谁，以什么协议
- 外部依赖（DB、MQ、缓存、第三方服务等）必须在边界中显式标注
- 上游依赖和下游暴露必须拆为子表逐条列出，禁止合并为一段文字
- 职责中必须声明与相邻模块的职责边界：哪些是本模块不负责、由其他模块承担的功能
- 下游暴露必须给出入参和出参，禁止只写接口名

### Part C: 配置变更清单

基于功能设计和边界定义，列出涉及变更的配置文件目录及修改内容。

**不遍历所有配置目录穷举**，只列出实际需要变更的。

**修改内容约束：**
- 每条修改内容必须指明**变更点的具体位置**，描述格式为：`变更位置 → 变更内容`
- 示例：
  - SQL 变更：`user.xml 中 queryUserInfo → 新增 status 过滤条件`
  - Spring 配置变更：`application.yml 中 spring.datasource.url → 从 dev 改为 prod 地址`
  - 环境变量变更：`.env 中 REDIS_HOST → 新增，值为 127.0.0.1`
- 禁止模糊描述如"修改数据库配置"、"调整超时时间"——必须指明具体哪个配置文件/哪个语句/哪个配置项

### Part D: 模块交互时序

基于功能设计中的业务流程，绘制模块间的调用时序图（mermaid格式）。

**要求：**
- 按调用时序从左到右排列参与方
- 必须体现外部依赖（数据库、缓存、外部服务、消息队列等）
- 必须体现对外接口
- 覆盖 Part A 中所有受影响模块
- 与 Part B 的边界定义一致

---

步骤 3: 启动 Subagent 进行对抗式审查

启动第二个 subagent 校验 module-boundary-design.md，重点审查边界冲突：

请对已生成的 `module-boundary-design.md` 进行对抗式审查（假设文档内容完全错误）。

`module-boundary-design.md` 作用：在功能设计完成后，明确各受影响模块的边界定义、模块间交互契约，并发现潜在的边界冲突。

以下文档是审查参考：
1. 功能设计文档：`SR-design.md`（或 `AR-clarify.md`，如果存在）
2. 软件架构文档：`.sdd/software_architecture.md`
3. 现有模块的代码实现（探索相关模块目录）

---

## 审查要点

### 1. 模块覆盖审查（含交叉验证审查）

**第一层：功能设计提取是否准确**
- Part A 中标注为"AR-clarify提取"或"SR-design提取"的模块，是否确实在对应功能设计文档中涉及？
- 来源标注是否正确？（有 AR-clarify 时不应出现"SR-design提取"）
- 是否错误地列出了未被影响的模块？

**第二层：架构交叉验证是否充分**
- 审查方也需独立对照 `software_architecture.md`，检查是否还有遗漏的模块：
  - 功能涉及的数据，其数据主权模块是否都在 Part A 中？
  - 功能流程必经的通路模块是否都在 Part A 中？
  - 功能触发事件的消费方模块是否都在 Part A 中？
- 如果发现 Part A 标注"无遗漏"但实际有遗漏 → 指出具体遗漏的模块和理由
- 如果 Part A 已有"架构验证补全"的模块 → 确认补全是否充分，有无继续遗漏

**第三层：新增模块是否合理**
- 新增模块的判断是否合理？（现有模块职责确实无法覆盖？）
- 是否本应归属已有模块却错误标记为新增？

### 2. 边界冲突审查（核心）

对每个受影响模块，检查以下冲突类型：

**职责泄漏：**
- 功能是否放在了不该放的模块里？（A 模块做了 B 模块该做的事）
- 新增功能是否本应归属某个已有模块？

**循环依赖：**
- A 调用 B，同时 B（直接或间接）回调 A？
- 是否可以通过引入中间模块或事件机制解耦？

**边界破坏：**
- 某模块是否绕过数据主权方，直接访问其他模块的内部数据/数据库表？
- 某模块是否直接调用其他模块的内部方法（非公开接口）？
- 是否存在"胶水代码"跨越了应被隔离的边界？

**重复能力：**
- 功能设计中是否有已有模块已提供的能力被重新实现？
- 是否有两个模块承担了相同的职责？

**契约缺失：**
- 模块间调用是否缺少明确的接口定义（入参/出参/异常）？
- 外部依赖是否标注完整？（数据库、MQ topic、缓存 key 等）

### 3. 交互时序审查
- 时序是否与 Part B 的边界定义一致？
- 调用链路是否与 software_architecture.md 中现有依赖关系冲突？冲突处是否已标记？
- 是否存在同步调用链路过长的问题？

### 4. 可追溯性审查
- 是否有 Part B 定义了边界但时序图中未体现的模块？
- 是否有时序图中出现但 Part A 未列出的模块？（不应出现）

---

## 审查要求
- 假设原始文档完全错误，需重新验证每一个结论
- 必须探索代码实现来验证边界定义的准确性
- 审查后不能包含`可能、有概率、应该`等不明确的语言
- 请使用问题管理工具`add_question`添加问题

---

步骤 4: 使用问题管理工具闭环问题

使用问题管理工具逐个引导用户回答步骤 3 中发现的所有问题，并闭环问题刷新文档。

问题闭环后，汇总关键发现：

## 边界设计结论

- 受影响模块：{N} 个
- 新增模块：{X} 个
- 边界冲突发现：{Y} 处（已解决）
  - 职责泄漏：{a} 处
  - 循环依赖：{b} 处
  - 边界破坏：{c} 处
  - 重复能力：{d} 处

---

步骤 5: 询问是否刷新 software_architecture.md

如果 Part A 中有新增模块且 software_architecture.md 中未定义，询问用户是否更新 software_architecture.md。用户同意后执行更新。

---

步骤 6: 输出确认

向用户展示最终的 module-boundary-design.md 内容，请用户确认。

完成后回调

若不处于 aaw-workflow 编排中，请忽略此节。

本 skill 由 aaw-workflow 编排调用。交付件生成后：

1. 返回 aaw-workflow 流程
2. 执行 aaw next --sr <SR号> --json 查看进度
3. 若返回 deliverables_exist: true → 直接 aaw done --sr <SR> <id>
4. 否则 → 停止；是否放行下一步由 aaw-workflow 的 user_confirm 策略控制

不记得 SR 号 → 先 aaw status --json