ai-auto-dev

# 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 fi else STABLE_COUNT=0 LAST_SIZE=$CURRENT_SIZE fi fi sleep 30 done } ``` **监控策略**： - 检查频率：每 2 分钟（经验证为最优频率） - 监控成本：约占总 Token 的 0.9%（极低，不是优化重点） - 监控目的：发现"卡死"或"完全无法执行"，不是催促进度 --- ### 第四步：自动验收（三重纠错） Builder 完成后，Claude Code **自动**执行以下检查（无需用户确认）： #### 第一层：读取 Builder 的 Self-Check Report ```bash cat {output-dir}/self-check-report.md ``` 报告包含： - Static Analysis: PASS/FAIL + 错误数 - Test Results: PASS/FAIL + 通过/失败数 - Build Results: PASS/FAIL - Files Created/Modified: 列表 - Issues Found: 列表 - Overall Assessment: PASS/FAIL #### 第二层：PM 验证（如果 Self-Check 通过） 1. **文件完整性**（必须实际验证，不能只看日志）