Skip to content

本頁由 AI 根據韓語原文翻譯,可能存在錯誤。

第3章 規劃與規格說明——接受訪談,寫出 SPEC.md ​

必讀 想跟著這個階段學下去,一定要讀這一章。

一句話總結:要做什麼還模模糊糊的時候,不要自己一個人全部理清楚,而是讓 Claude 來採訪你。訪談結束後,Claude 會把那些內容寫成 SPEC.md(規格說明書)。 規格說明講的不是"怎麼做",而是**"應該變成什麼樣"的約定**。這個約定,就是第4~6章裡製作、確認、評審的依據。

這一章依據 2026年11月1日確認的 Claude Code、GitHub 官方文件,以及 spec-kit、OpenSpec 倉庫裡的說明寫成。具體說明要交代什麼的要領,在 Claude Code 第5章學過了。這一章把那些要領擴充套件到"製作之前的階段"。

為什麼要先做規劃 ​

就像第1章看到的,AI 常常做出和我腦子裡想的不一樣的東西,常見的原因是缺了只讀倉庫是看不出來的資訊。[1] 那些資訊只在我腦子裡。比如誰來用、哪裡不方便、什麼事不做。

GitHub 的入門教程也說,寫程式碼之前,先把要做的東西記下來,並追蹤進度。[2]

說得越具體,來回修改的次數就越少。官方文件要求一開始就點明檔案、說出症狀,並說明"做完了"是什麼樣子。[3]

不夠好的例子更好的例子
做一個顯示待辦事項的頁面一個把會議紀要裡的待辦事項表彙總起來,按負責人、期限分別顯示的頁面。做完時,備忘裡的 5 個待辦事項必須全部看得到

來源:本指南的例子(要領來自官方文件)[3:1]

理解檢查

官方文件指出,AI 做出來的東西和我腦子裡想的不一樣,常見原因是什麼?

接受訪談,寫出 SPEC.md ​

想要的東西還不清楚也沒關係。官方文件說,不需要在寫提示詞之前全部想清楚,可以讓 Claude 來採訪你。[4] 把文件裡的示例譯成中文,大致是這樣。

我想做這樣一個東西,但還沒有深入想過。請先採訪我,直到能寫出規格說明為止,做完後寫進 SPEC.md。

這樣,Claude 會針對還沒有定下來的部分,用選擇題(從選項裡挑一個的問題)反過來問你。[5] 比如"待辦事項按負責人歸類,還是按期限歸類?"這種只要挑一個就行的問題。實際的問題每次都不一樣,從選項裡挑一個,或者用自己的話回答都可以。

如果是待辦事項看板,請求就會是這樣。

我想做一個網頁,把第3階段整理工具生成的會議紀要裡的待辦事項表彙總起來顯示。我還沒有深入想過。請先採訪我,直到能寫出規格說明為止,做完後寫進 SPEC.md。

SPEC.md 生成之後,在新會話裡讓它看著這個檔案來製作。這是為了從乾淨的上下文,以及用文字寫下來的"完成的定義"開始。[6] 這樣可以讓訪談中來回的那一長串對話,不要摻進製作過程裡。

做完之後,要對照 SPEC.md 來確認。 這件事,在第6章評審裡還會再講。

理解檢查

要做什麼還很模糊的時候,官方文件建議怎麼做?

好的規格說明是什麼樣 ​

規格說明裡寫的是從外面看得到的行為。意思是只寫看介面的人能察覺到的東西。如果是待辦事項看板的 SPEC.md,就會有這樣的句子。

好的句子不夠好的句子
會議紀要裡的待辦事項,一個不漏地都顯示出來用 JavaScript 讀取表格
過了期限的待辦事項,標記不一樣看起來漂亮
不顯示個人姓名,只顯示角色用整潔的程式碼來做

來源:本指南的例子

左邊的句子,可以用"是/否"來確認。 到了第5章,這些句子就直接成了確認的手段。

右邊的句子,是怎麼做(技術)或者模糊的感覺。下一節要看的規格說明工具,它們的說明書也是這麼說的。OpenSpec 的說明書說,規格說明"不是實現計劃,而是行為的約定",而且不改變外部可見行為的實現細節,通常不放進規格說明。[7] spec-kit 也說,在規格說明階段,應該專注於做什麼、為什麼,而不是技術,技術選擇要推遲到下一個計劃階段。[8]

理解檢查

在待辦看板的 SPEC.md 裡,適合寫進去的是哪一行?

規格驅動開發工具 ​

以規格說明為中心的開發方式,叫作規格驅動開發(Spec-Driven Development)。先定下要做什麼、為什麼做,再把那份規格說明變成計劃、任務、程式碼。[9] 幫助做這件事的工具有 spec-kit 和 OpenSpec。

本指南不安裝這兩個工具。 只靠上面學過的"訪談 → SPEC.md → 新會話"流程,也能實踐同樣的想法。這一節只記住名字就往下走也可以。

兩個工具都在中間留了人來確認的位置。

  • spec-kit(GitHub 做的工具):一個階段一個階段地執行規格說明 → 計劃 → 任務清單 → 實現,審查結果之後再往下走。[10]
  • OpenSpec(Fission-AI 做的工具):讓 AI 寫文件,而人在程式碼寫出來之前審查計劃。[11]

這和本指南流程裡閱讀並批准 SPEC.md 是同一個思路。

進一步瞭解這兩個工具(點選展開)
工具出品方做什麼
spec-kitGitHub分階段完成規格說明 → 計劃 → 任務清單 → 實現
OpenSpecFission-AI每次變更都建立提案、規格、設計、任務資料夾

來源:各工具的說明(只摘錄了一部分)[12][11:1]

安裝時需要另外的開發工具。spec-kit 需要 Python 3.11 及以上,以及叫 uv 的工具[13],OpenSpec 需要在終端安裝(或者 Node.js 22.12 及以上)。[14] Python、uv、Node.js 是用來執行程式的開發工具。跟著本指南做,一樣都用不到。以後做更大的專案時,再去了解它們。

理解檢查

這份指南是怎樣處理 spec-kit 和 OpenSpec 的?

動手試試 ​

  1. 在 Claude Code 應用裡,開啟第2章建的 todo-board 資料夾。
  2. 傳送上面的訪談請求,回答 Claude 的問題。不知道的話,說"給我推薦"也可以。
  3. 讀一讀生成的 SPEC.md,每一句都問問"能用是/否來確認嗎?"。不能的話,請它修改。
  4. 確認 SPEC.md 裡沒有放入真實姓名、聯絡方式(因為是公開倉庫)。
  5. 滿意的話,就留下記錄(提交)。

連續任務:第4章裡,我們會在新會話裡依據 SPEC.md 拿到計劃,並在分支上做出第一個畫面。

總結 ​

  • AI 常常做出離譜的東西,常見原因是缺了我腦子裡的資訊。製作之前先寫下來。
  • 不清楚的話,讓 Claude 採訪我,把結果寫成 SPEC.md。
  • SPEC.md 生成之後,在新會話裡製作。做完之後,對照 SPEC.md 檢查。
  • 規格說明裡寫的是從外面看得到的行為,而且要寫成能用是/否來確認。
  • spec-kit、OpenSpec 是幫助實踐同樣想法的工具。本指南不安裝。

術語整理 ​

術語中文名稱一句話解釋
Spec規格說明寫下應該變成什麼樣的約定
SPEC.mdSPEC.md 檔案寫著規格說明的檔案
Spec-Driven Development規格驅動開發先定規格說明,再據此製作的方式
Definition of done完成的定義"做完了"的標準

這一章讀完了嗎?

學習記錄只儲存在這個瀏覽器中。整體進度可以在 全部目錄中檢視。

下一章:第4章. 製作

參考資料(14 則)
  1. Claude Code 官方文件,「Best practices for Claude Code」。 "Claude built something different from what you had in mind, or it has to rediscover the same fact at the start of every session. It's missing information it can't get from reading the repo." code.claude.com (確認日期 2026-11-01) ↩︎

  2. GitHub 官方文件,「Planning your work」。 "Before you write code, capture what you want to build and track your progress." docs.github.com (確認日期 2026-11-01) ↩︎

  3. Claude Code 官方文件,「Best practices for Claude Code」。 "If you name the file, describe the symptom, and say what "fixed" looks like up front, you usually save yourself a round of corrections later." code.claude.com (確認日期 2026-11-01) ↩︎

  4. Claude Code 官方文件,「Best practices for Claude Code」。 "When you don't know exactly what you want yet, you don't have to work it all out before you prompt. Ask Claude to interview you instead:" code.claude.com (確認日期 2026-11-01) ↩︎

  5. Claude Code 官方文件,「Best practices for Claude Code」。 "Claude comes back with multiple-choice questions about the parts you haven't pinned down: per-user versus per-key limits, what happens to requests over the limit, what's out of scope." code.claude.com (確認日期 2026-11-01) ↩︎

  6. Claude Code 官方文件,「Best practices for Claude Code」。 "Once SPEC.md exists, start a fresh session to build from it, so the build begins with a clean context and a written definition of done." code.claude.com (確認日期 2026-11-01) ↩︎

  7. OpenSpec 文件,「Concepts」。 "A spec is a behavior contract, not an implementation plan." / "If implementation can change without changing externally visible behavior, it likely does not belong in the spec." github.com (確認日期 2026-11-01) ↩︎

  8. spec-kit 文件,「Spec-Driven Development Quickstart」。 "Creates the feature specification from a natural-language description. Focus on the what and why, not the tech stack." github.com (確認日期 2026-11-01) ↩︎

  9. spec-kit README. "Define what to build and why, then turn the specification into a plan, tasks, and working code." github.com (確認日期 2026-11-01) ↩︎

  10. spec-kit README. "Create a constitution once per project and repeat the remaining steps for each feature. Run these skills in your agent's chat, not your terminal, one at a time, reviewing each result before continuing." github.com (確認日期 2026-11-01) ↩︎

  11. OpenSpec README. "Stay organized — each change gets its own folder with proposal, specs, design, and tasks" / "Your AI writes these; you review the plan before any code is written." github.com (確認日期 2026-11-01) ↩︎

  12. spec-kit README. "Spec Kit is an open source toolkit that gives AI coding agents structured processes, reusable templates, and documented outcomes." github.com (確認日期 2026-11-01) ↩︎

  13. spec-kit README. "You need Python 3.11+, uv, and a supported AI coding agent on Linux, macOS, or Windows." github.com (確認日期 2026-11-01) ↩︎

  14. OpenSpec README. "Install OpenSpec. On macOS or Linux, in your terminal:" / "(needs Node.js 22.12.0 or higher)" github.com (確認日期 2026-11-01) ↩︎