Skill: mwangxiang/ai-auto-dev (version 1.0.0)

--- 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` 需配置： ```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. **文件完整性**（必须实际验证，不能只看日志） - 检查所有预期文件是否生成：`ls -lh [目标路径]` - 检查空文件：`find [目标路径] -name "*.ts" -size 0` - 统计代码行数：`wc -l [目标路径]/*.ts` - ⚠️ **必须用 ls 实际确认文件存在，不能只看 Builder 输出** 2. **代码质量**（抽查） - 读取 1-2 个关键文件，检查：类型注解、文档字符串、错误处理 3. **Verification Checklist 验证** - 根据 Spec 中的 Verification Checklist，逐项验证 - 重点检查 Functional Requirements 和 Edge Cases #### 第三层：反思机制（如果 Self-Check 失败） 1. **分析失败原因** - 读取 self-check-report.md 中的 Issues Found - 分类：语法错误、类型错误、测试失败、构建失败、权限问题 2. **生成修复建议** - Spec 不清晰 → 修改 Spec，重新执行 - Builder 理解错误 → 调整 Spec 描述，重新执行 - 环境问题（权限/依赖）→ 修复环境，重新执行 3. **决策** - 自动修复（简单问题） - 报告给 Boss（需要需求澄清） - 重新执行（Spec 已修改） #### PM-Builder 信任原则 **继续信任 Builder 的标志**： - Builder 还在尝试不同方案（输出中可以看到不同的思考和尝试） - Token 使用量稳定增长（说明 Builder 在工作，不是卡死） - 错误类型在变化（说明 Builder 在调整策略） - 执行时间在合理范围内（简单任务 <5 分钟，复杂任务 <30 分钟） **需要介入的标志**： - Builder 陷入循环报错（相同错误重复出现 3 次以上） - Builder 完全卡死（超过 5 分钟无任何输出） - Token 使用量异常增长（单任务超过 500 万 tokens） - 执行时间明显异常（简单任务超过 30 分钟） **介入方式**： 1. 先检查 Builder 的最新输出，确认是否真的需要介入 2. 如果确认需要介入，停止任务并分析原因 3. 修改 Spec 或指令，重新执行 4. 记录踩坑经验，更新记忆库 #### 难度分级标准（A1） | 级别 | 预期时间 | 预期 Token | 介入次数 | 典型场景 | |------|---------|-----------|---------|---------| | 简单 | ≤5 分钟 | ≤500K | 0 | 单文件修改、配置调整、小功能 | | 复杂 | ≤30 分钟 | ≤5M | 0-1 | 多文件功能、重构、新模块 | **超阈值判定**：实际值 > 2× 预期值 → 标记异常，写入实验日志，分析原因。 #### 死循环 vs 正常思考（A2） | 状态 | 判断依据 | |------|---------| | 正常思考 | 输出内容在变化 OR 错误类型在变化 OR Token 稳定增长 | | 死循环 | 相同错误 ≥3 次 AND Token 持续增长但无新进展 | | 完全卡死 | 超过 5 分钟无任何输出 | **数学条件**：`相同错误出现次数 ≥ 3` → 立即介入，不等待。 #### 生成最终验收报告（内联显示，不要只给文件链接） ``` ## 验收报告 ### 执行统计 **时间消耗：** - 实际执行时间：X 分钟 - 总墙上时钟时间：Y 分钟 - 串行预估时间：Z 小时（如适用） - 效率提升：N%（如适用） **Token 消耗：** - Spec 生成（PM）：XXK tokens - Builder 执行（Builder）：XXM tokens - PM 验证：XXK tokens - **总计：X.XM tokens** **成本效益：** - 人工开发预估：X-Y 天 - 自动化完成：Z 分钟 ### Builder Self-Check 结果 - Static Analysis: ✅ PASS / ❌ FAIL (X errors) - Test Results: ✅ PASS / ❌ FAIL (X/Y passed) - Build Results: ✅ PASS / ❌ FAIL - Overall: ✅ PASS / ❌ FAIL ### PM 验证结果 - 文件完整性: ✅ / ❌ - 代码质量: ✅ / ❌ - Verification Checklist: X/Y 项通过 ### 文件清单 | 文件 | 大小 | 行数 | 状态 | |------|------|------|------| ### 判定：✅ 通过 / ❌ 不通过 - 不通过原因（如有） - 修复建议（如有） ``` --- ### 第五步：文档归档暂存 1. 在工作目录下创建 `_archive_staging.md` 暂存文件 2. **不写入**正式文档（思维蒸馏、学习研究日志、记忆库等） 3. 暂存文件包含本次工作中所有值得记录的内容 **暂存文件格式**： ```markdown # 文档归档暂存 > 创建日期：YYYY-MM-DD > 项目：[项目名称] > 任务：[任务描述] > 状态：待用户审阅 --- ## 蒸馏内容 [本次工作中值得提炼的方法论、认知、经验] --- ## 日志内容 [本次工作的完整记录，按学习研究日志的会话格式编写] --- ## 踩坑记录 [遇到的问题和解决方案] --- ## 记忆库更新建议 [如有新的操作习惯或规则需要记录] ``` --- ### 第五步半：文档更新和 GitHub 同步（自动执行） **在第六步交付前，自动完成以下工作**： 1. **更新项目文档** - 更新 README.md（功能介绍、版本号） - 更新 CHANGELOG.md（新增版本记录） - 更新 API 配置指南或其他相关文档 2. **调用 dev-log skill** - 传入版本号参数（如 `v0.9.4`） - dev-log 自动完成：分析代码修改、生成 commit message、提交代码、打版本标签、推送到 GitHub 3. **验证同步结果** - 确认 commit 成功 - 确认标签已创建 - 确认推送到远程仓库 **注意**：此步骤在第五步之后、第六步之前自动执行，无需用户确认。如果 GitHub 同步失败，记录错误但继续交付流程。 --- ### 第六步：向用户交付 同时交付三样东西（**全部内联显示在对话中，不要只给文件链接**）： 1. **验收报告**（第四步生成的） - 通过/不通过判定 - 文件清单和测试结果 - 问题清单（如有） 2. **归档暂存文件**（第五步生成的） - 展示内容供用户审阅 - 说明每部分建议写入哪个正式文档 3. **GitHub 同步结果**（第五步半完成的） - Commit ID 和链接 - 版本标签 - GitHub Release 链接 4. 用户审阅后决定： - 确认收纳 → 调用 `/distill` 或手动写入正式文档 - 需要修改 → 修改后再收纳 - 不收纳 → 暂存文件保留在工作目录备查 --- ## Token 消耗统计方法 ### 从 Builder 日志提取 Token 数据 ```bash # 提取单个任务的 Token 消耗 extract_tokens() { local LOG_FILE=$1 grep "Usage:" "$LOG_FILE" | tail -1 | \ sed -E 's/.*input=([0-9]+) output=([0-9]+) total=([0-9]+).*/\1 \2 \3/' } # 统计所有任务的 Token 消耗 total_input=0; total_output=0; total_tokens=0 for log in logs/task-*.log; do read input output total <<< $(extract_tokens "$log") total_input=$((total_input + input)) total_output=$((total_output + output)) total_tokens=$((total_tokens + total)) done echo "Total Input: ${total_input}" echo "Total Output: ${total_output}" echo "Total Tokens: ${total_tokens}" ``` ### Token 消耗异常分析 | 现象 | 原因 | 修复 | |------|------|------| | 单任务 >500K tokens | 权限不足，陷入探测循环 | 改为 danger-full-access | | 单任务 >500K tokens | Spec 不清晰，反复猜测 | 补充 Assumptions，明确需求 | | PM Token 过高 | 读取了不必要的文件 | 遵守"PM 不读代码"原则 | | 总 Token 超预期 | 重复执行失败任务 | 先修复 Spec 再重新执行 | --- ## 核心规则 1. **每次必须暖场**：第零步不可跳过，每次调用都要执行暖场 2. **需求不清不动手**：第一步必须完成，复述确认后才进入第二步 3. **必须使用新 Spec 模板**：第二步必须使用 `specs/SPEC-TEMPLATE.md`，包含 5 个核心改进 4. **Spec 必须自包含**：Builder 无需额外信息即可完成全部工作 5. **三重纠错强制执行**：Builder 必须运行 Self-Check Requirements，生成 self-check-report.md 6. **全程自动化**：从第一步确认到第六步交付，PM 自动完成所有步骤，不在中途停下等待用户 7. **正式文档只读**：整个流程中不直接写入蒸馏、日志、记忆库 8. **归档只能暂存**：❗❗❗ 只能创建 `_archive_staging.md` 暂存文件，绝对不能直接写入正式文档 9. **验收必须实际验证**：必须用 `ls` 实际确认文件存在，不能只看 Builder 输出就报告成功 10. **验收不通过时**：分析原因，修改 Spec 重新执行，不要手动修补代码 11. **报告内联显示**：验收报告必须内联显示在对话中，不要只给文件链接 12. **文档和 GitHub 同步自动化**：第五步半自动更新文档并同步到 GitHub，无需用户确认 13. **PM 只读输出文件**：验收时 PM 只读 `self-check-report.md`、`ls` 输出、日志文件。不读源码（.ts/.js/.py）。"不读代码"= 不读源码，不等于不读报告。 --- ## 常见错误和修复方案 ### 错误 1：sandbox 权限不足 **现象**：Builder 无法运行 npx/node/tsc，Token 消耗异常高（60% 浪费在权限探测） **原因**：config.toml 中 `sandbox_mode = "workspace-write"` **修复**：改为 `sandbox_mode = "danger-full-access"` **验证**：`builder exec "echo hello"` 输出显示 `sandbox: danger-full-access` ### 错误 2：PM 未按完整流程执行 **现象**：PM 在中途停下等待用户指示，导致大量时间浪费 **原因**：误解了"全自动化"含义，认为需要在每个阶段询问用户确认 **修复**：执行完所有 6 步才交付，只有遇到无法解决的错误时才停下来 **数据**：错误做法导致 455 分钟空闲 vs 85 分钟工作，浪费比例 84% ### 错误 3：PM 混淆任务输出文件 **现象**：PM 报告任务成功，但文件根本不存在 **原因**：读取了错误的输出文件，没有实际验证文件是否存在 **修复**：必须用 `ls` 实际确认文件存在，必须运行编译检查才能声称编译通过 ### 错误 4：报告只给文件链接 **现象**：用户反馈"不好找"，阅读体验差 **原因**：PM 过度关注 Token 成本优化 **修复**：默认内联显示所有报告 **决策标准**：成本差异 <1 元/100 轮 → 优先用户体验，内联显示 ### 错误 5：过早介入 Builder **现象**：PM 在 Builder 还在工作时停止任务，导致成本翻倍 **原因**：PM 用自己的时间预估判断 Builder 是否卡死 **修复**：按照"PM-Builder 信任原则"判断，只有满足"需要介入的标志"才介入 --- ## 与其他 Skill 的配合 - **distill**：用户确认暂存内容后，可调用 `/distill` 写入正式蒸馏文档 - **sop-generator**：如果本次任务是新流程，可调用 `/sop-generator` 生成 SOP - **dev-log**：如果涉及版本管理，可调用 `/dev-log` 记录版本 --- ## Memory/RAG 实际落地（C2） > **现实约束**：当前没有 Gemini/向量数据库，Memory 角色由 PM 用文件检索替代。 ### 当前可用的"Memory"操作 | 需求 | 实际操作 | 命令 | |------|---------|------| | 查找相关文件 | Glob 模式匹配 | `Glob("src/**/*.ts")` | | 搜索历史决策 | Grep 关键词 | `Grep("pattern", path)` | | 读取基线数据 | Read 文件 | `Read("windtunnel/baselines/...")` | | 查找踩坑记录 | Read 暂存文件 | `Read("_archive_staging.md")` | ### PM 查询 Memory 的正确姿势 ``` ❌ 错误：直接读 src/ 下的源码文件来"理解"项目 ✅ 正确：读 self-check-report.md、CLAUDE.md、_archive_staging.md 获取上下文 ✅ 正确：用 Glob/Grep 定位文件路径，把路径写进 Spec，让 Builder 去读 ``` ### Spec 中的 Memory 引用格式 ```markdown ## 上下文（PM 查询 Memory 后填入） - 相关文件：`src/taskManager.ts`（通过 Glob 定位） - 历史决策：使用 danger-full-access（见 _archive_staging.md 权限进化历程） - 已知问题：activationEvents 缺失（见 CLAUDE.md Section 6） ``` --- ## 参考文档 - **Spec 模板**：`specs/SPEC-TEMPLATE.md` - **填写指南**：`specs/SPEC-TEMPLATE-GUIDE.md` - **Constitution**：`CLAUDE.md`（Section 3: Spec MD Format） - **验证报告**：`automated-comparison-test/FINAL-COMPARISON-REPORT.md`（61.4% 效率提升数据） - 记忆库中的「Builder CLI 使用规则」：config.toml 配置、指令-权限匹配原则 - SOP 暂存中的「权限进化历程」：7 阶段实验数据和踩坑经验 - 思维蒸馏中的「Claude Code + Builder 协作模式」：权限-效率-成本三角 --- ## 记忆保护协议（v2.1 新增） > **核心原则：重要信息必须立即落盘，不能只存在上下文中。** > 上下文压缩会导致风洞数据失真——压缩后的"记忆"不等于真实发生的事情。 ### 规则 1：会话开始时恢复上下文 每次新会话开始，PM 必须读取以下文件（按顺序）： ``` 1. ~/.claude/windtunnel/baselines/ai-auto-dev-baseline.md ← 基线数据 2. ~/.claude/windtunnel/experiments/{今日日期}-summary.md ← 今日实验记录（如存在） 3. {项目目录}/CLAUDE.md ← 项目约束 ``` **目的**：从文件恢复上下文，而不是依赖对话历史（对话历史可能已被压缩）。 --- ### 规则 2：实验数据立即落盘 以下数据必须在产生时**立即写入文件**，不能只存在对话中： | 数据类型 | 写入位置 | 触发时机 | |---------|---------|---------| | 任务开始记录 | `windtunnel/experiments/{日期}-log.md` | 第三步执行前 | | 验收结果 | `windtunnel/experiments/{日期}-log.md` | 第四步完成后 | | 基线对比 | `windtunnel/baselines/ai-auto-dev-baseline.md` | 每次任务完成后 | | 踩坑记录 | `_archive_staging.md` | 发现问题时立即记录 | **实验日志格式**（追加写入，不覆盖）： ```markdown ## {时间戳} | 任务：{任务名} | 难度：简单/复杂 **输入**：{需求一句话描述} **执行时间**：X 分钟 **Token 消耗**：X.XM **介入次数**：X **结果**：✅ PASS / ❌ FAIL **偏差**：与基线相比 +/-X%（如有） **备注**：{关键发现，一句话} ``` 写入命令（PM 在第四步后执行）： ```bash cat >> ~/.claude/windtunnel/experiments/$(date '+%Y-%m-%d')-log.md << 'EOF' {上述格式内容} EOF ``` --- ### 规则 3：上下文压缩防护 **禁止**：将以下内容只放在对话中： - 实验数据和测量结果 - 与基线的对比结论 - 决策记录（为什么选 A 不选 B） - 踩坑经验 **要求**：每次任务完成后，PM 必须确认以上内容已写入文件，才能进入第六步交付。 --- ### 规则 4：基线自动对比 每次任务完成后，PM 自动计算与基线的偏差并写入日志： ``` 偏差计算： - 时间偏差 = (实际时间 - 基线时间) / 基线时间 × 100% - Token 偏差 = (实际Token - 基线Token) / 基线Token × 100% - 偏差 > +50%：标记为异常，分析原因 - 偏差 < -20%：标记为改进，记录原因 ``` --- ## 版本历史 | 版本 | 日期 | 变更 | |------|------|------| | v1.0 | 2026-02-15 | 初始版本，建立基础流程 | | v2.0 | 2026-02-19 | 新增 Spec-Kit 改进（5 个核心机制）、三重纠错、PM-Builder 信任原则、Token 统计、常见错误修复方案 | | v2.1 | 2026-02-21 | 新增记忆保护协议：立即落盘原则、实验日志格式、上下文压缩防护、基线自动对比 | | v2.2 | 2026-02-22 | 新增中断恢复机制（`.codex-progress.json` 状态文件，active→pending 重置）、依赖图自动分析（替代手动 [P] 标记，自动拓扑排序分层） |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)