kb-skills/dev-workflow/SKILL.md

name, description

name	description
dev-workflow	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: 分支创建

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: 汇总问题并修复

{
  "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

开发完成后：

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 命令

# 创建 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 更贵