AI Auto Dev

👤 mwangxiang 📦 v1.0.0 ⭐ 4.4 ⬇️ 1.1K 下載

💻 開發程式設計免費

📖 技能介紹

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

如果任何檢查失敗： 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 後執行）：

提取每個任務的檔案目標：從 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 限流

並行執行前提條件： 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 通過）

檔案完整性（必須實際驗證，不能只看日誌）
檢查所有預期檔案是否生成：ls -lh [目標路徑]
檢查空檔案：find [目標路徑] -name "*.ts" -size 0
統計程式碼行數：wc -l [目標路徑]/*.ts
⚠️ 必須用 ls 實際確認檔案存在，不能只看 Builder 輸出
程式碼質量（抽查）
讀取 1-2 個關鍵檔案，檢查：型別註解、文件字串、錯誤處理
Verification Checklist 驗證
根據 Spec 中的 Verification Checklist，逐項驗證
重點檢查 Functional Requirements 和 Edge Cases

第三層：反思機制（如果 Self-Check 失敗）

分析失敗原因
讀取 self-check-report.md 中的 Issues Found
分類：語法錯誤、型別錯誤、測試失敗、構建失敗、許可權問題
生成修復建議
Spec 不清晰 → 修改 Spec，重新執行
Builder 理解錯誤 → 調整 Spec 描述，重新執行
環境問題（許可權/依賴）→ 修復環境，重新執行
決策
自動修復（簡單問題）
報告給 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 項通過

### 檔案清單
| 檔案 | 大小 | 行數 | 狀態 |
|------|------|------|------|

### 判定：✅ 通過 / ❌ 不通過
- 不通過原因（如有）
- 修復建議（如有）

第五步：文件歸檔暫存

在工作目錄下建立 _archive_staging.md 暫存檔案
不寫入正式文件（思維蒸餾、學習研究日誌、記憶庫等）
暫存檔案包含本次工作中所有值得記錄的內容

暫存檔案格式：

# 文件歸檔暫存

> 建立日期：YYYY-MM-DD
> 專案：[專案名稱]
> 任務：[任務描述]
> 狀態：待使用者審閱

---

## 蒸餾內容
[本次工作中值得提煉的方法論、認知、經驗]

---

## 日誌內容
[本次工作的完整記錄，按學習研究日誌的會話格式編寫]

---

## 踩坑記錄
[遇到的問題和解決方案]

---

## 記憶庫更新建議
[如有新的操作習慣或規則需要記錄]

第五步半：文件更新和 GitHub 同步（自動執行）

在第六步交付前，自動完成以下工作：

更新專案文件
更新 README.md（功能介紹、版本號）
更新 CHANGELOG.md（新增版本記錄）
更新 API 配置指南或其他相關文件
本技能來自小蔥技能站7w4.net。
呼叫 dev-log skill
傳入版本號引數（如 v0.9.4）
dev-log 自動完成：分析程式碼修改、生成 commit message、提交程式碼、打版本標籤、推送到 GitHub
驗證同步結果
確認 commit 成功
確認標籤已建立
確認推送到遠端倉庫

注意：此步驟在第五步之後、第六步之前自動執行，無需使用者確認。如果 GitHub 同步失敗，記錄錯誤但繼續交付流程。

第六步：向用戶交付

同時交付三樣東西（全部內聯顯示在對話中，不要只給檔案連結）：

驗收報告（第四步生成的）
通過/不通過判定
檔案清單和測試結果
問題清單（如有）
歸檔暫存檔案（第五步生成的）
展示內容供使用者審閱
說明每部分建議寫入哪個正式文件
GitHub 同步結果（第五步半完成的）
Commit ID 和連結
版本標籤
GitHub Release 連結
使用者審閱後決定：
確認收納 → 呼叫 /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 再重新執行

核心規則

每次必須暖場：第零步不可跳過，每次呼叫都要執行暖場
需求不清不動手：第一步必須完成，複述確認後才進入第二步
必須使用新 Spec 模板：第二步必須使用 specs/SPEC-TEMPLATE.md，包含 5 個核心改進
Spec 必須自包含：Builder 無需額外資訊即可完成全部工作
三重糾錯強制執行：Builder 必須執行 Self-Check Requirements，生成 self-check-report.md
全程自動化：從第一步確認到第六步交付，PM 自動完成所有步驟，不在中途停下等待使用者
正式文件只讀：整個流程中不直接寫入蒸餾、日誌、記憶庫
歸檔只能暫存：❗❗❗ 只能建立 _archive_staging.md 暫存檔案，絕對不能直接寫入正式文件
驗收必須實際驗證：必須用 ls 實際確認檔案存在，不能只看 Builder 輸出就報告成功
驗收不通過時：分析原因，修改 Spec 重新執行，不要手動修補程式碼
報告內聯顯示：驗收報告必須內聯顯示在對話中，不要只給檔案連結
文件和 GitHub 同步自動化：第五步半自動更新文件並同步到 GitHub，無需使用者確認
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] 標記，自動拓撲排序分層）

🤖 AI 評測

質量中等偏上。優點是流程完整、驗證機制嚴格，大型任務也能穩定跑完。缺點是太複雜了，光是看完文件就要很久，每次用還要先暖場、配環境，步驟繁瑣。而且這工具主要針對特定 AI 工具最佳化，換個環境就不靈了。適合有耐心的專業使用者，普通使用者可能會覺得門檻太高。

📊 多維度評分

適應性4.5

規範性4.2

有效性4.4

可靠性4.6

可信度4.3

📁 包含檔案 (3 個)

📄 SKILL.md 27.8 KB

📄 _meta.json 130 B

📄 skill-card.md 2.5 KB