ai-auto-dev

name ai-auto-dev description 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 需配置： ask_for_approval = "never" sandbox_mode = "danger-full-access" ⚠️ 重要 ：必须使用完整访问权限模式，受限模式会阻止 npx/node/tsc 等命令，导致三重纠错无法执行，Token 浪费 60%。 工作流程 第零步：会话暖场（每次必做） 目的 ：建立 Claude Code 会话信任，避免后续 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 秒），建立信任后一整天无需确认 第一步：需求对齐 用户提出需求 Claude Code 与用户反复讨论，直到完全理解 Claude Code 复述需求 给用户确认，必须包含： 要做什么 ：功能描述 技术栈和约束 ：语言、框架、依赖 目录结构 ：文件放在哪里 交付物清单 ：具体的文件名列表 测试要求 ：需要什么样的测试 用户确认后才进入下一步 禁止跳过此步 ：需求不清就开始执行 = 浪费 Token 第二步：生成 Spec MD 使用新模板 （v2.0 核心改进）： 复制 specs/SPEC-TEMPLATE.md 为 specs/TASK-{id}-{name}.md 参考 specs/SPEC-TEMPLATE-GUIDE.md 填写 Spec 必须包含以下 5 个核心改进： 改进 1：NEEDS CLARIFICATION 机制 最多 3 个问题（优先级：范围 > 安全/隐私 > 用户体验 > 技术细节） 其他不确定的地方用假设替代，记录在 ## Assumptions 章节 格式： [假设: 具体内容] 价值 ：减少执行时的犹豫，消除"猜测-验证"循环 改进 2：User Stories 结构 ### 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 执行后强制运行： ## Self-Check Requirements (MANDATORY) ### Check 1: Static Analysis ```bash npx tsc --noEmit --strict --skipLibCheck Check 2: Test Execution npm test # 或 jest / vitest --run Check 3: Build Verification 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（如果失败） 如果任何检查失败： 分析失败原因 生成修复建议 报告给 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 { "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 在第三步开始前执行）： # 检查是否有未完成的进度文件 if [ -f ".codex-progress.json" ]; then echo "检测到中断的任务进度：" cat .codex-progress.json fi 恢复规则 ： 状态为 done 的任务：跳过，不重复执行 状态为 active 的任务：重置为 pending ，重新执行（active 表示执行中被中断，结果不可信） 状态为 pending 的任务：正常执行 状态为 failed 的任务：分析原因后决定重试或跳过 更新时机 ： 每个任务 启动前 ：设为 active ，写入文件 每个任务 完成后 ：设为 done ，记录 token，写入文件 每个任务 失败后 ：设为 failed ，记录错误，写入文件 全部完成后：删除进度文件 PM 更新进度的命令 ： # 用 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 后执行）： 提取每个任务的文件目标 ：从 Spec 中提取 Files to Create/Modify 列表 构建依赖图 ：如果任务 B 要修改的文件是任务 A 要创建的文件，则 B 依赖 A 拓扑排序 ：按依赖关系分层，同层任务可并行 输出分组 ： 依赖分析结果： Layer 1 (并行): TASK-001, TASK-003, TASK-005 ← 无依赖，同时启动 Layer 2 (并行): TASK-002, TASK-004 ← 依赖 Layer 1 的输出 Layer 3 (串行): TASK-006 ← 集成任务，依赖全部 PM 执行依赖分析的命令 ： # 从所有 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. 执行任务 创建工作目录（如有必要） 将 Spec MD 传递给 Builder： builder exec --skip-git-repo-check " $(cat specs/TASK-{id}-{name}.md) " > logs/task-{ id }. log 2>&1 & 根据任务数量选择执行模式 启动主动监控 ：自动检测任务完成，无需等待明确信号 任务完成后自动进入第四步验收 分层引爆模型（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 限流 并行执行前提条件 ： 会话信任已建立（第零步暖场完成） 任务间无依赖（每个任务可独立完成） 资源不冲突（不同任务操作不同文件） 并发数量控制（最多 15 个任务同时执行） 执行脚本模板 ： # 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 个（稳定） 主动监控机制 ： 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 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 通过） 文件完整性 （必须实际验证，不能只看日志）