@modus-ai/modus 0.2.4 → 0.2.5

package/templates/skills/modus-agents/developer/SKILL.md

@@ -1,109 +1,148 @@
 ---
 name: modus-developer
-description: Use this skill when the Harness orchestrator needs to implement code changes based on the requirements analysis (01-analysis.md). Implements code layer by layer (data → service → orchestration → interface), runs build compilation, and generates 02-sprint-contract.md. Triggered by modus-harness after SubAgent 01 completes or during Loop 2 re-entry for P1/P2 fixes.
+description: Use this skill when the Harness orchestrator needs to implement code based on the sprint plan in 01-analysis.md and design brief in 01.5-design-brief.md. Executes each sprint layer by layer (data→service→orchestration→api), validates with build command after each sprint, and generates 02-sprint-contract.md. Triggered by modus-harness after Gate A0.5 passes.
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
 
 # modus-developer（代码开发 SubAgent）
 
-**调用方：** Harness Orchestrator  
-**输入：** `01-analysis.md` + 相关业务 Skill  
-**产出物：** `modus/plans/active/{story-id}/02-sprint-contract.md` + 实际代码变更
+**调用方：** Harness Orchestrator（Gate A0.5 通过后触发）  
+**输入：** `01-analysis.md` + `01.5-design-brief.md` + 业务 Skill 内容 + constitution  
+**产出物：** `modus/plans/active/{story-id}/02-sprint-contract.md` + 代码变更
 
 ## 职责
 
-核心代码生成者。按照需求分析报告中的 Sprint 计划，逐层实现代码，每个 Sprint 完成后验证可构建，遵循项目已有的架构规范和编码风格。
+按照设计方案（01.5-design-brief.md）的实现蓝图和 01-analysis.md 的 Sprint 计划，逐层实现代码。每个 Sprint 完成后自动验证编译，确保代码质量前置。
 
 ---
 
 ## 执行流程
 
-### Step 1：读取上下文
+### Step 1：读取输入
 
-1. 读取 `01-analysis.md`，理解 Sprint 计划和技术影响范围
-2. 读取相关业务 Skill，了解项目规范（层次结构、命名约定、技术约束）
-3. 读取 `modus/config.yaml`，获取项目技术栈信息
+1. 读取 `01.5-design-brief.md`（技术方案，重点关注节 5-8）
+2. 读取 `01-analysis.md`（Sprint 执行计划、验收标准）
+3. 确认 `constitution.hard_rules` 和 `key_patterns`（最高优先级约束）
+4. 按需读取 Skill 关键文件索引中的实际代码文件（Level 3 加载，≤ 10 个文件）
 
-### Step 2：逐 Sprint 实现
+### Step 2：逐 Sprint 实现（严格按层顺序，禁止跳层）
 
-按 Sprint 计划顺序实现，每个 Sprint 遵循以下步骤：
+**标准层次顺序（每层必须完成并通过编译验证后才能进入下一层）：**
 
-**2a. 分析现有代码**
-- 找到需要修改/新增的文件
-- 理解现有代码风格和命名规范
-- 识别可复用的工具类、基类、常量
+```
+Sprint 1：数据层
+  → Mapper 接口（必须在 dao 包下）
+  → XML Mapper 或注解式 SQL
+  → Domain / Entity 对象
+
+Sprint 2：服务层
+  → Manager / Service（核心业务逻辑）
+  → 事务边界（@Transactional，必须通过 AopContext.currentProxy() 调用）
+  → 分布式锁（如需，@DistributedLock）
+
+Sprint 3：接口层（如有）
+  → Controller / Facade
+  → Request / Response DTO（含 @Valid 校验注解）
+  → 权限注解（如 @UserAuthorization）
+
+Sprint 4：集成层（如有）
+  → MQ Consumer / Producer
+  → 定时任务
+  → 跨服务 RPC 调用
+```
 
-**2b. 实现代码**
-遵循的通用原则：
-- 命名遵循项目现有风格（从 Skill 或现有代码中获取规范）
-- 新增文件放置到正确的包/目录层次
-- 事务注解使用项目规范方式（避免同类内部调用失效）
-- 分布式锁按项目已有模式使用
-- 参数校验在接口层完成，服务层做业务校验
-- 所有数据库操作必须在正确的事务边界内
-- 金额字段使用 BigDecimal，避免浮点精度问题
+**每个 Sprint 完成后立即执行编译验证：**
 
-**2c. Sprint 验证**
-每个 Sprint 完成后记录：
-- 新增/修改的文件列表
-- 关键实现决策（与 `01-analysis.md` 中建议有出入时说明原因）
+```bash
+{constitution.build_command}  # 如 mvn clean compile -q
+```
 
-### Step 3：生成 Sprint Contract
+编译失败 → 立即修复，修复后重新验证，不进入下一 Sprint。
 
-所有 Sprint 完成后，生成 `02-sprint-contract.md`。
+### Step 3：Self Code Review（每个 Sprint 完成后执行）
 
----
+在记录产出物前，对本 Sprint 的代码进行自检：
 
-## 产出物格式（02-sprint-contract.md）
-
-```markdown
-# Sprint Contract
+```
+自检清单（必须全部通过）：
+□ Mapper 接口是否在 dao 包下（来自 constitution.hard_rules）
+□ 金额字段是否符合 constitution 的金额规范
+□ @Transactional 的同类调用是否通过 AopContext.currentProxy()
+□ 是否存在 for 循环内的 DB 查询（N+1 风险）
+□ 新增写入操作是否有事务保护
+□ 对外接口是否有参数校验（@NotNull/@Valid 等）
+□ 是否引用了 Skill [pitfall] 中记录的已知风险点并做了处理
+□ 所有修改是否都能追溯到 01.5-design-brief.md 的追踪矩阵
+```
 
-## 执行摘要
-- 完成 Sprint: {N} 个
-- 新增文件: {N} 个
-- 修改文件: {N} 个
-- 实现时间: {YYYY-MM-DD HH:mm}
+发现问题 → 立即修复，记入 02-sprint-contract.md 的「自检发现」字段。
 
-## Sprint 执行记录
+### Step 4：写入 Sprint Contract
 
-### Sprint 1：{名称}
-**状态：** ✅ 完成
+每个 Sprint 完成后，将执行情况追加到 `02-sprint-contract.md`：
 
-**文件变更：**
-- 新增: `{文件路径}` — {说明}
-- 修改: `{文件路径}` — {变更内容}
+```markdown
+## Sprint {N}：{层次名称}
 
-**关键实现决策：**
-- {决策说明}
+### 实现文件
+| 文件路径 | 变更类型 | 说明 |
+|---------|---------|-----|
+| {path} | 新增/修改 | {1句话} |
 
-### Sprint 2：{名称}
-...
+### 关键实现决策
+- {架构决策：如「选择注解式 SQL 而非 XML，因为逻辑简单」}
 
-## 已知风险/遗留问题
-- {问题描述：如某个边界情况暂未处理}
+### 自检结果
+- ✅ 所有检查通过 / ⚠️ 发现并修复：{问题描述}
 
-## 待 SubAgent 03/04/05 重点关注
-- {代码评审重点关注点}
-- {性能风险点提示}
-- {安全风险点提示}
+### 编译验证
+- 结果：✅ 通过 / ❌ 失败（已修复）
 ```
 
 ---
 
-## 编码规范
+## 产出物格式（02-sprint-contract.md）
+
+```markdown
+<!--HANDOFF
+agent: "02-developer"
+story_id: "{story-id}"
+sprint_count: {N}
+sprints_completed: {N}
+gate_status: "{passed|failed}"
+changed_files:
+  - "{文件路径}"
+key_decisions:
+  - "{实现中做出的关键决策}"
+-->
+
+# 代码开发执行合同 — {Story 标题}
+
+## 开发摘要
+- 开发时间: {YYYY-MM-DD HH:mm}
+- 完成 Sprint: {N}/{总计N}
+- 变更文件数: {N}
+
+{各 Sprint 详情，见 Step 4}
+```
+
+**`gate_status` 赋值规则：**
+- `passed`：所有 Sprint 完成，编译通过，Self Review 无 P1 问题
+- `failed`：编译失败无法自愈，或发现无法自行解决的架构问题 → 上报 Orchestrator
+
+---
 
-遵循业务 Skill 中记录的项目规范。如果 Skill 中没有明确说明，参考以下通用原则：
+## 编码规范（来自 constitution + 通用最佳实践）
 
-- **分层架构：** Controller/Facade → Service/Manager → Mapper/DAO，跨层只能向下调用
-- **事务：** `@Transactional` 只在最外层 Service/Manager 方法上，避免同类内部调用失效
-- **异常处理：** 业务异常抛出项目统一的业务异常类，不吞掉异常
-- **日志：** 关键业务入口和异常分支必须有日志，不打印敏感信息
-- **注释：** 复杂逻辑和非直觉的业务规则需要注释说明
+- **最高优先级**：`constitution.hard_rules` 中的规则不可违反
+- **事务**：同类方法调用事务失效问题，统一用 `AopContext.currentProxy().{method}()` 解决
+- **响应封装**：统一用 `constitution.key_patterns` 中规定的响应封装方式
+- **异常处理**：使用项目已有的异常类，不自创异常类
+- **日志**：关键业务操作（创建/修改/删除）必须有入参日志；异常必须 `log.error` 记录
 
-## 禁止行为
+## 越权禁止
 
-- 不修改已有测试用例（留给 SubAgent 03）
-- 不直接修改生产配置文件（留给 SubAgent 07）
-- 发现可能有性能问题但超出当前 Sprint 范围时，在产出物中标注，不擅自重构
+- 不修改测试文件（由 SubAgent 03 负责）
+- 不修改 Skill 文件（由 SubAgent 00 负责）
+- 不操作部署流程（由 SubAgent 07 负责）

package/templates/skills/modus-agents/perf-auditor/SKILL.md

@@ -1,116 +1,153 @@
 ---
 name: modus-perf-auditor
-description: Use this skill when the Harness orchestrator needs to perform static performance audit on code changes. Detects N+1 queries, missing batch operations, unbounded data fetches, deep pagination risks, and ES query issues. Generates 04-perf-report.md. Triggered by modus-harness in parallel with SubAgents 03 and 05 after Gate A passes.
-allowed-tools: Read, Write, Glob
+description: Use this skill when the Harness orchestrator needs to perform static performance audit on changed code. Detects N+1 queries, missing batch operations, unprotected large data queries, deep pagination risks, and ES query issues. Quantifies each risk by data volume impact and grades as high/medium/low. Generates 04-perf-report.md with HANDOFF block. Triggered by modus-harness in parallel with tester and security-auditor after Gate A passes.
+allowed-tools: Read, Glob
 disable: false
 ---
 
 # modus-perf-auditor（性能审计 SubAgent）
 
-**调用方：** Harness Orchestrator（与 03/05 并行启动）  
-**输入：** `02-sprint-contract.md` + 代码变更  
+**调用方：** Harness Orchestrator（Gate A 通过后，与 03/05 并行触发）  
+**输入：** `02-sprint-contract.md`（变更文件列表）+ 代码变更 + 业务 Skill（≤ 2 个）  
 **产出物：** `modus/plans/active/{story-id}/04-perf-report.md`
 
 ## 职责
 
-对代码变更进行静态性能审计，识别 N+1 查询、缺少批量操作、大数据量风险等，量化每个风险的影响，按高/中/低分级输出报告。
+对本次代码变更进行静态性能审计，重点检测高频性能反模式，量化每个风险的潜在影响（N 条数据 → N 次 SQL），按高/中/低分级输出报告。不执行代码，不修改文件。
 
 ---
 
-## 审计重点
+## 检测规则
 
-### 1. N+1 查询（高优先级）
+### Rule 1：N+1 查询（高风险）
 
-**检测模式：**
-- 循环体内包含 DB 查询调用（`for/while` 内调用 `mapper.select*`）
-- 循环内调用 RPC/HTTP 接口
+**触发条件：** Service / Manager 类的 for 循环 / forEach / stream 内包含 Mapper 调用
 
-**量化影响：**
-- 指出循环的数据量（N 条记录 → N 次 SQL）
-- 估算最坏情况下的查询次数
+```java
+// ❌ 触发 N+1
+for (Long orderId : orderIds) {
+    Order order = orderMapper.selectById(orderId);  // N 次 SQL
+}
 
-**修复建议：**
-- 将循环内查询提取为批量查询（IN 查询 / 批量 RPC）
-- 先查全量，再在内存中分组/关联
+// ✅ 正确：批量查询
+List<Order> orders = orderMapper.selectByIds(orderIds);  // 1 次 SQL
+```
+
+**量化影响：** `N 个订单 → N+1 次 SQL（实测 1000 条 ≈ 1001 次查询）`  
+**修复建议：** 改用 `selectByIds(ids)` 批量查询，结果用 Map 分组后使用
+
+---
+
+### Rule 2：无分页保护的大数据量查询（高风险）
+
+**触发条件：** Mapper/SQL 中存在以下任一情况：
+- `selectAll()` / `SELECT * FROM table` 无 WHERE 限制
+- 列表查询缺少 `LIMIT` 或时间范围条件
+- 分页参数未设置最大页大小保护
+
+**量化影响：** `全表扫描，数据量增长后 OOM 风险`  
+**修复建议：** 添加 `LIMIT` 或时间范围条件；分页接口验证 `pageSize ≤ 200`
 
 ---
 
-### 2. 缺少批量操作（中优先级）
+### Rule 3：深分页风险（中风险）
 
-**检测模式：**
-- 循环内调用单条 insert/update
-- 应使用 `insertBatch` 但使用了逐条 `insert`
+**触发条件：** SQL 中使用 `LIMIT offset, size` 且 offset 无上限控制
 
-**修复建议：**
-- 使用 `insertBatchSomeColumn` 或自定义批量 insert XML
-- 大批量操作分批提交（每批 500-1000 条），避免超大事务
+**量化影响：** `offset=10000, size=10 → 扫描 10010 行，只返回 10 行`  
+**修复建议：** 改用游标分页（`WHERE id > lastId LIMIT size`）或设置 offset 上限
 
 ---
 
-### 3. 大数据量无保护（高优先级）
+### Rule 4：循环内批量写操作（中风险）
 
-**检测模式：**
-- 查询无 LIMIT 限制
-- 分页查询缺少总数上限保护
-- 深分页（`OFFSET` 过大）
-- 全表扫描风险（无索引条件）
+**触发条件：** for 循环内包含 `insert` / `update` / `delete` 调用（而非批量接口）
 
-**修复建议：**
-- 对列表查询强制设置最大返回条数
-- 深分页改用游标分页（基于最后一条记录的 ID）
+**量化影响：** `N 个写入 → N 次 SQL，N 个事务提交`  
+**修复建议：** 改用 `insertBatch(list)` / `updateBatch(list)`，单事务批量提交
 
 ---
 
-### 4. 搜索引擎查询（如适用）
+### Rule 5：缺少索引的高频查询（中风险）
+
+**触发条件：** SQL 的 WHERE 条件字段组合在 Entity 注解或已知索引列表中不存在对应索引
 
-**检测模式：**
-- ES 查询缺少 `fetchSource`（返回不必要的字段）
-- 缺少 `trackTotalHits: false`（数据量大时计算总数代价高）
-- 聚合查询无 `size: 0`（无需 hits 时）
+**量化影响：** `全表扫描，数据量 > 10 万行后查询超时风险`  
+**修复建议：** 添加复合索引 `idx_{field1}_{field2}`
 
 ---
 
-### 5. 事务范围过大（中优先级）
+### Rule 6：前缀模糊匹配（低风险）
 
-**检测模式：**
-- `@Transactional` 方法内包含远程调用（RPC/HTTP）
-- 事务内包含大量数据查询或处理逻辑
+**触发条件：** SQL 中使用 `LIKE '%keyword%'`（前缀通配符导致索引失效）
 
-**修复建议：**
-- 将远程调用移到事务外
-- 大事务拆分为多个小事务
+**量化影响：** `索引失效，全表扫描`  
+**修复建议：** 改用全文索引（FULLTEXT）或引入 ES 搜索
+
+---
+
+## 执行流程
+
+### Step 1：确定审计范围
+
+读取 `02-sprint-contract.md` 的 `changed_files`，筛选需要审计的文件：
+- Service / Manager 类（Rule 1/4）
+- Mapper 接口 + XML（Rule 2/3/5/6）
+- Controller（Rule 2 的分页参数）
+
+### Step 2：逐规则扫描
+
+对每个目标文件，逐一应用上述 6 条规则，记录发现的风险。
+
+### Step 3：风险分级与量化
+
+| 风险等级 | 定义 | 处理要求 |
+|---------|------|---------|
+| 高（需 P2 重入）| 生产环境下数据量正常情况即会触发的性能问题 | modus-reviewer 将标记为 P2，触发 Loop 2 |
+| 中（建议修复）| 数据量增长后可能触发，当前影响有限 | cr-report 中作为 P3 建议 |
+| 低（记录观察）| 仅在极端场景下触发 | 记录但不阻塞 |
 
 ---
 
 ## 产出物格式（04-perf-report.md）
 
 ```markdown
-# 性能审计报告
+<!--HANDOFF
+agent: "04-perf-auditor"
+story_id: "{story-id}"
+gate_status: "passed"
+high_risks: {N}
+medium_risks: {N}
+-->
+
+# 性能审计报告 — {Story 标题}
 
 ## 审计摘要
 - 审计文件数: {N}
 - 高风险: {N} 个 | 中风险: {N} 个 | 低风险: {N} 个
 
-## 高风险问题
+## 高风险（需修复）
 
-### [HIGH-01] N+1 查询
+### [PERF-HIGH-01] N+1 查询 — {ClassName}.{method}()
 - **位置：** `{文件名}.java:{行号}`
-- **问题：** `for` 循环中对每条订单调用 `orderMapper.selectById()`，N 条数据产生 N 次 SQL
-- **影响：** 订单列表 100 条 → 100 次 SELECT，响应时间线性增长
-- **修复方案：**
-  ```java
-  // 改为批量查询
-  List<Long> ids = orders.stream().map(Order::getId).collect(toList());
-  Map<Long, Order> orderMap = orderMapper.selectBatchIds(ids)
-      .stream().collect(toMap(Order::getId, o -> o));
-  ```
-
-## 中风险问题
+- **风险描述：** 循环内调用 `{MapperClass}.{queryMethod}()`
+- **量化影响：** N 个{实体} → N+1 次 SQL（1000 条 ≈ 1001 次查询）
+- **修复建议：** 改为 `{MapperClass}.selectByIds(ids)` 批量查询
+
+## 中风险（建议修复）
 ...
 
-## 低风险问题
+## 低风险（观察记录）
 ...
 
-## 无性能问题确认
-{如无问题，明确说明已检查的内容，不要留空}
+## 无风险确认
+{若某类规则未发现风险，明确写出「Rule N：未发现 XXX 问题」}
 ```
+
+---
+
+## 质量标准
+
+- 每个风险必须有文件路径 + 行号定位
+- 高风险必须量化影响（N 条数据 → N 次查询）
+- **HANDOFF 块必须位于文件最顶部**，`high_risks` 字段供 modus-reviewer 决定是否报 P2

package/templates/skills/modus-agents/reviewer/SKILL.md

@@ -53,8 +53,8 @@ disable: false
 - 日志是否完整（入参、出参、异常信息）
 
 **金额处理：**
-- 金额字段是否使用 BigDecimal
-- 运算是否使用 BigDecimal API（避免 `+`/`*` 运算）
+- 金额字段是否符合项目宪法的规范（以 `constitution.hard_rules` 为准，如规则为「金额字段使用 Long（单位：分）」则检查 Long 类型，如规则为「使用 BigDecimal」则检查 BigDecimal；**不得硬编码检查某一具体类型**）
+- 若 `constitution.hard_rules` 未明确金额规范，则默认检查是否使用 BigDecimal，并在报告中标注「未找到金额规范配置，使用默认规则」
 
 ### 维度 3：测试覆盖（参考 03-test-report.md）
 
@@ -81,6 +81,23 @@ disable: false
 ## 产出物格式（cr-report.md）
 
 ```markdown
+<!--HANDOFF
+agent: "06-review"
+story_id: "{story-id}"
+gate_status: "{passed|failed}"
+issues:
+  - id: "P1-01"
+    level: "P1"
+    sprint: {受影响的 Sprint 编号，如 2}
+    file: "{文件名}.java:{行号}"
+    summary: "{一句话问题摘要，供 Orchestrator 定位重入范围}"
+  - id: "P2-01"
+    level: "P2"
+    sprint: {N}
+    file: "{文件名}.java:{行号}"
+    summary: "{一句话问题摘要}"
+-->
+
 # 代码评审报告
 
 ## 评审摘要
@@ -116,6 +133,12 @@ disable: false
 {如无 P1/P2 → "通过评审，可进入 Final Review"}
 ```
 
+**HANDOFF 块填写规则：**
+- `gate_status`：无 P1/P2 → `passed`；有 P1/P2 → `failed`
+- `issues`：仅列 P1/P2 问题（P3 不阻塞，Orchestrator 不读取）；无 P1/P2 时写空列表 `issues: []`
+- 每条 issue 的 `sprint` 字段：填写受影响代码所属的 Sprint 编号，供 Orchestrator 精准定位重入范围
+- HANDOFF 块**必须位于文件最顶部**，Orchestrator 仅读此块（≤ 20 行）以决策是否触发 Loop 2
+
 ---
 
 ## 创建 Bug 单（可选）