AI agent 正逐漸成為 CLI 的主要使用者，但「讓人用得順」與「讓 agent 做得對」並不是同一個問題。Human DX 重視可發現性與寬容；Agent DX 重視可預測性、機器可讀性與縱深防禦。這堂課不把 agent 當成更快的人類，而是從輸入、輸出、知識封裝與安全邊界重新設計 Skill／CLI。
mindmap
root(("Agent 能完美執行的 Skill"))
"要不要做 CLI"
"決策光譜"
"六項判準"
"反例"
"基礎概念"
"直譯 vs 編譯"
"單一 binary"
"錯誤時機"
"心智模型"
"Human DX"
"Agent DX"
"為什麼 Rust"
"強型別"
"單一 binary"
"七大設計原則"
"Raw JSON payload"
"Schema introspection"
"Context discipline"
"Input hardening"
"Agent skills"
"Multi-surface"
"Safety rails"
"四個案例"
"ecsctl"
"oabctl"
"octobroker"
"openab"
"Skill 三層模型"
"知識層 SKILL.md"
"工具層 CLI"
"防護層 Guardrails"
"實作檢查清單"
這張總圖要看的不是工具清單，而是層次關係：Rust 與七大原則支撐工具層，四個案例提供正反證據，Skill 三層模型則把知識、執行與防護整合成可驗收的整體。最後的檢查清單把心智模型轉成可落地的改造順序。
flowchart LR
C00["00 什麼樣的 Skill 需要 CLI"] --> C00B["00B 基礎概念<br/>非工程背景必讀、熟悉編譯者可跳過"]
C00B --> C01["01 心智模型總覽"]
C01 --> C02["02 為什麼是 Rust"]
C02 --> C03["03 七大設計原則"]
C03 --> C04["04 ecsctl"]
C03 --> C05["05 oabctl"]
C03 --> C06["06 octobroker"]
C03 --> C07["07 openab"]
C04 --> C08["08 抄作業對照表"]
C05 --> C08
C06 --> C08
C07 --> C08
C08 --> C09["09 Skill 設計指南"]
C09 --> C10["10 實作檢查清單"]
系列從第 00 章開始：先決定 Skill 到底要不要 CLI；接著第 00B 章用 Python／notebook 的日常經驗解釋直譯、編譯與單一 binary，非工程背景讀者必讀，已熟悉編譯語言者可跳過；第 01 章再建立 Human DX／Agent DX 心智模型。建議接著依序讀完 02–03 章；04–07 章可以依興趣並行閱讀，但進入第 08 章前應看完四個案例，才能理解比較矩陣中的「Present、Partial、Absent 與替代方案」並非評分，而是不同產品邊界下的取捨。
| 章節 | 一句話說明 | 主要 Mermaid 圖數 |
|---|---|---|
| 00 什麼樣的 Skill 需要 CLI | 先用介面光譜與六項判準決定要不要建 CLI。 | 5 |
| 00B 基礎概念：語言與編譯 | 非工程背景必讀；已熟悉編譯語言者可跳過。 | 5 |
| 01 心智模型總覽 | 分清 Human DX 與 Agent DX，建立 Skill 三層模型。 | 4 |
| 02 為什麼是 Rust | 用 codebase 證據理解 Rust 如何縮小 agent 的失敗面。 | 3 |
| 03 七大設計原則 | 深入 Poehnelt 的七項 agent-first CLI 原則。 | 8 |
| 04 案例：ecsctl | 觀察 preflight、快照與事後驗證如何形成安全網。 | 2 |
| 05 案例：oabctl | 從互動式確認看 Human DX 與 Agent DX 的衝突。 | 3 |
| 06 案例：octobroker | 研究 default-deny、MCP 與短命憑證的縱深防禦。 | 3 |
| 07 案例：openab | 看 AGENTS.md 與 docs-as-skills 如何構成知識層。 | 4 |
| 08 抄作業對照表 | 忠實比較四工具的落實、替代方案與缺口。 | 2 |
| 09 Skill 設計指南 | 把不變量、工具與對抗性審查寫成可執行 Skill。 | 4 |
| 10 實作檢查清單 | 以七個 gate 驗收 Agent-first CLI 改造。 | 2 |
| 來源與限制 | 集中列出來源、授權與研究限制。 | 0 |
本教材源自 Pahud Hsieh 推薦的功課：Justin Poehnelt 的文章 “You Need to Rewrite Your CLI for AI Agents”（2026-03-04）。Poehnelt 是 gws／Google Workspace CLI 原作者，文章發表時任職 Google；關於其後離職／裁員的細節屬媒體二手報導，本教材不把它當成技術論證。
教材也實際分析 oablab/ecsctl、openabdev/openab 與 openabdev/octobroker 三個公開 Rust repository，以及位於 openab operator/ 的獨立 crate oabctl。oablab/chi 在研究時回傳 404／Repository not found，推測可能為非公開或不存在，因此沒有把它當成可檢驗案例。另需注意：公開 GitHub API 無法直接證實 Pahud Hsieh 與 oablab／openabdev 的組織關係；完整限制見 SOURCES.md。
本教材引用之文章內容 © 2026 Justin Poehnelt，依 CC BY-SA 4.0 授權使用：https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/
程式碼案例僅依研究時取得的公開 repository 與檔案路徑說明；請以各專案自身授權條款為準。