前言¶

提 PR 之前，很多人會讓 AI「幫忙看一眼代碼」。常見結果有兩種：一種是隻挑空格和命名，真正的注入、越權和競態被略過；另一種是按關鍵詞亂報一通，把框架已經防住的寫法也標成漏洞。缺的不是「再審一遍」這句話，而是一套固定流程：先拿到完整 diff，再畫攻擊面，再按清單逐項覈對，最後還要證明問題確實存在。

find-bugs 就是把這套流程寫進 Agent Skill 的產物。它來自 Sentry 工程團隊維護的公開倉庫 getsentry/skills，官方說明見 skills/find-bugs/SKILL.md。倉庫 README 寫明：這是 Sentry 員工日常開發使用的 Agent Skills 集合，遵循 Agent Skills 開放格式，許可證爲 Apache-2.0。

這是什麼¶

一句話定位：針對當前本地分支相對默認分支的變更，按五階段流程查找 bug、安全漏洞和代碼質量問題，只出報告、不改代碼。

官方 frontmatter 如下：

• name：find-bugs
• description：在本地分支變更中查找 bug、安全漏洞和代碼質量問題；在被要求 review changes、find bugs、security review，或審計當前分支代碼時使用

目錄裏目前只有這一份 SKILL.md，沒有附帶腳本或 references/。它不是靜態分析器，也不會調用 Sentry 的產品 API；真正幹活的是讀了這份清單的 AI Agent，配合 git 和 GitHub CLI（gh）拿到完整 diff。

同倉庫裏還有職責相近、但範圍不同的 Skill，不宜混用：

• code-review：按 Sentry 工程實踐做 PR 審查（運行時錯誤、性能、測試、設計）
• security-review：安全專項審查，只報告高置信、可利用的漏洞，並帶有獨立的語言/基礎設施參考文檔

find-bugs 的邊界更窄：只看本分支相對默認分支的改動，安全、缺陷、質量一起過，但明確跳過純風格和格式問題。

核心功能與亮點¶

根據官方 SKILL.md，工作流固定爲五個階段。

階段 1：完整收集輸入¶

Agent 必須先拿到完整 diff，而不是摘要：

git diff $(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')...HEAD

這條命令用 gh repo view 查出倉庫默認分支（main / master 等），再對「默認分支…當前 HEAD」做三點 diff（即相對合並基線的本分支變更）。官方還要求：

1. 若輸出被截斷，就逐個打開改動文件，直到每一行改動都讀過
2. 進入下一階段前，先列出本分支修改過的全部文件

也就是說，不允許「掃了幾個文件就開始下結論」。

階段 2：攻擊面映射¶

對每個改動文件，先列出這些點，而不是直接猜漏洞：

• 所有用戶輸入（請求參數、Header、Body、URL 組成部分）
• 所有數據庫查詢
• 所有認證 / 授權檢查
• 所有會話 / 狀態操作
• 所有外部調用
• 所有密碼學操作

這一步的作用是把 diff 翻譯成「攻擊者能碰到什麼」，後面的清單纔有落點。

階段 3：安全清單（每個文件、每一項都要過）¶

官方清單共 11 項，要求對每個文件逐項勾選：

• Injection：SQL、命令、模板、Header 注入
• XSS：模板裏的輸出是否正確轉義
• Authentication：受保護操作是否都做了認證
• Authorization / IDOR：是否驗證了訪問控制，而不只是「已登錄」
• CSRF：改狀態的操作是否有防護
• Race conditions：讀後寫路徑上是否有 TOCTOU
• Session：固定會話、過期、Secure 等標誌
• Cryptography：安全隨機數、算法是否合適、密鑰是否進日誌
• Information disclosure：錯誤信息、日誌、時序側信道
• DoS：無界操作、缺限流、資源耗盡
• Business logic：邊界情況、狀態機被破壞、數值溢出

這不是「想到什麼查什麼」，而是一張必須走完的檢查表。

階段 4：覈實¶

對每一個可疑點，官方要求再確認三件事：

• 問題是否已在本次改動的其他位置處理過
• 是否已有測試覆蓋該場景
• 讀周圍上下文，確認問題是真的

目的是壓假陽性：看到 execute 或字符串拼接，不等於可以立刻報注入。

階段 5：收口前審計¶

給出最終結論之前，必須先做：

1. 列出審查過的每個文件，並確認讀完
2. 列出清單每一項：是發現了問題，還是確認乾淨
3. 列出未能充分覈實的區域及原因
4. 然後纔給最終發現

輸出格式¶

優先級固定爲：安全漏洞 > bug > 代碼質量。風格和格式問題直接跳過。

每條問題按下面字段寫：

• File:Line：簡要描述
• Severity：Critical / High / Medium / Low
• Problem：錯在哪裏
• Evidence：爲什麼這是真問題（例如：沒有在別處修掉、沒有現成測試）
• Fix：具體改法建議
• References：適用時引用 OWASP、RFC 等標準

官方還有兩條硬約束：

• 沒有明顯問題就直說，不要編造
• 不要改代碼，只報告；由使用者決定修哪些

安裝與啓用¶

該 Skill 收錄在 getsentry/skills 倉庫，作爲 sentry-skills 插件的一部分對外提供。安裝方式以官方 README 爲準。

Claude Code（官方插件市場）¶

claude plugin marketplace add getsentry/skills
claude plugin install sentry-skills@sentry-skills

裝完後重啓 Claude Code。官方說明：相關場景下 Skill 會自動啓用。更新可以用：

claude plugin marketplace update
claude plugin update sentry-skills@sentry-skills

或在對話裏運行 /plugin 打開插件管理。若用 claude plugin marketplace add --sparse 添加該倉庫，需要把 skills、agents 和 .claude-plugin 一併包含，因爲根目錄的插件清單會加載倉庫頂層的 skills/ 與 agents/。

skills.sh（Cursor / Claude Code / Copilot 等）¶

官方 README 同時提供 skills.sh 安裝方式，並寫明適用於 Claude Code、Cursor、Cline、GitHub Copilot 及其他兼容 Agent：

npx skills add getsentry/skills

若只裝這一個 Skill，skills.sh 上的命令是：

npx skills add https://github.com/getsentry/skills --skill find-bugs

手動放到各工具的 Skill 目錄¶

SKILL.md 是通用 Agent Skills 格式。按 Cursor 文檔，項目級會從 .agents/skills/、.cursor/skills/ 自動發現；用戶級對應 ~/.agents/skills/、~/.cursor/skills/。兼容目錄還包括 .claude/skills/、.codex/skills/ 以及對應的用戶級路徑。手動放置時目錄應類似：

.cursor/skills/find-bugs/SKILL.md

或：

.agents/skills/find-bugs/SKILL.md

Claude Code 項目級爲 .claude/skills/find-bugs/SKILL.md，用戶級爲 ~/.claude/skills/find-bugs/SKILL.md。Codex CLI 則掃描 $CODEX_HOME/skills（默認 ~/.codex/skills）以及項目內的 .codex/skills/。

啓用後，在 Agent 對話裏輸入 /，搜索 find-bugs 即可手動調用。官方 description 裏帶有 review changes、find bugs、security review、audit code 等觸發詞，描述匹配時 Agent 也可能自動選用。

典型用法示例¶

前置條件¶

按官方命令，運行環境需要：

• 當前目錄是 Git 倉庫，並且已經在一條功能分支上（相對默認分支有提交或未提交的可比對變更）
• 已安裝並登錄 GitHub CLI（gh），因爲默認分支名是靠 gh repo view 查的
• 遠程是 GitHub 上的倉庫；gh repo view 對非 GitHub 遠程會失敗，這時需要自己給出默認分支，再讓 Agent 用 git diff <default>...HEAD 補齊——這是環境限制，不是 Skill 正文裏的替代流程

喚起方式¶

官方沒有單獨給「示例提示詞」，但 description 已經寫清觸發場景。在已安裝 Skill 的對話裏，可以直接說（或先 /find-bugs 再補充）：

請按 find-bugs 審查當前分支相對默認分支的全部改動：
先拿到完整 diff，列出所有改動文件，做攻擊面映射，
再按安全清單逐項檢查，最後只輸出帶證據的問題報告，不要改代碼。

也可以把範圍說得更具體，例如「只看這次 API 鑑權相關的 diff」——Agent 仍應按五階段走完，而不是跳過收集 diff 直接下結論。

報告長什麼樣¶

官方要求的條目形態可以理解成下面這樣（路徑和行號必須來自當次 diff，不能照抄）：

**app/api/orders.py:142** - 按對象 ID 取訂單時未校驗歸屬
- **Severity**: High
- **Problem**: 已登錄用戶傳入任意 `order_id` 即可讀到他人訂單（IDOR）
- **Evidence**: 本分支新增該查詢；同文件及中間件未見對象級授權；無對應測試
- **Fix**: 查詢時加上當前用戶（或租戶）約束，例如 `order.user_id == request.user.id`
- **References**: OWASP A01:2021 Broken Access Control

如果五階段走完沒有值得上報的問題，按原文應明確說「沒有發現顯著問題」，而不是爲了交差編幾條風格意見。

適用場景與注意事項¶

適合

• 功能分支即將開 PR，希望先做一輪「安全優先」的本地審查
• 改動涉及用戶輸入、鑑權、會話、外部調用或密碼學，需要按清單過一遍，而不是隻看業務邏輯
• 團隊已經用 Cursor / Claude Code / Codex 等支持 Agent Skills 的工具，希望審查步驟可重複、可共享

使用時要注意

1. 依賴 gh 和 GitHub 遠程。 官方取 diff 的命令寫死了 gh repo view。沒裝 gh、未登錄、或倉庫不在 GitHub 上時，這條命令會失敗；需要先解決環境，或明確告訴 Agent 默認分支名稱。
2. 範圍是「本分支相對默認分支」，不是整個倉庫。 它不會替代全量安全審計，也掃不到你沒改、但被這次改動間接觸達的舊代碼——階段 4 只要求讀周圍上下文做覈實，並不是全庫掃描。
3. 只報告、不修改。 原文最後一句是：不要改代碼，由你決定修哪些。若需要順手修，應另開一輪對話或改用別的工作流，避免和這份 Skill 的職責衝突。
4. 質量不等於風格。 官方明確跳過 stylistic / formatting。想查命名和空格，不該用它。
5. 假陽性仍可能出現，但流程在壓它。 階段 4 要求覈對「是否已處理、是否有測試、上下文是否坐實」。即便如此，Agent 仍可能誤判框架默認防護（例如模板自動轉義、ORM 參數化）。同倉庫的 security-review 在這一點上更嚴：只報高置信、攻擊者可控輸入已確認的問題。需要更強安全專項時，可以在 find-bugs 之後再跑 security-review。
6. 沒有測試套件或評測集。 當前目錄只有 SKILL.md。效果取決於模型是否嚴格執行五階段，尤其是「diff 被截斷時必須讀完每個文件」和「收口前必須列出清單覆蓋情況」。

小結¶

find-bugs 把 Sentry 團隊自己在用的「分支級審查」寫成一份可移植的 Skill：完整 diff → 攻擊面 → 11 項安全清單 → 覈實 → 收口審計，再按「安全 > 缺陷 > 質量」輸出帶證據的報告。它不替代專業滲透測試，也不自動改代碼，但能把「讓 AI 隨便看看」收成一條可重複執行的預提交掃描。

官方地址：
https://github.com/getsentry/skills/tree/main/skills/find-bugs