跟 AI 一起寫程式：從一份 CLAUDE.md 到 Skills 跟規範
2025 年初 AI 對我來說還是拿來問問題的工具，到了 2026 年幾乎所有程式都是 Claude Code 寫、我做 review。這一年多我經手的幾個專案，給 AI 的設定也一路演變：先是把所有東西塞進一份上千行的 CLAUDE.md，再把固定流程拆成 Skills，最後連領域知識、規格流程跟測試閘門都做進去。這篇整理這三個階段、每個階段的做法，還有為什麼會這樣改。
目錄
2025 年初，AI 對我來說主要還是拿來問答的工具，用的是 GPT、Copilot 跟 Cursor。到了年底，幾乎都是用 Claude Code 在開發。2026 年更進一步，很少有人一行一行手寫程式了，大部分的程式是 AI 寫的，我們做的是把需求講清楚跟 review。
這一年多我經手了三個專案，三個專案給 AI 的設定剛好是三個階段。這篇把這條演變整理下來，講每個階段怎麼做、遇到什麼問題、為什麼改成下一種。
先講幾個名詞
Claude Code 這類工具讀專案的方式大概有幾層，後面會一直用到。
CLAUDE.md 是專案根目錄的一份說明，每次對話都會載入，放的是專案是什麼、怎麼跑、有哪些規則。它是常駐的，所以放進去的每一行都會佔每一次對話的空間。
Skill 是放在 .claude/skills/ 底下的一個資料夾，裡面有一份 SKILL.md，開頭用幾句話描述「什麼時候用這個」。AI 在判斷任務符合描述的時候才會去讀它，平常不載入。Skill 可以帶 references/ 資料夾，放更詳細的規則或對照表。
Command 是使用者打 / 主動呼叫的指令，例如 /commit。它跟 Skill 的差別在觸發方式，一個是人叫它，一個是 AI 自己判斷要不要用。
Subagent 是 AI 另外開一個獨立的對話去做一件事，做完回報結果。它有自己的 context，不會跟主對話混在一起。
第一階段：什麼都寫進 CLAUDE.md
2025 年中，第一個導入 Claude Code 的專案是一套能源管理系統。那時候的想法很直覺，AI 不知道的事就寫給它看，於是 CLAUDE.md 一路長到一千多行，.claude/ 底下還放了幾十份說明文件，架構、後端規範、資料庫操作、領域知識、各功能的實作細節，分成好幾個資料夾。
同一時期也在 Cursor 的 rules 裡放了類似的東西。
這樣做有效，AI 寫出來的程式確實比較符合專案的做法，但問題很快就出現。一千多行的文件每次對話都載入，佔掉一大塊 context，真正的任務反而沒空間。
文件跟程式碼也會分岔，程式改了文件沒改，AI 就照著過期的規則做。還有就是太長了，連人都不會從頭讀，AI 也一樣，重要的規則埋在中間，常常被忽略。
第二階段：CLAUDE.md 瘦身，固定流程做成 Skills
2025 年底開始的第二個專案，CLAUDE.md 縮到一百多行。留下來的只有專案概覽、常用指令、幾條關鍵的開發模式跟領域規則，其他的變成「延伸文件」的連結，需要的時候再讀。
另一個改變是把固定會做的事做成 Skills。一開始是 commit 跟 mr 兩個 command，後來改成五個 Skills：commit、mr、plan、review、test。
commit 照專案的 Conventional Commits 規範寫訊息，mr 產生 PR 的描述跟給 reviewer 的重點，plan 先規劃再動手，review 審查目前的變更，test 跑測試、修失敗的案例、幫關鍵邏輯補測試。
為什麼從 command 改成 Skill？因為這些事不一定是人想到才做。寫完一段程式 AI 自己就會去跑 test Skill，要交出去的時候自己用 commit Skill 的規範寫訊息，人不用每次提醒。CLAUDE.md 變短也是同一個道理，常駐的東西只留最小集合，其他按需載入。
第三階段：領域知識、規格流程跟閘門都做進去
2026 年 3 月開始的第三個專案是一套電力調度的模擬系統，領域知識很重，這個我在上一篇寫過。這個專案的 AI 設定是目前最完整的，Skills 從五個長到二十幾個，可以分成四類。
流程類還是 commit、mr、plan、review、test 那幾個。
領域類是這個專案才有的。最大的一個 Skill 把電力領域的規則整理成近千行，電壓的顏色、開關的狀態邏輯、警報的分級、各種常數，都在裡面，還附 references 記每條規則的出處。另外還有針對單一變電所的語意對照、三張表格的規範、各類考題的產生跟校正。AI 碰到領域判斷的時候讀這些，而不是靠猜。
工具類是專案自己的工具怎麼用，例如單線圖的解析跟渲染管線、連到現場主機的方式、題庫稽核工具的開發。
文案類只有一個，介面文案的寫作原則，寫按鈕、錯誤訊息、空狀態的時候用。
除了 Skills，還有幾個東西是這個階段才有的。
規格流程
改動比較大的功能不直接開始寫，先用 OpenSpec 的流程產生三份文件，proposal 寫要做什麼跟為什麼，design 寫怎麼做，tasks 列實作步驟，確認之後才進入實作，做完歸檔。這等於把我們團隊在需求流程上學到的東西搬到跟 AI 協作上，先講清楚再動手。
行為準則
CLAUDE.md 裡有一節參考 Andrej Karpathy 對 LLM 寫程式常見問題的觀察寫成的準則，不要假設、不確定就問、用最少的程式碼解決問題、不做沒被要求的功能、不順手改無關的程式碼。這一節直接改變了 AI 的工作方式，它會先說出假設再動手。
閘門
AI 寫的程式不能只靠 review，專案裡有一組 guard 腳本，改到單線圖或狀態相關的程式碼就要先跑它，改到保護邏輯就要跑基準比對。CI 也有對應的檢查。這些閘門擋下的問題，比人眼 review 擋下的多。
走查紀律
跟畫面、題庫、評分有關的任務，最後都要用瀏覽器以考生或考官的視角實際操作一次，確認資料對得上、console 沒錯誤，截圖附在回覆裡。程式碼看起來對，不等於使用者看到的對，這條規則就是從幾次「看起來對」的失敗裡來的。
給其他工具的入口
還有一份很薄的 AGENTS.md，給 Codex、Cursor、Copilot 這些其他工具讀，裡面只寫「規則在 CLAUDE.md，Skills 在 .claude/skills」，不重複任何內容，避免兩份規則分岔。
關於 subagent
老實說我自己很少用 subagent，大部分時候是一個對話從頭做到尾。團隊裡的資深同事用得多，像是把一件事拆給幾個 subagent 平行做，或是把探索、審查這類會讀很多檔案的工作丟出去，只拿結論回來，主對話的 context 就不會被檔案內容塞滿。
我目前的理解是，subagent 適合三種情況：要讀很多東西但只需要結論的，可以平行做的，還有需要獨立視角的，例如用一個沒看過你寫法的 subagent 來 review。代價是它看不到主對話的脈絡，交代要寫清楚，結果也要驗證。這部分我還在學，之後用熟了再補一篇。
回顧
把三個階段放在一起看，變的是形式，不變的是一個問題：AI 需要知道的事，要用什麼方式給它。第一階段的答案是全部給，結果是太多反而沒用。後來的答案是分層，常駐的只留最小集合，其他做成 Skill 按需載入，規則要有出處，能用程式驗證的就做成閘門，不要靠讀。
另一件事是這些設定跟團隊的流程其實是同一件事。需求先講清楚再動手，在 AI 這邊變成 OpenSpec 的 proposal 跟 design。會議的結論要有出處，在 AI 這邊變成 Skill 的 references。程式碼看起來對不等於真的對，在 AI 這邊變成 guard 跟走查。
給 AI 的規範寫得愈清楚，其實也是把團隊自己的做法寫得愈清楚。