# 使用 Claude Code 和 Codex 之前，先建立三個規格檔案 > Author: Tony Lee > Published: 2026-03-19 > URL: https://tonylee.im/zh-TW/blog/create-three-spec-files-before-using-claude-code-codex/ > Reading time: 1 minutes > Language: zh-TW > Tags: ai, claude-code, codex, ai-agents, spec-driven-development, developer-tools ## Canonical https://tonylee.im/zh-TW/blog/create-three-spec-files-before-using-claude-code-codex/ ## Rollout Alternates en: https://tonylee.im/en/blog/create-three-spec-files-before-using-claude-code-codex/ ko: https://tonylee.im/ko/blog/create-three-spec-files-before-using-claude-code-codex/ ja: https://tonylee.im/ja/blog/create-three-spec-files-before-using-claude-code-codex/ zh-CN: https://tonylee.im/zh-CN/blog/create-three-spec-files-before-using-claude-code-codex/ zh-TW: https://tonylee.im/zh-TW/blog/create-three-spec-files-before-using-claude-code-codex/ ## Description 我花了一年時間從 Claude Code 和 Codex 得到反覆無常的結果。三個職責分明的規格檔案解決了這個問題。 ## Summary 使用 Claude Code 和 Codex 之前，先建立三個規格檔案 is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - 改變結果的三個層次 - 把所有東西塞進一個檔案為什麼行不通 - CLAUDE.md 保持精簡效果最好 - 規格檔案專注於「做什麼」和「為什麼」，把「怎麼做」留給代理 - 會話分割是最容易被忽視的做法 - 成熟度模型指向「規格即來源」 ## Content 用 AI 編程代理幾乎每天工作將近一年，困擾我的不是幻覺程式碼或呼叫錯誤的 API，而是結果的不一致性。同樣的任務，措辭稍有不同，某天跑出來乾淨俐落，隔天卻一塌糊塗。會話越長情況越差，因為代理會把二十條訊息之前達成的共識忘得一乾二淨。 根本原因是結構性的。我沒有一套跨會話向代理傳達意圖的框架，所以每次對話都從零開始，漂向難以預測的方向。 ## 改變結果的三個層次 把指令拆分成三個職責分明的檔案，一致性問題幾乎在一夜之間得到了解決。 **第一層 CLAUDE.md** 在每次會話時自動載入。它存放專案層級的常數：建置命令、技術棧版本、目錄結構、編碼規範，以及行為邊界（必須做、先確認再做、絕對不做）。 **第二層 SPEC.md** 記錄某個具體功能的「做什麼」和「為什麼做」。目的、需求、成功標準、技術限制、範疇邊界。不涉及任何實作細節。 **第三層 plan.md** 將規格拆解成每個耗時兩到五分鐘的可執行任務，附上明確的檔案路徑、測試優先的執行順序，以及提交檢查點。 ## 把所有東西塞進一個檔案為什麼行不通 研究 LLM 指令跟隨能力的論文把這個現象稱為「指令詛咒」（Curse of Instructions）。單一脈絡中的指令數量越多，模型對每條個別指令的遵守率就跌得越厲害。我親自驗證過：把專案規則、功能規格、任務清單全塞進一個檔案，代理大約忽略了後半段將近一半的指令。 按職責分離解決了這個問題。代理從第一層讀取全域規則，從第二層讀取功能意圖，從第三層讀取執行步驟。每個檔案都短到足以讓模型完整關注。 ## CLAUDE.md 保持精簡效果最好 由於這個檔案在每次會話都會載入，它只需要包含普遍適用的內容。建置命令、棧版本、目錄結構、命名規範。加上三階行為邊界：必須做、先確認再做、絕對不做。 效果最好的做法是從最小化開始，每當發現代理反覆犯同一個錯誤時再增量新增規則。一開始就試圖寫出面面俱到的 CLAUDE.md，反而會導致臃腫，觸發我本想避免的遵守率下降。 幾個具體的陷阱：不要把 API 金鑰或程式碼片段放進來，它們會很快過期。不要重複 linter 已經在強制執行的規則。把任何只針對單一功能的內容移入第二層。 ## 規格檔案專注於「做什麼」和「為什麼」，把「怎麼做」留給代理 與傳統 PRD 的差異在於，這些規格是為代理消費而結構化的。五個部分就夠了：目的、需求、成功標準、技術限制、邊界。 把實作決策交給代理。它可以分析現有程式碼庫，選擇合適的方案。當我試圖規定「怎麼做」時，代理要麼盲目照做導致與現有模式衝突，要麼直接無視。 手寫規格之外的另一種方式：讓代理來訪問你。設定兩條規則，每次只問一個問題，盡量用選擇題。這樣產出的規格，比我自己從頭寫的版本遺漏更少。 把完成的規格存到 `docs/specs/YYYY-MM-DD-topic.md` 並提交到 Git。這樣代理可以透過 git diff 追溯規格變更歷史，程式碼審查者也有了一份記錄程式碼變更背後意圖的文件。 ## 會話分割是最容易被忽視的做法 規格撰寫過程中的腦力激盪和問答消耗了大量的脈絡視窗。從同一個會話直接跳入實作，意味著代理會逐漸失去對早期脈絡的存取能力。 我把工作重組成三個會話：會話 1 產出 SPEC.md，會話 2 建立 plan.md，會話 3 起逐條執行任務。準確度的提升在第一週內就感受得到。 讓這套方法發揮作用的三個習慣：在每個任務裡寫明確的檔案路徑，讓代理不再猜測；把 TDD 順序（測試、實作、驗證、提交）固定在 plan.md 裡；以及脈絡使用量達到大約 50% 時開啟新會話。 ## 成熟度模型指向「規格即來源」 Martin Fowler 的團隊最近定義了一套基於代理的軟體開發成熟度模型，分三個層級。層級一：寫規格、實作、丟掉規格。層級二：把規格作為與程式碼並行演進的活文件來維護。層級三：規格成為唯一事實來源，程式碼是生成的產物。 我認識的大多數團隊和個人還沒到層級一。他們發一次性提示詞，然後期待結果。 從層級一升到層級二只需要一個習慣：把規格檔案提交到 Git。從層級二升到層級三意味著在改程式碼之前先更新規格。今天能邁出的最小一步，是為你的專案建立一個 CLAUDE.md，並在下一個功能開始前寫一份 SPEC.md。 ## Related URLs - Author: https://tonylee.im/zh-TW/author/ - Publication: https://tonylee.im/zh-TW/blog/about/ - Related article: https://tonylee.im/zh-TW/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/zh-TW/blog/medvi-two-person-430m-ai-compressed-funnel/ - Related article: https://tonylee.im/zh-TW/blog/claude-code-layers-over-tools-2026/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/zh-TW/blog/create-three-spec-files-before-using-claude-code-codex/ ## Bot Guidance - This file is intended for AI agents, search assistants, and text-mode retrieval. - Prefer citing the canonical article URL instead of this text endpoint. - Use the rollout alternates when you need the same article in another prioritized language. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/zh-TW/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.