我從 Claude 身上學到的 7 個協作原則：規格驅動、邊界優先、答完就是決定

TL;DR 給趕時間的人

讓 AI 真的能獨立開發，只需要做對一件事：把規格寫成契約，不寫成願望。具體拆成 7 條原則：規格先於程式、Given/When/Then 消除歧義、以終為始、邊界情境優先、問題與指令不混、答完就是決定、自我驗證才收尾。這篇把每條原則都配上 Joseph 開發過程中的真實片段。

---

本系列三篇總覽

• [第一篇] 身份故事篇：為什麼砍掉三個專案才做出 Joseph
• [第二篇（本文）] 方法論：讓 AI 獨立開發的 7 條原則
• [第三篇] 實戰紀錄：9 次 DRY RUN 失敗、T+2 三重鎖、458 測試、18 個 cron

---

開場：為什麼「保姆式協作」不可持續

很多人用 AI 寫程式，流程是這樣的——丟一個模糊需求 → AI 寫一坨 → 看起來怪怪的 → 改 prompt → AI 再寫一坨 → 跑起來壞了 → 改 prompt → 永遠在改 prompt。

這種流程的問題不是 AI 不夠強，是協作契約沒建立。你沒告訴它「完成」長什麼樣、「對」怎麼驗證，它只能一直揣摩。

Joseph 做下來有一份我很珍惜的文件叫 docs/AI協作到AI全自動開發攻略.md。它的第一段寫著：

「規格不是文件，是契約。寫得夠好的規格，AI 可以獨立跑完整個開發流程，包含 coding、testing、debugging、reporting。」

這篇文章就是把這句話拆成 7 條可執行的原則。

---

原則 1：規格先於程式

做法：不先寫程式。先寫 SPEC_*.md。規格裡面至少要有三段——「目的、驗收標準（Given/When/Then）、不可以發生的事」。

Joseph 例子：實盤上線前我寫了 docs/DRY_RUN_FIX_SPEC.md，先定義好「什麼叫修好」——每個修復都有可執行驗證命令，例如 grep "BUY" logs/trading.log | tail -1 應該要回傳某個格式的交易紀錄。有驗證命令，才有「完成」可以討論。

為什麼有效：規格寫不出來，通常代表你自己也沒想清楚。這時候讓 AI 寫程式只是把混亂加速。先讓規格把你逼清楚，AI 再動工。

---

原則 2：Given / When / Then 消除歧義

做法：所有驗收標準用這三個關鍵字硬格式。Given = 前置狀態；When = 觸發動作；Then = 預期結果。別用自然語言。

Joseph 例子：實盤 Gate 10 的 T+2 守衛驗收這樣寫：

Given: 昨日賣出 10 張，尚未結算
When:  今日 allocator 計算 available_cash
Then:  扣除 pending_settlements 中未到交割日的金額
驗證命令：python -m core.capital_manager --dry-check

為什麼有效：自然語言會說「系統應該正確處理 T+2」——什麼叫「正確」？什麼叫「處理」？AI 解讀一百種。Given/When/Then 只有一種解讀。

常見錯誤：Then 寫太弱，像「回傳結果」——回傳什麼？格式？錯誤處理？寫到可以用命令驗證那種程度才算夠。

---

原則 3：以終為始（Test-First Thinking）

做法：動手前問「我要怎麼證明這是對的？」把驗證方法寫下來，再開始寫程式。

Joseph 例子：Task #7 要補 _call_shioaji_place_order() 的實盤下單能力。動手前我先定義：「通過」等於 72 個 unit test 全綠 + 在 Shioaji 模擬帳戶登入成功 + 能看到 polling + fallback 終態覆蓋。這三個條件決定了我要寫哪些 test、哪些 code。

為什麼有效：驗證方法決定實作方向。如果你不知道怎麼驗證一件事做對了，你就寫不出真正對的程式——只能寫出「看起來對」的程式。看起來對的程式，上線後會教你做人。

---

原則 4：邊界情境優先

做法：正常流程放後面寫。先把所有邊界情境列出來——沒網路、API 錯誤、資料為空、權限不足、時區變換、數字溢位、同時請求、部分失敗。

Joseph 例子：4/10 DRY RUN 爆了三個邊界 bug：

1. equity=0 時 allocations 全零 → 補 fallback：equity = cash + marked_value
2. Scanner 08:30 被判為 closed → 邊界時段錯誤
3. ShadowExecutor 缺 async get_balance() / get_positions() → 非同步 fallback 缺席

這三個都是「正常情況下不會發生」——但在真實 cron 啟動第一分鐘就全發生了。

為什麼有效：正常情況人人會寫。真正把系統搞死的都是邊界。先列邊界，等於先買保險。

---

原則 5：問題與指令不混

做法：問 AI 問題時，不要順便夾指令。反過來也一樣——要 AI 做事時，不要夾模糊問題。

錯誤示範：「幫我看看 trader_live.py 有沒有什麼可以優化的，然後順便把 polling 邏輯補齊。」——這是兩件事。AI 會糊在一起給你。

正確示範：

• 問題版：「trader_live.py 的 _call_shioaji_place_order() 目前支援哪些 order status？有沒有缺的？」
• 指令版：「請把 _call_shioaji_place_order() 補上 FILLED / CANCELLED / REJECTED / FAILED 四種終態，用 exhaustive match，缺一種就拋 UnknownOrderStatusError。」

為什麼有效：問題模式下 AI 給資訊；指令模式下 AI 改程式。兩種模式的心智不同。混在一起，它會在「該給資訊」和「該改程式」之間搖擺，結果兩個都做不到位。

---

原則 6：答完就是決定

做法：AI 給完一個可執行答案後，你要當下決定「採用 / 不採用 / 改這個參數」——不要開新對話、不要「我再想想」。當場決策。

Joseph 例子：4/17 T+2 診斷那天，Claude 給了六個備選設計：A（擴充 shadow_ledger）、B（新增 pending_settlements 模組）、C（混合）、D（延遲到 Go-Live 後補）...。我當下看完選 B，理由寫進 PRELIVE_T2_DIAGNOSIS_20260417.md，下一步直接進 Task #6 實作。沒有「再想想」。

為什麼有效：AI 的時間很便宜，你的注意力很貴。一個問題開越多輪討論，成本越高、結論越稀釋。答案給出來那一刻是決策的最佳時機——因為所有上下文都還在熱的。冷掉再決定，你會忘記為什麼當初那六個選項要那樣排序。

重要補充：答完就是決定，不代表決定永遠不能改。它代表當下不要拖。後來發現決定錯，就光明正大地翻——但不要用「我早就覺得…」這種後見之明鑽牛角尖。

---

原則 7：自我驗證才收尾

做法：AI 做完事情，不是交給你就結束。要求它自我驗證——跑測試、檢查 log、比對規格——然後更新進度文件。沒做自我驗證的任務，一律視為未完成。

Joseph 例子：每個 Task 收尾前，我都讓 Claude 跑 pytest tests/ -v，確認 458 個測試全綠，然後更新 docs/DEV_PROGRESS.md。如果測試沒跑、或 DEV_PROGRESS 沒更新，那個 Task 我不收。

為什麼有效：AI 的「我做完了」跟「我做對了」是兩回事。它會誠實回報「我改了什麼」，但不一定確認「我改的東西是對的」。自我驗證這一步把 claim 變成 evidence。

具體文件：Joseph repo 有一份 docs/DEV_PROGRESS.md 是 Claude 自己維護的「我做了什麼 / 驗證結果 / 下一步」時間軸。這份文件救過我好幾次——當 Go-Live 前我忘記某個 fix 做到哪，翻這份就知道。

---

7 條原則放在一起長什麼樣

舉一個實際 session：

1. 我寫規格（原則 1）：TASK7_DIAGNOSIS_20260418.md，描述 _call_shioaji_place_order 的缺口。
2. 規格含 Given/When/Then（原則 2）：4 個終態各一條驗收。
3. 驗證命令先寫（原則 3）：pytest tests/test_trader_live_real.py -v，期望 72 個測試全綠。
4. 邊界情境列一欄（原則 4）：網路掉線、Shioaji 登入失敗、order 進「未知狀態」三個 case 都要有 test。
5. 丟給 Claude 的指令清楚（原則 5）：純指令，沒夾雜問題。
6. Claude 回完方案當場選（原則 6）：選了方案 B，理由寫進 IMPL_LOG。
7. 收尾跑測試 + 更新 DEV_PROGRESS（原則 7）：72 tests 全綠，IMPL_LOG 寫完，才收。

整個過程我沒釘在旁邊。我去上班、去吃飯、去睡覺。回來看 commit log、讀 IMPL_LOG、跑一次測試，確認結果符合規格。這就是「獨立開發」的樣子。

---

一個不存在的原則：「三人分工」

有些文章會說「讓 AI 當策略師 / 實作工程師 / UX 判官」。我試過這種 prompt role play，對 Joseph 這種系統沒幫助。原因：

• AI 不真的會「切角色」，它只會切語氣
• 真正切分工的是階段，不是角色——規格階段（我寫規格）、執行階段（Claude 執行）、驗證階段（自動化跑測試）

我的實際分工是：

• 人（我）= 寫規格、做決策、審查 PR
• Claude Code = 讀規格、寫程式、跑驗證、回報
• 測試套件 = 裁判，誰的話都不聽，只看結果

這三者的邊界很硬。角色扮演聽起來浪漫，邊界硬才真的有用。

---

為什麼這些原則對非工程師特別重要

工程師即使沒規格也能寫程式，因為他們腦中有模型。非工程師沒有這個模型，規格寫不清楚就會被 AI 拖去不知道的地方。規格是非工程師的手煞車，不是流程上的儀式。

Joseph 能活下來，很大一部分是我接受了「自己不是工程師」這件事，所以把規格當最高優先級在寫。這不是謙虛，是實用主義。

---

FAQ

Q1：這些原則適用所有 AI 工具還是只限 Claude Code？ 骨架一樣。我是用 Claude Code 做 Joseph，但 Given/When/Then、規格先行、以終為始這些原則不綁工具。工具差異在於 Claude Code 可以直接執行命令、跑測試、讀 log，所以「自我驗證」那步特別順。換別的工具你可能要自己跑測試再把結果貼回去。

Q2：規格要寫多長？ 規格長度不是重點，是否可驗證才是。一個 3 行的 Given/When/Then 如果驗證命令寫得出來，比 30 行的自然語言描述強 100 倍。

Q3：AI 給的方案跟我想的不一樣怎麼辦？ 當場討論，不要開新對話。說清楚「為什麼我想要 A，你提 B 有什麼我沒想到的優點」。AI 很擅長解釋自己的推理。一輪對話你就知道要選 A 還是 B。

Q4：自我驗證那一步，要驗到什麼程度？ 至少要能回答「這份程式現在做對了什麼」。最低門檻是測試全綠。再來是跑一次真實場景（DRY RUN）。再來是翻 log 確認沒 error。三層都過才是真的「做完」。

Q5：這 7 條裡面最難做到的是哪條？ 原則 6（答完就是決定）。因為做決定會累，會想拖到明天。但拖到明天你會忘記 60% 上下文，隔天決策品質一定比當下差。訓練自己「看完就斷」是我花最久時間練的事。

Q6：什麼情況下這些原則會失敗？ 當你不知道自己要什麼的時候。規格驅動的前提是你知道終點長什麼樣——哪怕只是模糊的形狀。如果你連「我想做什麼」都還沒想清楚，先別寫規格，先在日記本上寫「我想解決的真實問題」。那不是這 7 條原則能幫你的地方。

Q7：Claude Code 真的能自己跑完整個開發？ 可以，但前提是規格夠清楚、驗證命令夠具體、邊界情境夠完整。Joseph 進入實盤前的最後兩週，Task #6 和 Task #7 都是我寫完規格後，Claude 獨立實作 + 跑測試 + 寫 IMPL_LOG，我只審最後結果。但這兩個 Task 的規格文件各自都超過 200 行。AI 的獨立性 ≈ 規格的完整度。

Q8：有沒有一份範本可以直接抄？ Joseph repo 公開的 docs/JOSEPH_FOUNDATIONAL_RULES.md 和 docs/AI協作到AI全自動開發攻略.md 就是範本。格式比內容重要。

---

下一篇

第三篇：從 9 次 DRY RUN 失敗到 Go-Live →

講完方法論，下一篇全是硬數據——9 個 DRY RUN 失敗模式、T+2 三重鎖怎麼設計、Shioaji 踩坑、18 個 cron 排程。寫給想看一個真實自動化投資系統長什麼樣的人。