Module boundary design

前置操作：工作流编排检查

若本 skill 是由 aaw-workflow 的工作单调用的，跳过本节，直接执行正文。

否则，在执行正文之前，先向用户发起一次二选一确认：

是否回到 aaw-workflow 工作流中执行？

• 是，回到工作流（推荐）——进度会被跟踪和上报
• 否，单独执行本 skill——本次执行将不纳入流程跟踪

• 用户选“是” → 加载 aaw-workflow skill，按其流程执行（其入口意图判定会引导继续已有工作流或新建），不再单独执行本 skill 正文。
• 用户选“否” → 继续执行本 skill 正文，之后不再提及工作流。

本节最多询问一次，不得重复打扰。

若工作单输出已存在，仍按当前要求完整执行：先读取并评估已有成果，复用仍有效的信息和已确认答案，可局部修改或整体重写，并写回原路径。

Module Boundary Design

设计理念

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

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

问题管理工具

本 Skill 依赖 question-tracker MCP Server。可用工具：

工具	session	作用
create_session	必填	新建问题池（唯一建池入口；同名池已存在时幂等返回）
add_questions	必填	批量添加问题；池须已存在（先 create_session 建池）
answer_question	必填	记录用户答案
update_answer	必填	修改已记录问题的答案
get_status	必填	查看所有问题及状态（含已答答案）
finalize_questions	必填	闭环确认；ready 后该池自动归档
reset_questions	必填	重置问题池
list_sessions	不需要	列出当前项目下所有问题池（发现与审计入口）
reopen_session	必填	将已归档的池重开回活跃区
delete_session	必填	删除活跃池（需 confirm: true）
cleanup_sessions	不需要	归档池受控清理（默认只列不删）

MCP 错误处理（任何错误都不得成为跳过问题池跟踪的理由）：

错误类型	判定方式	处置
选池指引（非错误）	结果含 "action_required": "select_session"（reason 为 missing_session 或 session_not_found）	本次调用未执行。按 guidance 行动：能从 available_sessions/archived_sessions 确定目标 → 用正确池名重试；不能确定 → 将列表展示给用户，请用户选择使用哪个池、或决定用 create_session 新建。这是正常引导不是失败，不计入连续失败次数
基础设施故障	工具不存在、未注册或连接失败	暂停流程，提示用户参照 skills/question-tracker-mcp/INSTALL.md 完成注册/修复并重启后重试；用户无法或不修复时，此类失败同样计入连续失败次数，满 3 次按下方「连续失败降级」执行
invalid_session	工具结果含 "error": "invalid_session"	宿主参数封装异常（session 不是字符串），与"池不存在"无关——不得新建池，原样重试；仍失败则提示用户在 MCP 配置 env 中设 QUESTION_TRACKER_DEBUG=1 并重启宿主取证（日志位置见 INSTALL.md §4.1）。计入连续失败次数
参数校验错误	工具结果含其他 "error" 文案（如池名含 :、/）	按错误文案修正参数后重试；反复失败计入连续失败次数

工具返回 isError 或结果中含 "error" 字段即视为失败调用，含 "action_required" 为选池指引：两者都必须先按上表处置，严禁静默跳过问题池、退化为纯对话提问。

连续失败降级：任意 MCP 调用（含上表所有错误类型）按上表处置后仍连续失败满 3 次，停止重试，向用户明确声明一次："问题池 MCP 持续不可用（连续失败 {N} 次），本次改为在对话上下文中维护问题清单，不再写入问题池。"此后按既有提问流程继续：问题、答案与矛盾比对均基于对话上下文维护。降级生效后不再调用任何问题池工具——包括取问题用的 get_status、收尾的一致性校验与 finalize_questions——收尾改为对话内输出完整问答汇总供用户核对。降级必须显式声明、每个会话只声明一次——未声明即脱离问题池仍属违规。注意：上下文压缩可能丢失早期问答细节，生成文档前应就关键决策请用户复核。

问题池调用纪律

1. session 必填：所有池操作必须传 session。忘记池名时先 list_sessions，不得随意起名另开新池。
2. 命名规范：<工作单元编号>-<语义关键词>。编号精确索引（如 sr001、sr001-ar002），关键词帮助失忆后的 AI 从列表中联想找回。
3. list-first：启动时先 list_sessions 检查目标池是否存在，存在则续用，不存在再 create_session 新建。
4. 无法确定时问人：任何时刻凭语义无法唯一确定目标池——启动选池、收到选池指引后的恢复、上下文压缩后池名不确定——不得猜测，必须将 list_sessions 的结果展示给用户，请用户指定。
5. 池名不含敏感信息：同一 project 下池名对所有调用方可见，不得包含密码、密钥、个人隐私。

本 Skill 的问题池使用与本 AR 的 ar-clarify 完全相同的 session 名（{SR编号}-{AR编号}-<语义关键词>）。同 AR 的澄清决策与边界冲突问题记录在同一池中，该 AR 的全部决策轨迹集中可追溯。

工作流执行流程

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

---

步骤 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

---

步骤 1.5: 问题池准备

根据输入模式确定问题池并使其处于活跃状态：

AR 模式（经过 ar-clarify）：

1. 池名前缀：{SR编号}-{AR编号}-（ar-clarify 建池时追加的语义关键词由它自行归纳，本 skill 不得假设一致）。
2. 调用 list_sessions（include_archived: true），按该前缀（非全名精确匹配）定位本 AR 的池：
   • 唯一命中且在归档区（{前缀}<关键词>-<日期后缀>，说明 ar-clarify 已 finalize）→ 调用 reopen_session（session: <含日期后缀的归档名>）将池重开回活跃区，该 AR 的澄清决策全部恢复可见（reopen 返回的 reopened 字段即为后续使用的活跃池名）；
   • 唯一命中且在活跃区（说明 ar-clarify 异常中断、未 finalize）→ 直接使用，调用 get_status（session: <池名>）加载既有内容；
   • 多个候选命中 → 将候选列表展示给用户，请用户指定，不得自行猜测；
   • 无命中（ar-clarify 未执行过）→ 调用 create_session（session: {SR编号}-{AR编号}-<语义关键词>）建池并确认成功返回，否则不得开始提问。

SR 模式（免拆分，AR=ALL，不经过 ar-clarify）：

• 池名：{SR编号}-ALL-<语义关键词>；无需 reopen，调用 create_session 建池（幂等，created:false 即续用）并确认成功返回，否则不得开始提问。

---

步骤 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_questions` 添加问题（`session` 必须使用步骤 1.5 确定的池名——主 agent 在派发本提示词时将其填入此处：<池名>）

---

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

使用问题管理工具逐个引导用户回答步骤 3 中发现的所有问题，并闭环问题刷新文档。闭环过程中的所有问题管理工具调用（add_questions / answer_question / update_answer / get_status / finalize_questions）均携带步骤 1.5 确定的 session 参数。finalize_questions 返回 ready 后问题池自动归档至 .archive/；若后续需修改已归档的答案，使用 reopen_session 重开该池后再 update_answer。

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

## 边界设计结论

- 受影响模块：{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