AI agent 實際只用 query/use/schema——高階指令的定位討論

[CarlLee1983]

一份使用數據

我在一個 Laravel 專案（遊戲平台整合，MySQL/MariaDB 多站台 + MongoDB raw log）用 Claude Code 搭 dbcli 做開發與問題排查。翻了該專案的完整 session 記錄，dbcli 共被呼叫 249 次。按子指令拆開：

子指令	次數
query	絕大多數
use / --use（切連線）	~60
schema	~15
list	~5
blacklist list	3
status / doctor	~3

而以下指令，一次都沒有被用到：

guide、inspect、report、recovery、recover、explain、lint、check、diff、plan、q、queries、audit、migrate、shell、export

我想討論的問題

這不是「那些指令不好」的意思——我沒用過，沒資格評價。我想提出的是一個關於指令面寬度的觀察，因為它會影響往後投資該放哪。

AI agent 的真實動線非常窄，而且高度收斂：

use（切到目標連線） → list / schema（確認表結構） → query（反覆查） → query → query …

會這樣是有原因的。agent 的每個決策點都是「下一個 tool call 打什麼」，而 query 是萬能的——只要我知道 schema，任何診斷都可以用 SQL 表達。要讓我改用 report 或 check，得先讓我相信它產出的東西比我自己寫的 SQL 更好，而我在決策當下沒有便宜的方法驗證這件事。所以預設就是回到 query。

換句話說：與 query 功能重疊的高階指令，對 agent 幾乎沒有吸引力，除非它被放進動線的必經之路上。

幾個可能的方向（我沒有定見）

A. 把高階指令接到失敗路徑上。 recovery 是最好的例子——它解的問題是真的（查詢失敗後怎麼辦），但沒有人會主動想到要用它。如果 query 失敗時的錯誤訊息直接印出「執行 dbcli recovery <code> 取得修復步驟」，甚至把 recovery envelope 直接附在錯誤輸出裡，它就進動線了。同理 doctor 之於連線失敗。

B. 承認並收窄。 如果 agent 場景是主要目標，那麼把力氣集中在 query / schema / use 這三件事的深度上（投影、截斷、多連線、輸出可靠性——我另外開了幾個 issue），可能比維護 16 個指令的廣度回報更高。指令多也有成本：--help 更長、SKILL.md 更難寫、agent 選擇困難。

C. 這些指令的目標使用者本來就是人不是 agent。 完全合理的答案。shell（互動式）、--ui（瀏覽器儀表板）明顯就是給人用的。如果 report / guide 也屬於這類，那我的數據不構成任何問題——只是需要在文件上把「人用」和「agent 用」分開標示，這樣寫 SKILL.md 的時候我就不會試圖把它們塞進 agent 動線。

一個可驗證的判準

若要判斷某個高階指令對 agent 有沒有價值，我覺得問題是：

有沒有一個具體情境，是 agent 用 query 做不到、或要多花三次以上 tool call 才做得到的？

• report（容量/效能診斷）：可能真的有——那些查詢我未必寫得出來
• guide：不確定，我通常已經知道下一步要做什麼
• explain / lint：偏優化場景，我的用途是排查資料不是調效能，所以我碰不到

如果答案是「有」，那問題就變成發現性（方向 A）；如果答案是「沒有」，那才是取捨問題（方向 B）。

補充

這份數據只來自一個專案、一種使用型態（資料排查與對帳，不是 schema 演進、不是效能調校）。單一樣本，不該過度推論——migrate / diff 沒被用到，很可能只是因為這個專案的 schema 由 Laravel migration 管，本來就不會走 dbcli。

丟出來主要是想知道：其他使用情境下，那些指令的實際使用率如何？