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

工具預設就是深色的

IT Diagnostic Agent 從第一版開始，預設介面就是深色（dark mode）。

沒有特別的原因，就是我個人偏好。深色對眼睛比較友善，特別是在伺服器機房或昏暗的機房環境工作的時候。

所以一開始根本沒有「主題切換」這件事，就是一套深色樣式走天下。

朋友：「可以加淺色模式嗎？」

某天一個朋友試用之後說：「深色看起來很酷，但我在辦公室用，白天螢幕反光，淺色比較好看。」

需求合理。我決定加淺色模式，並加上一個切換按鈕。

我的做法：丟給 Claude

說實話，我沒有自己動手寫 CSS。

我把當時的 index.html 完整貼給 Claude，說：「幫我加一個深色/淺色模式切換，預設深色，加一個 toggle 按鈕。」

Claude 很快就給了一版：用 CSS Custom Properties（CSS 變數）管理顏色，切換時改 data-theme 屬性。

架構上是對的。程式碼跑起來也沒報錯。

問題：切到淺色，文字全部消失了

朋友切換到淺色模式之後，傳來一張截圖。

介面是白的。按鈕是白的。文字……也是白的。

整個畫面幾乎是一片白，什麼都看不到。

發生了什麼事

問題的原因很典型：

Claude 幫我定義深色和淺色的 CSS 變數時，深色那組是完整的，但淺色那組有幾個文字顏色的變數沒有覆蓋到，沿用了深色的值：

:root {
  /* 預設：深色 */
  --bg-primary: #1a1a2e;
  --text-primary: #e0e0e0;   /* 淺色文字 */
  --button-text: #ffffff;
}

[data-theme="light"] {
  --bg-primary: #ffffff;    /* 背景改白了 */
  /* --text-primary 沒有覆蓋！繼承了深色的 #e0e0e0 */
  /* 白底 + 淺灰文字 = 幾乎看不見 */
}

白色背景 + 淺灰色文字 = 文字消失。

這不是 Claude 寫錯，是 prompt 沒有說清楚「淺色模式要有完整的顏色定義」，Claude 只改了它認為需要改的部分。

修法：補齊淺色模式的所有顏色變數

我把截圖傳給 Claude，說：「淺色模式文字都不見了，你看一下哪裡的顏色變數沒設好。」

Claude 對照了一遍，補齊了淺色模式裡所有缺漏的變數：

[data-theme="light"] {
  --bg-primary: #ffffff;
  --bg-secondary: #f5f5f5;
  --text-primary: #1a1a1a;      /* 深色文字，在白底上清楚可見 */
  --text-secondary: #555555;
  --border-color: #dddddd;
  --accent-color: #0055bb;
  --card-bg: #f5f5f5;
  --button-bg: #0055bb;
  --button-text: #ffffff;
  --shadow: rgba(0, 0, 0, 0.08);
}

修完之後正常了。

這個翻車的教訓

這次不是 Claude 能力的問題，是 AI 協作的 prompt 品質問題。

我說「幫我加淺色模式」，Claude 的理解是「在現有深色基礎上加一組覆蓋」，它只改了明顯需要改的背景色，沒有意識到所有文字顏色也要重新定義一遍。

比較好的 prompt 應該是：

「幫我加淺色模式。注意：所有的顏色變數（背景、文字、按鈕、border、陰影）在淺色主題下都要重新定義，不能繼承深色的值。」

說清楚你的「完成定義」，AI 才能交出你真正想要的結果。

一個協作流程的觀察

這個 bug 的修復過程，其實很能說明人 + AI 協作的現實樣貌：

1. 我提需求（加淺色模式）
2. Claude 實作，交出第一版
3. 朋友測試，發現 bug
4. 我把截圖和描述傳給 Claude
5. Claude 找到問題，修好
6. 正常了

這個循環不是「AI 出錯，很糟糕」，而是很正常的迭代流程。

重點不是 AI 一次就做對，而是回饋的速度夠快、修復的成本夠低。

明天預告： 工具上線後，朋友在手機上試用，傳來一張截圖——按鈕跑出畫面外了。然後這張截圖，一樣是轉發給 Claude 去處理的。

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