系列：從現場踩坑到 AI 工具 — IT Diagnostic Agent 開發實錄

先說清楚我是誰

前面二十天講了很多技術細節：Adapter Pattern、CSS 變數、i18n、混合內容政策、八個維度的 API 差異。

看起來像一個前端工程師寫的東西。

但我不是。

我是 IT 基礎建設工程師。二十年來我的工作是網路、伺服器、AD、機房、廠區佈線。我會寫腳本、看得懂程式碼、能改設定檔——但我不是一個每天寫應用程式的人。

那這個三千兩百行的單檔工具是怎麼來的？

這一章就是回答這個問題。而 Anthropic 有一個數字剛好可以當開場：他們說 Claude 的使用情境裡，軟體開發只佔三成多，另外六成多是各行各業的跨界應用。

我就是那六成多裡的一個樣本。

我的環境

• 機器：ASUS ROG 筆電，Windows
• 位置：柬埔寨
• 工具：Claude Code CLI + GSD agent，都裝在 D:\AI\it-diagnostic-agent

GSD（get-shit-done）是一個把開發任務拆成階段、逐步執行並驗證的 agent。它會先讀專案、產出規劃文件、然後分階段實作。

GSD 的設定，以及每個選擇的理由

第一次跑 GSD 時，它會問一連串設定問題。這些選擇後來證明比我想像的重要，所以完整記錄下來：

兩個 Verify 都開 = Yes，是我最不後悔的決定。

因為 AI 說「完成了」和「真的完成了」之間有距離，而這個距離在沒有自動化測試的專案裡，只能靠強制驗證步驟來填。

GSD 做的第一件事：畫出這個專案的地圖

它沒有直接開始寫程式，而是先產出了一份 codebase map——7 個檔案、1185 行：

STACK.md          技術棧
INTEGRATIONS.md   外部整合（就是那四個 LLM adapter）
ARCHITECTURE.md   架構
STRUCTURE.md      檔案結構
CONVENTIONS.md    程式碼慣例
TESTING.md        測試現況
CONCERNS.md       已知風險

我第一個反應是：這 1185 行的文件，是在描述我自己寫的東西。

而讀完之後我發現，有些東西是我做了但沒有意識到自己在做的。比如 CONVENTIONS.md 裡記下了「inline styles only，不新增 CSS class」——這是我在某次對話裡隨口提的限制，它變成了正式的專案慣例。

這是 AI 協作一個沒被講夠的價值：它會把你的隱性慣例變成顯性文件。

而 CONCERNS.md 裡那條「沒有自動化測試」，後來直接影響了一個關鍵決策。

三個 Phase

Phase 1 — JSON Export

把診斷內容匯出成 JSON。完成，commit。

Phase 2 — JSON Import

把 JSON 匯入回工具。完成，commit。
（這個 Phase 留下了一個很值得寫的故事，就是明天 Day 22 的主題。）

Phase 3 — 表單式編輯器

這是最大的一個，分成 4 個 waves 執行。交付的東西：

• Topbar 的編輯器切換鈕
• 左側編輯器 + 右側即時預覽的版面
• GUIDES 步驟編輯器（新增 / 刪除 / 排序，含下拉選單的路由防呆）
• 節點卡片文字編輯（標題 / 副標 / 步驟清單，用 textarea）
• 每一次按鍵都即時更新預覽，並跟隨當前語言設定
• 自動存到 localStorage 的 it_import_data（跟匯入功能同一個 key）
• Reset to Defaults 按鈕
• 可以直接從編輯器匯出

那個「同一個 key」的細節值得說：編輯器和匯入器共用 it_import_data。這代表你匯入一份 JSON，編輯器打開就看得到；你在編輯器改完，匯出的就是改過的版本。兩個功能不需要互相知道對方存在，靠一個共用的儲存 key 就串起來了。

Phase 3 最重要的決定：不重寫靜態樹的 HTML

這是整章我最想寫的一個決策。

Phase 3 原本可以做得更徹底：把所有節點卡片都變成動態生成，那樣編輯器就能完全控制每一張卡片。

我沒有做。

原因是 CONCERNS.md 裡那條：這個專案沒有自動化測試。

而重寫靜態樹卡片的 HTML，是大約 200 行的改動。200 行、沒有測試、動的是使用者最常走的主要路徑。

如果改壞了，我不會立刻知道。我會在某個使用者回報「某個節點點下去空白」的時候才知道。

所以最後的範圍是一個混合方案：

能改文字，不能改結構。

這個決定讓編輯器的能力有明顯的天花板。但它把迴歸風險壓到接近零。

在一個沒有測試網的專案裡，我選擇不走鋼索。

我的實際工作方式：貼截圖，問要選哪個

講到這裡要誠實交代我在這個流程裡真正在做什麼。

GSD 是 Interactive 模式，所以它會不斷停下來問我問題：這個階段要不要繼續？這個選項選 A 還是 B？這個改動範圍要多大？

而我的做法是：把 GSD 的提問截圖，貼給 Claude，問它我該選哪一個、為什麼。

然後根據 Claude 給的理由，我做決定。

所以實際的迴路是三層：

GSD 提問
   ↓
我截圖 → Claude 分析選項與風險 → 給建議與理由
   ↓
我判斷（有時採納，有時不採納）
   ↓
回答 GSD
   ↓
GSD 執行

我在這個迴路裡的位置是決策者，不是實作者。 而我做決策的依據，是二十年的現場經驗告訴我「哪種壞法我承受不起」。

比如上面那個 200 行的決定：Claude 可以分析技術風險，但「使用者在柬埔寨工廠現場點開一個空白節點」的代價有多大——那個判斷是我的。

一個到現在還沒解決的問題

誠實記錄一下：GSD 在我的 Windows 環境上，bash hook 一直報錯。

cannot execute binary file

我查過了：所有 .sh 檔都確認是 LF 換行、UTF-8 編碼，手動執行完全正常。

但 GSD 呼叫它們的時候就是報這個錯。

我最後的處理是：判定為非阻斷性，忽略它。

因為它不影響任何實際功能——每個 Phase 都正常完成、正常 commit。它只是每次執行都吐一行紅字。

這個決定在 IT 圈有個說法叫「已知問題，可接受風險」。做維運的人都懂：不是每個錯誤訊息都值得你花一天去追。 判斷哪些能忍、哪些不能忍，本身就是專業的一部分。

（如果有人知道這個錯誤的原因，歡迎告訴我。但我不會為了它停下開發。）

結構化地看這個流程

可控 vs 不可控

兩個 Verify 開 Yes，就是把「不可控的實作」接到「可控的驗證」上。

核心 vs 外部

核心是「工具不能壞」。實作誰做的、用什麼 agent、幾個 phase，全部是外部細節。

所以每次 GSD 的 Recommended 選項跟「不破壞既有功能」衝突時，我都選保守的那個。AI 推薦的選項，不等於我的正確選項。

這條原則後來變成一整組決策準則，那是 Day 23 的主題。

今天的反思

我一直以為「不會寫程式」是我做工具的障礙。

實際做下來，障礙不在那裡。障礙在知道什麼該做、什麼不該做、什麼壞了會出人命。

前者現在可以外包。後者不行。

而諷刺的是，我二十年來累積的正好是後者。

明天預告： Phase 2 那個 JSON Import 功能，留下了整個系列裡我最喜歡的一個故事。起因只是「這個按鈕的顏色我看不出差別」，最後查出來的東西，讓我對 AI agent 協作的認知整個換了一層。而且過程中 Claude 錯了兩次。

作者：Rich Chang | IT 基礎建設工程師 | 越南・柬埔寨・台灣