2026 年如何在 Claude Code 中設定 Spec Kit：以規格取代提示詞

2026 年 5 月，氛圍式編碼發生了什麼事？#

在接下來的一年裡，「氛圍式編碼」成了所有缺乏結構的 AI 代理工作方式的代名詞。

一年後，也就是 2026 年 2 月 4 日，他發布了一則回顧串文：

在 Sequoia Ascent 2026 的演講中，他說得更精確：「氛圍式編碼提高了底線——讓每個人都能在軟體上做到更多。代理式工程則維持了天花板——專業開發的品質門檻。」同一個舞台上，他還說了一句進入業界詞彙的話：「不能因為氛圍式編碼就引入漏洞。你仍然要像以前一樣，為自己的軟體負責。」

兩件事同時發生。2025 年 9 月，GitHub 發布了 Spec Kit 工具，在 8 個月內獲得 107,000 顆 stars。2026 年 2 月，AWS 發表詳細的藥物探索案例研究，報告「95% 的商業邏輯由規格產生，節省 80 多個小時」。

截至 2026 年 5 月底，英語資訊圈已形成共識：氛圍式編碼作為工作方法，屬於入門階段；接下來是 Spec-Driven Development。本指南將說明如何安裝並採用這種做法。

Spec Kit 與 Spec-Driven Development 是什麼？#

GitHub 官方文件用一句話概括這套方法的核心理念：

實際流程分成 4 個階段（Spec Kit 另外加上第 0 階段 constitution，後文會介紹）：

1. Specify - 用自然語言寫下你想要的規格：要做什麼，以及為什麼做；不是怎麼做。
2. Plan - 代理根據規格整理技術計畫：使用哪些技術、採用什麼架構，以及有哪些元件。
3. Tasks - 代理將計畫拆成具體、可驗證且附有相依關係的任務。
4. Implement - 代理（或其子代理）逐項處理任務並撰寫程式碼。

Implement 之後，現行版本的 Spec Kit 有一個名為 Converge 的驗證步驟：代理會檢查完成的程式碼是否符合規格、計畫和任務，並把遺漏項目加進 tasks.md。反覆執行 Implement 和 Converge，直到 Converge 回覆「Converged」。

每個階段在儲存庫中都是獨立的 Markdown 檔案。在 Claude Code 中，每個階段也有自己的斜線命令：/speckit-specify、/speckit-plan、/speckit-tasks、/speckit-implement；檢查命令則是 /speckit-converge。Spec Kit 文件以點號（/speckit.specify）寫出相同命令，但 Spec Kit 在 Claude Code 中會以技能形式安裝，呼叫時使用連字號。如果任何步驟出錯，就編輯 Markdown 檔案，再重新執行下一階段。

Spec Kit 是 SDD 的一種具體實作。到了 2026 年 5 月，它已支援 30 多種 AI 代理整合。在同一個儲存庫中，Spec Kit 可用於 Claude Code、Cursor、GitHub Copilot、Codex CLI、Windsurf、Qwen、Tabnine、Amazon Q、Gemini、Goose，以及另外十多種代理。

因此，一輪流程結束後，儲存庫不只包含程式碼，也包含規格、計畫和任務。一個月後回到專案時，你可以閱讀 spec.md，了解做了什麼、為什麼要這麼做。這不再是「氛圍式編碼，忘記程式碼存在」——這是專案的工作記憶。

不會寫程式碼的氛圍式編碼者為什麼需要它？#

Spec Kit 以 4 個斜線命令，將規劃拆成不同步驟。邏輯是：把「先想清楚」和「實際實作」分開，讓它們在不同的脈絡視窗中進行。每個階段都會得到乾淨的脈絡，不會被前一階段的內容弄得混亂。

對氛圍式編碼者來說，有三個具體好處：

• 可預測性。 當你告訴代理「做一個有電子郵件確認的註冊表單」，它會自行猜測 10 個細節，其中 3 個可能和你的想法不符。如果你有一份包含 User Stories、Acceptance Scenarios，以及每個不確定處都標記 [NEEDS CLARIFICATION] 的 spec.md，就不必猜測。
• 專案記憶。 一個月後，你不會記得在聊天中和代理討論了什麼。但 spec.md、plan.md 和 tasks.md 會和程式碼一起留在儲存庫的 specs/###-feature/ 資料夾中。它們不只說明做了什麼，也解釋為什麼這麼做。
• 擴充規模。 涉及 1-2 個檔案的功能，差異不明顯。涉及 20 個檔案和 5 個資料實體的功能，差別可能是「4 小時後全部重寫」或「4 小時後一切都已進入主分支」。AWS Kiro 在 TargetID 專案中展示了從規格自動化產生 95% 商業邏輯的成果。

氛圍式編碼最大的錯覺，是它一開始看起來比較快。半小時就有原型。但到了第一週，原型就會壞掉，直接丟掉反而容易。Spec-Driven Development 一開始會多花一點時間（1 小時而非半小時），但一週後你仍在同一個儲存庫中工作。

如何在 Claude Code 中安裝 Spec Kit（4 個步驟）#

步驟 1. 安裝 uv。 只需安裝一次，之後會留在系統中。

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

確認 uv 已安裝：

uv --version

步驟 2. 安裝 Spec Kit。 執行一個命令：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

確認：

specify --version

步驟 3. 初始化儲存庫。 進入專案資料夾（或建立新資料夾）並執行：

specify init --here --integration claude

--integration claude 旗標會直接選擇 Claude Code。若不加這個旗標，Spec Kit 會要求你從互動式清單選擇代理，也可能詢問腳本類型（macOS 和 Linux 使用 sh）。如果資料夾不是空的，Spec Kit 會警告它將合併檔案；請先提交你的工作，再加上 --force 旗標重跑命令。

之後，儲存庫中會出現以下內容：

.specify/
  memory/
    constitution.md        # 專案規則，由 /speckit-constitution 填寫
  scripts/
  templates/
    spec-template.md
    plan-template.md
    tasks-template.md
.claude/
  skills/
    speckit-constitution/SKILL.md
    speckit-specify/SKILL.md
    speckit-clarify/SKILL.md
    speckit-plan/SKILL.md
    speckit-checklist/SKILL.md
    speckit-tasks/SKILL.md
    speckit-analyze/SKILL.md
    speckit-implement/SKILL.md
    speckit-converge/SKILL.md
    speckit-taskstoissues/SKILL.md

步驟 4. 開啟 Claude Code 並確認斜線命令。 在同一個資料夾中執行：

claude

在工作階段中輸入 /speckit，建議清單中應會出現 /speckit-* 命令。如果沒有出現，請重新啟動 Claude Code，讓它重新讀取 .claude/skills/。如果專案根目錄已有 CLAUDE.md，Spec Kit 不會更動它，而是透過 .specify/memory/constitution.md 與它並行運作。

Spec Kit 也可以不搭配 Claude Code 使用（支援 30 多種代理），但本指南介紹的是與 Claude 搭配的設定方式。如果你想立刻安裝兩個工具，可以參閱設定 CLAUDE.md和Claude Code 的 Plan Mode的獨立指南。

Spec Kit 是「代理聘用契約」的第一個建構元件。完整設定包含三者：AI 分身（以 Skills 和子代理呈現你的方法論）、第二大腦（代理每次都會回訪的 business/ 結構），以及脈絡工程（Spec Kit、Plan Mode、/compact）。這三大支柱是避免 AI 產生幻覺的基礎。

如何撰寫第一份規格（Specify）#

在 Claude Code 中輸入：

/speckit-specify

接著代理會詢問功能描述。這個階段請用平常的語言，不要使用技術術語：

我想在應用程式中加入註冊表單。使用者輸入電子郵件
和密碼後會收到確認信，確認後進入儀表板。確認期限為 48 小時；期限到仍未確認的
帳戶，應在其後 5 分鐘內刪除，絕不刪除已確認帳戶。

此示意已把刪除容忍時間釐清為 48 小時到期後 5 分鐘。真實產品應在 Plan 前確認；精確 48 小時期限需更強設計與測試。代理會建立 specs/001-registration/spec.md，開啟可見類似結構：

# Feature Specification: User Registration

**Feature Branch**: `001-registration`
**Created**: 2026-05-31
**Status**: Draft
**Input**: User Description: "I want a registration form..."

## User Scenarios & Testing *(mandatory)*

### Primary User Story
As a new user, I want to register an account with email confirmation,
so that I can access the dashboard with a verified identity.

### Acceptance Scenarios
1. **Given** I am on the registration page,
   **When** I submit valid email and password,
   **Then** I receive a confirmation email within 1 minute.
2. **Given** I clicked the confirmation link within 48 hours,
   **When** I land on the dashboard,
   **Then** I see my email confirmed in profile.
3. **Given** 到 48 小時期限仍未確認，
   **When** 清理於其後 5 分鐘內執行，
   **Then** 刪除帳戶並釋出信箱供重新註冊。
4. **Given** 帳戶未滿 48 小時或已確認，
   **When** 清理執行，
   **Then** 不刪除帳戶。

## Requirements *(mandatory)*

### Functional Requirements
- **FR-001**: System MUST accept registration via [NEEDS CLARIFICATION:
  email/password only, or also SSO/OAuth?]
- **FR-002**: System MUST send confirmation email within 60 seconds
- **FR-003**: 確認 MUST 在 48 小時到期；系統 MUST
  在期限後 5 分鐘內刪除仍未確認帳戶，且 MUST NOT 刪已確認帳戶
- **FR-004**: System MUST log all registration attempts for [NEEDS
  CLARIFICATION: how long do we retain logs - 30 days, 90 days, forever?]

### Key Entities
- User: email, password_hash, email_verified_at, created_at, deleted_at
- ConfirmationToken: token, user_id, expires_at, used_at

## Success Criteria *(mandatory)*
- **SC-001**: 95% of confirmation emails delivered within 60 seconds (p95)
- **SC-002**: 0 accidental deletions of confirmed accounts
- **SC-004**: 48 小時前不刪除；受測負載下，所有符合條件的
  未確認帳戶都在年齡 48 小時 5 分鐘前刪除
- **SC-003**: Registration completion rate > 60% (from form open to dashboard)

請留意 [NEEDS CLARIFICATION: ...] 標記。Spec Kit 會刻意在你的文字沒有提供明確答案之處插入標記。進入 Plan 階段前，你必須在 spec.md 手動回答，或執行 /speckit-clarify，讓代理在對話中逐一詢問不清楚的地方。

在 Spec Kit 中，內建的 /speckit-clarify 命令取代了口頭說「請問我問題」。效果相同：在 spec.md 中不再有 [NEEDS CLARIFICATION] 標記之前，不要進入 Plan。

spec.md 裡不應有任何技術。不要提到 React、Postgres、Prisma 或 Redis。規格要從使用者和業務的角度描述系統會做什麼。技術堆疊留待下一階段處理。

Claude 在 Plan 階段會做什麼？#

spec.md 準備好後，執行：

/speckit-plan

也可以直接在命令中提供技術提示：

/speckit-plan Next.js App Router, Prisma, PostgreSQL, Resend for email

Claude 會讀取三種來源：spec.md、CLAUDE.md（或 memory/constitution.md），以及儲存庫中的既有程式碼。輸出的 plan.md 大致如下：

# Implementation Plan: User Registration

## Technical Context
- Framework: Next.js 14 App Router
- Database: PostgreSQL via Prisma
- Email: Resend (single transport)
- Validation: Zod schema in shared lib
- Auth: NextAuth.js with credentials provider

## Architecture Decisions

### 1. Token storage
Tokens stored in DB (table ConfirmationToken), not in JWT.
Reason: need server-side revoke on email re-register.

### 2. Email delivery
Async via cron `/api/cron/send-confirmation` triggered immediately
after registration. Retries handled by Resend.

### 3. Auto-delete cron
每分鐘執行 `/api/cron/cleanup-unconfirmed`，只刪除符合
created_at <= NOW() - INTERVAL '48 hours' AND email_verified_at IS NULL。
本例釐清可容忍最多 5 分鐘延遲，應驗證排程落後與執行時間；
超出上限要回報失敗，不能當每日清理成功。

## Data Model
See data-model.md

## API Contracts
See contracts/
- POST /api/auth/register
- POST /api/auth/confirm
- GET /api/auth/resend-confirmation

## Implementation Phases
1. Database migration (Prisma schema + migration file)
2. API routes (3 endpoints)
3. UI: registration form + confirmation success page
4. Cron jobs (send + cleanup)
5. Email template
6. Integration tests

data-model.md 會描述實體及彼此關係。contracts/ 將包含 API 契約雛形（OpenAPI YAML 或 TypeScript 要求／回應型別）。這些不是程式碼，而是 Claude 之後會轉成實際路由的設計意圖。

Plan 階段的主要優點是脈絡乾淨。Claude 不必同時記住規格和實作，而是先思考、將決策記錄在檔案中，再繼續下一步。

接下來有一個選用的 /speckit-analyze 命令。在 Tasks 階段後、Implement 階段前執行：它會檢查 spec.md + plan.md + tasks.md 是否互相矛盾，並確認計畫與任務涵蓋了規格中的所有要求。它不會編輯檔案，只會產生報告。本質上，這是在實作前正式做一次合理性檢查。

如何把工作拆成任務（Tasks）#

有了 spec.md 和 plan.md 後，執行：

/speckit-tasks

Claude 會把計畫展開成 tasks.md：

# Tasks: User Registration

## Phase 1: Database (no dependencies)
- [ ] T-001: Add User model to prisma/schema.prisma (parallel-safe)
- [ ] T-002: Add ConfirmationToken model to prisma/schema.prisma (after T-001)
- [ ] T-003: Generate migration `add-user-registration` (after T-002)

## Phase 2: API contracts (no dependencies)
- [ ] T-004: Create Zod schemas in shared/validation/auth.ts
- [ ] T-005: Define TypeScript types in shared/types/auth.ts (after T-004)

## Phase 3: Routes (depends on Phase 1+2)
- [ ] T-006: Implement POST /api/auth/register
- [ ] T-007: Implement POST /api/auth/confirm
- [ ] T-008: Implement GET /api/auth/resend-confirmation

## Phase 4: UI (parallel with Phase 3)
- [ ] T-009: Build /register page with form
- [ ] T-010: Build /register/confirm/[token] page
- [ ] T-011: Build /register/success page

## Phase 5: Cron + integration (depends on Phase 3+4)
- [ ] T-012: Cron /api/cron/send-confirmation
- [ ] T-013: Cron /api/cron/cleanup-unconfirmed
- [ ] T-014: Email template registration-confirmation.tsx
- [ ] T-015: Integration tests (Playwright)，包含未滿 48h、
  正好 48h、48h 5m 前刪除、延遲工作失敗及已確認帳戶保護

## Notes
- T-001, T-004, T-009-T-011 are parallel-safe (different files)
- T-002 conflicts with T-001 (same file: schema.prisma) - run sequentially
- T-006 needs T-003 (migration applied) and T-005 (types)

注意 parallel-safe 和 after T-NNN 標記。這就是日後可讓多個階段平行執行的相依關係圖。Spec Kit 加速流程的基礎就在這裡：有些任務可以交給 5 個不同的 Claude Code 工作階段同時處理，有些則必須嚴格依序進行。

Spec Kit 可用一個命令自動完成這件事，開箱即可使用。

選用的 /speckit-taskstoissues 命令會讀取 tasks.md，並依照清單建立 GitHub Issues，每個 Issue 都會連回 spec.md。如果你和團隊一起工作，或想透過 GitHub Projects 追蹤進度，這項功能很實用。

如何用子代理實作（Implement）#

/speckit-implement

Claude 從 tasks.md 的第一項任務開始。每項任務都經過一個小型循環：讀取相關檔案、撰寫差異、執行測試、勾選 [x]。需要時會自動呼叫子代理：一個負責程式碼審查，一個負責執行 linter，另一個負責檢查回歸問題。

他另外也談到規則：

在 Spec Kit 中，這個循環已正式化。你有作為唯一可信來源的 spec.md、記錄技術決策的 plan.md，以及核取清單 tasks.md。如果 Claude 在任何一步偏離方向，就回到規格並指出：「這不符合 FR-003，請重做。」不需要冗長地提醒「記得我們討論過什麼……」——完整紀錄都在檔案裡。

如果你已連接 Opus 4.8 的 Dynamic Workflows，就可以讓 Spec Kit 完全自動化：執行一次 /speckit-implement，Claude 就會平行處理工作、整合結果並檢查。上限是同時執行 1000 個子代理。大多數功能使用 10-30 個就足夠。

所有 [x] 項目都勾選完成，而且下一節的檢查回覆「Converged」後，就審查 PR（任務很多時可能是一系列 PR），然後合併。spec.md、plan.md 和 tasks.md 這些產物會留在儲存庫，成為功能文件。一年後，你不必從程式碼逆向推敲邏輯。

如何檢查代理是否遺漏內容（Converge）#

/speckit-converge

代理會先提供發現內容的摘要，並標示嚴重程度，接著回報兩種結果之一。「Converged」代表沒有遺漏，tasks.md 的位元組內容完全未變，可以進入審查。「Tasks appended」代表找到了遺漏項目，並已將它們加入 tasks.md 的 Convergence 區段；代理也會告訴你新增了幾項。

Converge 不會編輯或刪除程式碼；唯一的寫入操作是在 tasks.md 中新增任務。因此你可以放心執行，但前提是 /speckit-implement 已經處理完目前的 tasks.md。每次再執行，找到的遺漏都會減少。

Spec Kit 和 CLAUDE.md、Plan Mode 有什麼不同？#

用 5 項特性比較：

用 Spec Kit 的說法，這就是 .specify/memory/constitution.md。初始化時，Spec Kit 可以將現有 CLAUDE.md 作為 constitution 的基礎，也可以在旁邊建立獨立檔案。我通常讓 CLAUDE.md 保持全域「契約」的角色（技術堆疊、詞彙表、部署流程），並將 Spec Kit constitution 用於功能專屬規則，例如「所有表單都透過 Zod 驗證，不做手動檢查」。

Plan Mode 的關係比較簡單。Plan Mode 是單一工作階段內快速「寫程式之前先規劃」的模式。它適合小型變更（修正錯誤、重構函式）。對大型功能而言，Plan Mode 就不夠用了，因為單一工作階段的脈絡視窗不足以容納 3000 行的計畫。我在直播中直接解釋過：

Spec Kit 是一種具體的脈絡工程工具。它把「架構桌布」從聊天移到檔案中。Spec.md 留在儲存庫裡，每個新的 Claude 工作階段都會重新讀取；你不必一再重複說明。

大型專案可以這樣設定：

1. CLAUDE.md - 技術堆疊、詞彙表、禁止事項。放在根目錄。
2. .specify/memory/constitution.md - Spec Kit 專用、適用於這套工作流程的規則。
3. specs/001-feature-A/spec.md、plan.md、tasks.md - 第一個功能。
4. specs/002-feature-B/spec.md、plan.md、tasks.md - 第二個功能。
5. 日常工作可使用 /speckit-implement（處理已準備好的任務）或 /plan（變更前快速再確認）。

實際有哪些案例有效？#

具體案例：

• AWS Kiro——藥物探索代理。 在一篇日期為 2026 年 2 月 18 日的 AWS Industries 部落格文章中，團隊介紹了 TargetID 專案。3 位開發者、3 週時間，打造一個藥物探索代理。文章中的數據是：Kiro 產生了超過 95% 的商業邏輯程式碼，節省 80 多個開發小時。此外還提到：「Kiro 撰寫的 README 文件估計替我們節省了 8 小時」，以及「反覆提示和修正的循環減少了 40%」。
• Rackspace Technology。 同一篇 AWS 部落格中，Rackspace 報告：「僅用 3 週就完成預估 52 週的工作」，「效率提升 90%」。這不再是小功能，而是完整的企業專案。
• GitHub Spec Kit 的成長。 儲存庫截至 2026 年 5 月 31 日有 107,000 顆 stars。

對讀者來說，這表示這套方法不是紙上談兵：已有認真的團隊在正式環境中使用它。

哪些情況不適合使用 Spec Kit？#

不適用情況 #1——小型修改。 如果工作只是「重新命名變數」、「修正文案中的錯字」或「新增一筆記錄」，跑完 Specify → Plan → Tasks 所花的時間會比修改本身還久。小型修改使用 Plan Mode，或直接在 Claude Code 下提示詞更快。

不適用情況 #2——即時實驗。 當你還不知道自己要什麼，必須在介面裡「摸索」，或快速拼出原型看看「效果好不好」時，寫規格毫無意義。價值就在於你正在即興探索。在「玩點子」的階段，真正有效的是氛圍，而不是規格。

不適用情況 #3——狀態複雜的舊程式碼。 商業邏輯快速變動時，維護規格會成為負擔。

另一項風險是產生錯誤的掌控感：結構雖然優雅，但代理常常忽略指示，或反過來，過度照著範本執行。結果可能是結構正確，卻不符合你的特定儲存庫；規格無法保證代理按照你的意圖理解內容。

業界分析人士曾警告瀑布式開發：在寫程式碼之前先撰寫大型規格，這條路早在 200 頁需求文件的年代就曾讓整個產業陷入困境。從那時起，工程師對這種做法一直很謹慎，而且這種警戒有其道理。

如何處理。 我建議一條簡單規則：比較功能規模和撰寫規格所需的時間。如果功能實作時間不到 2 小時，就不要寫規格——Plan Mode 更快。如果功能要花一週，就一定要用 Spec Kit；節省的時間會是那一小時規格撰寫時間的五倍。介於 2 小時和一週之間時自行判斷。不過我個人連半天就能完成的功能也會寫規格，因為產物留在儲存庫中的價值，勝過省下 30 分鐘。

接下來怎麼做：如何將 Spec Kit 整合進專案？#

接下來 7 天可以這樣安排：

• 第 1 天。 安裝 uv 和 Spec Kit（5-10 分鐘）。確認 Claude Code 中已出現 /speckit-* 命令。先不要套用到既有專案，從新專案開始。
• 第 2 天。 選一項準備開發的實際功能。用自由形式的描述執行 /speckit-specify。打開 spec.md 閱讀，並回答每個 [NEEDS CLARIFICATION]。不要急著進入 Plan。
• 第 3 天。 執行 /speckit-plan，並附上技術堆疊提示。閱讀 plan.md，特別是 Architecture Decisions 區段。若有不合適的內容，手動編輯。
• 第 4-5 天。 執行 /speckit-tasks，再執行 /speckit-analyze 以重新檢查規格、計畫和任務，接著執行 /speckit-implement。觀察 Claude 如何在 tasks.md 中勾選 [x]。它可能會卡住，這很正常。回到 spec.md 澄清需求，再指定特定任務重新啟動 /speckit-implement。任務完成後執行 /speckit-converge，重複 Implement 和 Converge，直到收到「Converged」。
• 第 6-7 天。 審查 PR（或一系列 PR），並合併。閱讀你的 spec.md 和 plan.md——它們會是接下來一年的功能文件。

建議同時閱讀：

• 如何在 2026 年設定 CLAUDE.md - Spec Kit constitution 的基礎。
• Claude Code 的 Plan Mode - 小型任務的快速替代做法。
• 2026 年的脈絡工程 - Spec Kit 為何有效。
• Skills、Subagents、MCP 或 Plugins - 在 Spec Kit 上加入哪些工具以配合工作流程。
• Claude Code 的 Dynamic Workflows - 如何在 Implement 階段一次啟動多個子代理。

完整脈絡工作流程：AI 分身 + 第二大腦 + 脈絡工程。

更多資料請見 Ailoot。