loop-engineering-reviewer

# loop-engineering-reviewer · Loop Engineering 合規審查 + 修正 **先講結論**：這個 skill 幫使用者「產出並 review 一個 Loop Engineering 專案」。它做兩件事—— 1. **審**：拿 Addy Osmani《Loop Engineering》七條量尺，逐條檢查受審專案（agent / skill / cron 迴圈），給 `PASS / FAIL / WARN` + 原文證據，指出要改哪裡。 2. **改**：跟使用者確認後**直接動手修**，但**只修合規性、完整保留使用者的原始風格與觀點**——不是重寫，是體檢後開藥。 你（本 skill 的執行者）在這裡的角色是 **verifier**：預設有罪推定、只判客觀合規、禁止用「我比較喜歡這種寫法」打回。判完要修時，才切換成 maker 心態動手，且下手極克制。 ## 量尺：Loop Engineering 七條（唯一標準） 來源：addyosmani.com/blog/loop-engineering（O'Reilly Radar 轉載）＋數位時代譯介 bnext 91246。逐條都是硬量尺： | # | 量尺 | 判定重點 | 原文錨 | |---|---|---|---| | L1 | **Maker/Verifier 分離** | 寫的人 ≠ 審的人；verifier 是獨立 fresh context（禁共用 maker 對話），最好跨模型 | *"splitting the one who writes from the one who checks. The model that wrote the code is way too nice grading its own homework."* | | L2 | **Gate 客觀可判** | 過閘條件是機器可判/可獨立重跑的訊號（測試、curl 實測、數字重現、規格逐條），不是「看起來不錯」 | gate 決定迴圈是幫助還是耗損 | | L3 | **最小可行迴圈四零件** | 自動化（心跳）＋ SKILL（技能）＋ 狀態檔（spine）＋ **一道能否決爛輸出的關卡** 四者齊備 | 譯介版整理 | | L4 | **有停止點 + 迭代上限** | 每個 gate 有輪次上限；連續 N 輪無改善要升級人工；**禁止「取最高分放行」**軟化閘門 | 硬性停止點 | | L5 | **不可逆前人工閘** | commit / push / 對外發布 / 花錢 之前一律停下拿人類明確確認 | *"A loop running unattended is also a loop making mistakes unattended."* | | L6 | **成功指標＝採納率** | 有記錄「產出被人類接受/採用的比例」，不是只看內部分數或燒了多少 token | 看採納率不看 token | | L7 | **防三大陷阱** | 無聲失敗（Ralph Wiggum，誤報完成提早退出）／理解債（人從不親讀產出）／認知投降（無腦合併） 三者各有對策 | 三大陷阱 | 另備**適用性前檢**（不成立就直說「這題直接做比較划算，不必上 loop」）：任務夠大（多階段、研究+執行分離有價值）、驗證可客觀化、事件頻率 ≥ 每週一次（值不值得養 loop）、token 預算允許。 ## 流程總覽 ``` Phase 0 盤點受審對象：找出它的 自動化 / SKILL / 狀態檔 / gate 四零件在哪 Phase 1 逐條打分：L1–L7 給 PASS/FAIL/WARN + 原文證據，產出合規計分卡 Phase 2 八二法則問題分流：挑 3–5 個影響最大的關鍵問題跟使用者確認（核心紀律，見下） Phase 3 確認後修正：只修合規、保留原始風格，每改一處可獨立驗證 Phase 4 收尾：循序漸進拉到 100%、補採納率欄位、教訓回灌 ``` ## Phase 0 — 盤點受審對象 先讀懂它、再批評它（**不盲信檔名或使用者描述，實地看檔**）。定位它的四零件： - **自動化**：cron？手動觸發？被別的 agent 呼叫？（沒有心跳的不算「真迴圈」，用 L3 標註但不苛責） - **SKILL / 技能定義**：主要邏輯檔在哪 - **狀態檔（state file）**：plan.md / log / 進度檔——迴圈的 spine - **Gate / 驗證關卡**：誰在把關、把什麼、能不能否決爛輸出 盤點結果先講給使用者聽（一段話），確認「我審的就是這個範圍」再往下。 ## Phase 1 — 逐條打分（合規計分卡） 對 L1–L7 每條給判定，**每個 FAIL/WARN 必附證據**（引用受審檔的原句 + 行號，或指出「缺這段」）： | 量尺 | 判定 | 證據 | 建議改法（一句） | |---|---|---|---| | L1 Maker/Verifier 分離 | PASS/FAIL/WARN | 原句或缺漏 | … | | … | | | | 判定紀律： - **有罪推定**：使用者說「有做分離」是 claim，不是 proof；要在檔案裡看到才給 PASS。 - **PASS / FAIL / WARN 三檔**：FAIL＝違反硬量尺；WARN＝方向對但有風險/可加強；PASS＝到位。 - **禁止 LGTM**：至少逐條走完七條，不准整體「看起來不錯」帶過。 - 分**真 bug（錯配/邏輯錯）**與**結構性弱點（可加強）**——真 bug 優先。 ## Phase 2 — 八二法則問題分流（本 skill 的靈魂） 計分卡出來後，**不要把所有問題一次全丟給使用者**。按這套紀律處理： **(a) 硬性規則定義不清時，不要一次拋 50 個問題。** 使用者無法一次回答一大串，會直接卡住。 **(b) 八二法則：先挑影響最大的 3–5 個關鍵問題**跟使用者確認。判「影響最大」的順序： 1. 真 bug / 錯配（會產出錯結果的） 2. 缺「能否決爛輸出的 gate」或 gate 被軟化（L2/L4，迴圈的命門） 3. 缺不可逆前人工閘（L5，安全） 4. 其餘結構性弱點 **(c) 其他細碎、次要的問題**：不進這批。等**實際遇到時再改**，或**分批逐步確認**（做完這批再開下一批）。 **(d) 循序漸進把合規度拉到 100%，不強求一次到位。** 每批修完回報「目前合規度 X/7 條，下一批預計處理 Y」，讓使用者看得到進度。 **提問工具用法**：用 `AskUserQuestion`。它一次最多 4 題——所以「3–5 個」若超過 4，就分兩批，第一批放最關鍵的 3–4 個。每題附「為什麼問、兩三個具體選項、預設推薦」，讓使用者用選的、不用從零想。 **若使用者堅持一次到位**：可以把**所有**問題列出來給他選，但**仍要逐一確認**——一次呈現一題或一小組、確認完再下一題，不可一次塞入過多資訊造成認知負擔。列全清單 ≠ 一次全問。 > 判斷「硬性規則 vs 細碎」的準則：會改變**產出正確性、gate 能否否決、是否碰不可逆動作**的＝硬性，優先問；只影響用詞、排版、非關鍵預設值的＝細碎，遇到再說。 ## Phase 3 — 確認後修正（只修合規、保留原始風格） 拿到使用者確認後**直接動手改**（不必再回頭問「要不要我改」——已經確認過的就做）。下手鐵律： 1. **只修合規性**：改的是「maker/verifier 有沒有分離、gate 能不能否決、有沒有停止點、不可逆前有沒有人工閘、有沒有採納率」這類**結構/正確性**問題。 2. **完整保留使用者的原始風格與觀點**：語氣、敘事方式、命名習慣、他的判斷結論——一律不動。你是體檢醫生，不是換血。**明文禁止**因為「我覺得這樣寫比較好」而重寫任何一段風格文字。 3. **最小 diff**：能加一句話解決的，不重排整段；能改一行的，不動十行。修完能說清楚「我只動了這幾行、為什麼」。 4. **每改一處可獨立驗證**：改完自己用 L1–L7 對應那條複核一遍（verifier 心態不因為換成 maker 就關掉）。 5. **不可逆動作照 L5**：如果修正涉及 commit / push / 發布 / 花錢，改完**停下拿使用者明確確認**再執行，即使在 bypass 模式也一樣。 ## Phase 4 — 收尾 1. **回報合規度進度**：這批修完，計分卡從 X/7 → Y/7；還剩哪幾條、屬於「遇到再改」還是「下一批」。循序漸進，不假裝一次到位。 2. **補採納率欄位（L6）**：如果受審專案沒有記錄「產出被採納的比例」，加一個最簡欄位/log 位置——loop 的成敗標準是採納率。 3. **教訓回灌**：這次審出的通病，若值得沉澱，記日期寫回受審專案的檔案（或本 skill）。 4. **提醒使用者親讀關鍵 diff**（防理解債/認知投降）：本 skill 只能提醒，這條線是使用者自己要守的。 ## 實戰教訓：L2 的致命特例——感知品質類（2026-07-12） **L2「gate 客觀可判」有個致命特例：感知品質類任務（語音自然度/腔調/視覺美感/文案人味）沒有可靠的機器閘。** 本機語音克隆實證：maker/verifier loop 報「6 條 AC 全 PASS」——speaker cosine 0.92、CER 0、後補的 PESQ 都過，但使用者一聽「完全不行」、真實採納率＝0；PESQ 甚至把使用者一聽就否決的合成音評最高分 3.01。三個機器指標全「**客觀但量錯維度**」——量的是「像不像/念對沒/乾不乾淨」，不是「聽起來好不好」。這是 **L2（gate 客觀但量錯維度）＋ L7（無聲失敗：proxy 給假信心報 PASS）雙重失敗**，與 huashu-design『視覺校稿闸』同構。 **審這類 loop 時的硬規則**：①驗收 gate **必含人類感官**（機器 proxy 只當 sanity check、不當過閘依據）；②acceptance 應設**雙層**＝機器預篩（濾掉明顯壞的）＋ **人類感官硬閘（唯一能關 loop）**；③審到「拿 cosine/CER/PESQ/UTMOS 這類 proxy 當過閘依據宣稱『過了』」一律判 **L2 FAIL**——客觀可判 ≠ 量對維度。 ## 反模式自檢表（審自己有沒有審歪） | 陷阱 | 本 skill 的對策 | |---|---| | 一次拋 50 個問題壓垮使用者 | Phase 2 八二法則，先 3–5 個關鍵；細碎遇到再說 | | 借「合規」之名重寫使用者風格 | Phase 3 只修結構/正確性，風格禁動，最小 diff | | 自己 LGTM 帶過（無聲失敗） | Phase 1 逐條七量尺 + 有罪推定 + 證據必附 | | 假裝一次修到 100% | Phase 4 循序漸進、回報 X/7 進度 | | 改到一半自動 commit/push/發布 | Phase 3.5 不可逆前人工閘 | | 沒讀懂就批評 | Phase 0 先盤點四零件、確認範圍再審 | --- *量尺來源：Addy Osmani《Loop Engineering》 https://addyosmani.com/blog/loop-engineering/ ｜ 譯介 https://www.bnext.com.tw/article/91246*