starmen1265
630dc09062
- 更新 SKILL.md：完整的 Cross 模式流程文档 - 更新 dev_workflow.py：新增 record-debate、record-review 命令 - 新增 debate-template.md：Cross-Debate 模板 - 用户介入点：Phase 1 方案选择 + Phase 6 最终审核 - 六条铁律：Briefing 原则、安全约束等 - 禁止 auto-merge：防止流程错误
367 lines
10 KiB
Markdown
367 lines
10 KiB
Markdown
---
|
||
name: dev-workflow
|
||
description: "Spec-Driven 开发流程技能，支持 Cross-Debate 和 Cross-Review。当用户说'添加功能'、'开发XXX'时使用。"
|
||
---
|
||
|
||
# dev-workflow - Agent Engineering 开发流程
|
||
|
||
## 什么时候使用
|
||
|
||
当用户发送包含以下模式的消息时触发：
|
||
|
||
| 触发词 | 行为 |
|
||
|--------|------|
|
||
| `添加功能` + 描述 | 开始 Agent Engineering 开发流程 |
|
||
| `开发` + 描述 | 同上 |
|
||
| `实现` + 描述 | 同上 |
|
||
|
||
## 环境变量
|
||
|
||
| 变量名 | 用途 | 必需 |
|
||
|--------|------|------|
|
||
| `GITEA_TOKEN` | Gitea API Token（创建 PR） | 是 |
|
||
| `GITEA_URL` | Gitea 服务地址 | 否（默认 http://192.168.1.22:8418） |
|
||
| `GITEA_REPO` | 仓库路径 | 否（默认 starmen1265/kb-skills） |
|
||
|
||
## 工作流程（Cross 模式）
|
||
|
||
```
|
||
用户描述需求
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ Phase 1: Cross-Debate（方案辩论） │
|
||
│ - 3个 Agent 分别出方案 │
|
||
│ - 汇总辩论结果 │
|
||
│ - 用户选择/调整方案 │
|
||
│ - 生成统一 spec.md │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ Phase 2: 分支创建 │
|
||
│ - 创建 feature/* 分支 │
|
||
│ - 切换到功能分支 │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ Phase 3: 子代理开发 │
|
||
│ - 基于 spec 启动开发子代理 │
|
||
│ - 子代理执行开发任务 │
|
||
│ - 本地测试通过 │
|
||
│ - 提交代码到功能分支 │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ Phase 4: Cross-Review（交叉审核） │
|
||
│ - 3个 Agent 交叉审核代码 │
|
||
│ - 汇总问题列表 │
|
||
│ - 自动修复（或请求用户确认） │
|
||
│ - 多轮迭代直到通过 │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ Phase 5: 安全审计 │
|
||
│ - 搜索安全最佳实践 │
|
||
│ - 审计权限/注入/密钥等问题 │
|
||
│ - 修复安全漏洞 │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ Phase 6: 创建 PR │
|
||
│ - 调用 Gitea API 创建 PR │
|
||
│ - ⚠️ 禁止 auto-merge │
|
||
│ - 返回 PR 编号 │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
通知 pr-review-gate 最终审查
|
||
```
|
||
|
||
## 用户介入点
|
||
|
||
| 阶段 | 介入方式 | 说明 |
|
||
|------|---------|------|
|
||
| **Phase 1** | 方案选择 | Cross-Debate 后选择或调整方案 |
|
||
| **Phase 4** | 可选确认 | 有无法决定的问题时介入 |
|
||
| **Phase 6** | 最终审核 | 查看 PR，决定是否合并 |
|
||
|
||
---
|
||
|
||
## 执行步骤详解
|
||
|
||
### Phase 1: Cross-Debate（方案辩论）
|
||
|
||
#### Step 1.1: 启动多 Agent 辩论
|
||
|
||
使用 `sessions_spawn` 并行启动 3 个 Agent：
|
||
|
||
```
|
||
# Agent 1: Claude Code（偏保守，重视安全）
|
||
sessions_spawn(
|
||
task="为以下需求设计方案。你是保守派，重视安全性和稳定性。
|
||
需求：{{用户需求}}
|
||
输出：1) 技术方案 2) 潜在风险 3) 实现步骤",
|
||
agentId="claude-code",
|
||
runtime="acp"
|
||
)
|
||
|
||
# Agent 2: Codex（偏全面，考虑边界情况）
|
||
sessions_spawn(
|
||
task="为以下需求设计方案。你是全面派，考虑所有边界情况。
|
||
需求：{{用户需求}}
|
||
输出：1) 技术方案 2) 边界情况 3) 实现步骤",
|
||
agentId="codex",
|
||
runtime="acp"
|
||
)
|
||
|
||
# Agent 3: Gemini CLI（偏快速，先出方案再补细节）
|
||
sessions_spawn(
|
||
task="为以下需求设计方案。你是快速派，优先快速实现。
|
||
需求：{{用户需求}}
|
||
输出：1) 技术方案 2) MVP范围 3) 实现步骤",
|
||
agentId="gemini",
|
||
runtime="acp"
|
||
)
|
||
```
|
||
|
||
#### Step 1.2: 汇总辩论结果
|
||
|
||
收集三个方案后：
|
||
1. 提取共同点（通常是正确的方向）
|
||
2. 列出分歧点（需要用户决策）
|
||
3. 生成辩论汇总报告
|
||
|
||
#### Step 1.3: 用户选择方案
|
||
|
||
向用户展示：
|
||
```
|
||
## 🗳️ Cross-Debate 结果
|
||
|
||
### 共识点
|
||
- ✅ 使用 XX 技术栈
|
||
- ✅ 需要 YY 数据结构
|
||
|
||
### 分歧点
|
||
| Agent | 方案 | 理由 |
|
||
|-------|------|------|
|
||
| Claude Code | 方案A | 安全性更高 |
|
||
| Codex | 方案B | 考虑边界情况 |
|
||
| Gemini | 方案C | 实现更快 |
|
||
|
||
请选择方案（A/B/C）或提出调整：
|
||
```
|
||
|
||
#### Step 1.4: 生成 Spec
|
||
|
||
用户确认后，创建 `.planning/spec.md` 文件。
|
||
|
||
---
|
||
|
||
### Phase 2: 分支创建
|
||
|
||
```bash
|
||
python3 dev_workflow.py create-branch --spec .planning/spec.md
|
||
```
|
||
|
||
分支命名规则：
|
||
- `feature/<简短描述>` - 新功能
|
||
- `fix/<简短描述>` - Bug 修复
|
||
- `refactor/<简短描述>` - 重构
|
||
|
||
---
|
||
|
||
### Phase 3: 子代理开发
|
||
|
||
使用 `sessions_spawn` 启动开发子代理：
|
||
|
||
```
|
||
sessions_spawn(
|
||
task="""根据 spec 开发 {{功能名称}}
|
||
|
||
## Spec 文件
|
||
读取 .planning/spec.md
|
||
|
||
## 要求
|
||
1. 只写目标，不指定具体文件（自己探索）
|
||
2. 本地测试通过后再提交
|
||
3. 提交信息遵循 Conventional Commits
|
||
|
||
## 安全约束
|
||
- 不能 fail-open
|
||
- 并发请求不能超额
|
||
""",
|
||
cwd="~/work/kb-skills",
|
||
runtime="acp"
|
||
)
|
||
```
|
||
|
||
**Briefing 原则：**
|
||
- ✅ 写目标：Pro 用户改成月度字符预算
|
||
- ✅ 写约束：砍掉所有按次计费逻辑
|
||
- ❌ 不写文件：改 src/api/user.ts
|
||
|
||
---
|
||
|
||
### Phase 4: Cross-Review（交叉审核）
|
||
|
||
#### Step 4.1: 启动多 Agent 审核
|
||
|
||
```
|
||
# Agent 1: 纯代码审查
|
||
sessions_spawn(
|
||
task="审查当前分支的代码变更。纯看代码，不给参考文档。
|
||
检查：1) 逻辑错误 2) 边界情况 3) 代码风格",
|
||
agentId="claude-code",
|
||
runtime="acp"
|
||
)
|
||
|
||
# Agent 2: 带文档审查
|
||
sessions_spawn(
|
||
task="审查当前分支的代码变更。先搜索相关官方文档，再审代码。
|
||
检查：1) API使用正确性 2) 最佳实践 3) 文档一致性",
|
||
agentId="codex",
|
||
runtime="acp"
|
||
)
|
||
|
||
# Agent 3: 测试覆盖审查
|
||
sessions_spawn(
|
||
task="审查当前分支的测试覆盖。检查：
|
||
1) 单元测试覆盖 2) 边界情况测试 3) 集成测试",
|
||
agentId="gemini",
|
||
runtime="acp"
|
||
)
|
||
```
|
||
|
||
#### Step 4.2: 汇总问题并修复
|
||
|
||
```json
|
||
{
|
||
"critical": [
|
||
"外键顺序 bug：扣费逻辑先写子表再写父表"
|
||
],
|
||
"high": [
|
||
"RPC 权限暴露：任何登录用户都能直接调"
|
||
],
|
||
"medium": [
|
||
"Booster 购买没验证 payment_status"
|
||
]
|
||
}
|
||
```
|
||
|
||
自动修复或请求用户确认。
|
||
|
||
#### Step 4.3: 多轮迭代
|
||
|
||
如果发现问题：
|
||
1. 修复后重新触发 Cross-Review
|
||
2. 重复直到无 Critical/High 问题
|
||
|
||
---
|
||
|
||
### Phase 5: 安全审计
|
||
|
||
```
|
||
sessions_spawn(
|
||
task="""安全审计当前分支代码。
|
||
|
||
## 审计清单
|
||
1. 搜索 OWASP Top 10 相关最佳实践
|
||
2. 搜索平台（如 Stripe/Supabase）安全文档
|
||
3. 检查以下问题：
|
||
- SQL 注入
|
||
- 权限暴露（如 PostgreSQL 函数权限）
|
||
- 密钥泄露（检查日志、错误信息）
|
||
- fail-open 问题
|
||
- 并发竞态条件
|
||
|
||
## 输出
|
||
- Critical 漏洞（必须修复）
|
||
- High 风险（建议修复）
|
||
- 安全建议
|
||
""",
|
||
agentId="claude-code",
|
||
runtime="acp"
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
### Phase 6: 创建 PR
|
||
|
||
开发完成后：
|
||
|
||
```bash
|
||
python3 dev_workflow.py create-pr --branch feature/xxx --title "PR 标题"
|
||
```
|
||
|
||
**⚠️ 禁止 auto-merge**：必须等待用户最终审核。
|
||
|
||
PR 创建后告知用户：
|
||
|
||
```
|
||
✅ PR #xxx 已创建
|
||
|
||
**分支:** feature/xxx
|
||
**链接:** http://192.168.1.22:8418/starmen1265/kb-skills/pulls/xxx
|
||
|
||
**已完成：**
|
||
- ✅ Cross-Debate（3个Agent辩论）
|
||
- ✅ Cross-Review（3个Agent审核，X轮）
|
||
- ✅ 安全审计
|
||
|
||
**下一步：** 请审核 PR，确认无误后合并。
|
||
```
|
||
|
||
---
|
||
|
||
## CLI 命令
|
||
|
||
```bash
|
||
# 创建 spec（从 Cross-Debate 结果）
|
||
python3 dev_workflow.py create-spec --title "标题" --description "描述"
|
||
|
||
# 从 spec 创建分支
|
||
python3 dev_workflow.py create-branch --spec .planning/spec.md
|
||
|
||
# 创建 PR（禁止 auto-merge）
|
||
python3 dev_workflow.py create-pr --branch feature/xxx --title "PR标题"
|
||
|
||
# 查看当前状态
|
||
python3 dev_workflow.py status
|
||
|
||
# 记录 Cross-Debate 结果
|
||
python3 dev_workflow.py record-debate --file .planning/debate.md
|
||
|
||
# 记录 Cross-Review 结果
|
||
python3 dev_workflow.py record-review --round 1 --issues '[{"level":"critical","desc":"..."}]'
|
||
```
|
||
|
||
---
|
||
|
||
## 与其他技能的协作
|
||
|
||
| 技能 | 协作方式 |
|
||
|------|----------|
|
||
| **pr-review-gate** | PR 创建后触发最终审查 |
|
||
| **kb-workflow** | 可复用其目录结构 |
|
||
| **GSD** | 采用其 Spec-Driven 方法论 |
|
||
|
||
---
|
||
|
||
## 六条铁律
|
||
|
||
1. **Briefing 写目标，不写文件** - 你是 PM，Agent 是工程师
|
||
2. **Agent 共识需要人类验证** - 三个 AI 同意不代表正确
|
||
3. **本地完成所有工作再推远端** - 实现、测试、审核、修复全在本地
|
||
4. **安全约束要写进 Briefing** - "不能 fail-open"、"并发不能超额"
|
||
5. **密钥永远不过聊天** - 用环境变量文件，命令里用变量名
|
||
6. **Briefing 必须包含产品上下文** - 用户画像、产品定位、商业模式
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. 确保 `GITEA_TOKEN` 已配置
|
||
2. 功能分支命名遵循规范
|
||
3. 提交信息遵循 Conventional Commits
|
||
4. 开发前先 pull 最新代码
|
||
5. **禁止 auto-merge** - 流程错误比代码 bug 更贵
|