kmloureiro/agent-verify

agent-verify 是做什麼的？

讓你建構的東西能透過最便宜的機制來驗證。預設透過 CLI 驗證。模型應該只讀取約 20 個 Token（PASS / FAIL: line），絕不要讀 DOM 轉儲或螢幕截圖。

唯一規則

使用最能證明功能錯誤的最輕量機制。僅在無法證明時才升級。

in-process assert  →  CLI / curl + exit code  →  DB test (TAP)  →  headless browser (visual only, last)
   最便宜                                                              最昂貴

代理建構的 90% 功能（邏輯、資料、API 合約、流程）完全不需要瀏覽器就可驗證。將瀏覽器保留給像素相關的驗證。

循環（每個功能）

1. 偵測一次。 執行 scripts/detect-stack.sh。它會用幾行輸出印出測試執行器和技術棧。不要強制導入新的框架——使用既有的。
2. 建構功能。
3. 撰寫一個極簡 Token 的檢查，使用該技術棧的 in-process / CLI 原始方法（請參考 reference/stacks/）。檢查必須印出 PASS 或單行 FAIL: ——絕不要轉儲。
4. 在 VERIFICATION_MAP.md 中附加一行：feature | command | pass-signal。這是代理下次讀取的契約。
5. 執行 scripts/verify.sh [feature] 並只讀取結果。根據結果進行編輯 → 驗證 → 重複，不要根據日誌。

不要做的事

• 不要為了檢查邏輯、資料或 API 回應而使用 Playwright/瀏覽器。這就是此 SKILL 存在要阻止的 Token 洩漏。
• 不要規定 TDD 儀式。呈現 哪個 檢查能證明 這個 功能，而不是一個流程。（沒有針對性上下文的流程會適得其反——請參閱 reference/patterns.md。）
• 不要將原始輸出回傳到上下文。在沙盒中過濾，呈現結果。（console.log(result)，而不是那 10k 行。）
• 不要讓檢查擴張。一個功能，一個快速確定性檢查。保持 VERIFICATION_MAP.md 簡短——簡短的映射表現優於長的映射。

輸出契約（始終如此）

PASS auth-login
FAIL create-invoice: expected 201, got 500

Exit 0 = 全部通過。非零 = 有項目失敗。模型只需要這些。

當瀏覽器無法避免時

僅用於真正視覺化的 UI（佈局、樣式、視覺回歸），並且只用在最後階段。即便如此：一次 headless 執行，回傳 PASS/FAIL 或差異判決——絕不要將完整螢幕截圖或 DOM 帶入上下文。請參閱 reference/stacks/nextjs.md。

檔案

• scripts/detect-stack.sh — 印出技術棧和執行器，極簡 Token。
• scripts/verify.sh — 執行映射的檢查，僅輸出 PASS/FAIL 和失敗行。
• VERIFICATION_MAP.md — 簡短的功能→指令映射（由代理維護）。
• reference/stacks/ — 複製貼上食譜：FastAPI（in-process TestClient）、Supabase（seed + reset + pgTAP）、Next.js（route handlers + last-resort visual）。
• reference/patterns.md — 極簡 Token 驗證模式及其背後的證據。
• reference/anti-patterns.md — 不穩定測試、假 PASS、過度設計的防護。
• templates/ — 映射、FastAPI 測試、Supabase seed 的起點。