從 0 建設個人網站
AI 寫的網站我看不懂,以後要怎麼改?2026 讓自己維護得動的做法
看不懂程式碼也能維護 AI 做的網站:改之前先存版本、把決定寫進說明檔、加功能前先寫規格、讓 AI 跑檢查才算完成,也說明什麼時候該重來。
Kelvin Wang · · 16 分鐘閱讀
重點整理
- 越修越壞多半是因為每次對話都從零開始、只修症狀,而且沒有東西能判斷「修好了沒」。
- 每次叫 AI 改之前先 commit,改完讀 diff;工具內建的復原功能可以用,但不能取代 git。
- 把做過的決定寫進 CLAUDE.md、AGENTS.md 或工具的專案規則,下一次對話才不會重新發明。
- 給 AI 一個會回報成功或失敗的檢查(建置、測試),並要它拿出指令和輸出當證據。
這個網站從 2026 年 6 月開始用 AI coding agent 寫,到 11 月有將近 700 個 commit,到現在還改得動:昨天加的功能沒有弄壞上個月的頁面,新開的對話也知道三個月前做過的決定。撐住這件事的是幾個習慣,跟會不會寫程式關係不大。下面每一條都附上這個 repo 實際怎麼做,用 Claude Code、Codex、Cursor、v0 或 Lovable 都適用。
為什麼 AI 寫的網站會越修越壞?
先看清楚是什麼在惡化,後面的做法才看得出在解決什麼。常見的原因有四個:
- 每次只修症狀。你說「按鈕跑版了」,AI 就在那個按鈕上加一段樣式。它不知道跑版的原因是三個頁面共用的版面設定,於是修好這裡、弄壞那裡,下一輪再補一段。補丁疊補丁,程式碼越來越難懂,連 AI 自己都開始讀錯。
- 對話結束,決定就消失。AI 工具每開一個新對話都從零開始。上週講好「顏色只用這三個」「資料表不要給訪客讀」,這週它不會記得,會照它看過最多次的做法重寫一遍。
- 沒有東西能判斷「修好了」。AI 改完說完成,你打開首頁看一眼,看起來沒問題就收下。壞掉的是你沒點進去的那一頁,要等幾天後才發現,那時已經分不清是哪一次改壞的。
- 沒有存檔點。改壞了想回到昨天的版本,卻發現昨天的版本根本沒存。只能繼續叫 AI 修,於是回到第一條。
這四件事都跟你看不看得懂程式碼無關,所以解法也不需要你先學會寫程式。
你不用看懂每一行程式碼,但要讓每一次修改都有存檔點、有紀錄、有檢查。
每次叫 AI 改之前,要先做什麼?
先存一個版本。git 是程式碼的存檔系統,每個 commit 就是一個可以隨時回去的存檔點。還沒裝 git 的話,先照 AI 寫程式前的準備 把 git 和 GitHub 裝好。
每次修改照這個順序做:
- 確認現在是乾淨的。在專案資料夾執行
git status,看到nothing to commit, working tree clean才開始。有沒存的修改,先 commit 掉。 - 一次只要一件事。「把文章列表改成兩欄」是一件事;「改兩欄、順便換字型、再修一下手機版」是三件事,混在一起改壞了就分不出是哪一件。
- 改完看 diff。執行
git diff(或在 VS Code、GitHub Desktop 的變更面板看),看它動了哪些檔案。看不懂內容沒關係,先看範圍:只要求改文章列表,它卻動了登入相關的檔案,就該停下來問為什麼。 - 結果對就 commit,不對就丟掉重來。對的話,先確認放金鑰的
.env已經寫進.gitignore(做法見 AI 寫的網站上線後會壞在哪),再git add -A、git commit -m "文章列表改成兩欄"。不對的話,git restore .會把原本就有的檔案改回上一次存檔的樣子,但 AI 這次新建的檔案會留著:先用git clean -nd列出來(-n只列出、不刪除,-d連新建的資料夾一起列),確定都不要了再用git clean -fd刪掉。這次的修改如果已經git add過,要先執行git restore --staged .,不然git restore .只會退回到 add 的那一刻。git restore .和git clean -fd丟掉的東西都救不回來(git restore --staged .只是取消 add,不會丟東西),Pro Git 也特別警告git restore是危險指令,確定不要了才用1。
git status # 1. 確認乾淨
# … 叫 AI 改一件事 …
git diff --stat # 3. 先看動了哪些檔案
git diff # 再看改了什麼
git add -A && git commit -m "文章列表改成兩欄" # 4a. 對:存檔
git restore --staged . # 4b. 不對:已經 add 過的話,先取消
git restore . # 原本就有的檔案改回去
git clean -nd # 只列出 AI 新建的檔案和資料夾,不刪
git clean -fd # 確定不要了才刪
已經 commit 的修改想撤銷:先用 git log --oneline 找到那一次 commit 的編號,再執行 git revert --no-edit <commit 編號>(--no-edit 直接用預設的 commit 訊息,不會跳出文字編輯器)。revert 會新增一個把那次修改反過來的 commit,原本的紀錄都還在。一次 revert 只撤銷一個 commit;要撤銷好幾個,就從最新的開始一個一個來。叫 AI 做也可以,直接說「revert commit xxx,不要用 reset」,因為 reset 會改掉歷史紀錄。
AI 工具大多有自己的復原功能,可以搭配用,但要知道它的範圍。例如 Claude Code 的 /rewind 能把檔案退回某一句提示之前,可是只追蹤它用檔案編輯工具改過的檔案;只被終端機指令改過的檔案、你自己手動改的檔案都不在裡面,官方文件也寫明 checkpoint 不能取代版本控制2。Cursor 的 checkpoint 存在本機、跟 git 分開,文件要你只拿它復原 agent 的修改,長期的版本紀錄交給 git11。v0 每次依對話改程式都會產生一個新版本,還原舊版會建立一個新的最新版本;但你直接在編輯器裡改的程式碼不會產生版本3。這些功能救得了這次對話裡的失誤,救不了上個月的。
這個網站的做法是改動小、commit 多:將近 700 個 commit,大多只做一件事,有些 commit 訊息還會記下我當初怎麼要求的,例如 2026-11-16 的一個 commit 記著「確保介紹文章可以跟tools都有互相連動」。幾個月後想知道某段程式為什麼長這樣,git log 找得到原因,不用靠記憶。
怎麼讓 AI 下一次對話不要重來一遍?
把決定寫成檔案,放在專案裡,讓 AI 每次開始工作時自動讀到。每個工具的檔名不一樣,作用相同:
| 工具 | 專案說明放哪 | 什麼時候讀 |
|---|---|---|
| Claude Code | CLAUDE.md;沒有 CLAUDE.md 時直接讀 AGENTS.md,兩個都要讀可以用 @AGENTS.md 匯入 | 每次對話開始時 |
| Codex | AGENTS.md,從 repo 根目錄一路讀到目前的資料夾 | 每次啟動時重新讀,預設合計上限 32 KiB |
| Cursor | .cursor/rules 裡的 .mdc 檔,也支援 AGENTS.md | 依規則設定套用,檔案進版本控制 |
| Lovable | Project settings → Instructions,上限 10,000 字元;另外讀專案根目錄的 AGENTS.md、CLAUDE.md | 每一則訊息都會讀 |
2026-11-16 查詢各工具官方文件:Claude Code [4]、Codex [5]、Cursor [6]、Lovable [7]。
要寫什麼?只寫 AI 讀程式碼看不出來的事,大致分成這幾類:
- 怎麼跑、怎麼檢查。開發、建置、測試的指令各是哪一行。這個網站的
CLAUDE.md寫了Tests: npx vitest run。 - 做過的決定和原因。例如這個網站的後台是好幾個人共用的工作區,所以
CLAUDE.md裡有一條:新資料表的權限規則要用工作區成員的判斷,不能寫成owner_id = auth.uid(),不然其他成員看不到資料。這條是 2026 年 9 月一次審查之後加的,之後每一張新資料表都照它做。 - 你已經糾正過兩次的事。同一件事講第二次,就寫進檔案,不要等第三次。
- 哪裡容易做錯。例如這個網站寫了:新文章要加進
src/content/topics.ts的某個主題,否則tests/blog-topics.test.ts會失敗。
不用寫:框架介紹、每個資料夾放什麼。AI 會自己讀 repo,寫了只是佔位置。這個網站的 CLAUDE.md 本身只有十幾行,較長的規則各自放在獨立檔案,用一行指過去或匯入:畫面設計看 DESIGN.md,文章版面看 writing-design-guidance.md。
還要知道一件事:說明檔是給模型讀的參考資料,模型可能不照做。例如 Claude Code 的文件就把它歸為 context,不是強制設定;真的不能有例外的規則,要用 hook 或權限設定擋住4。
想深入 Claude Code 教學 2026:安裝、CLAUDE.md、skills,用它做出一個個人網站 CLAUDE.md 放哪、寫什麼,以及我的全域與專案設定。加新功能之前要先寫什麼?
先寫一頁規格(spec),再叫 AI 動手。規格回答三件事:為什麼要做、做完長什麼樣子、這次不做什麼。最後一項最常被省略,也最能防止 AI 順手多改一堆東西。
到 2026 年 11 月,這個網站的 spec/ 資料夾裡有 58 份用日期命名的規格,例如 2026-11-05-file-based-articles.md,記錄把文章從資料庫搬回 repo 檔案的決定。它的結構是:我當時在對話裡的原話、這次做了哪些決定、為什麼(Why)、資料怎麼放、AI agent 要照什麼流程寫文章、不在範圍內的事(Not in scope)。之後任何一次對話要改文章相關的功能,先讀這份就知道來龍去脈。
畫面設計也一樣寫成檔案。這個網站的 DESIGN.md 有將近 600 行,被 112 個 commit 改過,開頭就規定「跟這份衝突的做法,先改這份再改程式」,所以文件和程式不會各說各話。
規格不用寫得長。有一頁、寫清楚「做完的樣子」,就比在對話裡講十句有用。範本可以直接拿 先寫 spec 再寫 plan 那一篇的。
想深入 讓 AI 做出不像模板的網站:先寫設計規格再動手(附範本) DESIGN.md 要寫哪七個部分,附可以直接複製的範本。看不懂程式碼,要怎麼開始看懂?
不用一次看懂全部,先讓 AI 畫一張地圖。在一個新對話裡這樣問:
用白話解釋這個專案:
1. 每個主要資料夾負責什麼,一句話一個
2. 使用者打開首頁時,依序經過哪些檔案
3. 哪些檔案碰到資料庫、登入或金鑰
不要修改任何檔案。
把回答整理成一份檔案放進 repo(例如 docs/map.md),之後每次要改東西,你就能自己判斷大概會碰到哪裡。地圖會過時,大改之後請 AI 對照現在的程式更新一次。
改之前先問,也是看懂的好時機:
- 「這個改動會碰到哪些檔案?為什麼?」 先聽它的計畫,覺得範圍太大就縮小需求。
- 「用白話說明你剛剛改了什麼,以及有什麼可能被影響。」 改完再問一次,對照
git diff看它說的跟實際改的一不一樣。 - 「這段程式如果刪掉會怎樣?」 對付看起來多餘、卻沒人敢刪的程式碼特別有用。
日子久了,你會開始在 diff 裡認出一些東西:哪個檔案是設定、哪裡是頁面、哪一段在連資料庫。這就是維護得動的開始。
為什麼要讓 AI 跑檢查,而不是自己點點看?
因為你點不完。AI 說完成的時候,它只知道「看起來做完了」。沒有可以執行、會回報成功或失敗的東西,你就變成了它的測試;有的話,它可以改完自己跑、壞了自己讀錯誤再修。工具的官方文件也這樣建議,例如 Claude Code 的最佳實踐文件8。
對個人網站來說,三種檢查就夠用:
- 建置。
npm run build能跑完、沒有錯誤。很多「本機看起來好好的」問題,在這一步就會現形。 - 型別檢查。用 TypeScript 的專案,跑一次型別檢查能抓到很多打錯欄位名稱的錯。
- 幾個測試。不用多,先替「最不能壞的東西」各寫一個:首頁打得開、文章頁有標題、聯絡表單送得出去。請 AI 幫你寫,你只要說清楚哪些東西不能壞。
這個網站的 tests/ 裡目前有一百四十多個測試檔,其中很多是用來守住某個決定的。例如 tests/build-config.test.ts 守住一個建置設定,設定被改回去就會失敗;tests/spacing-scale.test.ts 擋住設計規格之外的間距數字。決定寫在說明檔,AI 可能忘記;寫成測試,忘記了就會跑不過。
文章也有檢查:node tools/audit-writing.mjs 會掃過所有文章,列出不符合寫作規範的地方,例如問句標題漏了問號、清單沒有用粗體開頭。它只報告不擋建置,因為有些是判斷題,由我決定改不改。
最後,要 AI 拿出證據。「測試都過了」這句話本身沒有資訊,要它貼出跑了哪個指令、輸出是什麼;改畫面的話,要截圖。
想深入 AI 寫的網站上線後會壞在哪?部署失敗、憑證外洩與資料庫權限 建置失敗、金鑰外洩、資料庫權限的實際事故與檢查方法。遇到 bug 時,要怎麼跟 AI 說?
「登入壞了,幫我修」幾乎保證會得到一個只修症狀的補丁。要給它你知道、它看不到的資訊。格式範例(情境是虛構的):
問題:手機版打開 /blog 時,文章列表的標題被切掉一半。
怎麼重現:iPhone 寬度(390px),從首頁點「文章」進去。
預期:標題完整顯示,太長就換行。
實際:標題只有一行,後半段被截掉,沒有「…」。
已知:桌機版正常;上週改過文章卡片的樣式(commit <commit 編號>)。
請先說明你判斷的原因,再改;改完跑 npm run build。
這個格式的重點是:
- 先講怎麼重現。AI 能重現問題,才能確認改完真的好了。這個網站有一次建置只在 Cloudflare 上失敗、本機都正常,是先在本機重現出同樣的錯誤才確定原因,經過寫在 本機正常,部署就失敗? 那篇。
- 預期和實際分開寫。「壞了」不是描述,「應該換行,實際被截掉」才是。
- 附上你知道的線索。錯誤訊息整段貼上,不要自己摘要;最近改過什麼也寫上。
- 一次只修一個 bug。修好、commit,再修下一個。
如果同一件事糾正了兩次還是錯,不要再講第三次。開一個新對話(Claude Code 可以用 /clear 清掉對話),把學到的東西寫進一個新的提示重新開始,因為對話裡堆著兩次失敗的嘗試,AI 會一直讀到它們。Claude Code 的文件也是這樣建議的8。
技術選擇怎麼影響以後好不好改?
能用簡單的就不要用複雜的。每多一個套件、多一個服務,就多一個 AI 可能記錯版本、多一個要升級、多一個會壞的地方。
- 只有文章和介紹頁的個人網站,用靜態網站就夠。不需要資料庫和登入,就不會有權限設錯、金鑰外洩的問題。
- 不讓 AI 自己加套件。在說明檔寫一條「新增套件前先問我,說明為什麼需要」。
- 用不到的功能就拿掉。這個網站原本有一個在後台編輯文章的編輯器,但我從來不在那裡改文章,它還造成每篇文章要在資料庫和檔案兩邊同步。2026 年 11 月把它整個移除,文章改成直接放在 repo 裡的檔案,少了一整套要維護的東西。
這個網站本身不算簡單:它有後台、資料庫和登入,因為我用它管理其他事情。如果你的網站只是要放作品和文章,不用跟著加這些。
想深入 Vibe coding 是什麼?2026 新手入門:叫 AI 寫程式的做法、工具,和最容易出事的地方 什麼時候可以不讀程式碼,什麼時候一定要讀。什麼時候該重來,而不是繼續修?
「重來」有兩種,成本差很多。開一個新對話幾乎沒有成本,應該常常做;把整個專案重寫是大工程,要有理由。
| 情況 | 建議 |
|---|---|
| 同一個 bug 糾正兩次還是錯 | 開新對話,把學到的寫進新提示 |
| AI 開始改到不相關的檔案 | git restore . 改回原本的檔案,新建的檔案先用 git clean -nd 看清單、再用 git clean -fd 清掉,縮小需求再試 |
| 對話開了一整天,AI 開始忘記前面講過的事 | 把進度和決定寫進檔案,開新對話接著做 |
| 修一個地方總會壞另一個地方,而且沒有測試 | 先補測試守住會壞的地方,再繼續修 |
| 架構本身不適合(例如只想放文章,卻選了需要伺服器的框架) | 考慮在新 repo 重做,內容搬過去 |
| 程式碼裡混著不該公開的東西,或歷史紀錄裡有金鑰 | 開新 repo,只搬需要的部分 |
這個網站一開始就選了「開新 repo」而不是原地改造。2026 年 6 月,我原本打算把一個放個人財務資料的舊 repo 原地改造成網站,最後決定開一個全新的 repo:舊 repo 繼續管資料,敏感的資料夾從頭到尾不會進到網站的 repo,也就不用去清理舊的歷史紀錄。那次交接文件的「下一步」寫的是「在新的 repo 開一個新的 Claude 對話,從這裡接著做」,後面要做的步驟逐條列在下面。
重做時,文字內容(文章、介紹、圖片)通常可以直接帶走,要重寫的是包著它們的程式。所以內容最好一開始就放成獨立的檔案,例如每篇文章一個 Markdown 檔,換框架時才搬得動。
已經改爛了,今天可以從哪裡開始?
不用等到全部重來,照這個順序做,每一步都能單獨完成:
- 先存一個版本。專案還沒用 git 的話,
git init再把現況 commit 起來。現在壞掉的版本也值得存,它是之後比對的起點。 - 請 AI 畫地圖。用上面那段提示,把回答存成
docs/map.md並 commit。 - 寫一份最短的說明檔。依你的工具建
CLAUDE.md、AGENTS.md或專案規則,先寫三件事:怎麼啟動、怎麼建置、你最在意不能壞的東西。 - 加一個檢查。至少讓
npm run build能跑過;請 AI 替最重要的一頁寫一個測試。 - 一次修一個 bug。用上面的回報格式,修好、跑檢查、讀 diff、commit,再下一個。
這些習慣做久了會互相支撐:commit 小,diff 才讀得完;說明檔寫了決定,AI 才不會在 diff 裡偷偷改掉它;有測試,AI 改完才知道自己有沒有弄壞東西。這個網站的程式是 AI agent 寫的,每一次修改要不要留下、要不要上線,由我決定。
資料來源