monisuo/.agents/skills/monisuo-dev/SKILL.md

name, description

name	description
monisuo-dev	Monisuo 项目结构化开发流程。需求分析 → 架构设计 → 模块化开发 → 精简测试 → 功能验证 → 构建。

Monisuo 开发工作流

流程概览

Phase 1: 需求定义 → Phase 1.5: 架构设计 → Phase 2: 模块化开发（子任务逐步推进）
     ↑                                              │
     │                                              ↓
     │                                    主对话：同步更新 Spec
     │                                              │
     │                                              ↓
     │                                   [Agent A] Phase 3: 精简 + 测试 → 输出审查报告
     │                                              │
     │                                              ↓ (通过)
     │                                   [Agent B] Phase 4: 功能验证（接收审查报告）
     │                                              │
     │                                              ↓ (通过)
     │                                   [Agent C] Phase 5: 构建
     │                                              │
     └──────────────── Bug 修复 ←──────────────────┘

Phase 1/1.5/2 在主对话完成，Phase 3/4/5 分别启动独立 Agent。 所有 Agent prompt 中的 [feature-name] 由主对话替换为实际值后再传入。

---

Phase 1: 需求定义

将用户需求结构化为 Feature Spec，输出到 docs/features/[feature-name].md。

Feature Spec 结构

# [功能名称]

## 概述
功能名称 / 优先级(P0-P2) / 业务背景(痛点→方案→收益)

## 用户故事
作为 [角色]，我希望 [行为]，以便 [目的]

## 功能列表
- [ ] 功能点1
- [ ] 功能点2

## 技术方案（Phase 1.5 填充）
### API 设计
### 数据模型
### 技术决策

## 测试用例
- [ ] 正常 / 异常 / 边界

## 验收标准

执行步骤

1. 与用户确认需求，识别关键场景和约束
2. 创建 docs/features/[feature-name].md，填充概述、用户故事、功能列表、测试用例
3. 与用户评审确认

---

Phase 1.5: 架构设计

编码前确定技术方案。必须先探索代码库再设计。

执行步骤

1. 探索现有代码库

   • Glob/Grep/Read 扫描相关模块，理解现有模式和架构
   • 识别可复用的组件、Service、工具类
   • 确认集成点

2. 定义 API 契约 — 方法、路径、请求/响应体，写入 Spec 的「API 设计」

3. 设计数据模型 — 表结构、Entity/DTO/VO 映射，写入 Spec 的「数据模型」

4. 记录技术决策 — 选型理由、模块职责、关键约束，写入 Spec 的「技术决策」

完成标准

• 已扫描现有代码，无重复造轮子
• API 契约完整，前后端可并行开发
• 数据模型与现有表结构兼容

---

Phase 2: 模块化开发

依据 Spec 中的 API 契约和数据模型，按子模块逐步推进，自底向上开发：

2a. 数据层 → 2b. 后端 API → 2c. Flutter 前端 → 2d. Admin 前端（如有）
    DDL/Entity   Controller/Service  Model/Provider/UI   Vue Pages

子模块执行方式

• 每个子模块独立完成，不与其他子模块混在一起
• 每完成一个子模块，确认无编译错误再进入下一个
• 后端子模块完成后可先验证 API，前端再对接

代码规范

• Flutter: flutter analyze 无错，用 AppSpacing/AppRadius/AppColorScheme，禁止硬编码颜色
• Java: Lombok 简化，资金变动方法加 @Transactional(rollbackFor = Exception.class)，RESTful 设计

Spec 同步

Phase 2 全部完成后、启动 Agent 前，主对话必须更新 Spec：

• 实际实现与设计有差异时，以实现为准更新 Spec
• 确保 Phase 3/4 的 Agent 读到的是最新状态

---

Phase 3: 精简 + 测试（Agent A）

Phase 2 完成且 Spec 已同步后，启动独立 Agent 执行代码精简和自动化测试。

启动 Agent A

Agent(
  description: "精简+测试验证",
  prompt: |
    你是 Monisuo 项目质量 Agent，独立完成以下任务，不要询问用户。

    ## 1. 读取 Spec
    - 路径: docs/features/[feature-name].md
    - 理解验收标准

    ## 2. 代码审查
    - git diff 查看变更
    - Flutter: flutter analyze, AppSpacing/AppRadius/AppColorScheme 规范
    - Java: @Transactional 资金方法, 统一异常处理, RESTful 设计

    ## 3. 代码精简（simplify）
    - 对变更代码执行 /simplify：审查复用性、质量和效率，修复发现的问题
    - 精简完成后重新运行 git diff 确认变更合理

    ## 4. 测试
    - 后端: mvn test
    - Flutter: cd flutter_monisuo && flutter test
    - API: ./tests/api/test-[feature].sh（如存在）

    ## 5. 输出审查报告（供 Agent B 使用）
    ### 代码审查摘要
    - 变更文件列表及每个文件的核心改动
    - 代码规范检查结果
    - 精简改动摘要（改了什么、为什么改）

    ### 测试结果
    | 项目 | 状态 | 备注 |
    |------|------|------|
    | 代码审查 | ✅/❌ | |
    | 代码精简 | ✅/❌ | 改动摘要 |
    | 后端测试 | ✅/❌ | |
    | Flutter 测试 | ✅/❌ | |

    如有 Bug，列出：文件、原因、修复建议。返回主对话修复后重新验证。
)

---

Phase 4: 功能验证（Agent B）

Agent A 全部通过后，启动独立 Agent。Agent B 接收 Agent A 的审查报告，避免重复读代码。

启动 Agent B

Agent(
  description: "功能验证（用例驱动）",
  prompt: |
    你是 Monisuo 项目功能验证 Agent。基于 Feature Spec 中的测试用例，验证功能实现是否正确。不要询问用户。

    ## 1. 读取 Spec
    - 路径: docs/features/[feature-name].md
    - 提取「测试用例」和「验收标准」

    ## 2. 利用审查报告
    - Agent A 已完成代码审查，变更文件列表和核心改动见报告
    - 仅对报告未覆盖的逻辑路径做补充阅读
    - 对照 Spec 中的 API 设计，确认实现与契约一致

    ## 3. 逐条验证测试用例
    对 Spec 中的每条测试用例：
    - **正常流程**：追踪代码路径，确认主流程逻辑正确（参数传递、返回值、状态变更）
    - **异常流程**：确认错误处理覆盖（参数校验、权限检查、边界条件）
    - **边界条件**：空值、零值、溢出、并发等极端场景是否有防护

    ### 验证方法
    - **后端 API**：阅读 Controller → Service → Mapper 代码路径，确认请求参数、业务逻辑、数据库操作与 Spec 一致
    - **前端页面**：阅读 UI → Provider/State → Service 代码路径，确认交互流程、状态管理、错误展示正确
    - **数据一致性**：确认资金变动相关的操作有事务注解、余额校验、流水记录

    ## 4. 输出验证报告
    | 用例编号 | 用例描述 | 验证结果 | 备注 |
    |----------|----------|----------|------|
    | TC-01 | 正常：xxx | ✅ 通过 / ❌ 失败 | 具体原因 |
    | TC-02 | 异常：xxx | ✅ 通过 / ❌ 失败 | 具体原因 |
    | ... | ... | ... | ... |

    ### 总结
    - 通过率：X/Y
    - 未通过用例：列出失败原因和修复建议
    - 风险点：潜在问题或遗漏

    如有未通过用例，返回主对话修复后重新启动验证。
)

---

Phase 5: 构建（Agent C）

Agent A 和 Agent B 全部通过后，启动独立 Agent 执行构建。

启动 Agent C

Agent(
  description: "项目构建",
  prompt: |
    你是 Monisuo 项目构建 Agent，独立完成构建任务，不要询问用户。

    ## 1. 构建
    - 后端: mvn clean package -DskipTests → target/monisuo-*.jar
    - Flutter: cd flutter_monisuo && flutter build web --release --dart-define=ENV=prod → build/web/

    ## 2. 输出报告
    | 项目 | 状态 | 备注 |
    |------|------|------|
    | 后端构建 | ✅/❌ | 产物路径 |
    | Flutter 构建 | ✅/❌ | 产物路径 |

    如有构建失败，列出：模块、错误信息、修复建议。返回主对话修复后重新构建。
)

---

Bug 修复循环

• Agent A 失败（测试不通过）→ 主对话修复 Bug → 重新启动 Agent A
• Agent B 失败（功能验证不通过）→ 主对话修复逻辑 → 重新启动 Agent B
• Agent C 失败（构建不通过）→ 主对话修复构建问题 → 重新启动 Agent C
• 全部通过 → 开发完成