@dtt_siye/atool 1.4.0 → 1.5.0

package/skills/project-analyze/prompts/understand-agent.md

@@ -1,16 +1,29 @@
-# Phase 2 UNDERSTAND Sub-Agent Prompt Template
+# Phase 2 UNDERSTAND Sub-Agent Prompt Templates
 
 > **派发方**：Phase 2 控制器（主 agent）
-> **执行方**：sub-agent（每个模块 1 个）
+> **执行方**：sub-agent（每个模块 2 个 stage）
 > **输出目标**：三层文档 → `atool-analysis/modules/{module-name}/` + `.atool-docs/modules/{module-name}/`
 
 ---
 
-## Prompt Template
+## 设计原则
+
+**原始问题**：单次 prompt 要求 AI 同时产出 7 个文件（425 行指令），AI 实际只能产出 1 个巨型文件。
+
+**解决方案**：拆为 2 个 stage，每个 stage 只产出 1-3 个文件，降低单次指令复杂度。
+
+- **Stage 1**（~150 行）：提取结构化数据 → `data.json` + `README.md`（必须先完成）
+- **Stage 2**（~120 行）：基于 data.json 生成详细文档 → `api.md` + `data-model.md` + `dev-guide.md` + `prd.md` + `test-cases.md`
+
+Stage 2 依赖 Stage 1 的 `data.json`，不可并行。Stage 2 中的 5 个文件可在一个 sub-agent 中顺序生成（每个文件有明确的独立章节）。
+
+---
+
+## Stage 1 Prompt（结构化数据提取 + 业务摘要）
 
 ```
 ## 任务
-深度分析模块「{module_name}」，生成三层文档（业务摘要 + 开发指引 + PRD + 测试用例 + 机器数据）。
+分析模块「{module_name}」，提取结构化数据并撰写业务摘要。
 
 ## 已有数据（来自 Phase 1 pre-scan）
 
@@ -48,361 +61,206 @@
 
 ---
 
-## 输出文件 1：atool-analysis/modules/{module_name}/README.md
-（层1: 业务摘要 — 产品经理/业务人员必须能看懂）
+## 输出文件 1：.atool-docs/modules/{module_name}/data.json
+
+生成以下 JSON（所有字段必须存在，空值用 `[]` 或 `{}`）：
+
+```json
+{{
+  "module": "{module_name}",
+  "layer": "presentation|service|repository|domain|infrastructure|ui",
+  "business_domain": "用中文描述此模块的业务领域",
+  "responsibility": "用中文一句话描述核心职责",
+  "files": ["从 pre-scan 提取的实际源文件路径"],
+  "dependencies": [
+    {{"target": "other-module", "type": "imports", "files": ["具体引用文件"]}}
+  ],
+  "exposed_apis": [
+    {{"name": "方法名", "path": "/api/路径", "method": "POST", "file": "Controller文件名"}}
+  ],
+  "data_entities": [
+    {{"name": "实体名", "fields": ["字段列表"], "file": "Entity文件名"}}
+  ],
+  "data_flows": [
+    {{"trigger": "业务触发场景", "path": "Controller → Service → Repository → DB", "direction": "inbound|outbound"}}
+  ],
+  "quality_issues": [
+    {{"type": "high_complexity|dead_code|code_duplication|missing_error_handling", "file": "文件名", "detail": "具体问题描述", "severity": "high|medium|low"}}
+  ],
+  "quality_score": 0.75,
+  "business_terms": [
+    {{"term": "业务术语", "identifier": "代码标识符", "meaning": "业务含义"}}
+  ],
+  "security_issues": [
+    {{"type": "sql_injection|xss|hardcoded_secret|missing_auth", "file": "文件名", "line": 42, "detail": "具体漏洞描述", "severity": "high|medium|low"}}
+  ],
+  "test_coverage_estimate": {{
+    "has_tests": true,
+    "test_files": ["测试文件路径"],
+    "test_framework": "框架名",
+    "estimated_coverage": "high|medium|low|none",
+    "untested_apis": [],
+    "untested_functions": []
+  }},
+  "existing_docs": {{
+    "found": [],
+    "gaps": [],
+    "inconsistencies": []
+  }},
+  "refine_hints": {{
+    "detected_patterns": ["MVC", "CQRS"],
+    "key_decisions": ["从代码识别的设计决策"],
+    "cross_module_deps": ["跨模块依赖描述"]
+  }}
+}}
+```
+
+## 输出文件 2：atool-analysis/modules/{module_name}/README.md
 
-必须包含以下 4 节，**禁止出现代码块、类名、函数名**（那是 dev-guide.md 的内容）：
+业务摘要，**严格控制在 150 行以内**。禁止出现代码块、类名、函数名。
+
+必须包含以下 4 节：
 
 ### 这个模块是做什么的
 2-3 句话，用纯业务语言描述。
-示例：「用户服务负责管理系统中所有用户的注册、登录和个人信息维护，是系统的核心身份管理模块。」
 
 ### 它解决什么问题
 从业务视角描述，说清楚没有它会发生什么。
-示例：「如果没有用户服务，系统无法识别谁在操作，也无法控制不同角色的访问权限。」
 
 ### 核心业务场景
-3-5 个具体场景，主谓宾句式。每个场景 2-3 句描述完整业务流程。
-示例：
-1. **新用户注册**：用户提交注册信息后，系统验证邮箱唯一性，创建账户，发送验证邮件。
-2. **用户登录**：用户输入凭证后，系统验证身份，生成会话令牌，记录登录日志。
+3-5 个具体场景，主谓宾句式。
 
 ### 关键业务概念
-≤10 个，每个用 2 句话解释。表格格式：概念 | 含义 | 使用场景。
+≤10 个，表格格式：概念 | 含义 | 使用场景。
 
 ---
 
-## 输出文件 2：atool-analysis/modules/{module_name}/api.md
-（层2a: 接口文档 — 调用方视角）
-
-每个公开接口必须包含：
-- **签名**（方法名 + 参数类型 + 返回类型）
-- **用途**（一句话说清楚做什么）
-- **请求头**（Content-Type、Authorization、自定义 Header 等，标明必填/可选）
-- **参数说明**（每个参数：名称、类型、是否必填、含义）
-- **请求体 Schema**（JSON 格式，每个字段包含完整定义）：
-  | 字段名 | 类型 | 必填 | 校验规则 | 示例值 | 说明 |
-  |--------|------|------|----------|--------|------|
-- **返回值说明**：
-  - 成功响应（200/201）：完整结构 + 每个字段含义
-  - 失败响应（4xx/5xx）：每种错误的响应结构
-- **完整错误码表**：
-  | HTTP Status | Error Code | 触发条件 | 用户提示 | 解决方案 |
-  |-------------|------------|----------|----------|----------|
-- **curl 调用示例**（包含请求和响应）：
-  ```bash
-  # 请求
-  curl -X POST http://localhost:8080/api/users \
-    -H "Content-Type: application/json" \
-    -H "Authorization: Bearer {token}" \
-    -d '{"name": "张三", "email": "zhangsan@example.com"}'
-
-  # 成功响应 (201)
-  {"id": 1, "name": "张三", "email": "zhangsan@example.com", "createdAt": "..."}
-
-  # 失败响应 (409)
-  {"error": "DUPLICATE_EMAIL", "message": "该邮箱已注册"}
-  ```
-- **频率限制**（如有，从代码中的 rate limiter/throttle 配置推断）：
-  - 限制规则（如 100 次/分钟）
-  - 超限响应（429 状态码 + 响应体）
-  - 重试策略（Retry-After header）
-- **版本兼容性**（如有，从 URL 路径版本号或 Header 版本控制推断）
+## 禁止行为
+- 禁止在 README.md 中出现代码块、类名、函数名
+- 禁止使用未替换的模板占位符
+- 禁止编造不存在的 API、类、方法
 
-没有公开 API 的模块可跳过此文件（在 README.md 中注明）。
+## 完成标志
+输出完成后，你必须声明：
+"Stage 1 完成：data.json + README.md 已生成。"
+```
 
 ---
 
-## 输出文件 3：atool-analysis/modules/{module_name}/data-model.md
-（层2b: 数据模型 — 仅当模块有数据实体时生成）
+## Stage 2 Prompt（详细文档生成）
 
-必须包含：
-
-### ER 关系图
-- **Mermaid ER 图**（erDiagram 格式，展示实体关系，包含字段类型和关系基数）
-
-### 实体字段详表
-对每个实体，提供完整字段定义表：
-
-| 字段名 | 类型 | 约束 | 默认值 | 索引 | 业务含义 | 验证规则 |
-|--------|------|------|--------|------|----------|----------|
-
-约束列可选值：`NOT NULL`、`UNIQUE`、`PK`、`FK(表名.字段)`、组合约束
-索引列可选值：`PRIMARY`、`UNIQUE`、`INDEX`、`COMPOSITE(字段列表)`、无
-
-### 枚举值定义
-对状态、类型等枚举字段，列出所有可选值：
-
-| 枚举字段 | 可选值 | 含义 | 状态流转规则 |
-|----------|--------|------|-------------|
-
-示例：
-| `order_status` | `PENDING` | 待支付 | 创建后初始状态 |
-| | `PAID` | 已支付 | PENDING → PAID（支付成功） |
-| | `CANCELLED` | 已取消 | PENDING → CANCELLED（超时/手动） |
-| | `COMPLETED` | 已完成 | PAID → COMPLETED（确认收货） |
+```
+## 任务
+基于模块「{module_name}」的结构化数据，生成 5 个详细文档。
 
-如有状态流转逻辑，附 Mermaid stateDiagram。
+## 输入数据
 
-### 关联关系说明
-对每对关联实体：
-- 关系类型：1:1 / 1:N / N:M
-- 关联字段：外键字段名 + 被引用字段
-- 级联策略：`CASCADE` / `SET NULL` / `RESTRICT` / `NO ACTION`（从 ORM 注解或 migration 文件推断）
-- 业务含义：用业务语言解释为什么需要这个关联
+### data.json（Stage 1 已生成）
+请先读取 .atool-docs/modules/{module_name}/data.json
 
-### 数据量估算
-从代码中的分页参数、批处理大小、缓存策略推断：
-- 预估单表数据量级（百/千/万/百万）
-- 分页默认值（pageSize）
-- 批处理大小（batchSize）
-- 缓存 TTL
+### 需要时读取的源文件
+如果 data.json 中的信息不足以完成某个文档，按需读取以下文件：
+- API 相关：读取 exposed_apis 中列出的 Controller 文件
+- 数据模型：读取 data_entities 中列出的 Entity 文件
+- 架构约束：读取 dependencies 和 data_flows 涉及的关键文件
 
-### 数据库迁移
-如果可从 migration/flyway/liquibase/alembic 文件推断：
-- 迁移文件列表
-- 版本演进历史（关键 schema 变更）
+## 项目上下文
+- 技术栈：{stack}
+- 项目名：{project_name}
+- 模块路径：{module_path}
 
-没有数据实体的模块可跳过此文件。
+## 输出语言
+所有文档**必须中文**。
+例外（保持英文）：代码块、文件路径、技术标识符、API 路径、包名。
 
 ---
 
-## 输出文件 4：atool-analysis/modules/{module_name}/dev-guide.md
-（层2c: 开发指引 — 新开发者操作手册）
+## 输出文件 1：atool-analysis/modules/{module_name}/api.md
+（接口文档 — 调用方视角）
 
-> ⚠️ 此为初稿。Phase 2.5 将由 software-architecture 追加组件设计和 ADR 章节。
-> 初稿重点：准确描述开发操作流程和现有架构约束，不必追求架构文档的完整性。
+对 data.json 中每个 exposed_api，生成文档：
+- **签名** + **用途** + **参数说明表** + **返回值结构** + **错误码表** + **curl 示例**
+- 无公开 API 的模块：在 README.md 注明，不生成此文件
 
-必须包含以下 4 节：
+## 输出文件 2：atool-analysis/modules/{module_name}/data-model.md
+（数据模型 — 仅当 data_entities 非空时生成）
 
-### 如何添加新功能
-具体到哪个文件、哪个类、按什么模式添加。附代码模板（不是完整实现，而是骨架）。
-示例：「添加新的用户查询接口：1. 在 `UserController.java` 添加新的 @GetMapping 方法 → 2. 在 `UserService.java` 添加业务逻辑 → 3. 在 `UserRepository.java` 添加查询方法」
+包含：ER 关系图（Mermaid）+ 字段详表 + 枚举定义 + 关联关系 + 数据量估算
+无数据实体时跳过此文件。
 
-### 如何修改数据模型
-数据库迁移步骤、ORM 映射更新方式。
+## 输出文件 3：atool-analysis/modules/{module_name}/dev-guide.md
+（开发指引 — Zero-KT 标准，新开发者操作手册）
 
-### 常见 Bug 排查
-按症状组织（3-5 个）：
-| 症状 | 可能原因 | 排查步骤 | 解决方案 |
+> ⚠️ 此为初稿。Phase 2.5 将由 software-architecture 追加组件设计和 ADR 章节。
 
-### 架构约束
-不允许做什么、为什么。
-示例：「禁止在 Controller 层直接操作 Repository — 必须经过 Service 层，因为 Service 包含事务管理和业务校验逻辑。」
+必须包含 4 节：
+1. **如何添加新功能**：具体到文件/类/模式，附代码骨架（含实际包路径和类名，从 data.json 的 files 提取）
+2. **如何修改数据模型**：迁移步骤、ORM 映射更新（引用实际 Entity 类名和字段）
+3. **常见 Bug 排查**：按症状组织（3-5 个），表格格式：症状 | 可能原因 | 排查命令 | 修复方法
+4. **架构约束**：不允许做什么、为什么（如"Controller 不允许直接调用 Mapper"、"Entity 不允许引用 Service"）
 
----
-
-## 输出文件 5：atool-analysis/modules/{module_name}/prd.md
-（层2d: 模块级 PRD — 按钮级别功能定义）
+## 输出文件 4：atool-analysis/modules/{module_name}/prd.md
+（模块级 PRD — 按钮级别功能定义，客户交付级初稿）
 
 > ⚠️ 此为初稿。Phase 2.5 将按 requirements-writer 的 8 节标准模板精炼。
-> 初稿重点：准确提取业务逻辑和功能点，不必追求格式完美。
-
-质量标准：开发者拿到此文档 + api.md + data-model.md，无需再问产品经理任何问题即可完成全部开发。
-
-必须包含以下 4 节：
-
-### 1. 模块概述
-- **业务问题**（1-2 句，为什么需要这个模块）
-- **解决方案**（1-2 句，这个模块怎么解决）
-- **成功标准**（3-5 个可度量 KPI，从代码中的监控指标/日志/计数器推断）
-  示例：「注册转化率 > 80%」「API 平均响应时间 < 200ms」「错误率 < 0.1%」
-
-### 2. 功能需求（按页面/功能点组织）
-对每个功能点/页面：
-
-#### 2.x {功能名}
-- **用户故事**：As a [角色], I want to [操作] so that [收益]
-- **验收标准**：
-  - [ ] 条件1
-  - [ ] 条件2
-- **UI 交互定义**（从代码中的组件/模板/路由推断）：
-  - 页面布局（文字描述或 ASCII 线框图）
-  - 按钮行为：`[按钮名]` → 触发 `{API}` → 成功/失败反馈
-  - 输入字段：
-    | 字段 | 类型 | 必填 | 校验规则 | 默认值 | 占位文本 |
-    |------|------|------|----------|--------|----------|
-  - 四种状态：加载中 / 空数据 / 错误 / 正常（每种状态的 UI 表现）
-  - 权限控制：哪些角色可见/可操作（从代码中的 RBAC/权限注解推断）
-- **边界条件**：
-  - 并发场景（如多用户同时操作同一资源）
-  - 数据量极端情况（空列表/超大列表/超长文本）
-  - 网络异常处理（超时/断线/重试策略）
-
-### 3. 非功能需求
-- **性能**：API 响应时间要求（从代码中的超时设置/缓存配置/异步处理推断）
-- **安全**：认证方式 / 授权粒度 / 数据脱敏规则（从代码的安全配置推断）
-- **兼容性**：浏览器/设备/API 版本兼容（从代码中的 polyfill/UA 检测/版本号推断）
-
-### 4. 非目标（Not in Scope）
-本模块明确不负责的功能（从代码中的 TODO/FIXME、未实现接口、注释中的 "out of scope" 推断）。
-列出每项非目标及推断依据。
-
----
-
-## 输出文件 6：atool-analysis/modules/{module_name}/test-cases.md
-（层2e: 模块级测试用例 — QA 直接可用）
-
-质量标准：QA 团队可直接用此文档编写自动化测试脚本。
-
-必须包含以下 4 节：
-
-### 1. 功能测试用例
-对每个核心 API/功能，生成完整用例表：
-
-| 用例 ID | 场景 | 前置条件 | 操作步骤 | 预期结果 | 优先级 |
-|---------|------|----------|----------|----------|--------|
-| TC-{module}-001 | 正常创建用户 | 用户已登录+有权限 | POST /api/users {...} | 201 + 返回用户对象 | P0 |
-| TC-{module}-002 | 缺少必填字段 | 同上 | POST /api/users {} | 400 + 错误消息 | P0 |
-| TC-{module}-003 | 重复邮箱 | 邮箱已存在 | POST /api/users {...} | 409 + 冲突消息 | P1 |
-
-优先级定义：
-- P0：核心正常路径，必须通过
-- P1：常见异常路径，必须通过
-- P2：边界条件，应当通过
-- P3：极端场景，建议通过
-
-### 2. 边界测试
-针对每个输入字段，覆盖以下边界条件：
-- 空值/null/undefined
-- 超长字符串（>255 字符、>65535 字符）
-- 特殊字符（SQL 注入 payload：`' OR 1=1 --`、XSS payload：`<script>alert(1)</script>`）
-- 超大数值（Integer.MAX_VALUE、负数、0、小数）
-- 并发竞争（两个请求同时创建相同资源 → 预期仅一个成功）
-- 空列表 / 超大分页（pageSize=0、pageSize=10000）
-
-### 3. 安全测试
-- 未授权访问（无 Token → 401）
-- 角色越权（普通用户访问管理员接口 → 403）
-- CSRF 防护验证
-- XSS payload 注入（在所有输入字段）
-- SQL 注入 payload（在所有查询参数）
-- 敏感数据泄露（response 中不应包含密码/密钥/内部路径）
-- 水平越权（用户 A 访问用户 B 的资源 → 403/404）
-
-### 4. 集成测试建议
-- 依赖模块的 Mock 策略（哪些模块需要 mock、推荐 mock 方式）
-- 端到端场景描述（完整业务流程的测试路径）
-- 测试数据准备（需要预置哪些数据、推荐的 seed 脚本）
-
----
-
-## 已有文档检测
-
-在生成文档前，先检查模块目录中是否存在以下文件：
-- README.md、PRD.md、CHANGELOG.md、API.md、docs/*.md
-
-如果存在，读取其内容并与代码实现进行对比：
-1. 代码中已实现但文档未描述的功能 → 补充到 prd.md，标注 `[补齐：代码中已实现但文档未记录]`
-2. 文档中描述但代码未实现的功能 → 在 prd.md 中标注 `[待实现：文档有描述但代码中未找到实现]`
-3. 文档与代码不一致的地方 → 标注 `[不一致：文档说X，代码实际做Y]`
-
-将检测结果写入 data.json 的 `existing_docs` 字段。
-
----
-
-## 输出文件 7：.atool-docs/modules/{module_name}/data.json
-（层3: 机器数据 — Phase 3 图谱构建使用）
-
-```json
-{
-  "module": "{module_name}",
-  "layer": "presentation|service|repository|domain|infrastructure|ui",
-  "business_domain": "用中文描述此模块的业务领域",
-  "responsibility": "用中文一句话描述核心职责",
-  "files": ["src/path/to/file1.java", "src/path/to/file2.java"],
-  "dependencies": [
-    {"target": "other-module", "type": "imports", "files": ["具体引用文件"]}
-  ],
-  "exposed_apis": [
-    {"name": "createUser", "path": "/api/users", "method": "POST", "file": "UserController.java"}
-  ],
-  "data_entities": [
-    {"name": "User", "fields": ["id", "name", "email", "role"], "file": "User.java"}
-  ],
-  "data_flows": [
-    {"trigger": "用户注册", "path": "Controller → Service → Repository → DB", "direction": "inbound"}
-  ],
-  "quality_issues": [
-    {"type": "high_complexity", "file": "UserService.java", "detail": "方法 createUser 圈复杂度 15", "severity": "medium"}
-  ],
-  "quality_score": 0.75,
-  "business_terms": [
-    {"term": "审批流", "identifier": "approval_flow", "meaning": "多级审批的流程定义"}
-  ],
-  "security_issues": [
-    {"type": "sql_injection|xss|hardcoded_secret|insecure_deserialization|path_traversal|missing_auth", "file": "UserController.java", "line": 42, "detail": "用户输入直接拼接到 SQL 查询中，未使用参数化查询", "severity": "high|medium|low"}
-  ],
-  "test_coverage_estimate": {
-    "has_tests": true,
-    "test_files": ["tests/user.test.ts", "tests/user.spec.ts"],
-    "test_framework": "jest|junit|pytest|go_test|...",
-    "estimated_coverage": "high|medium|low|none",
-    "untested_apis": ["DELETE /api/users/{id}", "PATCH /api/users/{id}/role"],
-    "untested_functions": ["UserService.batchImport", "UserService.exportCsv"]
-  },
-  "existing_docs": {
-    "found": ["README.md", "docs/api.md"],
-    "gaps": ["PRD 缺失用户删除功能描述", "API 文档缺少错误码表"],
-    "inconsistencies": ["文档说支持批量删除，代码中未实现", "文档中的字段名与代码不一致：文档用 userName，代码用 username"]
-  }
-  ,
-  "refine_hints": {
-    "detected_patterns": ["MVC", "CQRS", "Event-Driven"],
-    "key_decisions": ["选择 Redis 作为缓存层因为...", "使用 JWT 而非 Session 因为..."],
-    "cross_module_deps": ["依赖 user-service 的 /api/users/{id}", "消费 order-events 队列"]
-  }
-}
-```
 
-**refine_hints 说明**：为 Phase 2.5 精炼提供线索，避免精炼 agent 重新读源码。
-- `detected_patterns`: sub-agent 识别到的架构模式名称
-- `key_decisions`: 从代码中识别的关键设计决策（原始描述，无需 ADR 格式）
-- `cross_module_deps`: 跨模块依赖的具体描述（API 路径、事件名、共享实体）
-
-字段说明：
-- `layer`：架构层（从路径和类名推断）
-- `quality_score`：0.0-1.0（从 quality_issues 的数量和严重程度计算）
-- `quality_issues`：实际发现的代码质量问题（不是通用建议）
-- `security_issues`：实际发现的安全问题（从代码扫描中发现的具体漏洞，不是通用建议）
-- `test_coverage_estimate`：测试覆盖估算（从测试文件存在性和测试用例覆盖的 API/函数推断）
-- `existing_docs`：已有文档检测结果（发现的文档、缺失内容、与代码的不一致）
-- 所有数组字段如果为空则使用空数组 `[]`，不要省略字段
-- 所有对象字段如果无数据则使用空对象 `{}` 或保留结构填充默认值，不要省略字段
+必须包含 4 节：
+1. **模块概述**：业务问题 + 解决方案 + 成功标准（可度量 KPI，如"用户下单到支付完成 < 3步"）
+2. **功能需求**：按页面/功能点组织，每个功能点含：
+   - 功能编号（FR-{MOD}-001 格式，{MOD}为模块缩写大写）
+   - 用户故事（As a... I want... So that...）
+   - 验收标准（Given-When-Then 格式，至少 1 条）
+   - UI 交互描述（按钮/表单/列表的具体行为）
+   - 权限要求
+3. **非功能需求**：每条标注编号（NFR-{MOD}-001），覆盖性能/安全/兼容性，给出具体量化指标
+   - 性能示例：API 响应 < 200ms（P95），列表加载 < 1s
+   - 安全示例：所有写入 API 需鉴权，敏感数据加密存储
+4. **非目标**：明确不负责的功能（防止需求蔓延）
+
+**质量要求**：prd.md 必须 ≥ 50 行。如果功能较少，每个功能点的验收标准和 UI 交互描述必须更详细。
+
+## 输出文件 5：atool-analysis/modules/{module_name}/test-cases.md
+（测试用例 — QA 直接可用）
+
+必须包含 4 节：
+1. **功能测试用例**：用例表（ID/场景/前置条件/操作/预期/优先级）
+2. **边界测试**：空值/超长/特殊字符/并发
+3. **安全测试**：未授权/越权/XSS/SQL注入
+4. **集成测试建议**：Mock 策略/E2E 场景/测试数据
 
 ---
 
 ## 禁止行为
-- 禁止在 README.md 中出现代码块、类名、函数名（那是 dev-guide.md 和 api.md 的内容）
-- 禁止使用未替换的模板占位符（com/example/、{{PROJECT_NAME}}、xxx、TODO、...）
 - 禁止使用通用建议替代实际分析结果（如"建议添加单元测试"）
-- 禁止重新提取 pre-scan 已包含的结构信息
+- 禁止使用未替换的模板占位符
 - 禁止编造不存在的 API、类、方法
+- 禁止在 api.md 中遗漏 data.json 中列出的任何 exposed_api
 
-## 深度级别追加指令
-{depth_instructions}
+## 完成标志
+输出完成后，你必须声明：
+"Stage 2 完成：api.md + data-model.md + dev-guide.md + prd.md + test-cases.md 已生成。"
 ```
 
 ---
 
 ## Depth-Specific Instructions
 
-**重要：`{depth_instructions}` 变量必须内联替换为完整指令内容，禁止只写"L3 分析"等抽象标签。**
+**重要：`{depth_instructions}` 变量必须内联替换到 Stage 1 prompt 末尾。**
 
 具体填充方式（根据当前 depth 值）：
 
 - **L1**: 此 prompt 不使用（Phase 2 跳过，使用 pre-scan 数据直接生成 lite 文档）
 - **L2**: 留空（使用上方标准模板即可）
-- **L3**: 内联以下内容：
+- **L3**: 内联以下内容到 Stage 1 末尾：
   ```
   ## L3 深度追加要求
-  在标准输出之外，dev-guide.md 额外包含：
+  dev-guide.md 额外包含：
   1. 每个核心函数的完整签名 + 参数说明 + 返回值 + 调用链
   2. 设计模式识别（Factory/Strategy/Observer 等）+ 为什么选择此模式
   3. 设计决策记录（ADR 格式）：每个重要决策的 选择/替代方案/理由/权衡
   4. 模块内部架构图（Mermaid 类图或组件图）
   ```
-- **L4**: 内联以下内容：
+- **L4**: 内联以下内容到 Stage 1 末尾：
   ```
   ## L4 函数级追加要求
   在 L3 基础上，额外分析：
@@ -411,7 +269,7 @@
   3. 安全审计点（SQL 注入、XSS、未验证输入、硬编码凭证）
   4. data.json 额外字段：call_chains[], performance_hotspots[], security_issues[]
   ```
-- **L5**: 内联以下内容：
+- **L5**: 内联以下内容到 Stage 1 末尾：
   ```
   ## L5 跨模块追加要求
   在 L4 基础上，额外分析：

package/skills/project-analyze/rules/java.md

@@ -4,13 +4,81 @@
 
 ## 模块发现策略
 
-- **Maven 多模块**：检查根 `pom.xml` 的 `<modules>` 标签，每个 `<module>` 为独立分析单元
+### 基础发现
+
+- **Maven 多模块**：检查根 `pom.xml` 的 `<modules>` 标签，识别所有 `<module>`
 - **Gradle 多模块**：检查 `settings.gradle` / `settings.gradle.kts` 的 `include` 声明
 - **包路径推断**：从 `pom.xml` `<groupId>` 推断（跳过 `org.springframework.*` 等框架 groupId），备选读首个 `.java` 文件的 `package` 声明；禁止使用 `com.example` 等占位符
 - **Java 版本推断**：从 `<java.version>` / `sourceCompatibility` 提取；禁止默认使用 JDK 17+
 
 模块间依赖拓扑：从所有模块 pom.xml/build.gradle 提取，检测循环依赖（标记 Critical）。
 
+### Maven 多模块聚合规则（关键）
+
+**问题**：Maven 多模块项目通常包含大量基础设施 starter（如 `dtt-spring-boot-starter-mybatis`），这些不应作为独立分析单元。需要将子模块聚合为有业务含义的分析模块。
+
+**聚合规则**（按优先级）：
+
+1. **业务模块**（`module-*` / `*-service` / `*-api`）→ 保持独立分析单元
+   - 匹配模式：目录名含 `module-`、`service`、`api`、`app`、`application`
+   - 示例：`dtt-module-mall`、`dtt-module-system`、`dtt-gateway` → 各自独立
+
+2. **框架/基础设施模块**（`framework`、`common`、`*-starter-*`）→ **聚合为单个 `framework` 模块**
+   - 匹配模式：目录名含 `framework`、`common`、`starter`、`lib`、`core`、`shared`、`infrastructure`
+   - 示例：`dtt-framework/dtt-common` + `dtt-framework/dtt-spring-boot-starter-mybatis` + ... → 聚合为 `dtt-framework`
+   - 聚合后只分析框架的公共 API 和扩展点，不逐个分析 starter
+
+3. **依赖管理模块**（`dependencies` / `bom` / `parent`）→ **跳过**（无源码）
+   - 匹配模式：目录名含 `dependencies`、`bom`、`parent`，且该目录下无 `.java` 文件
+   - 示例：`dtt-dependencies` → 跳过
+
+4. **脚手架/模板模块**（`scaffold` / `template` / `demo`）→ **跳过**
+   - 匹配模式：目录名含 `scaffold`、`template`、`demo`、`example`、`sample`
+
+**聚合后的模块列表呈现**：
+
+```
+原始发现：71 个子模块
+聚合后：16 个分析模块
+
+业务模块（12 个）：
+  ✅ dtt-gateway          — API 网关
+  ✅ dtt-module-system    — 系统管理
+  ✅ dtt-module-infra     — 基础设施
+  ✅ dtt-module-member    — 会员管理
+  ✅ dtt-module-bpm       — 流程引擎
+  ✅ dtt-module-pay       — 支付
+  ✅ dtt-module-report    — 报表
+  ✅ dtt-module-mp        — 微信小程序
+  ✅ dtt-module-mall      — 商城
+  ✅ dtt-module-crm       — CRM
+  ✅ dtt-module-erp       — ERP
+  ✅ dtt-module-ai        — AI
+  ✅ dtt-module-iot       — IoT
+  ✅ dtt-module-invest    — 投资
+
+框架模块（1 个）：
+  📦 dtt-framework        — 聚合 20 个 starter（common/mybatis/redis/mq/...）
+
+已跳过（1 个）：
+  ⏭️ dtt-dependencies     — 纯依赖管理，无源码
+```
+
+**聚合决策树**（AI 在 Phase 1 执行时遵循）：
+
+```
+对每个发现的子模块：
+  1. 该目录下是否有 .java 源文件？
+     → 否：标记 "skip"，跳过
+     → 是：继续
+  2. 目录名是否匹配 framework/starter/common/core/lib/shared？
+     → 是：归入 "framework" 聚合模块
+     → 否：继续
+  3. 目录名是否匹配 module-*/service/api/app？
+     → 是：保持为独立业务模块
+     → 否：归入最近的父级业务模块
+```
+
 ## 入口识别
 
 | 标记 | 含义 |