迭代改版不炸掉:需求描述術與 CLAUDE.md

上一課你的網站正式上線了,恭喜。但真實故事通常是這樣接下去的:你看著上線的網站,想說「順便把導覽列改一下好了」,於是跟 AI 說「幫我把導覽列弄好看一點,順便加個深色模式,About 頁也重寫一下」。五分鐘後,導覽列是變了,但首頁排版整個歪掉、深色模式只有一半的字看得到、About 頁被改成一種你根本沒要求的風格——而且你不知道怎麼退回去。

這不是 AI 太笨,是改法不對。網站做出來只是起點,之後 90% 的時間你都在「改」:加功能、調樣式、修 bug。這堂課要教的就是改東西的正確姿勢,讓你每次迭代都改得動、退得回、不炸掉。

這堂課適合誰適合:已經用 Claude Code 做出網站、想繼續加功能改樣式的人。需要基礎:零程式基礎 OK,但要會用電腦與終端機(第 3 課教過)。前置課:第 3 課(Claude Code 建站)、第 4 課(GitHub + Vercel 部署)。本課程屬進階應用專區。

這堂學什麼

需求描述術:一次一件事、把驗收條件講在前面,讓 AI 一次改對
CLAUDE.md:把專案規則寫成「班規」,AI 每次對話自動記住,不用重複交代
git 當後悔藥:三種退回法,改壞 3 秒復活
實戰:加深色模式、加一頁作品集,完整走一遍安全迭代流程
何時該開新對話:4 個訊號,以及 /clear 和 /compact 怎麼選

觀念一:安全迭代循環——一次只改一件事

改版會炸掉,九成是因為「一次要求太多件事」。AI 同時改 A、B、C 三個地方,只要其中一個改壞,你就分不出是哪個改動害的,也沒辦法只退回壞的那個。

正確的節奏是一個循環:講清楚一件事 → AI 改 → 你驗證 → 通過就 git commit 存檔、壞掉就退回重講。每繞完一圈都留下一個存檔點,永遠退得回去。

安全迭代循環:講清楚 → AI 改 → 驗證 → commit 或退回

「一件事」的大小怎麼抓?一個判斷標準:你能不能用一句話講完驗收條件。「加深色模式切換鈕」是一件事;「把網站改好看」不是,那是十件事糊在一起。

觀念二:需求描述術——驗收條件講在前面

同一個需求,講法不同,結果天差地遠。對照看:

需求描述對照表:模糊講法 vs 講清楚,以及好需求公式

好需求的公式是四個要素:改哪裡 + 改成什麼樣 + 驗收條件 + 不准動什麼。其中最容易被漏掉、也最值錢的是後兩個:

驗收條件:你怎麼判斷「改好了」?寫出來,AI 就會朝著這個目標做,你驗證時也有清單可以逐條打勾,而不是憑感覺「好像可以了」。
不准動什麼:AI 有「順手優化」的壞習慣,你叫它改按鈕,它可能順便重構整個檔案。明講「其他地方不要動」,可以擋掉大部分災難。

還有一個進階招:大一點的改動,先要計畫再動手:

我想加一個作品集頁面。先不要動手改任何檔案,
先告訴我:你會新增或修改哪些檔案、大概怎麼做。

AI 列出計畫後你先看方向對不對,對了再說「照這個計畫做」。方向錯在計畫階段就攔下來,成本是零;等它改完才發現方向錯,成本是整段重來。

觀念三:CLAUDE.md——把班規寫下來,AI 才記得住

你可能已經發現:每次開新對話,AI 就忘記你交代過的事。「用台灣繁中」「不要動 package.json」這種規則,講十次它忘十次——因為對話結束,記憶就歸零。

解法是 CLAUDE.md:放在專案根目錄的一個文字檔,Claude Code 每次開新對話都會自動先讀它。規則寫進去,就等於刻在 AI 腦子裡。

CLAUDE.md 架構:放專案根目錄、每次對話自動載入、內容範例

建立方式:在專案資料夾裡進 Claude Code,輸入 /init,它會掃描專案自動生成一份初稿。接著你手動補上自己的規則。一份適合本課程專案的 CLAUDE.md 長這樣:

# 專案簡介
個人品牌網站,Next.js + Tailwind CSS,部署在 Vercel。

# 風格規則
- 主色 #4a90d9,圓角統一 12px
- 所有文案用台灣繁體中文
- 新增元件放在 components/ 資料夾

# 不准動的檔案
- 沒有我明確同意,不要修改 package.json
- 不要碰 .env 和 /public/photos 裡的任何東西

# 工作習慣
- 大改動前先列出計畫,等我確認再動手
- 一次只做一件事,做完提醒我 git commit

逐段講:「專案簡介」讓 AI 秒懂技術棧,不會用錯框架的寫法;「風格規則」保證改十次網站,顏色圓角都一致;「不准動的檔案」是保命條款——.env 裡有機密(第 6 課細講),package.json 亂動會讓整個專案跑不起來;「工作習慣」把這堂課的迭代紀律直接變成 AI 的預設行為。

另外一個隨手技:對話中發現想加規則,直接輸入 # 開頭的訊息(例如 # 以後 commit 訊息用中文寫),Claude Code 會問你要存到哪份記憶檔,選專案的 CLAUDE.md 即可。

短而狠,一頁以內 CLAUDE.md 只寫「每次都適用」的規則。寫成三千字論文,重點會被稀釋,AI 反而開始漏看。一條規則如果只有這次用得到,放進當次的 prompt 就好,別進班規。

觀念四:git 是你的後悔藥

第 4 課你已經用過 git 推上 GitHub,這課把它變成你的時光機。核心觀念只有一句:commit 過的東西幾乎不可能弄丟,沒 commit 的東西隨時可能蒸發。所以每完成並驗證一件事,馬上:

git add -A
git commit -m "加深色模式切換"

改壞了怎麼退?依「壞掉的改動 commit 了沒」選藥:

Git 三帖後悔藥:git restore、git revert、git reset --hard 的適用時機

# 藥 1:AI 剛改壞、還沒 commit(90% 的情況用這帖)
git restore .

# 藥 2:已經 commit 甚至 push 了,想安全地反悔
git revert HEAD

# 藥 3:確定最近這個 commit 整個不要了(危險,會蒸發未 commit 的東西)
git reset --hard HEAD~1

git restore . 把所有未 commit 的修改清空,回到最近一次存檔——AI 改壞的當下用它,3 秒復活。git revert HEAD 不刪歷史,而是長出一個「把上一個 commit 反過來」的新 commit,已經 push 上線的網站用這帖最安全,Vercel 會自動重新部署成退回後的版本。git reset --hard 則是直接把歷史砍掉一截,威力最大也最危險,新手記得:下這行之前,先確認沒有還沒 commit 的心血。

懶得背指令?這些操作你也可以直接叫 Claude Code 做:「把還沒 commit 的修改全部丟掉」「退回上一個 commit」,它會下對指令。但你要看得懂它在做什麼,才不會被一個 reset --hard 帶走。

手把手實戰:加深色模式 + 加作品集頁

用第 3、4 課做好的個人品牌網站,實際走兩圈迭代循環。先確認起點乾淨:git status 顯示 nothing to commit, working tree clean 再開始。

建立 CLAUDE.md

在專案資料夾開 Claude Code,輸入 /init 生成初稿,再把上面範例的「不准動的檔案」「工作習慣」兩段補進去。存檔後 commit:git add -A && git commit -m "加入 CLAUDE.md 專案規則"

第一件事:深色模式——先要計畫

貼這段:

我要加深色模式。先不要動手,告訴我你會改哪些檔案、怎麼做。驗收條件:1. 導覽列右上角有太陽/月亮切換按鈕 2. 重新整理後記住上次的選擇 3. 深色模式下所有文字都清楚可讀。

看計畫、放行、驗證

它會列出計畫(通常是 Tailwind 的 dark mode + localStorage 記錄偏好)。方向對就回「照計畫做,改完自己跑 npm run dev 確認能編譯」。跑起來後,你親手做三件事:點按鈕切換、重新整理看有沒有記住、把每一頁都切到深色檢查文字。三條驗收全過才算過。

存檔

git add -A && git commit -m "加深色模式切換"。這圈結束,存檔點+1。

第二件事:作品集頁——開新對話

深色模式是做完的一件事,換任務就換對話:輸入 /clear。然後:

新增一頁 /works 作品集。驗收條件:1. 導覽列多一個「作品集」連結 2. 頁面用卡片呈現 3 個作品,每張卡有標題、一句介紹、連結 3. 手機版卡片直向排列 4. 深色模式下也正常顯示。作品資料先用假資料,寫成一個陣列方便我以後自己改。

驗證、存檔、上線

電腦版和手機版(瀏覽器開發者工具切手機尺寸)都檢查過、深淺兩種模式都看過,就 commit 並推上線:git push,Vercel 幾十秒後自動部署完成。用第 4 課的網址開給朋友看吧。

注意第 5 步的細節:「寫成一個陣列方便我以後自己改」——這種一句話的小要求,會讓你之後改作品內容時完全不用求 AI,直接編輯那個陣列就好。需求描述術的紅利就是這樣一點一點累積的。

何時該開新對話

對話不是越長越好。AI 的記憶(context)有限,對話太長,早期的指示會被擠掉,而且錯誤的嘗試也留在脈絡裡,會把它越帶越歪。

該開新對話的 4 個訊號,以及 /clear 與 /compact 的差別

四個訊號:換任務了、AI 開始忘記你講過的規則、同一個 bug 鬼打牆修 3 次、回應開始變慢跳針。出現任何一個,就用 /clear 清空重來;如果事情做到一半、前面的脈絡還需要,用 /compact 讓它先把對話壓縮成摘要再繼續。

很多人捨不得開新對話,怕「AI 忘記一切」。現在你知道不用怕了:規則在 CLAUDE.md、進度在 git commit,這兩樣都不會跟著對話消失。對話是免洗的,檔案才是記憶。

常見坑

坑 1:一次餵一大串需求,炸了才來拆

症狀:網站直接白畫面,終端機或瀏覽器噴出類似這樣的錯:

Error: Hydration failed because the initial UI does not match
what was rendered on the server.

這類錯誤常在深色模式這種「跟瀏覽器狀態有關」的功能一次混著其他改動時出現。解法:git restore . 全部退掉,回到迭代循環,一次只做一件事重來。單獨做深色模式還遇到這個錯的話,把錯誤訊息整段貼給 AI 並要求「先解釋原因再修」,它就能正確處理(通常是要等頁面載入後才讀取主題設定)。

坑 2:reset --hard 下手太快,心血蒸發

症狀:想退回上個 commit,順手 git reset --hard HEAD~1,結果連同今天下午還沒 commit 的三小時修改一起消失,而且 git log 裡完全找不到。預防勝於治療:下 reset --hard 前先跑 git status,看到任何 modified: 的紅字就先 commit 或先 git stash(暫存)。真的誤砍了 commit 過的東西,還有最後一線生機:git reflog 可以列出所有歷史動作,找到編號後 git reset --hard 那個編號 救回;但沒 commit 過的,神仙難救。

坑 3:在錯的資料夾下 git 指令

症狀:

fatal: not a git repository (or any of the parent directories): .git

意思是你目前所在的資料夾不是 git 專案——通常是終端機開在家目錄,忘了先 cd 進專案資料夾。跑 cd 你的專案路徑 再試一次即可。反過來的坑也有:在專案 A 的終端機貼了要給專案 B 的指令,commit 進錯專案。習慣動作:下任何 git 指令前瞄一眼終端機提示的目前路徑。

坑 4:CLAUDE.md 寫了,AI 還是不理

症狀:明明班規寫了「不要動 package.json」,它還是動了。三個檢查點:一、檔名必須是 CLAUDE.md(大寫),放在專案根目錄,不是子資料夾;二、規則是不是淹沒在三千字裡?砍到一頁以內,重要的條目用「絕對不要」「一律」這種強字眼;三、對話是不是已經很長了?太長的對話連 CLAUDE.md 的規則都會被擠出記憶——這正是該 /clear 的訊號。改完 CLAUDE.md 要開新對話才會生效,舊對話讀的是舊版。

作業

給你的專案建立 CLAUDE.md,至少包含「風格規則」「不准動的檔案」「工作習慣」三段,commit 起來
完成深色模式 + 作品集頁兩個迭代,每個都要:驗收條件寫在 prompt 裡、驗證通過才 commit
演習一次後悔藥:隨便叫 AI 改個東西,然後不 commit,用 git restore . 退回,確認網站回到原樣
進階挑戰:作品集頁再迭代一圈,把假資料換成你的真實作品(記得,只改那個陣列)

下一課預告

你的網站現在會迭代、能進化了。但有件事必須現在說:AI 生成的程式碼,預設是不安全的。API 金鑰直接寫在程式碼裡、表單沒有防護、資料庫權限全開——這些 AI 都可能默默幫你埋好,而你的網站已經公開在網路上。下一課「AI 生成程式的資安坑:你的網站正在裸奔嗎」,帶你看懂 vibe coding 最容易中招的資安地雷,先知道刀從哪裡來,第 7 課再教你怎麼擋。