AI Agent 工作流程架構：從 Issue 到 PR 的全自動開發

為什麼線性腳本行不通

大多數人第一次設計 AI Agent 工作流程，都會做成這樣：

async function buildFeature(issue) {
  await readIssue(issue);
  await createBranch(issue);
  await writeCode(issue);
  await runTests();
  await createPR();
}

這在 demo 裡運作完美。在生產環境裡，它在第 3 步崩潰了，從頭重跑，再次崩潰，無限循環。問題在哪？

• 沒有狀態持久化：崩潰後不知道做到哪裡
• 沒有錯誤分類：所有錯誤都用同樣方式處理
• 沒有隔離：多個 Issue 並行時互相干擾
• 沒有恢復點：一個步驟失敗就要重跑全部

狀態機設計

把工作流程設計成明確的狀態機。每個 Issue 都有一個狀態，狀態轉換是原子操作（要麼完成，要麼不做）：

type IssueState =
  | 'PENDING'          // 等待處理
  | 'ANALYZING'        // 分析 Issue 內容
  | 'WORKTREE_CREATED' // Git worktree 已建立
  | 'CODING'           // AI 正在寫程式碼
  | 'TESTING'          // 執行測試
  | 'REVIEWING'        // 六重審查中
  | 'PR_CREATED'       // PR 已建立，等待 merge
  | 'COMPLETED'        // 完成
  | 'FAILED'           // 失敗，需要人工介入
  | 'ESCALATED';       // 升級給人工處理

interface IssueWorkflow {
  issueId: string;
  state: IssueState;
  worktreePath: string;
  checkpoints: Checkpoint[];
  retryCount: number;
  lastError?: string;
  startedAt: Date;
  updatedAt: Date;
}

關鍵原則：狀態轉換前先寫入，狀態轉換後再執行。這樣即使在執行中崩潰，重啟後也知道上次做到哪裡。

Worktree 隔離策略

git worktree 是這套架構最關鍵的技術選擇。它讓多個 Issue 可以並行進行，同時完全隔離：

# 每個 Issue 建立獨立的 worktree
git worktree add \
  /tmp/worktrees/issue-${issueId} \
  -b issue-${issueId}

# Agent 在這個路徑下工作
# 不影響主 repo 或其他 Issue 的 worktree

# 完成後清理
git worktree remove /tmp/worktrees/issue-${issueId}
git branch -d issue-${issueId}

隔離帶來的好處：

• Issue #42 正在重構 auth module，Issue #43 同時在加新功能，不會互相干擾
• 一個 Issue 失敗不會污染其他 Issue 的工作環境
• 清理失敗的工作只需要刪除 worktree 目錄，不需要手動 git reset

我們的生產環境同時跑最多 6 個並行 Issue（受限於 Claude API rate limit，不是技術限制）。

Checkpoint 持久化

Checkpoint 是讓 Agent 能從任何點恢復的關鍵機制。每 15 分鐘（或每完成一個重要步驟）自動儲存：

interface Checkpoint {
  id: string;
  issueId: string;
  state: IssueState;
  timestamp: Date;
  context: {
    filesModified: string[];
    testsRun: number;
    testsPassed: number;
    reviewResults: ReviewResult[];
    nextSteps: string[];
  };
}

// 儲存到 Redis（快速讀取）+ PostgreSQL（持久化）
async function saveCheckpoint(workflow: IssueWorkflow) {
  const checkpoint = buildCheckpoint(workflow);
  await redis.setex(
    `checkpoint:${workflow.issueId}`,
    3600, // 1 小時 TTL
    JSON.stringify(checkpoint)
  );
  await db.checkpoint.create({ data: checkpoint });
}

系統崩潰後的恢復流程：讀取最新 checkpoint → 還原 Agent context → 從上次中斷的步驟繼續（不是從頭重跑）。實測恢復時間平均 47 秒。

錯誤分類與恢復機制

這是整個架構最複雜、也最重要的部分。我們把錯誤分成三類，每類有不同的處理策略：

第一類：可自動恢復（Recoverable）

這類錯誤可以直接自動重試，不需要人工介入：

• API rate limit（等待後重試）
• 網路暫時中斷
• 測試因環境問題失敗（不是程式碼問題）
• lint 錯誤（Claude Code 可以自己修）

// 自動重試邏輯：指數退避
async function withRetry(fn: () => Promise, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (err) {
      if (!isRecoverable(err)) throw err;
      if (i === maxRetries - 1) throw err;
      await sleep(Math.pow(2, i) * 1000); // 1s, 2s, 4s
    }
  }
}

第二類：需人工確認（Needs Human）

技術上可以繼續，但有商業決策需要人確認：

• 需求不明確（Issue 寫得太模糊）
• 有 breaking change 風險
• 涉及安全性敏感改動

處理方式：Agent 暫停，在 GitHub Issue 留言說明需要什麼確認，等待工程師回覆後繼續。

第三類：需要放棄（Fatal）

Agent 無法繼續，需要完全人工介入：

• 連續 3 次測試失敗，且原因不同（可能是更深層的架構問題）
• 審查員發現安全漏洞且無法自動修復
• Issue 需求與現有架構根本性衝突

處理方式：標記為 ESCALATED，清理 worktree，通知工程師，生成完整的失敗報告（包含嘗試了什麼、為什麼失敗、建議的下一步）。

實際效果數據

這套架構在海衫科技運行 4 個月的數據：

• 每天平均自動完成 Issue 數：4.2 個
• 自動完成率（不需人工介入）：73%
• 需人工確認後完成：19%
• 需要完全人工介入：8%
• 平均 Issue 完成時間：2.3 小時（從建立到 PR merge）
• 工程師有效產能提升：4.3 倍

最重要的指標不是自動完成率，而是「工程師花在每個 Issue 上的時間」——從平均 4.1 小時降到 0.8 小時（主要是審查 PR 的時間）。這就是真正的生產力提升。