/agentic-workflow-audit

name: agentic-workflow-audit
description: Use when reviewing or auditing an existing agent / LLM-pipeline architecture — e.g. 'is my workflow actually decomposed or secretly a mega-agent?', 'are my task boundaries and success criteria right?', 'is our shared state a blackboard?', 'can this retry loop run forever?' — even without the word 'audit'. ｜ 要檢視／review／稽核既有 agent 或 LLM pipeline 的架構，或問「有沒有拆好」「是不是變成 mega agent」「task 邊界／成功標準對不對」「共享狀態是不是黑板」「退回會不會無限轉」「拓撲畫不畫得出來」時使用；任何評估既有 agent 系統結構的請求都觸發。不適用：要新建或自動化流程（改用 agentic-sop）。

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：做完直接呼叫下一步而無驗證；或「成功」僅等於「沒丟出例外」。

檢查 4 — 每步是否有獨立 SOP，且未被融進單一巨型 prompt

各步驟的作業規範是否各自獨立可見（獨立 prompt 檔 / SKILL.md / 文件）。

• PASS：每步規範彼此分離、可單獨定位。
• FAIL：存在一個包山包海的巨型 system prompt 把所有步驟規則全塞在一起。這是 mega agent 偷渡回來的最常見徵兆。

檢查 5 — 控制流由誰掌握

「下一步做什麼」由編排層程式決定，還是每輪交給模型自由決定。

• PASS：流程走向可從編排碼直接讀懂（預定義路徑）。
• FAIL：流程必須實際跑起來才知道模型會怎麼走（控制流落在單一模型手上）。

檢查 6 — 失敗邊是否存在，且是否有界

把「失敗處理」當成**拓撲問題**來查：圖上有沒有那條往回走的邊，以及那條邊會不會轉不停。

• PASS：失敗路徑明確（重試 / 帶錯誤上下文回退 / 標記人工介入）；**退回邊有宣告上界**；

且**進度**由感測器量測（產物內容變沒變），無可驗證進度即早停——不是只靠次數。

• FAIL：失敗即中斷無回退（圖上根本沒有那條邊）；或 try/except 吞掉錯誤默默往下走；

或回退時不帶錯誤上下文（會原地打轉）；或**退回邊沒有上界**（能無限轉）； 或上界只是散文寫在 prompt／README 裡而不是程式強制。

• 逐一問清：**哪條邊是退回邊？上界是多少？寫在哪一行程式？撞到上界之後會怎樣？**

四題有一題答不出來 → FAIL。答「模型會自己判斷什麼時候停」→ FAIL（那是檢查 5 的問題）。

檢查 7 — 拓撲畫不畫得出來，且合不合法

不執行的情況下，能否從編排宣告畫出整張圖，並靜態判掉這些結構錯誤。

• PASS：拓撲可從宣告（flow / graph 定義）直接產生；且下列各項有檢查在把關：

**不可達節點**（宣告了卻沒有路徑到得了）、**read-before-write**、**寫入衝突**（一欄位兩 writer）、 **無界環**、**孤邊**（指向不存在的步驟）。最強證據是這些檢查會讓 CI／dry-run 以非零退出碼失敗。

• PARTIAL：畫得出來，但合法性只靠人看、沒有檢查。
• FAIL：拓撲只存在於某人腦中或某張手繪圖裡，與實際程式沒有任何綁定關係；

或「圖」是一張手動維護的圖片／Mermaid，**沒有任何測試綁住它與程式一致**（那是一份會說謊的文件）。

三項決定性試金石（務必各自單獨執行並回報）

1. **單步隔離執行**：能否抽出任一步驟、以固定輸入單獨執行並驗證輸出？不能 → 切分不是真的。 2. **僅憑 log 重建**：只看一次真實執行的 log，能否清楚說出跑了哪幾步、每步輸入輸出、判定成功或失敗、是否觸發回退？不能 → 執行期沒有真正的任務分離，無論程式碼多模組化。 3. **宣告畫圖、對照實走**：只看編排宣告（不執行）畫出拓撲，再拿一次真實執行的紀錄比對—— 實際走過的節點順序（含重訪）是否都在那張圖的邊上？

• 走過圖上沒有的邊 → 真正的控制流不在宣告裡（回頭看檢查 5）。
• 紀錄裡看不出走了哪條邊、某節點被重訪幾次 → 觀測不足以稽核，判 `UNKNOWN` 而非 PASS。
• 圖畫不出來 → 檢查 7 直接 FAIL。

可觀測性騙不了人，它直接反映底層結構——這三項是最能戳破「看起來模組化、其實攪在一起」的測試。 第 3 項尤其能抓到「文件上是一張漂亮的圖、跑起來是另一回事」。

輸出格式

務必照此結構回報：

## 逐項結果
（檢查 1–7，各列：判定 / 證據[檔案:行號 或 log 摘錄] / 具體缺口 / 修補建議）

## 拓撲
（用宣告畫出來的節點與邊；標出退回邊及其上界、每個狀態欄位的 owner；畫不出來就說明卡在哪）

## 試金石結果
（三項試金石各自的結論與依據）

## 總體判定（三選一）
- 真・拆解式 workflow：七項多數 PASS，三項試金石皆通過
- 部分退化：模組化存在但若干關鍵項 FAIL（點名是哪幾項）
- mega agent 傾向：控制流落在模型手上、或巨型 prompt 主導、或無法單步隔離、或拓撲只存在於腦中

## 最高風險項
（最該優先修補的 1–3 點，依嚴重度排序）

紅線

• 不得修改任何檔案。
• 每個判定必附證據；無證據即 `UNKNOWN`，不得臆測為 PASS。
• 不得因文件或註解的宣稱而從寬判定。**一張沒有測試綁住的架構圖也是宣稱**，不是證據。
• 不得因為「有共用狀態」就直接判 FAIL——先照檢查 2 的分野查有沒有契約；

同樣不得因為「有環」就直接判 FAIL——先查那條退回邊有沒有程式強制的上界。 **從嚴的方向是要求證據，不是禁止設計。**