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 秒），建立信任后一整天无需确认

---

第一步：需求对齐

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 结构

### 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（如果失败）

如果任何检查失败：

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

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

恢复规则：

1. 状态为 done 的任务：跳过，不重复执行
2. 状态为 active 的任务：重置为 pending，重新执行（active 表示执行中被中断，结果不可信）
3. 状态为 pending 的任务：正常执行
4. 状态为 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 后执行）：

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 执行依赖分析的命令：

# 从所有 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：

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 个任务同时执行）

执行脚本模板：

# 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 通过）

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. 暂存文件包含本次工作中所有值得记录的内容

暂存文件格式：

# 文档归档暂存

> 创建日期：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 数据

# 提取单个任务的 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 引用格式

## 上下文（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	发现问题时立即记录

实验日志格式（追加写入，不覆盖）：

## {时间戳} | 任务：{任务名} | 难度：简单/复杂

**输入**：{需求一句话描述}
**执行时间**：X 分钟
**Token 消耗**：X.XM
**介入次数**：X
**结果**：✅ PASS / ❌ FAIL
**偏差**：与基线相比 +/-X%（如有）
**备注**：{关键发现，一句话}

写入命令（PM 在第四步后执行）：

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] 标记，自动拓扑排序分层）