434 lines
14 KiB
Markdown
434 lines
14 KiB
Markdown
---
|
||
name: monisuo-dev
|
||
description: Monisuo 项目结构化开发流程。融合超级技能体系：需求探索 → 计划分解 → 子代理开发 → 双重审查 → 验证门控 → 构建。
|
||
---
|
||
|
||
# Monisuo 开发工作流
|
||
|
||
融合超级技能（Superpowers）的完整开发流程。每个阶段引用对应的超级技能，确保高质量交付。
|
||
|
||
## 流程概览
|
||
|
||
```
|
||
Phase 0: 分支隔离 → using-git-worktrees
|
||
↓
|
||
Phase 1: 需求探索 → 融合 brainstorming（提问→方案→评审）
|
||
↓
|
||
Phase 1.5: 计划分解 → 融合 writing-plans（咬合级任务+TDD）
|
||
↓
|
||
Phase 2: 开发执行 → 融合 subagent-driven-development（子代理+双重审查）
|
||
↓
|
||
Phase 3: 质量验证 → verification-before-completion 铁律门控
|
||
│ ↓ (通过)
|
||
│ [Agent A] 精简 + 测试 → 输出审查报告
|
||
│ ↓ (通过)
|
||
│ [Agent B] Phase 4: 功能验证
|
||
│ ↓ (通过)
|
||
│ [Agent C] Phase 5: 构建
|
||
↓
|
||
Phase 6: 分支完成 → finishing-a-development-branch
|
||
↑
|
||
Bug 修复循环 → systematic-debugging（根因分析优先）
|
||
```
|
||
|
||
**Phase 0/1/1.5 在主对话完成**（需与用户交互，子代理无法代替）。但其中的**代码库探索**环节可并行派发 Explore 子代理加速。
|
||
**Phase 2 用子代理驱动，Phase 3/4/5 分别启动独立 Agent。**
|
||
|
||
---
|
||
|
||
## Phase 0: 分支隔离
|
||
|
||
**引用技能:** `superpowers:using-git-worktrees`
|
||
|
||
开发前创建隔离工作区，避免在 main 分支直接修改。
|
||
|
||
### 执行步骤
|
||
1. 确认当前在 main 分支且工作区干净
|
||
2. 使用 `EnterWorktree` 创建隔离工作树，分支名 `feat/[feature-name]`
|
||
3. 后续所有开发在 worktree 中进行
|
||
|
||
### 例外
|
||
- 紧急热修复可跳过 worktree，直接在 main 分支操作
|
||
- 用户明确要求跳过时可以跳过
|
||
|
||
---
|
||
|
||
## Phase 1: 需求探索
|
||
|
||
**引用技能:** `superpowers:brainstorming`
|
||
|
||
将用户需求通过协作对话转化为结构化设计。不再直接写 Spec，而是先充分探索。
|
||
|
||
### 执行步骤
|
||
|
||
1. **探索项目上下文** — 检查相关文件、文档、最近提交，理解现有架构
|
||
- **可用 Explore 子代理并行加速**：涉及多个独立模块时（如后端+Flutter+Admin），派发多个 Explore 子代理并行扫描，结果汇总到主对话
|
||
- 单模块时直接在主对话 Glob/Grep/Read 即可，无需子代理
|
||
|
||
2. **逐步提问** — 一次一个问题，理解目的、约束、成功标准（必须主对话）
|
||
- 优先使用选择题，也可开放式
|
||
- 评估范围：如果涉及多个独立子系统，先分解再逐个设计
|
||
|
||
3. **提出 2-3 个方案** — 含权衡分析和推荐理由
|
||
- 领先展示推荐方案及原因
|
||
- 每个方案列出优劣
|
||
|
||
4. **逐节呈现设计** — 按复杂度控制篇幅
|
||
- 每节确认是否正确
|
||
- 覆盖：架构、组件、数据流、错误处理、测试
|
||
|
||
5. **写入 Feature Spec** — 保存到 `docs/features/[feature-name].md`
|
||
|
||
```markdown
|
||
# [功能名称]
|
||
|
||
## 概述
|
||
功能名称 / 优先级(P0-P2) / 业务背景(痛点→方案→收益)
|
||
|
||
## 用户故事
|
||
作为 [角色]，我希望 [行为]，以便 [目的]
|
||
|
||
## 功能列表
|
||
- [ ] 功能点1
|
||
- [ ] 功能点2
|
||
|
||
## 技术方案（Phase 1.5 填充）
|
||
### API 设计
|
||
### 数据模型
|
||
### 技术决策
|
||
|
||
## 测试用例
|
||
- [ ] 正常 / 异常 / 边界
|
||
|
||
## 验收标准
|
||
```
|
||
|
||
6. **Spec 自审** — 快速内联检查
|
||
- 占位符扫描：有无 TBD、TODO、未完成章节？修复。
|
||
- 内部一致性：各章节是否矛盾？
|
||
- 范围检查：是否聚焦到单个实施计划？
|
||
- 歧义检查：需求是否有两种解读？选定一种明确写出。
|
||
|
||
7. **用户确认** — 让用户审阅 Spec 文件，确认后才进入下一阶段
|
||
|
||
### 硬门控
|
||
**用户未确认 Spec 之前，不得进入 Phase 1.5。**
|
||
|
||
---
|
||
|
||
## Phase 1.5: 计划分解
|
||
|
||
**引用技能:** `superpowers:writing-plans`
|
||
|
||
将 Spec 转化为咬合级实施计划，每步 2-5 分钟。必须先探索代码库再设计。
|
||
|
||
### 执行步骤
|
||
|
||
1. **探索现有代码库**
|
||
- **可用 Explore 子代理并行加速**：涉及多个独立模块时（如后端现有 API、Flutter 现有页面、Admin 现有路由），派发多个 Explore 子代理并行扫描
|
||
- 单模块时直接在主对话 Glob/Grep/Read 即可
|
||
- 识别可复用的组件、Service、工具类
|
||
- 确认集成点
|
||
|
||
2. **更新 Spec 技术方案**
|
||
- 定义 API 契约 — 方法、路径、请求/响应体
|
||
- 设计数据模型 — 表结构、Entity/DTO/VO 映射
|
||
- 记录技术决策 — 选型理由、模块职责、关键约束
|
||
|
||
3. **映射文件结构** — 列出所有需要创建/修改的文件及职责
|
||
|
||
4. **编写实施计划** — 保存到 `docs/superpowers/plans/YYYY-MM-DD-[feature-name].md`
|
||
|
||
计划头部：
|
||
```markdown
|
||
# [功能名称] Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task.
|
||
|
||
**Goal:** [一句话描述]
|
||
|
||
**Architecture:** [2-3 句方案描述]
|
||
|
||
**Tech Stack:** [关键技术]
|
||
|
||
---
|
||
```
|
||
|
||
5. **任务分解原则**
|
||
- 每步一个动作（2-5 分钟）
|
||
- TDD 红绿循环：写失败测试 → 验证失败 → 最小实现 → 验证通过 → 提交
|
||
- 按模块自底向上：数据层 → 后端 API → Flutter 前端 → Admin 前端
|
||
- 不允许占位符：每步必须包含实际代码和命令
|
||
|
||
```markdown
|
||
### Task N: [组件名称]
|
||
|
||
**Files:**
|
||
- Create: `exact/path/to/file`
|
||
- Modify: `exact/path/to/existing.java:123-145`
|
||
- Test: `tests/exact/path/test`
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
- [ ] **Step 2: 运行验证失败**
|
||
- [ ] **Step 3: 最小实现**
|
||
- [ ] **Step 4: 运行验证通过**
|
||
- [ ] **Step 5: 提交**
|
||
```
|
||
|
||
6. **计划自审** — 对照 Spec 逐条检查
|
||
- 覆盖性：Spec 每条需求都有对应任务？
|
||
- 占位符扫描：无 TBD/TODO
|
||
- 类型一致性：前后任务的类型、方法签名一致
|
||
|
||
7. **用户提供执行选择**
|
||
- 推荐子代理驱动开发（Phase 2 默认方式）
|
||
- 用户选择内联执行时，按 `superpowers:executing-plans` 执行
|
||
|
||
### 完成标准
|
||
- 已扫描现有代码，无重复造轮子
|
||
- API 契约完整，前后端可并行开发
|
||
- 数据模型与现有表结构兼容
|
||
- 每个任务有完整代码和验证命令
|
||
|
||
---
|
||
|
||
## Phase 2: 开发执行
|
||
|
||
**引用技能:** `superpowers:subagent-driven-development`
|
||
|
||
每个子任务独立子代理执行，完成后双重审查（规格合规 + 代码质量）。
|
||
|
||
### 核心原则
|
||
- 每个任务启动**新的子代理**，不继承主对话上下文
|
||
- 主对话负责提取任务文本、构造上下文、传递给子代理
|
||
- 子代理完成后，先做规格合规审查，再做代码质量审查
|
||
|
||
### 执行流程
|
||
|
||
对计划中的每个任务：
|
||
|
||
```
|
||
1. 提取任务全文和上下文
|
||
2. 启动实现子代理（implementer）
|
||
3. 子代理提问？→ 回答后重新派发
|
||
4. 子代理实现、测试、提交、自审
|
||
5. 启动规格审查子代理 → 不通过？→ 实现子代理修复 → 重新审查
|
||
6. 启动质量审查子代理 → 不通过？→ 实现子代理修复 → 重新审查
|
||
7. 标记任务完成
|
||
```
|
||
|
||
### 模型选择策略
|
||
- **机械任务**（1-2 文件，Spec 完整）→ 快速模型
|
||
- **集成任务**（多文件，模式匹配）→ 标准模型
|
||
- **架构/审查任务** → 最强模型
|
||
|
||
### 子代理行为准则
|
||
- Flutter: `flutter analyze` 无错，用 AppSpacing/AppRadius/AppColorScheme，禁止硬编码颜色
|
||
- Java: Lombok 简化，资金变动方法加 `@Transactional(rollbackFor = Exception.class)`，RESTful 设计
|
||
- Admin: TypeScript strict，TanStack Vue Query 做数据请求，shadcn-vue 组件不手动编辑
|
||
|
||
### 禁止事项
|
||
- 不要在 main/master 分支直接实现
|
||
- 不要跳过任何审查（规格或质量）
|
||
- 不要在审查有未修复问题时进入下一任务
|
||
- 不要并行派发多个实现子代理（会冲突）
|
||
- 不要让子代理自行读取计划文件（主对话提供全文）
|
||
|
||
### Spec 同步
|
||
Phase 2 全部完成后、启动 Agent A 之前，**主对话必须更新 Spec**：
|
||
- 实际实现与设计有差异时，以实现为准更新 Spec
|
||
- 确保 Phase 3/4 的 Agent 读到的是最新状态
|
||
|
||
---
|
||
|
||
## Phase 3: 质量验证（铁律门控）
|
||
|
||
**引用技能:** `superpowers:verification-before-completion`
|
||
|
||
### 验证铁律
|
||
|
||
```
|
||
没有新鲜验证证据，不得声明任何状态。
|
||
```
|
||
|
||
Phase 2 完成后，启动独立 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（读取输出，确认 0 failures）
|
||
- Flutter: cd flutter_monisuo && flutter test（读取输出，确认 0 failures）
|
||
- API: ./tests/api/test-[feature].sh（如存在）
|
||
|
||
## 5. 输出审查报告（供 Agent B 使用）
|
||
### 代码审查摘要
|
||
- 变更文件列表及每个文件的核心改动
|
||
- 代码规范检查结果
|
||
- 精简改动摘要（改了什么、为什么改）
|
||
|
||
### 测试结果
|
||
| 项目 | 状态 | 证据（命令输出摘要） |
|
||
|------|------|----------------------|
|
||
| 代码审查 | ✅/❌ | |
|
||
| 代码精简 | ✅/❌ | 改动摘要 |
|
||
| 后端测试 | ✅/❌ | X/Y 通过 |
|
||
| Flutter 测试 | ✅/❌ | X/Y 通过 |
|
||
|
||
如有 Bug，列出：文件、原因、修复建议。返回主对话修复后重新验证。
|
||
)
|
||
```
|
||
|
||
### 门控
|
||
Agent A 报告中任何一项 ❌ → 主对话修复 → 重新启动 Agent A。
|
||
|
||
---
|
||
|
||
## Phase 4: 功能验证（Agent B）
|
||
|
||
**Agent A 全部通过后**，启动独立 Agent。
|
||
|
||
### 启动 Agent B
|
||
|
||
```
|
||
Agent(
|
||
description: "功能验证（用例驱动）",
|
||
prompt: |
|
||
你是 Monisuo 项目功能验证 Agent。基于 Feature Spec 中的测试用例，验证功能实现是否正确。不要询问用户。
|
||
|
||
## 铁律
|
||
没有运行验证命令，不得声称"通过"。逐条代码追踪，不是靠印象。
|
||
|
||
## 1. 读取 Spec
|
||
- 路径: docs/features/[feature-name].md
|
||
- 提取「测试用例」和「验收标准」
|
||
|
||
## 2. 利用审查报告
|
||
- Agent A 已完成代码审查，变更文件列表和核心改动见报告
|
||
- 仅对报告未覆盖的逻辑路径做补充阅读
|
||
- 对照 Spec 中的 API 设计，确认实现与契约一致
|
||
|
||
## 3. 逐条验证测试用例
|
||
对 Spec 中的每条测试用例：
|
||
- **正常流程**：追踪代码路径 Controller → Service → Mapper，确认参数传递、返回值、状态变更
|
||
- **异常流程**：确认错误处理覆盖（参数校验、权限检查、边界条件）
|
||
- **边界条件**：空值、零值、溢出、并发等极端场景是否有防护
|
||
|
||
## 4. 输出验证报告
|
||
| 用例编号 | 用例描述 | 验证结果 | 证据 |
|
||
|----------|----------|----------|------|
|
||
| TC-01 | 正常：xxx | ✅/❌ | 追踪的具体代码路径 |
|
||
| TC-02 | 异常：xxx | ✅/❌ | 具体原因 |
|
||
|
||
### 总结
|
||
- 通过率：X/Y
|
||
- 未通过用例：列出失败原因和修复建议
|
||
- 风险点：潜在问题或遗漏
|
||
|
||
如有未通过用例，返回主对话修复后重新启动验证。
|
||
)
|
||
```
|
||
|
||
### 门控
|
||
Agent B 报告中有 ❌ → 主对话修复 → 重新启动 Agent B。
|
||
|
||
---
|
||
|
||
## Phase 5: 构建（Agent C）
|
||
|
||
**Agent A 和 Agent B 全部通过后**，启动独立 Agent。
|
||
|
||
### 启动 Agent C
|
||
|
||
```
|
||
Agent(
|
||
description: "项目构建",
|
||
prompt: |
|
||
你是 Monisuo 项目构建 Agent，独立完成构建任务，不要询问用户。
|
||
|
||
## 铁律
|
||
没有运行构建命令并看到 exit 0，不得声称"构建成功"。
|
||
|
||
## 1. 构建（必须运行并读取完整输出）
|
||
- 后端: mvn clean package -DskipTests → target/monisuo-*.jar
|
||
- Flutter: cd flutter_monisuo && flutter build web --release --dart-define=ENV=prod → build/web/
|
||
|
||
## 2. 输出报告
|
||
| 项目 | 状态 | 证据（命令输出摘要） |
|
||
|------|------|----------------------|
|
||
| 后端构建 | ✅/❌ | 产物路径 |
|
||
| Flutter 构建 | ✅/❌ | 产物路径 |
|
||
|
||
如有构建失败，列出：模块、错误信息、修复建议。返回主对话修复后重新构建。
|
||
)
|
||
```
|
||
|
||
### 门控
|
||
Agent C 报告中有 ❌ → 主对话修复 → 重新启动 Agent C。
|
||
|
||
---
|
||
|
||
## Phase 6: 分支完成
|
||
|
||
**引用技能:** `superpowers:finishing-a-development-branch`
|
||
|
||
所有 Phase 通过后，完成开发分支。
|
||
|
||
### 执行步骤
|
||
1. 确认所有测试通过（Phase 3 证据）
|
||
2. 确认功能验证通过（Phase 4 证据）
|
||
3. 确认构建成功（Phase 5 证据）
|
||
4. 向用户展示选项：
|
||
- 合并到 main
|
||
- 创建 PR
|
||
- 保留分支待后续处理
|
||
5. 执行用户选择
|
||
6. 退出 worktree
|
||
|
||
---
|
||
|
||
## Bug 修复循环
|
||
|
||
**引用技能:** `superpowers:systematic-debugging`
|
||
|
||
遇到 Bug 时，严禁猜测式修复。
|
||
|
||
### 四阶段流程
|
||
1. **根因调查** — 重现问题 → 缩小范围 → 找到根因（未完成此阶段不得提出修复）
|
||
2. **修复方案** — 针对根因设计最小修复
|
||
3. **实施修复** → 回到 Phase 3 重新验证
|
||
4. **回归验证** — 确认修复未引入新问题
|
||
|
||
### 错误修复路由
|
||
- **Agent A 失败**（测试不通过）→ 主对话用 systematic-debugging 修复 → 重新启动 Agent A
|
||
- **Agent B 失败**（功能验证不通过）→ 主对话用 systematic-debugging 修复 → 重新启动 Agent B
|
||
- **Agent C 失败**（构建不通过）→ 主对话修复构建问题 → 重新启动 Agent C
|
||
- **全部通过** → Phase 6 分支完成
|
||
|
||
### 严禁
|
||
- 不准跳过根因分析直接修复
|
||
- 不准用"应该修好了"代替验证
|
||
- 不准在疲劳时降低验证标准
|