AI agent 老是在猜，可能是開發工具沒有把狀態說清楚
我最近看 coding agent 跑前端專案，最常卡住的地方往往很無聊。
它執行了 dev，終端機沒有退出，於是它不知道該繼續等，還是另開一個 session。第二次啟動時，連接埠已被占用。它接著讀一段有顏色、有動畫、有縮排的 log，從裡面猜網站是不是已經 ready。猜錯了，就先睡五秒再試一次。
這些動作看起來有點笨，所以我們很容易把問題歸到模型身上：推理不夠好、工具使用能力不夠強、應該再加一段 prompt。
但換成人來操作，我們其實也會想知道幾件很普通的事：程序有沒有啟動、網址在哪裡、現在是否可用、出了什麼錯、要怎麼停掉。差別只在於，人可以看懂終端機裡那些約定俗成的暗示，agent 需要比較明確的介面。
如果一個工具只能靠人類「看起來差不多好了」來判斷狀態，那麼 agent 一再猜錯，未必是 AI 的問題。也可能是 developer experience 還停在只替人眼設計的年代。
Dev server 也需要一個控制面
Astro 7 對 coding agent 的處理很值得看。它沒有停在一個 AI 標章，而是把 dev server 原本含糊的生命週期拆開來處理。
背景模式啟動後，命令會等到 server ready，再回傳網址與 PID。之後可以另外查 status、讀 logs、執行 stop，也有 health endpoint 可以直接確認服務狀態。重複啟動不會默默再養一份程序，而是回傳現有 instance；停止一個不存在的程序，也不必製造新的失敗噪音。
這些細節沒有哪一項很炫，但放在一起，agent 就不必靠 sleep 和重試拼出一套自己的控制流程。
更重要的是，這種設計沒有把 agent 擬人化。它沒有假設模型會像資深工程師一樣讀懂每一種 CLI 習慣，而是承認長時間程序本來就該有 identity、有 ready signal，也該能被查詢和停止。
我覺得這才是 agent-friendly DX 比較可靠的方向。模型當然還會進步，但工具不該把所有模糊之處都留給模型猜。那些原本只能意會的狀態，應該有能直接讀取的介面。
JSON log 不是給 AI 的特殊待遇
一提到 machine-readable output，很容易讓人覺得這是為 agent 增加的負擔。既有 CLI 已經能用了，為什麼還要維護 JSON 格式？
但人類其實也早就在承受純文字輸出的成本。
CI 需要從 log 判斷哪一步失敗，本機 script 需要從輸出抓網址，監控工具需要辨認 warning 和 error。只要輸出格式稍微改版，多一個顏色碼或換一行，黏在外面的 parser 就可能壞掉。Agent 只是讓這個老問題變得更明顯。
結構化 log 的價值，是讓事件、層級、時間和錯誤內容有穩定欄位。人仍然可以閱讀整理過的終端畫面，agent、CI 和其他工具則讀同一份底層狀態。兩邊不必各自發明一套真相。
這也會改變 review 的品質。Agent 若說「dev server 已正常啟動」，我們不必只相信它的摘要，可以回頭看 readiness check、程序 ID 和實際事件。錯誤發生時，也比較容易分清楚是 build 壞了、連接埠衝突，還是服務根本沒有啟動。
好的 observability 原本就該做到這些。Agent 只是在提醒我們，終端機文字從來不等於狀態本身。
文件開始進入執行環境
Runtime 之外，另一個正在改變的是文件。
過去我們會把文件想成一個網站：需要時搜尋、點進去、找到範例，再把資訊帶回專案。Agent 也可以這樣做，只是過程很不穩定。它可能找到舊版頁面、部落格裡過時的設定，或只讀到搜尋摘要，最後用一份看似合理但已經失效的範例改壞專案。
Vercel 最近把 Next.js、AI SDK、Functions 等平台知識包成可以裝進 VS Code 與 GitHub Copilot CLI 的 plugin。Plugin 只是形式。真正有意思的是，產品團隊開始處理一個以前常被丟給使用者的問題：agent 到底讀到哪一版 API，拿到哪些建議做法？
文件一旦能安裝、更新和版本化，它就不再只是網站內容，也成了開發環境的一部分。小團隊未必需要立刻做一套 plugin，但至少要知道哪份文件是 canonical、範例對應哪個版本、過時做法是否還會被搜尋到。否則 agent 取得 context 的速度越快，只會越快把錯誤帶進程式碼。
GitHub 的 repository overview 也有類似效果。Copilot 可以整理 repo 的用途、技術棧與 contribution rules，甚至在缺少 README 時先產生一份。這對第一次進專案的人很方便，但生成摘要不會修復來源矛盾。
如果 README 說用 npm，lockfile 卻是 pnpm；contribution guide 要求跑一組測試，package scripts 裡早已沒有那條命令；目錄名稱和文件對不上，overview 只會把混亂壓縮成一個更流暢的第一印象。
Agent-friendly repo 的基本功，仍然是讓文件、設定與實際結構彼此對得上。
小團隊先把五個地方說清楚
不是每個 CLI 都需要偵測 coding agent，也不是每個框架都該長出一整套 AI 子系統。工具為了追趕趨勢而不斷膨脹，最後維護成本還是會回到使用者身上。
如果資源有限，我會先檢查五件事：服務有沒有明確的 health check；錯誤能不能輸出成穩定欄位；成功與失敗是否真的反映在 exit code；背景程序能否查狀態並安全停止；文件裡的命令能不能在乾淨環境重現。
這份清單看起來不像 AI roadmap。它比較像一份普通的工程清理工作，而且多半早就該做了。
判斷一個 agent-friendly 功能值不值得加，我也會用同一個標準：介面是否夠窄，能否組合，非 AI 的 workflow 是否同樣受益。Health endpoint 可供 agent 使用，也能拿來做監控。JSON log 可被模型解析，也能進 CI。可查詢的背景程序能避免 agent 留下 zombie process，人類開發者同樣少踩幾次坑。
這些改善不需要把框架變成 agent 平台。它們只是把原本藏在經驗裡的操作方式，變成工具願意負責的契約。
少一點猜測，才是真正的下一代 DX
我們常把 developer experience 理解成更漂亮的錯誤訊息、更快的啟動速度，或更順手的 autocomplete。Coding agent 進入日常工作後，DX 又多了一個很實際的要求：專案正在發生什麼，必須能被可靠地讀出來。
這不代表所有介面都要優先服務機器。人仍然需要清楚的文字、好讀的文件和能理解的操作流程。只是底層不能再只剩「看終端機感覺一下」這種默契。
當程序可被識別、服務有 readiness、log 有結構、文件有版本、repo 規則彼此一致，人和 agent 才能看到同一個事實。Review 不必相信一段自信摘要，除錯也不必從猜測開始。
下一代 developer experience，未必需要更多 AI 功能。它首先需要少一點必須靠 AI 猜的地方。
Source notes
- Astro 7.0 (astro.build/blog/ast...)
- Vercel Plugin now available in VS Code and GitHub Copilot CLI (vercel.com/changelog...)
- Ask Copilot for a repository overview (github.blog/changelo...)
- Astro 7.0 Released: A Summary of What's New (www.reddit.com/r/ast...)