Communitygithub.com

lMysticl/bug-receipt

可攜式智能體技能,用於以證據為基礎的錯誤修復、根本原因分析和可驗證的 AI 編碼智能體結果。

bug-receipt 是什麼?

Bug Receipt 是一項專為 AI 編碼智能體(如 Claude Code、Cursor、Codex)設計的可攜式技能,旨在強制執行結構化、以證據為基礎的錯誤修復和事件結案流程。其核心是一個強制性的「收據」格式,該格式強制智能體在每次結案時回傳包含問題、基線、根本原因、變更、證明和差距等字段的輸出,從而確保了可追溯性和驗證能力。該技能定義了嚴格的證據邊界(例如,必須在當前運行中執行直接檢查,或明確標記為「已提供」),並要求智能體透過重現失敗、追蹤即時擁有者路徑以及針對受影響的合約層(如 UI、API、持久性或競爭條件)執行精確檢查來閉合證明迴路。透過強制要求狀態為「VERIFIED」、「PARTIAL」或「BLOCKED」,該技能能夠防止智能體產生幻覺或給出未經驗證的答案,使開發人員能夠獲得可靠、可審計的修復結果,並清楚了解任何已識別的差距。它支援機器可讀的 JSON 收據,可用於 CI/CD 集成,並提供驗證指令碼來確保合規性。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add lMysticl/bug-receipt

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

錯誤收據

強制性結案輸出

對於每個錯誤或事件結案決策,即使使用者要求簡潔回覆或未指定此格式,也應將以下完整收據作為整個面向使用者的結果回傳。簡潔會縮短欄位值;但絕不會刪除或重新命名任何行。不得以散文形式取代收據。

錯誤收據 · VERIFIED | PARTIAL | BLOCKED

問題    <觀察到的缺陷和預期行為>
基線    <失敗的互動或命令及決定性結果;或未執行>
根本原因 <已驗證的機制;或未經證實的假設>
變更     <負責的變更;或無>
證明     <提供或執行的檢查:結果;包含每個決定性層>
差距     <無;或確切的缺失證明及單一下一個實驗/套件>
來源     立即執行 | 已提供 | 混合

明確使用 未執行、未經證實 或 無。切勿為了讓收據看起來完整而省略任何行。

建立證據邊界

在編輯之前,記錄觀察到的問題、預期行為、最強的直接檢查以及證據來源:立即執行、已提供 或 混合。切勿暗示已提供的證據是在當前運行中執行的。

保持證據的隱私最小化。編輯掉憑證、令牌、Cookie、個人資料、私人 URL 和敏感負載;僅保留重現或關聯失敗所需的識別符和摘錄。

盡可能在安全檢查範圍內重現失敗。如果無法重現,請保留所獲得的證據,並將結果限制為 PARTIAL 或 BLOCKED。

追蹤並修復

  1. 從輸入到症狀,沿著即時擁有者路徑進行追蹤。
  2. 區分觀察到的事實、有界限的推論以及差距。
  3. 在命名根本原因之前,需要一個具體的位置或執行時期轉換。
  4. 進行最小範圍的負責變更;避免不相關的清理、重試、靜默回退以及特定於測試裝置的例外。

不要將看似合理的修補程式、過時的日誌、原始碼讀取或通過的建置轉換為使用者可見行為的證明。

閉合證明迴路

僅執行受影響合約要求的檢查:

  • 原始重現或直接接受度檢查;
  • 最接近的否定或回歸檢查;
  • 受影響的建置或整合關卡;
  • 當斷言跨越該邊界時,進行真實的 UI、API、持久性、並發性或執行時期路徑檢查。

使用以下決定性邊界:

表面所需的直接證明
邏輯或失敗的測試原始失敗輸入或聚焦測試現在通過
UI 行為真實互動加上相關的控制台和網路觀察
API 或整合請求、回應以及負責服務的行為
持久性透過即時擁有者路徑進行寫入/讀取或重新載入的往返
競爭條件或生命週期重複的並發觸發;零或一次成功;受影響行和事務證據;最終不變量
跨系統阻塞器一個經過清理的失敗請求/回應(附帶時間戳或請求 ID)、邊緣和應用程式日誌,以及當追蹤到達該擁有者時的識別提供者日誌

分配狀態

  • VERIFIED:觀察到的基線、具體原因、負責的變更、所有宣告的檢查均已通過,無重大差距。
  • PARTIAL:存在有用的證據,但缺少必要的證明層或證明層不確定。
  • BLOCKED:特定的外部條件阻止了重現、修復或證明。

對於 PARTIAL 或 BLOCKED,請指定能夠消除決定性差距的單一最小實驗或相關證據套件。切勿虛構命令、觀察、計數、位置或結果。

如需機器可讀的收據或 CI 集成,請閱讀 references/receipt-contract.md 並遵守其 JSON 字段、證據來源標記、相容性規則和狀態不變量。

當請求 JSON 工件時,請從 assets/receipt.template.json 開始,將其寫入任務擁有的路徑,並使用此技能目錄中的 node scripts/validate-receipt.mjs <receipt.json> 對其進行驗證。除非使用者要求,否則不要提交生成的收據。

相關技能