Agent 友善的 CLI 設計正在成為開發者必須正視的課題。隨著大型語言模型日益成熟，許多開發者開始構建 Agent 優先的命令列工具，卻發現現有的人類導向 CLI 設計指南無法應對 Agent 的實際需求。本文提出七項原則，填補「技術可用」與「設計完善」之間的鴻溝。

設計背景與市場定位

作者在開發 Agent 友善 CLI 的過程中發現，現有的 CLI 設計資源（如《The Command Line Interface Guidelines》和《CLI-Anything》）完全以人類使用者為中心。這些資源未能解決的核心問題是：當 Agent 或技能衍生的子 Agent 在背景執行時，互動式 CLI 會完全失效。同時，彩色輸出浪費 token、無邊界的回應吞噬 context window，而人類優先的設計假設為 Agent 消費者製造了實際的故障模式。相比之下，Message Control Protocol（MCP）雖然存在，但在載入工具定義前就要消耗數千甚至數萬 token，而精心設計的 CLI 則更快、更便宜、更可靠。

嚴重程度分級機制

本文採用三層嚴重程度評估，而非簡單的通過/失敗判斷。Blocker 表示命令懸掛、需要人工干預，或產生 Agent 無法恢復的輸出。Friction 指 Agent 可使用但效率低下，導致更多重試、浪費 token、脆弱的解析、額外的工具呼叫。Optimization 代表 CLI 運作正常但可更快、更便宜或更可靠。評估時應根據命令類型進行差異化判斷，而非機械地套用所有原則。

原則一：預設非互動模式

任何 Agent 可能自動化的命令都不應有提示符。當子 Agent 衍生並執行 CLI 時，沒有機制將互動提示回傳給使用者，導致命令無限期掛起。即使在互動式 Agent 會話中，提示符也造成摩擦：額外的往返、模糊的選單導航、wasted token。

• 當 stdin 非 TTY 時，命令不應提示
• 支援 --no-input 或 --non-interactive 旗標
• 接受 --yes/--force 繞過確認
• 透過旗標、檔案或 stdin 接收結構化輸入

測試方法是簡單的：分離 stdin 並強制超時。命令懸掛是 Blocker，部分提示可繞過但行為不一致是 Friction，全面旗標覆蓋搭配全域非互動模式是 Optimization 目標。

原則二：結構化、可解析的輸出

Agent 需要資料契約，而非展示格式。精美對齊的表格配 ANSI 色彩對人類有用，對 Agent 試圖提取文章 ID 則毫無用處。若唯一輸出是散文或裝飾表格，Agent 必須自行從工具中抓取資料，這既脆弱又浪費資源。

• 在資料承載命令上支援 --json
• 成功使用 exit code 0，失敗使用非零代碼
• 結果資料寫入 stdout，診斷訊息寫入 stderr
• 當未連接至 TTY 時，抑制顏色、旋轉動畫和裝飾性輸出

許多 CLI 正確檢測 TTY 以處理提示，卻仍將 ANSI 逃脫碼寫入管道輸出。Agent 解析 \x1b[32m✓ Published\x1b[0m 正在燃燒 token 處理雜訊。完全缺乏結構化輸出是 Blocker，覆蓋不一致或混合 stdout/stderr 是 Friction，所有資料承載命令上的完整 --json 搭配清晰分隔是 Optimization 目標。

原則三：快速失敗搭配可行性錯誤

命令失敗時，錯誤應教導 Agent 如何在下一次嘗試中成功。「Error: missing required arguments」告訴 Agent 幾乎沒有資訊，而「Error: --content is required」則精確指出修正方向。

良好錯誤輸出應執行四項操作：命名具體問題、顯示正確的呼叫形狀、建議有效值、包含範例。獲得此類錯誤的 Agent 可在一次重試中自我修正，而獲得「missing required arguments」的 Agent 必須猜測，導致額外工具呼叫、浪費 token 和再次出錯的機會。

• 驗證側效應前的早期驗證
• 在錯誤輸出中包含正確語法
• 驗證失敗時建議有效值
• 偏好可行文字而非原始追蹤堆疊

模糊或無聲失敗是 Blocker，命名問題但不提供修復方法是 Friction，完整更正路徑是 Optimization 目標。

原則四：安全重試與明確的變更邊界

Agent 會重試、恢復和有時重播命令。應變命令應在可能時使其安全，危險變更應明確標示。這對 Agent 更重要，因為 Agent 更可能自動重試。人類執行命令兩次會發現重複，但在重試迴圈中操作的 Agent 則不會，除非 CLI 告訴它發生了什麼。

# 重複相同命令不會建立重複工作
$ blog-cli publish --content my-post.md
Already published "My Post" to personal, no changes (post_id: post_8k3m)

# 危險變更是明確的
$ blog-cli posts delete --slug my-post --confirm

目標並非到處嚴格冪等。對於建立/更新/部署命令，使重複應用成為無操作或清晰可檢測是高價值的。對於追加/傳送/觸發命令，完全冪等可能不可行，但 CLI 應至少明確變更邊界並返回識別符讓 Agent 判斷是否重複了工作。

• 提供 --dry-run 予重大變更
• 對危險操作使用明確破壞性旗標
• 在成功輸出中返回足夠狀態以驗證發生了什麼

重試靜默複製或破壞狀態的變更命令是 Blocker，可寫入破壞命令但預覽或狀態回饋有限是 Friction，安全重試搭配明確危險旗