# 喺畀 Claude Code 或 Codex 做嘢之前，先整好三個規格檔案 > Author: Tony Lee > Published: 2026-03-12 > URL: https://tonylee.im/zh-HK/blog/three-spec-files-before-ai-agent-coding/ > Reading time: 1 minutes > Language: zh-HK > Tags: ai-agents, claude-code, context-engineering, developer-tools, spec-driven-development ## Canonical https://tonylee.im/zh-HK/blog/three-spec-files-before-ai-agent-coding/ ## Rollout Alternates en: https://tonylee.im/en/blog/three-spec-files-before-ai-agent-coding/ ko: https://tonylee.im/ko/blog/three-spec-files-before-ai-agent-coding/ ja: https://tonylee.im/ja/blog/three-spec-files-before-ai-agent-coding/ zh-CN: https://tonylee.im/zh-CN/blog/three-spec-files-before-ai-agent-coding/ zh-TW: https://tonylee.im/zh-TW/blog/three-spec-files-before-ai-agent-coding/ ## Description 用咗 AI 代理接近一年之後，我發現結構化嘅規格檔案比任何提示詞技巧都更能解決結果唔一致嘅問題。 ## 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 係項目憲法 - 第二層：SPEC.md 講乜嘢同點解 - 第三層：plan.md 係可執行任務 - 令成件事真正有效嘅 Session 拆分 - 呢條路去邊 ## Content 用咗 AI 代理編碼超過一個星期，你大概已經撞過呢個情況：同一個任務，星期一出來係乾淨漂亮嘅程式碼，星期二同一個 prompt 出來嘅係垃圾。Codebase 無變，提示詞基本上都係一樣，但結果就係唔同。 我花咗接近一年時間追查呢個問題。試過更精細嘅提示詞、更詳細嘅說明、唔同嘅模型，通通都解決唔到根本問題。真正嘅問題係：我冇一個結構化嘅方法去傳達意圖。我靠住一個提示詞去承載所有嘢：項目規則、功能需求、執行步驟、編碼規範。單一輸入負擔太重，一定撐唔住。 解決方法係將指示拆分成三個檔案，分三個層次。改變之後，跨 session 嘅質素落差幾乎消失咗。 ## 單一檔案點解會出事 研究 LLM 指令跟隨嘅論文裏面有個現象叫「指令詛咒」（Curse of Instructions）：單一 context 入面嘅指令數量越多，代理跟隨每條個別指令嘅成功率就跌得越厲害。我親身測試過：將項目規則、功能規格、任務清單一起塞入同一個 CLAUDE.md，代理差不多忽略咗後半段嘅所有指令。 Attention 機制係點運作呢。一份混雜咗多種關注點嘅長文件，會迫使模型實時決定乜嘢最重要，結果係做咗一堆差劣嘅取捨。解決方法係將資訊按職責分層，每一層保持焦點。 ## 第一層：CLAUDE.md 係項目憲法 CLAUDE.md（或者你用嘅代理工具嘅對應檔案）每個 session 都會自動載入。正正因為咁，呢個位唔應該放功能特定嘅指令，只應該放整個項目都成立嘅嘢： - Build 指令同技術棧版本 - 目錄結構同命名規範 - 三層行為規則：「必定要做」、「先問再做」、「絕對唔做」 我學到唔好一開頭就塞晒所有諗到嘅嘢落去。反而係觀察代理喺邊度反覆出錯，然後逐步補充規則。呢個方式比起事前巨細無遺嘅規格更有效，因為每條規則都係從真實問題提煉出嚟嘅。 有幾類嘢要特別留意唔好放入 CLAUDE.md：API 金鑰（會過期）、程式碼片段（會同實際程式碼脫節）、linter 已經處理好嘅風格規則、任何只針對單一功能嘅內容。呢啲嘢屬於下一層。 ## 第二層：SPEC.md 講乜嘢同點解 規格檔案描述一個功能。佢回答以下問題：功能做乜嘢、點解存在、成功標準係乜、技術限制係乜、邊界喺邊。就係咁，五個部分。 同傳統 PRD 最關鍵嘅分別：規格檔案係為代理消費而設計，唔係為人類審查會議而寫。而且係刻意略去「點做」。代理應該靠分析現有 codebase 去搞清楚實作方式，唔係靠規格裏面嘅逐步編碼指示。 寫好一份規格有兩個方法。你可以自己用上面五個部分嘅結構起草。或者可以讓代理訪問你。訪問模式出奇地好用，但要守住兩個規則：每次只問一個問題，盡量用選擇題而唔係開放式問題。呢樣生成出嚟嘅規格通常會覆蓋到我自己獨力起草時漏咗嘅邊界情況。 完成嘅規格存入 `docs/specs/YYYY-MM-DD-topic.md` 然後 commit 落 Git。呢樣做創造出一條代理可以用 `git diff` 跟蹤嘅紀錄，同時畀 code reviewer 一個方式分辨哪些係刻意決定、哪些係意外產生。 ## 第三層：plan.md 係可執行任務 Plan 檔案係最窄嘅一層。佢將規格拆解成每個只需時兩至五分鐘嘅任務，附上明確嘅檔案路徑同固定執行順序。我會將每個 plan 錨定到 TDD 循環：先寫測試、實作最少量程式碼令測試通過、確認測試過咗、然後 commit。 明確嘅檔案路徑比我預期更加重要。冇咗佢哋，代理會猜檔案應該放喺邊，而呢啲猜測喺唔同 session 之間會出現分歧。將路徑釘死可以消除呢個變數。 ## 令成件事真正有效嘅 Session 拆分 以下係我錯過咗好幾個月嘅部分。即使有咗三個乾淨嘅檔案，如果我喺同一個 session 入面寫規格同跑實作，質素仍然會下滑。原因係直接嘅：規格撰寫期間嘅腦力激盪同問答消耗咗 context window 嘅一大截。到實作開始嘅時候，代理已經忘記咗早前嘅決定。 解決方法好簡單。Session 1：寫 SPEC.md 然後儲存。Session 2：由規格生成 plan.md。Session 3 起：逐一執行任務。我同時會喺 context window 大概去到一半滿嘅時候開新 session。準確度嘅提升係即時感受到嘅。 ## 呢條路去邊 Agile 宣言背後嘅團隊發表過一個基於代理嘅軟件開發成熟度模型，同呢個分層方式正好對應： - **Level 1**：寫規格、實作、然後棄掉規格。 - **Level 2**：讓規格成為跟隨程式碼一起演進嘅活文件。 - **Level 3**：規格成為唯一真相來源，程式碼係生成出嚟嘅產物。 我接觸過嘅大多數開發者連 Level 1 都未到。佢哋仍然係以提示詞作為唯一輸入、程式碼作為唯一輸出嘅模式運作。細小任務係夠用，但複雜度一升上嚟就崩。 由 Level 1 升到 Level 2 只需要一個習慣：將規格檔案 commit 入 Git。由 Level 2 升到 Level 3 係一個工作流變化：需要改動程式碼嘅時候，先更新規格再重新生成。 今日就可以開始。用你嘅項目基本資料建立一個 CLAUDE.md，喺動任何程式碼之前為下一個功能寫一份 SPEC.md，睇睇有乜變化。差別會快速複利累積。 ## Related URLs - Author: https://tonylee.im/en/author/ - Publication: https://tonylee.im/en/blog/about/ - Related article: https://tonylee.im/zh-HK/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/zh-HK/blog/claude-code-layers-over-tools-2026/ - Related article: https://tonylee.im/zh-HK/blog/codex-folder-structure-why-config-breaks/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/zh-HK/blog/three-spec-files-before-ai-agent-coding/ ## 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-HK/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.