AI Auto Dev

AI全自动化编程,Claude Code作为项目经理指挥Builder自动完成编程任务(需求对齐→指令生成→自动执行→验收→文档归档暂存)

# AI 全自动化编程 (ai-auto-dev) v2.2

Claude Code 作为项目经理，Builder 作为执行者的全自动化编程流程。

> **v2.2 更新**（2026-02-22）：新增中断恢复机制（FlowPilot 启发）、依赖图自动分析（替代手动 [P] 标记）

---

## 前置条件

选择一个 Builder（AI 编程执行工具），推荐以下任一：

| Builder | 安装 | 执行命令 |
|---------|------|---------|
| Codex CLI | `npm i -g @openai/codex` | `codex exec --skip-git-repo-check "$(cat spec.md)"` |
| Claude Code | 已内置 | 直接在对话中执行 |
| Aider | `pip install aider-chat` | `aider --message "$(cat spec.md)"` |

**关键要求**：Builder 必须有完整文件系统访问权限，能执行 npx/node/tsc 等命令。

以 Codex 为例，`~/.codex/config.toml` 需配置：
```toml
ask_for_approval = "never"
sandbox_mode = "danger-full-access"
```

> ⚠️ **重要**：必须使用完整访问权限模式，受限模式会阻止 npx/node/tsc 等命令，导致三重纠错无法执行，Token 浪费 60%。

---

## 工作流程

### 第零步：会话暖场（每次必做）

**目的**：建立 Claude Code 会话信任，避免后续 Bash 后台任务需要确认

**操作**：
```bash
echo "Warmup at $(date '+%Y-%m-%d %H:%M:%S')" && sleep 2 && echo "Ready"
```

**要求**：
- 每次调用 `/ai-auto-dev` 都必须先执行暖场
- 使用 `run_in_background: true` 参数
- 等待完成通知（约 2-3 秒）
- 完成后进入第一步

**原理**：
- Claude Code 的会话信任机制存储在内存中
- 重启电脑后会清除，需要重新建立
- 首次后台任务需要确认，后续任务无需确认
- 暖场任务快速完成（<5 秒），建立信任后一整天无需确认

---

### 第一步：需求对齐

1. 用户提出需求
2. Claude Code 与用户反复讨论，直到完全理解
3. Claude Code **复述需求**给用户确认，必须包含：
   - **要做什么**：功能描述
   - **技术栈和约束**：语言、框架、依赖
   - **目录结构**：文件放在哪里
   - **交付物清单**：具体的文件名列表
   - **测试要求**：需要什么样的测试
4. 用户确认后才进入下一步
5. **禁止跳过此步**：需求不清就开始执行 = 浪费 Token

---

### 第二步：生成 Spec MD

**使用新模板**（v2.0 核心改进）：

1. 复制 `specs/SPEC-TEMPLATE.md` 为 `specs/TASK-{id}-{name}.md`
2. 参考 `specs/SPEC-TEMPLATE-GUIDE.md` 填写
3. Spec 必须包含以下 5 个核心改进：

#### 改进 1：NEEDS CLARIFICATION 机制
- 最多 3 个问题（优先级：范围 > 安全/隐私 > 用户体验 > 技术细节）
- 其他不确定的地方用假设替代，记录在 `## Assumptions` 章节
- 格式：`[假设: 具体内容]`
- **价值**：减少执行时的犹豫，消除"猜测-验证"循环

#### 改进 2：User Stories 结构
```markdown
### US1: 功能名称 (Priority: P1)
作为[角色]，我需要[功能]，以便[价值]。

**Acceptance Scenarios:**
- **Given** [前置条件]，**When** [操作]，**Then** [预期结果]

**Test Criteria:**
- [ ] {具体可测试的标准}
```

#### 改进 3：[P][US] 标记
- `[P]` = 可与其他 [P] 步骤并行执行
- `[US1][US2]` = 关联到对应用户故事
- 格式：`### Step 1: 创建模块 [P] [US1]`

#### 改进 4：Self-Check Requirements（三重纠错）
Spec 中必须包含此章节，Builder 执行后强制运行：

```markdown
## Self-Check Requirements (MANDATORY)

### Check 1: Static Analysis
```bash
npx tsc --noEmit --strict --skipLibCheck
```

### Check 2: Test Execution
```bash
npm test  # 或 jest / vitest --run
```

### Check 3: Build Verification
```bash
npm run build
```

### Check 4: Generate self-check-report.md
创建 {output-dir}/self-check-report.md，包含：
- Static Analysis: PASS/FAIL + 错误数
- Tests: PASS/FAIL + 通过/失败数
- Build: PASS/FAIL
- Files Created: 列表
- Issues Found: 列表
- Overall: PASS/FAIL

### Check 5: Reflection（如果失败）
如果任何检查失败：
1. 分析失败原因
2. 生成修复建议
3. 报告给 PM
```

#### 改进 5：Verification Checklist
```markdown
## Verification Checklist

### Code Quality
- [ ] TypeScript 编译无错误
- [ ] 所有测试通过
- [ ] 无 console.log 残留

### Functional Requirements (US1)
- [ ] {US1 的具体需求}

### Functional Requirements (US2)
- [ ] {US2 的具体需求}

### Edge Cases
- [ ] 空输入处理
- [ ] 边界值处理

### Security & Performance
- [ ] 无安全漏洞
- [ ] 无性能瓶颈
```

**任务拆解原则**：
- 每个任务 3-5 个相关函数
- 单个文件不超过 200 行
- 任务间无依赖
- 使用英文编写 Spec（Builder 对英文理解更精确）

**展示 Spec 给用户确认后进入第三步。**

---

### 第三步：执行

#### 3a. 中断恢复检测（v2.2 新增，每次进入第三步前必做）

**目的**：如果上次会话中途中断（compact、崩溃、关窗口），自动从断点续接。

**状态文件**：`{项目目录}/.codex-progress.json`

```json
{
  "session_id": "2026-02-22-001",
  "tasks": [
    {"id": "001", "spec": "specs/TASK-001.md", "status": "done", "token": 125000},
    {"id": "002", "spec": "specs/TASK-002.md", "status": "active", "token": 0},
    {"id": "003", "spec": "specs/TASK-003.md", "status": "pending", "token": 0}
  ],
  "updated_at": "2026-02-22 10:30:00"
}
```

**检测逻辑**（PM 在第三步开始前执行）：

```bash
# 检查是否有未完成的进度文件
if [ -f ".codex-progress.json" ]; then
  echo "检测到中断的任务进度："
  cat .codex-progress.json
fi
```

**恢复规则**：
1. 状态为 `done` 的任务：跳过，不重复执行
2. 状态为 `active` 的任务：重置为 `pending`，重新执行（active 表示执行中被中断，结果不可信）
3. 状态为 `pending` 的任务：正常执行
4. 状态为 `failed` 的任务：分析原因后决定重试或跳过

**更新时机**：
- 每个任务**启动前**：设为 `active`，写入文件
- 每个任务**完成后**：设为 `done`，记录 token，写入文件
- 每个任务**失败后**：设为 `failed`，记录错误，写入文件
- 全部完成后：删除进度文件

**PM 更新进度的命令**：
```bash
# 用 Python 更新进度文件（比 jq 可靠）
python3 -c "
import json
with open('.codex-progress.json', 'r') as f: data = json.load(f)
for t in data['tasks']:
    if t['id'] == '${TASK_ID}': t['status'] = '${NEW_STATUS}'
data['updated_at'] = '$(date '+%Y-%m-%d %H:%M:%S')'
with open('.codex-progress.json', 'w') as f: json.dump(data, f, indent=2)
"
```

#### 3b. 依赖图自动分析（v2.2 新增，替代手动 [P] 标记）

**目的**：PM 不再手动标记 `[P]`，而是自动分析任务间依赖关系，生成并行分组。

**分析规则**（PM 在生成所有 Spec 后执行）：

1. **提取每个任务的文件目标**：从 Spec 中提取 `Files to Create/Modify` 列表
2. **构建依赖图**：如果任务 B 要修改的文件是任务 A 要创建的文件，则 B 依赖 A
3. **拓扑排序**：按依赖关系分层，同层任务可并行
4. **输出分组**：

```
依赖分析结果：
  Layer 1 (并行): TASK-001, TASK-003, TASK-005  ← 无依赖，同时启动
  Layer 2 (并行): TASK-002, TASK-004            ← 依赖 Layer 1 的输出
  Layer 3 (串行): TASK-006                      ← 集成任务，依赖全部
```

**PM 执行依赖分析的命令**：
```bash
# 从所有 Spec 中提取文件目标，分析依赖
for spec in specs/TASK-*.md; do
  TASK_ID=$(basename "$spec" .md | sed 's/TASK-//')
  # 提取 Files to Create/Modify 章节中的文件路径
  FILES=$(grep -A 20 "Files to Create\|Files to Modify" "$spec" | grep '^\s*-\s*`' | sed 's/.*`\(.*\)`.*/\1/')
  echo "TASK-$TASK_ID: $FILES"
done
```

**与分层引爆模型的关系**：
- 旧方式：PM 手动标记 `[P]` → 分组 → 分层引爆
- 新方式：PM 自动分析依赖 → 自动分层 → 分层引爆
- 分层引爆模型（A→B→C）不变，只是分组不再需要人工判断

---

#### 3c. 执行任务

1. 创建工作目录（如有必要）
2. 将 Spec MD 传递给 Builder：
```bash
builder exec --skip-git-repo-check "$(cat specs/TASK-{id}-{name}.md)" > logs/task-{id}.log 2>&1 &
```
3. 根据任务数量选择执行模式
4. **启动主动监控**：自动检测任务完成，无需等待明确信号
5. 任务完成后自动进入第四步验收

**分层引爆模型（A→B→C）**：

```
A1（主引线）：暖场 + 任务分组
  ↓ 串联触发（快速，<5秒）
B1 ── B2 ── B3（二级引线，各组并行启动）
↓      ↓      ↓
C1    C2    C3（组内任务，并行执行）
```

- **A1**：第零步暖场完成后，将所有任务按依赖关系分组
- **B层**：每组作为独立批次，各组同时启动（`execute_batch` 并行调用）
- **C层**：每组内任务全部并行执行（`builder exec ... &`）

**分组原则**：
- 同组任务：操作不同文件、无依赖 → 可完全并行（C层）
- 跨组依赖：B1 组完成后才启动 B2 组 → 串联
- 组内上限：每组最多 15 个任务

**并发规则（15 并发标准）**：
- **标准配置**：每批 15 个任务并行执行
- **核心原则**：一次串流不超过 15 个
- **执行模式**：真·并行（所有任务同时启动）
- **性能保证**：~30 秒/15 任务，100% 成功率，无 API 限流

**并行执行前提条件**：
1. 会话信任已建立（第零步暖场完成）
2. 任务间无依赖（每个任务可独立完成）
3. 资源不冲突（不同任务操作不同文件）
4. 并发数量控制（最多 15 个任务同时执行）

**执行脚本模板**：
```bash
# 15并发真·并行模式
BATCH_SIZE=15
TOTAL_TASKS=<任务总数>
BATCH_COUNT=$(( (TOTAL_TASKS + BATCH_SIZE - 1) / BATCH_SIZE ))

mkdir -p logs

execute_batch() {
    local BATCH_ID=$1
    local START_TASK=$2
    local END_TASK=$3

    echo "[批次${BATCH_ID}] 启动任务 ${START_TASK}-${END_TASK}"

    for i in $(seq $START_TASK $END_TASK); do
        TASK_NUM=$(printf '%03d' $i)
        builder exec --skip-git-repo-check "$(cat specs/TASK-${TASK_NUM}.md)" \
            > "logs/task-${TASK_NUM}.log" 2>&1 &
    done

    wait
    echo "[批次${BATCH_ID}] 完成"
}

TASK_ID=1
for batch in $(seq 1 $BATCH_COUNT); do
    START_TASK=$TASK_ID
    END_TASK=$((TASK_ID + BATCH_SIZE - 1))
    if [ $END_TASK -gt $TOTAL_TASKS ]; then
        END_TASK=$TOTAL_TASKS
    fi
    execute_batch $batch $START_TASK $END_TASK &
    TASK_ID=$((END_TASK + 1))
done

wait
```

**扩展策略**：
- 任务数 ≤ 15：单批次执行（最快）
- 任务数 16-50：分批执行，每批 15 个（推荐）
- 任务数 > 50：分批执行，每批 15 个（稳定）

**主动监控机制**：

```bash
monitor_codex_execution() {
    local LOG_FILE=$1
    local TARGET_FILE=$2
    local STABLE_COUNT=0
    local LAST_SIZE=0

    while true; do
        if [ -f "$LOG_FILE" ]; then
            CURRENT_SIZE=$(stat -f%z "$LOG_FILE" 2>/dev/null || stat -c%s "$LOG_FILE" 2>/dev/null)

            if [ "$CURRENT_SIZE" -eq "$LAST_SIZE" ]; then
                STABLE_COUNT=$((STABLE_COUNT + 1))
                if [ $STABLE_COUNT -ge 4 ]; then
                    echo "✅ 日志稳定，任务可能已完成"
                    if [ -f "$TARGET_FILE" ]; then
                        FILE_TIME=$(stat -f%m "$TARGET_FILE" 2>/dev/null || stat -c%Y "$TARGET_FILE" 2>/dev/null)
                        CURRENT_TIME=$(date +%s)
                        TIME_DIFF=$((CURRENT_TIME - FILE_TIME))
                        if [ $TIME_DIFF -lt 300 ]; then
                            echo "✅ 目标文件已更新，触发验证"
                            return 0
                        fi
                    fi