claude_dev
03a3d9ae5e
- 添加 Issue 结构（工作清单模式） - 添加 6 步工作流程 - 添加 Comment 标记约定 - 添加流程图 - 添加偏差处理机制 - 简化感知机制：Sub 完成标记 → Main 主动读取 Gitea
26 KiB
26 KiB
sanguo_moziplus_v3 设计文档 v0.5
项目名称: sanguo_moziplus_v3
版本: v0.5
状态: Draft
创建日期: 2026-07-01
摘要
sanguo_moziplus_v3 是一个基于 Claude Code 的多 Agent 协作系统。系统采用 Main Agent 编排 + Sub Agents 执行 的架构，通过动态编排实现灵活的任务协作。
核心特性：
- Main Agent 作为编排者，根据任务需要动态安排 Sub Agents
- 集成标准化工作流（规划、执行、审查、调试、完成）
- 通过工程审慎决策框架（Linus 三问）过滤需求和方案
- 上下文隔离确保各 Agent 专注执行
目录
1. 系统架构
1.1 架构概览
┌─────────────────────────────────────────────────────────────────┐
│ Main Agent (编排者) │
│ │
│ 职责: │
│ • 接收用户需求 │
│ • 工程审慎决策 (Linus 三问) │
│ • 需求讨论与澄清 │
│ • 分析任务复杂度 │
│ • 动态安排 Sub Agents │
│ • 验收整合结果 │
│ │
│ 核心能力: │
│ • 需求讨论 (deep-interview) │
│ • 方案规划 (writing-plans) │
│ • 代码审查 (requesting-code-review) │
│ • 问题诊断 (systematic-debugging) │
│ • Agent 编排工具 │
└─────────────────────────────────────────────────────────────────┘
│
│ Agent 工具动态编排
│
┌──────────┼──────────┐
│ │ │
▼ ▼ ▼
┌──────────────────┐ ┌──────────┐ ┌──────────┐
│ Sub Agent: │ │Sub Agent:│ │Sub Agent:│
│ Execute │ │Review │ │Test │
│ │ │ │ │ │
│ 专业角色: │ │专业角色: │ │专业角色: │
│ • backend-dev │ • 代码质量 │ • 单元测试 │
│ • frontend-dev │ • 安全性 │ • E2E测试 │
│ • database-dev │ • 性能 │ • QA测试 │
│ • infrastructure │ │ │
└──────────────────┘ └──────────┘ └──────────┘
所有 Agent 都能访问标准化工作流能力
1.2 核心设计原则
| 原则 | 说明 |
|---|---|
| 动态编排 | Main Agent 根据任务需要决定安排哪些 Sub Agents，不使用固化流程 |
| 专业分工 | Sub Agents 有明确的专业角色（Execute/Review/Test） |
| 上下文隔离 | 每个 Sub Agent 只能看到完成工作所需的最小信息 |
| 验证整合 | Main Agent 负责最终验收和结果整合 |
| 标准化工作流 | 所有 Agent 遵循相同的五阶段工作流 |
1.3 标准化工作流
系统遵循五阶段工作流（源自 Superpowers 标准实践）：
┌──────────────┐ ┌──────────────┐ ┌───────────────┐ ┌──────────────┐ ┌──────────────┐
│ 1. 规划 │ → │ 2. 执行 │ → │ 3. 审查 │ → │ 4. 调试 │ → │ 5. 完成 │
│ writing-plans │ │ executing │ │ requesting │ │ systematic │ │ finishing │
│ │ │ -plans │ │ -code-review │ │ -debugging │ │ -development │
│ │ │ │ │ │ │ │ │ -branch │
└──────────────┘ └──────────────┘ └───────────────┘ └──────────────┘ └──────────────┘
编写计划 执行计划 请求审查 系统调试 完成收尾
2. 角色定义
2.1 Main Agent (编排者)
职责范围：
| 领域 | 职责 | 工具/方法 |
|---|---|---|
| 需求管理 | 接收、澄清、确认需求 | deep-interview skill |
| 工程决策 | Linus 三问审慎判断 | 决策框架 |
| 任务分析 | 评估复杂度、确定所需 Sub Agents | 分析逻辑 |
| 编排执行 | 安排 Sub Agents、协调协作 | Agent 工具 |
| 验收整合 | 验证结果、一致性检查、整合输出 | requesting-code-review skill + 一致性检查 |
工作方式：
1. 接收用户需求
2. Linus 三问过滤（是否现实问题、是否需要解决、方案是否可行）
3. 需求澄清（如需要，使用 deep-interview）
4. 分析任务复杂度
5. 决定编排策略（简单/中等/复杂）
6. 执行编排
7. 验收整合
8. 向用户汇报
严格限制：
- 不亲自编写代码
- 不亲自执行具体实现
2.2 Sub Agent: Execute (执行者)
专业角色：
- backend-dev: 后端开发（API、数据库、业务逻辑）
- frontend-dev: 前端开发（UI/UX、交互、状态管理）
- database-dev: 数据库开发（Schema、迁移、优化）
- infrastructure: 基础设施（部署、监控、配置）
上下文：接收任务描述和项目代码访问权限
2.3 Sub Agent: Review (审查者)
专业角色：
- 代码质量审查：代码规范、可维护性、设计模式
- 安全审查：安全漏洞、权限控制、数据保护
- 性能审查：性能瓶颈、资源使用、优化建议
上下文：接收需要审查的代码和审查标准
2.4 Sub Agent: Test (测试者)
专业角色：
- 单元测试：代码级测试、覆盖率、边界情况
- E2E 测试：端到端场景、用户流程、集成测试
- QA 测试：质量保证、测试计划、验收标准
上下文：接收需要测试的功能和测试要求
3. 编排机制
3.1 编排策略
Main Agent 根据任务复杂度采用不同的编排策略：
| 复杂度 | 特征 | 编排策略 |
|---|---|---|
| 简单 | 明确的 bug 修复、小改动 | Execute → 验收 |
| 中等 | 单一功能实现 | 需求讨论 → Execute → Review → 验收 |
| 复杂 | 多功能、跨领域 | 需求讨论 → 规划 → Execute → Review → Test → 验收 |
| 调试 | 问题定位和修复 | 定位 → Execute → Test → 验收 |
3.2 工程审慎决策（Linus 三问）
Main Agent 在编排前必须通过三问过滤：
| 问题 | 判断标准 | 拒绝条件 |
|---|---|---|
| 1. 这是现实问题还是想象问题？ | 有明确证据或用户反馈 | "可能需要"、"也许将来" |
| 2. 这个问题真的需要解决吗？ | 影响核心功能或用户体验 | 边缘场景、伪需求 |
| 3. 这个方案真的能解决问题吗？ | 有明确验证路径 | 理论上可行但无验证 |
决策流程：
用户需求
↓
Linus 三问
↓
┌─────────────┐
│ 通过？ │
└──────┬──────┘
├─ 否 → 拒绝/澄清
└─ 是 → 继续编排
↓
需求清晰？
├─ 否 → deep-interview
└─ 是 → 执行编排
3.3 需求讨论机制
当需求不清晰时，Main Agent 使用 deep-interview 方法：
ASK → LISTEN → WRITE → DEEPEN → REPEAT
- ASK: 每次提问不超过 2-3 个问题
- LISTEN: 认真听取用户回答
- WRITE: 立即记录到
requirements/目录 - DEEPEN: 根据答案深入追问
- REPEAT: 直到需求清晰为止
3.4 上下文隔离
隔离原则：
Main Agent
│
├─ Execute Sub Agent
│ └─ 只看到: 任务描述 + 项目代码
│
├─ Review Sub Agent
│ └─ 只看到: 需要审查的代码
│
└─ Test Sub Agent
└─ 只看到: 需要测试的功能
为什么隔离：
- Execute 不受 Review 影响，专注实现
- Review 不受实现过程影响，客观评估
- Test 不受实现细节影响，独立验证
3.5 编排模式
并行编排
// 独立任务可并行执行
const [backend, frontend] = await Promise.all([
agent({ prompt: "后端: 实现 API" }),
agent({ prompt: "前端: 实现页面" })
])
串行编排
// 有依赖关系需串行执行
const execute = await agent({ prompt: "实现功能" })
const review = await agent({ prompt: `审查: ${execute.files}` })
条件编排
// 根据中间结果决定下一步
const execute = await agent({ prompt: "实现功能" })
const review = await agent({ prompt: `审查: ${execute.files}` })
if (review.passed) {
return await integrate(execute, review)
} else {
const fix = await agent({ prompt: `修复: ${review.findings}` })
return await integrate(fix, await agent({ prompt: `重新审查: ${fix.files}` }))
}
3.6 验收机制：需求-设计-编码一致性检查
Main Agent 在验收时必须执行三向一致性检查：
┌─────────────────────────────────────────────────────────────┐
│ 验收：三向一致性检查 │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 需求 │ ←→ │ 设计 │ ←→ │ 编码 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ ↑ ↑ ↑ │
│ └──────────────┴──────────────┘ │
│ 一致性检查 │
└─────────────────────────────────────────────────────────────┘
检查方法：
对照三向检查，逐项验证：
- 需求 → 设计：设计是否完整覆盖需求？
- 设计 → 编码：编码是否正确实现设计？
- 需求 → 编码：实现是否满足原始需求？
偏差处理：
发现偏差时，重新进入 Superpowers 五阶段工作流：
验收发现偏差
↓
┌─────────────────────────────────┐
│ 重新进入 Superpowers 工作流 │
│ │
│ 1. 规划 (writing-plans) │ ← 需求/设计偏差
│ 2. 执行 (executing-plans) │ ← 编码偏差
│ 3. 审查 (requesting-code-review) │
│ 4. 调试 (systematic-debugging) │
│ 5. 完成 (finishing-development) │
│ │
│ → 重新验收 │
└─────────────────────────────────┘
一致性检查时机：
- 复杂任务：每次 Sub Agent 完成后检查
- 中等任务：Review 阶段检查
- 简单任务：最终验收时检查
4. 工作流程
4.1 标准工作流（五阶段）
阶段 1：规划 (writing-plans)
何时使用：复杂任务（涉及多个领域或需要架构决策）
输出：一份假设执行者对代码库零上下文的实现计划
内容包括：
- 任务背景和目标
- 技术方案选择
- 实施步骤
- 验收标准
阶段 2：执行 (executing-plans)
方式：通过 Agent 工具编排 Sub Agents
执行模式：
- 并行执行独立任务
- 串行执行有依赖的任务
- 根据审查结果调整执行
阶段 3：审查 (requesting-code-review)
何时使用：代码实现完成后、向用户汇报前
检查维度：
- 逻辑正确性和边界情况
- 安全漏洞
- 性能影响
- 测试覆盖率
- 错误处理
阶段 4：调试 (systematic-debugging)
何时使用：遇到问题或错误时
方法：
- 系统化定位问题（而非随机尝试）
- 分析根本原因
- 设计验证方案
阶段 5：完成 (finishing-a-development-branch)
内容：
- 确认所有测试通过
- 验证代码质量
- 准备提交
- 清理临时文件
4.2 任务类型示例
简单任务：修复 Bug
用户: "登录接口报错"
↓
Main Agent: 快速确认错误信息
↓
安排 debugger Sub Agent 定位问题
↓
安排 Execute Sub Agent 修复
↓
安排 Test Sub Agent 验证
↓
验收整合
中等任务：实现登录功能
用户: "实现用户登录功能"
↓
Main Agent: deep-interview 需求讨论
↓
记录需求到 requirements/requirements.md
↓
安排 Execute Sub Agent 实现
↓
安排 Review Sub Agent 审查
↓
验收整合
复杂任务：实现用户认证系统
用户: "实现用户认证系统"
↓
Main Agent: deep-interview 深度需求讨论
↓
使用 writing-plans 规划
↓
并行安排 Execute Sub Agents（后端 + 前端）
↓
安排 Review Sub Agents（代码 + 安全）
↓
安排 Test Sub Agent 验证
↓
验收整合
5. 实施指南
5.1 环境配置
项目结构：
sanguo_moziplus_v3/
├── .claude/
│ ├── CLAUDE.md # Main Agent 配置
│ └── workflows/
│ └── dynamic-orchestration.js # 编排脚本
├── requirements/ # 需求文档
└── docs/design/ # 设计文档
Main Agent 配置 (.claude/CLAUDE.md)：
# Main Agent 配置
## 角色
你是任务编排者，负责与用户讨论需求、动态安排 Sub Agents、验收整合。
## 核心职责
1. 需求讨论 - 使用 deep-interview skill
2. 工程决策 - Linus 三问过滤
3. 任务分析 - 评估复杂度
4. 编排执行 - 动态安排 Sub Agents
5. 验收整合 - 验证并整合结果
## 严格限制
- 不亲自编写代码
- 不亲自执行具体实现
## 可用能力
- deep-interview - 需求讨论
- writing-plans - 方案规划
- requesting-code-review - 代码审查
- systematic-debugging - 问题诊断
- Agent 工具 - 编排 Sub Agents
5.2 编排脚本示例
export const meta = {
name: 'dynamic-orchestration',
description: 'Main Agent 根据任务需要动态编排 Sub Agents',
phases: [
{ title: '分析', detail: '分析任务需求' },
{ title: '编排', detail: '决定 Sub Agents' },
{ title: '执行', detail: 'Sub Agents 执行' },
{ title: '验收', detail: '验收整合' }
]
}
export default async function (task) {
// 1. 分析任务
const analysis = await analyzeTask(task)
// 2. 根据复杂度编排
if (analysis.complexity === 'high') {
// 复杂任务：规划 → 执行 → 审查 → 测试
const plan = await Skill({ skill: 'writing-plans', args: task })
const execute = await executeAgents(plan)
const review = await reviewAgents(execute)
const test = await testAgents(execute)
return await integrate(plan, execute, review, test)
}
if (analysis.complexity === 'medium') {
// 中等任务：执行 → 审查
const execute = await executeAgents(task)
const review = await reviewAgents(execute)
return await integrate(execute, review)
}
// 简单任务：直接执行
const execute = await executeAgents(task)
return await integrate(execute)
}
5.3 Gitea 协作流程
系统使用 Gitea Issue 作为协作中心，Main Agent 和 Sub Agents 在同一个 Issue 中协作。
5.3.1 Issue 结构
Issue 标题格式：
[sanguo_moziplus_v3] 功能描述
Issue 正文结构：
## 项目信息
- 项目: sanguo_moziplus_v3
- 需求编号: D-N
- 复杂度: 简单/中等/复杂
## 需求描述
<!-- 用户需求概述 -->
## 执行清单
### 📋 Execute Sub Agent
> **负责**: Execute Sub Agent
> **状态**: 🔄 进行中
- [ ] 任务1...
- [ ] 任务2...
**完成时标记**: `@main-agent ✅ EXECUTE_DONE`
### 📋 Review Sub Agent
> **负责**: Review Sub Agent
> **状态**: ⏳ 等待中
- [ ] 检查项1...
- [ ] 检查项2...
**完成时标记**: `@main-agent ✅ REVIEW_DONE verdict=approved/rejected`
### 📋 Test Sub Agent
> **负责**: Test Sub Agent
> **状态**: ⏳ 等待中
- [ ] 测试项1...
- [ ] 测试项2...
**完成时标记**: `@main-agent ✅ TEST_DONE result=passed/failed`
### 📋 Main Agent 验收
> **负责**: Main Agent
> **状态**: ⏳ 等待中
- [ ] 需求 → 设计 一致性
- [ ] 设计 → 编码 一致性
- [ ] 需求 → 编码 一致性
**完成时标记**: `@main-agent ✅ VERIFICATION_PASSED`
## 执行状态
| 阶段 | 负责者 | 状态 | 更新时间 |
|------|-------|------|---------|
| Execute | Execute Sub Agent | 🔄 进行中 | - |
| Review | Review Sub Agent | ⏳ 等待 | - |
| Test | Test Sub Agent | ⏳ 等待 | - |
| 验收 | Main Agent | ⏳ 等待 | - |
5.3.2 工作流程
Step 1: Main Agent 创建 Issue
Main Agent 接收需求后，创建 Issue 并制定工作清单。
Step 2: Sub Agents 工作并更新
Sub Agents 在工作过程中通过 Issue Comments 更新进度：
@main-agent 📝 **进度更新: Execute 阶段**
## 已完成
- ✅ 1.1 数据库迁移
- ✅ 1.2 核心逻辑实现
## 进行中
- 🔄 1.3 API 接口实现
---
**进度**: 66% (2/3 完成)
Step 3: Sub Agent 完成后发布标记
Sub Agent 完成工作后，发布标准格式的完成标记：
@main-agent ✅ **EXECUTE_DONE**
## 完成总结
### 交付物
1. `db/migrations/001_login_attempts.sql` - 数据库迁移
2. `src/auth/login_checker.py` - 核心逻辑
3. `src/api/routes/auth.py` - API 集成
### 测试状态
- 本地运行: ✅ PASS
- 覆盖率: 85%
---
**执行者**: Execute Sub Agent
**完成时间**: 2026-07-01 12:00
Step 4: Main Agent 读取 Gitea 并编排下一阶段
Sub Agent 完成后，Main Agent 主动读取 Gitea 状态：
// Main Agent 感知 Sub Agent 完成并编排
async function checkAndOrchestrate(issueNumber) {
// 1. 读取 Issue Comments
const comments = await gitea.getIssueComments(issueNumber)
// 2. 解析完成标记
const executeDone = comments.some(c => c.body.includes('✅ EXECUTE_DONE'))
const reviewDone = comments.some(c => c.body.includes('✅ REVIEW_DONE'))
const testDone = comments.some(c => c.body.includes('✅ TEST_DONE'))
// 3. 根据状态编排下一阶段
if (executeDone && !reviewDone) {
// Execute 完成 → 启动 Review + Test 并行
await notifyAgents(issueNumber, 'Review 和 Test 可以开始了')
}
if (reviewDone && testDone) {
// Review + Test 完成 → 启动验收
await startVerification(issueNumber)
}
}
Step 5: Main Agent 执行三向一致性检查
Main Agent 在验收时执行一致性检查，并发布结果：
@main-agent ✅ **VERIFICATION_PASSED**
## 三向一致性检查
### 1️⃣ 需求 → 设计
| 需求项 | 设计覆盖 | 状态 |
|--------|---------|------|
| IP 5次/5分钟 | login_attempts + 计数逻辑 | ✅ |
| 用户名 3次 | login_attempts + 计数逻辑 | ✅ |
| 锁定 30/15分钟 | locked_until 字段 | ✅ |
✅ **需求→设计: 通过**
### 2️⃣ 设计 → 编码
| 设计 | 代码 | 状态 |
|------|------|------|
| 数据库表 | 001_login_attempts.sql | ✅ |
| 检查逻辑 | login_checker.py | ✅ |
✅ **设计→编码: 通过**
### 3️⃣ 需求 → 编码
| 需求 | 代码实现 | 状态 |
|------|---------|------|
| IP 5次/5分钟 | IP_MAX_ATTEMPTS=5, IP_WINDOW=300 | ✅ |
| 锁定 30/15分钟 | IP_LOCK_DURATION=1800 | ✅ |
✅ **需求→编码: 通过**
## 最终结论
✅ **三向一致性检查全部通过**
**VERDICT**: ✅ APPROVED FOR MERGE
---
**执行者**: Main Agent
**完成时间**: 2026-07-01 13:00
Step 6: 关闭 Issue
Main Agent 更新 Issue 状态：
## 最终状态: ✅ COMPLETED
### 完成链路
1. ✅ Execute Sub Agent 完成 (12:00)
2. ✅ Review Sub Agent 通过 (12:30)
3. ✅ Test Sub Agent 通过 (12:45)
4. ✅ Main Agent 验收通过 (13:00)
### 三向一致性
- 需求 → 设计: ✅
- 设计 → 编码: ✅
- 需求 → 编码: ✅
---
**状态**: Closed
**标签**: completed, verified, D-1
5.3.3 Comment 标记约定
| Sub Agent | 完成标记格式 | 说明 |
|---|---|---|
| Execute | @main-agent ✅ EXECUTE_DONE |
包含交付物清单 |
| Review | @main-agent ✅ REVIEW_DONE verdict=approved |
包含检查结果 |
| Test | @main-agent ✅ TEST_DONE result=passed coverage=85% |
包含测试结果 |
| Main | @main-agent ✅ VERIFICATION_PASSED |
包含三向检查结果 |
5.3.4 流程图
┌─────────────────────────────────────────────────────────────────────┐
│ Gitea 协作流程 │
│ │
│ Main Agent 创建 Issue #42 │
│ ├─ 标题: [sanguo_moziplus_v3] 功能描述 │
│ ├─ 工作清单: Execute / Review / Test / 验收 │
│ └─ 状态表: 初始状态 │
│ ↓ │
│ Execute Sub Agent 工作... │
│ └─ Comment: "@main-agent ✅ EXECUTE_DONE" │
│ ↓ │
│ Main Agent 读取 Gitea → 感知到 EXECUTE_DONE │
│ └─ @review @test 请开始工作 │
│ ↓ │
│ Review + Test 并行工作... │
│ ├─ Review: "@main-agent ✅ REVIEW_DONE verdict=approved" │
│ └─ Test: "@main-agent ✅ TEST_DONE result=passed" │
│ ↓ │
│ Main Agent 读取 Gitea → 感知到 REVIEW_DONE + TEST_DONE │
│ └─ 开始三向一致性检查 │
│ ↓ │
│ Main Agent Comment: "@main-agent ✅ VERIFICATION_PASSED" │
│ ↓ │
│ Main Agent 更新 Issue → Closed ✅ │
│ │
└─────────────────────────────────────────────────────────────────────┘
5.3.5 偏差处理
如果 Main Agent 在验收时发现偏差：
@main-agent ❌ **CONSISSYENCY_ISSUE**
## 发现偏差
### 问题: 需求 → 编码 偏差
**需求**: "锁定期间即使密码正确也不允许登录"
**代码**: login_checker.py:L45 中，锁定检查在密码验证之后执行
### 处理要求
1. 将锁定检查移到密码验证之前
2. 添加测试用例验证此场景
3. 重新提交 review
---
**标签**: needs-consistency-fix 🔴
Sub Agent 修复后重新发布完成标记，Main Agent 重新验收。
6. 附录
6.1 术语表
| 术语 | 说明 |
|---|---|
| Main Agent | 编排者，负责任务编排和结果整合 |
| Sub Agent | 执行者，负责具体实现、审查、测试 |
| deep-interview | 需求讨论方法，ASK→LISTEN→WRITE→DEEPEN→REPEAT |
| Linus 三问 | 工程审慎决策框架 |
| 标准化工作流 | 五阶段：规划→执行→审查→调试→完成 |
6.2 版本历史
| 版本 | 日期 | 变更 |
|---|---|---|
| v0.5 | 2026-07-01 | Main Agent + Sub Agents 动态编排 |
| v0.5.1 | 2026-07-01 | 补充 Linus 三问 + 标准化工作流 |
6.3 参考资料
- Superpowers 标准工作流规范
- Claude Code Agent 工具文档
- Linus Torvalds: "Talk Like a Kernel Developer"
文档版本: v0.5
最后更新: 2026-07-01
维护者: Claude Dev