diff --git a/docs/superpowers/specs/2026-07-31-mybatis-output-layout-design.md b/docs/superpowers/specs/2026-07-31-mybatis-output-layout-design.md
new file mode 100644
index 0000000..319b75c
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-31-mybatis-output-layout-design.md
@@ -0,0 +1,80 @@
+# MyBatis 生成输出布局设计
+
+日期：2026-07-31
+
+## 目标
+
+将三个彼此独立的输出路径改为“选择项目根目录后统一推导”，同时保留高级自定义能力，并让生成前风险与生成后结果可读、可追踪。
+
+## 输出目录策略
+
+新增不可变 `OutputLayout`，包含：
+
+- `projectRoot`
+- `modelDirectory`
+- `mapperDirectory`
+- `xmlDirectory`
+
+新增无 UI 依赖的 `OutputLayoutPolicy`：
+
+- Model：`<projectRoot>/src/main/java`
+- Mapper 接口：`<projectRoot>/src/main/java`
+- XML Mapper：`<projectRoot>/src/main/resources`
+- 路径统一规范化为绝对路径，禁止空根目录和普通文件。
+- 推导只负责目标工程目录；Java/XML 的包目录仍由现有 MyBatis Generator 配置追加。
+
+## UI
+
+- 默认模式只显示一个“项目根目录”选择框。
+- 三个派生目录以只读预览展示。
+- “自定义输出目录”开关启用后，三个目录才允许编辑。
+- 从左侧项目树选择节点时，可将该节点设为项目根目录并立即刷新预览。
+- 重置配置恢复标准推导模式，不保留旧的自定义开关状态。
+
+## 生成前摘要
+
+新增不可变 `GenerationPlan`，展示：
+
+- 选中表数量与表名。
+- Model、Mapper、XML 三个目标目录。
+- 目标目录是否存在、是否可写。
+- 目标目录中已有 `.java`、`.xml` 文件数量，作为覆盖风险提示。
+
+第一阶段不猜测 MyBatis Generator 最终类名，因此不声称可以精确列出将覆盖的文件。精确文件差异由生成前后快照给出。
+
+## 生成结果
+
+新增 `GenerationResult`，包含：
+
+- `createdFiles`
+- `updatedFiles`
+- `unchangedFiles`
+- `warnings`
+- 原始生成器消息
+
+生成用例在执行前后对三个输出目录中的 `.java`、`.xml` 文件做轻量快照，以路径、大小和最后修改时间判断差异。结果界面提供打开目录和复制路径，不自动打开外部程序。
+
+## 错误处理
+
+- 根目录无效：在提交任务前阻止生成。
+- 派生目录不存在：允许生成器创建，但在摘要中标记“待创建”。
+- 已存在但不可写：阻止生成并明确指出目录。
+- 快照失败：不阻止生成，将原因记录为 warning。
+- 生成器失败：保留错误状态，不把部分结果标记为成功。
+
+## 代码边界
+
+- `OutputLayoutPolicy` 不读取 JavaFX 控件或配置文件。
+- Window 只收集根目录、自定义开关和表选择。
+- `GenerateArtifactsUseCase` 负责计划、快照、执行与结果组装。
+- 现有 `MyBatisGeneratorService` 的覆盖行为保持不变。
+- Git 评审不参与修改。
+
+## 测试与验收
+
+- `OutputLayoutPolicy`：标准目录、规范化、非法根目录、自定义目录。
+- `GenerationPlan`：目录存在、待创建、不可写和已有文件计数。
+- `GenerationResult`：新增、更新、未变化文件分类。
+- 请求对象保持不可变，Window 不直接遍历输出目录。
+- 完整测试、编译、`git diff --check`。
+- UI 只读验收默认推导、自定义切换、重置及生成前摘要；不连接数据库、不实际生成。