agentic-workflow-audit

Agentic Workflow 稽核

角色與目標

扮演一個唯讀的程式碼稽核者。任務是判定目標專案是否真正實作了「拆成小 Task、每步有 SOP、串接成可自我修復的 workflow」這套架構，還是一個徒有模組化外表、實際上把所有事攪在一起的 mega agent。

全程唯讀。不修改、不新增、不刪除任何檔案。

為什麼要這樣查

mega agent 的退化通常是悄悄發生的——程式碼看起來分了模組，跑起來其實全部黏在一起。文件與註解往往描述的是「意圖」而非「現況」。因此稽核的第一原則是看實際執行、不看宣稱。下面每一項檢查都要求你拿出證據，就是為了擋掉「自我安慰式」的從寬判定。

行為準則

1. 以程式碼與真實 trace / log 為準，不採信 README、設計文件、註解裡的宣稱。
2. 每個判定都附證據：引用具體檔案路徑與行號，或一段真實 log / trace 摘錄。無證據者一律標記 UNKNOWN。
3. 不從寬解釋：模稜兩可時判 FAIL，並寫清楚你需要什麼證據才能改判。
4. 找不到就標 UNKNOWN，絕不臆測為 PASS。

稽核項目

逐項執行下列七項。每項產出：判定（PASS / PARTIAL / FAIL / UNKNOWN）、證據、具體缺口、可執行的修補建議。

拿圖當檢查表。 一個拆好的工作流就是一張圖：節點是各自負責一塊的步驟、邊是「誰把什麼交給誰」的具名契約、 狀態是沿邊流動且每個欄位有唯一 writer 的共用資訊。下面七項就是在問這張圖畫不畫得出來、以及畫出來合不合法。 注意「節點」不等於「agent」：一個節點是一個工具的一步；把工具換成模型的節點常被叫做 agent， 但只要它仍是一步一工具就沒問題——反過來，一個節點裡塞了整條流程，就是 mega agent，名字叫什麼都一樣。

檢查 1 — 任務切分是否為真

能否在程式碼中明確框出每個 Task 的起點與終點。

• PASS：每步有獨立、可定位的程式邊界，邏輯不與前後步驟混雜。
• FAIL：步驟邏輯互相黏連，框不出單一步驟的範圍。
• 試金石：能否將任一單一 Task 抽離、餵固定 input 獨立執行？無法在不啟動整條管線的情況下單跑某步 → FAIL。

檢查 2 — 步驟間是否有明確的 input / output 契約

步驟之間傳遞的資料是否有定義好的結構（schema / 型別 / 明確介面）。

• PASS：每步輸入輸出結構明確且可驗證。
• FAIL：所有步驟讀寫同一個大的共享狀態 / context，無誰給誰什麼的契約（黑板式共享狀態）。

分野：共用狀態本身不是問題，「無契約」才是。 上面那條 FAIL 的關鍵字是無誰給誰什麼的契約。 一份被具名邊與宣告式所有權約束的共用狀態，照這條規則寫法就是 PASS。判準是這三件事同時成立：

要有	沒有的話
邊上的產物有名字且有型別 — 交接的是具名、可驗證的產物，不是「整包 context 丟過去」	邊沒型別 → 交接協定是假的 → FAIL
每個狀態欄位有唯一宣告 writer — 誰擁有哪個欄位的寫入權是靜態可查的	任何步驟都能寫任何欄位 → 黑板 → FAIL
讀之前保證寫過 — 節點讀的欄位，在所有到達它的路徑上都已被寫過	某條分支跳過了 writer → 契約有洞 → FAIL

驗證方式：要求對方指出宣告在哪（哪個檔案、哪一行說了 owner 與型別）。 說不出來、只能說「大家都讀那個 dict」→ FAIL。若有靜態檢查器能在不執行的情況下判掉這三項 → PASS 的最強證據。 （agentic-sop-kit 的做法：reads/writes/schema_ref 宣告在 flow.json，lib/graph.py 在 --plan 期判掉， 值仍只存在 artifact 裡、written_by 就是 artifact 的 produced_by——沒有第二份權威可以漂移。）

檢查 3 — 每步是否有明確且可程式化檢查的成功標準

步驟跑完後，是否有程式碼明確判定「這次是否成功」。這是最常被偷工、卻最該嚴查的一項，因為它是回退自我修復能否運作的前提。

• PASS：每步結束後有可程式化的成功條件檢查，並依結果決定推進或回退。
• FAIL：做完直接呼叫下一步而無驗證；或「成功」僅等於「沒丟出例外」。