Communitygithub.com

fix-bug

當程式中有錯誤時使用:測試失敗、CI 紅燈、API 回傳錯誤結果、出現堆疊追蹤,或使用者說「壞了」或「修正這個」。不要用於沒有失敗的新功能、僅類型工作或文件。

fix-bug 是什麼?

這是一個專門用於除錯和修正 Bug 的 AI 代理技能。其核心原則是要求代理程式在進行任何修補之前,必須先透過日誌和假設嚴格定位根因,禁止猜測性修復。此技能支援所有開發平台,透過一系列嚴格的程序來引導除錯:從讀取錯誤資訊(程序 1)、建立非表面假設(程序 2)、植入除錯日誌並消除假設(程序 3),到最後撰寫會失敗的測試並進行精準修復(程序 4)。它還會在修復完成後,詢問使用者是否要載入「prove-it」技能進行正式驗證(程序 5),若無則直接結束(程序 6)。此技能對於要避免常見除錯反模式(如掩蓋錯誤、隱藏競爭條件、不做假設曲線就動工)的開發者特別有用,能確保團隊能透過結構化且紀律嚴明的方式處理 Bug。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AlemTuzlak/skills/tree/HEAD/skills/fix-bug

在你喜歡的 AI 中提問

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

說明文件

修正 Bug

找出根本原因。不要修補症狀。不論是應用程式還是函式庫,這個原則都不變。

此技能僅在修復完成且變更為綠色後,才會載入 prove-it,而且只有當使用者選擇它或已要求證明時才會載入。它不會覆蓋 CopilotKit 的除錯技能。

使用時機

當失敗發生時載入:失敗的測試、紅燈的 CI、非預期的結果、堆疊追蹤,或使用者說「壞了」/「修正這個」。

跳過沒有失敗的全新功能開發。跳過文件及純類型修改。

嚴格守則

  1. 在從日誌中確定原因之前,不得進行任何修復。 不允許「隨便試幾個方法」。
  2. 在熱路徑上,至少要提出三個假設,且須來自不同位置(我們的函式、呼叫者、依賴項)。
  3. 在每個假設的路徑前後加入除錯日誌。如果涉及的第三方套件有除錯模式,請在此次調查中開啟它。
  4. 當原因確定後:刪除此技能加入的所有日誌,並關閉第三方除錯模式。 然後撰寫會失敗的測試。最後才進行修復。日誌絕不能留在修復中。
  5. 不得跳過、刪除或停用失敗的測試 來讓測試變成綠色。不得吞沒錯誤(|| true、空的 catch 區塊)。不得為了隱藏競爭條件而提高超時時間。
  6. 修復根本原因,以及同檔案或附近模組中的相同模式。不要做額外的重構。
  7. 除非使用者選擇,或已要求證明此次修復,否則不要載入 prove-it。 測試套件變成綠色不代表已經過證明。預設為跳過。

熱路徑

從失敗的測試(或使用者操作)開始,沿著堆疊向下到錯誤行,以及呼叫和被呼叫的函式。

從那裡開始。排除。 縮小範圍。只有在該路徑上的所有假設都無效時,才擴大範圍。

程序

程序 1:讀取

  1. 讀取完整的錯誤訊息、堆疊追蹤或 CI 日誌。每一行都要看。
  2. 如果有的話,讀取失敗測試的內容。
  3. 如果有的話,讀取可能引入此錯誤的差異比對。
  4. 尚不進行編輯。

程序 2:假設

  1. 繪製熱路徑圖(檔案和函式)。
  2. 提出至少三個假設:「錯誤是由 X 引起的,因為 Y。」它們必須涵蓋整個熱路徑(不能只是對同一行程式碼的三種猜測)。
  3. 如果無法寫出三個,表示你讀得不夠。回到程序 1。

程序 3:植入儀器

  1. 對於假設中提到的每個第三方套件:查閱其文件,看是否有除錯旗標或環境變數。如果有,就開啟它。
  2. 在每個假設分支的前後加入暫時的日誌(輸入值進來、輸出值出去)。使用該儲存庫既有的日誌記錄器或 console。不要新增日誌記錄套件。
  3. 重現一次錯誤。讀取日誌。劃掉日誌證明為無效的假設。
  4. 如果三個假設都無效,將熱路徑向外擴展一步(下一個呼叫者或下一個依賴項)。提出新的假設。加入新的日誌。再次排除。
  5. 當一個原因被確定時:刪除此技能加入的所有日誌。 關閉第三方除錯模式。確認工作目錄中已沒有那些日誌殘留。

程序 4:先寫失敗測試,再修復

  1. 撰寫一個會因為這個 Bug 而失敗的測試(紅燈)。測試需有獨立預期值。不可跳過此步驟。
  2. 執行它。它必須因為你所指名的原因而失敗。
  3. 僅修正根本原因。同時修正同一個檔案或附近模組中相同錯誤的副本。
  4. 執行該測試(綠燈)。然後執行此套件/此檔案對應套件的現有測試。
  5. 如果出現新的失敗,將其視為新的 Bug。從程序 1 開始。不要在第一個修復之上疊加新的錯誤就出貨。

程序 5:選擇性證明(prove-it)

  1. 在此套件的測試套件變成綠色且日誌已移除後,詢問一次。選項:載入 prove-it,或跳過。預設 跳過。
  2. 等待。在使用者選擇之前,不要載入 prove-it。
  3. 如果他們在此對話中已經要求證明這個修復,則跳過詢問。直接載入 prove-it。
  4. 如果跳過: 說明此修復未經證明,是一個使用者路徑。不要將綠燈的測試套件當作證明。進入程序 6。
  5. 如果他們選擇 prove-it:載入 prove-it 並遵循其指示。然後進入程序 6。
  6. 不要在此技能內部點擊應用程式、curl API 或編寫證明報告。這些工作屬於 prove-it。

程序 6:結束

在跳過之後,或在 prove-it 回傳結果之後,結束。

決策樹

  • 失敗發生 → 程序 1 → 2 → 3 → 4 → 5 → 6。
  • 無法重現 → 結束。說明無法重現。請使用者提供步驟。不要猜測性地修復。
  • 日誌推翻了所有熱路徑假設 → 擴大範圍,再次進行程序 2。
  • 修復後測試仍然是紅燈 → 原因錯誤。還原修復。回到程序 2。
  • 下一個函式中發現相同模式 → 在同一變更中一併修正(嚴格守則 6)。
  • 測試套件變成綠色,但尚未詢問證明 → 程序 5(詢問,預設跳過)。
  • 使用者已要求證明此修復 → 載入 prove-it,然後進入程序 6。

紅旗警示

訊號代表意義應該怎麼做
一個假設,然後直接修補猜測程序 2。在熱路徑上建立三個假設。
沒有日誌的修復未經排除程序 3。
差異比對中仍有除錯 console.log日誌未清除程序 3 的步驟 5。然後才寫測試。
第三方 DEBUG=* 仍處於開啟狀態除錯旗標被發布與日誌一同關閉。
.skip / 刪除失敗測試處理症狀修正程式碼。
`true` / 空的 catch 區塊
更長的超時時間隱藏競爭條件修正競爭條件。
在修復時一併重構順便亂改只修正根本原因 + 相同模式。
執行整個 monorepo 的測試未經要求只執行這個套件 / 這個測試套件。
「在我機器上可以跑」環境不同使用與失敗時相同的命令 / 相同的條件。
未經詢問就載入 prove-it未經要求的證明程序 5。預設跳過。
在此技能內進行迷你瀏覽器驗證與 prove-it 重複待使用者選擇後載入 prove-it。
「測試通過了,所以已經過證明」將綠燈套件當作證明程序 5。跳過即表示未經證明。

錯誤處理

  • 無法重現: 說明情況。列出你執行了哪些步驟。不要憑空發明修復。
  • 依賴項沒有除錯模式: 跳過該步驟。仍然對我們自己的熱路徑程式碼進行日誌記錄。
  • 日誌過大: 只記錄假設分支的日誌,不要記錄檔案中的每一行。
  • 尚無法撰寫失敗測試(無測試框架): 用一個單一檔案的腳本來斷言這個 Bug,作為替代方案。腳本仍是紅燈,然後修復,然後變成綠燈。
  • 修復導致另一個測試失敗: 對該失敗進行程序 1。在第一個修復造成的連鎖問題解決之前,不要推送它。
  • 此代理程式上缺少 prove-it: 說明情況。提議跳過。不要在此技能內自創第二個證明程序。
  • 使用者選擇 prove-it,然後在裡面跳過: 此修復未經證明。程序 6。

此技能不會放置輔助工具或撰寫文件。證明僅是程序 5。

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

AlemTuzlak/skills

Use when the user wants to write a blog post about a feature, product change, PR, git diff, or any technical topic - accepts marketing briefs, PRs, git refs, codebase paths, or freeform descriptions as input

AlemTuzlak/skills

Use when the user wants to generate a changelog, release notes, or document what changed between versions, tags, or PRs

AlemTuzlak/skills

Use when writing, editing, or organizing documentation, when planning what docs a feature needs, and whenever planning or implementing a new feature or change in a repo (docs ship with the code). Also use when tempted to write docs without showing the discovered readers to the user, without asking for tone, or without loading simple-english and i-have-adhd. Triggers on "write docs for X", "document this feature", "add a guide", "update the docs", "reorganize the docs", "plan feature X", "implement X", or /docs.

AlemTuzlak/skills

Use when the user invokes /i-have-adhd, says they have ADHD, or asks for ADHD-friendly output. Also used as a required writing filter by the docs skill. Don't use for marketing copy or after the user says "stop adhd mode" or "normal mode".

AlemTuzlak/skills

Use when a settled change must be turned into an ordered stack of small blocks before anyone implements. Don't use for unsettled intent, typos, comments, formatting, docs-only work, or writing the implementation itself.

AlemTuzlak/skills

Use when the user wants to write a product update email, feature announcement newsletter, or digest email for users or subscribers

AlemTuzlak/skills

Use when the user wants to turn a raw talking-head / screen-share recording into a finished, edited, annotated video plus a full content package. Removes silences, flags mistakes for the user to cut, transcribes, adds transcript-synced overlays (code, on-screen code highlights, word highlights, lists, comparisons, diagrams, section labels, punch-in zooms), renders with original audio, then generates blog/socials/YouTube content. Triggers on "produce a video", "edit my video", "annotate my recording", "/produce-video".

AlemTuzlak/skills

Use when the user runs /prove-it or says prove it, prove the changes, show me in the browser, or asks to prove a UI or API change. Don't use only because the agent is about to say done, for types-only work, or for docs with no behavior to prove.

AlemTuzlak/skills

Use when the user wants to write, draft, or author an RFC (Request for Comments) / technical design doc for a feature, change, or architectural decision. Interactively interviews the user, grounds the proposal in the actual codebase, presents 2-3 concrete API/code-snippet approaches to choose from, then writes a review-ready RFC. Triggers on "write an RFC", "draft an RFC", "RFC for X", "design doc for X", or /rfc.

AlemTuzlak/skills

Use when the user wants to deeply learn a new topic from scratch. Runs a pre-interview (current knowledge, end-goal proficiency, depth, practice load, background, scope), researches online (articles, niche-influencer blogs, canonical docs, subtopic landscape), then produces a structured markdown course with mandatory visual diagrams, evidence-based learning-science features (retrieval practice, spaced callbacks, worked-example fading, concept ledger, jargon gate, analogy hygiene), and a self-contained interactive HTML mini-course. Triggers on /teach-me, "teach me about X", "I want to learn X", "deep dive on X", "create a course on X", "study X with me".

AlemTuzlak/skills

Use when the change intent is already settled and the agent must map what a behavior change touches before an implementation plan or any code. Use for new features, bug fixes, and refactors that move a boundary. Don't use for typos, comments, formatting, lockfile-only diffs, docs with no code, or while the user is still deciding what they want.

AlemTuzlak/skills

Use when the user wants to transcribe a video or audio file to text with word-level timestamps — spins up a self-contained local Whisper (whisper.cpp) Docker service bundled in this skill and returns transcript.txt, transcript.srt, and word-level transcript.words.json. Also used as a building block by /produce-video. Triggers on "transcribe this video", "get a transcript", "transcribe-video".

AlemTuzlak/skills

Use when the user wants to write a video script for a product demo, feature walkthrough, launch video, or social media video about a feature or product change

AlemTuzlak/skills

Use when the user wants YouTube metadata for a video — a click-worthy title, an SEO/above-the-fold description, tags, and timestamped chapters. Accepts a transcript (ideally timestamped SRT), a topic, a PR, or a freeform description. Used standalone and by /produce-video. Triggers on "youtube title", "youtube description", "youtube chapters", "youtube tags", "youtube metadata", "youtube-copy".

相關技能