query-inspector：Claude Code 技能，在程式碼提交前診斷與優化 SQL/ORM 查詢

query-inspector 是一個 Claude Code 技能，能從專案原始碼中提取 SQL/ORM 查詢，並診斷及優化遺漏索引、N+1 問題和反模式。它能揪出那些在資料量變大後才出問題的查詢，以及程式碼審查時被忽略的 N+1 問題。它還能揭露 ORM 實際生成的 SQL 語法，這些在程式碼中通常是隱形的。所有這些問題都能在程式碼提交前被發現，而非等到上線後才浮現。

常見的陷阱包括，一個沒有索引的查詢在資料量達到數萬筆時，會突然變成全表掃描。N+1 問題可能在程式碼審查中被忽略，導致一個列表 API 觸發數十次查詢。僅憑程式碼本身，很難判斷 JPA 或 QueryDSL 實際會生成什麼樣的 SQL 語法。

程式碼審查通常側重邏輯，而非從 SQL 角度審視「這次變更會產生哪些查詢」。品質保證（QA）也很少能發現這些問題，因為測試資料量太小，不足以讓遺漏索引或 N+1 問題導致的效能遲緩浮現。這些問題都有一個共同點：它們只會在程式碼上線後才顯現。query-inspector 將發現問題的時機提前到程式碼提交之前。

總覽：這是一個 Claude Code 外掛程式，由兩個技能組成：tuning-report 會提取你 git 變更中的 SQL/ORM 查詢，診斷遺漏索引、N+1 問題和反模式，並產生一份包含可立即套用修復建議的報告。inventory-report 則會編目專案執行的所有查詢，包含完整的查詢內容和索引覆蓋率。

這兩個技能都不會修改你的程式碼，它們只會產生報告。在提交程式碼前執行它，就能發現那些否則只會在程式碼上線後才出現的效能問題。

亮點：過去已有檢查查詢效能的方法，例如執行時的 SQL 日誌（如 p6spy、Hibernate statistics）或應用程式效能管理（APM）工具。然而，這些方法都只能在查詢執行後才發現問題。query-inspector 則是在任何程式碼執行前，針對你即將提交的變更進行檢查。

在不執行 ORM 的情況下推斷它將生成的 SQL，這種方法只有在近期 AI 技術進步後才變得實用。它只分析你上次優化後所做的變更，而非每次都掃描整個專案。這使得它執行快速，並能自然地融入你日常的 git add -> 執行 query-inspector -> commit 工作流程。

當然，它也支援對整個專案進行掃描。程式碼未直接揭露的 SQL：明確的 SQL 語法會直接採用，而對於 JPA 衍生方法、@Query、QueryDSL、Kotlin JDSL 和 MyBatis 動態查詢，它會推斷實際生成的 SQL，然後進行分析或編目。

每個查詢都會帶有 EXACT（精確）、INFERRED（推斷）或 AMBIGUOUS（模糊）的信心標籤，讓你了解每個查詢的可靠程度。從靜態分析到即時 EXPLAIN，深度隨你選擇：即使沒有資料庫，它也能發現大多數問題（遺漏索引、N+1 問題、SQL 方言不匹配、反模式）。

只有當你需要更高的確定性時，它才會連接到你的開發資料庫並執行真正的 EXPLAIN。為了安全起見，預設會阻止連接生產環境主機，且只執行唯讀查詢。

可立即執行的報告：它不只停留在「這可能很慢」的層面。你會獲得一個包含正確欄位順序的 CREATE INDEX 語句、精確的檔案與行號，以及可直接複製使用的「行動項目」。開發人員，或協助開發人員的 AI，可以閱讀報告並立即開始修復。追蹤過往建議：它會將上次執行的建議與你目前的程式碼進行比較，並標示出尚未套用的項目。

即使是本次執行中未修改的檔案，也會納入檢查範圍。JVM 優先的技術棧，在地化報告：目前版本主要支援 Kotlin/Java（JPA、Hibernate、QueryDSL、MyBatis、原生 SQL）。Python（Django/SQLAlchemy）也受支援，但驗證程度不如主要技術棧。

未來計畫支援更多技術棧。SQL 方言（MySQL/MariaDB、PostgreSQL）會自動偵測。報告會以你與 Claude 聊天時使用的語言輸出（你也可以強制指定特定語言）。

報告範例：以下是 tuning-report 掃描你的變更後產生的一部分內容：# Query Tuning Report - incremental (2 changed files) - Severity (open): 🔴 3 / 🟡 2 / ⚪ 1 / Follow-up: ✅ 2 resolved / ⚠️ 2 still open ## 🔴 [critical] Missing index - FK orders.user_id - OrderMapper.xml - Why critical: it is the N+1 child query, so every user triggers a full scan of orders . - Suggestion: CREATE INDEX idx_orders_user_id ON orders (user_id); - Verify (live EXPLAIN): type: ALL -> ref。

將同一個專案指向 inventory-report，它會列出查詢目錄而非優化建議：# Query Inventory - Queries: 24 ( SELECT 18 / INSERT 3 / UPDATE 2 / DELETE 1 ) #### [order-03] Orders for a given user - Source: OrderMapper.xml:42 (selectOrdersByUser) / Type: SELECT - Target: orders / Access columns: WHERE user_id, ORDER BY created_at - Index coverage: ❌ uncovered (no index on user_id)。

使用 tuning report 找出需要修復的問題，並使用 inventory 查看所有執行的查詢。

開始使用：安裝和使用說明請參閱 GitHub README：github.com/jogakdal/query-inspector。如果你有 Claude Code，可以使用以下兩個指令安裝它：claude plugin marketplace add jogakdal/query-inspector 和 claude plugin install query-inspector@query-inspector-marketplace。

想先看看輸出結果嗎？請瀏覽儲存庫中的範例報告和 Docker 範例。目前仍是 v1.0.0 版本。試用後，請透過 GitHub issues 提交回饋，這將有助於下一個版本的改進；如果你覺得它有用，也歡迎給予星號。在下次提交程式碼前，就執行它吧。