GitHub Spec Kit 实战（六）：/speckit.implement 怎么用、怎么审、怎么发现 spec 阶段的遗漏------五部曲收官
Spec Kit 五部曲最后一篇。前面五篇把"想清楚"的部分都讲完了------constitution 定规矩、specify 写需求、plan 做选型、tasks 拆工单。/speckit.implement 是真正动键盘的一步。
但这步和前四步完全不一样：
- 前四步 AI 在"写文档"，你审文档
- implement 阶段 AI 在"写代码 + 跑命令 + 改文件"------动作成本高、出错成本也高
implement 翻车方式更隐蔽：
- AI 写完代码，单元测试不跑（"我看着像对"）
- AI 把 TDD 顺序搞反------先写实现再补测试
- 阶段之间不切------Setup 还没跑通就进 Foundational
- 跑命令报错静默继续------"build 报了几个 warning，没事"
- spec 阶段的遗漏到 implement 才暴露------发现时已经写了一周
这篇文章拆 5 个 implement 阶段最值得守的关卡，外加 3 个"事后发现 spec 漏了"的实用补救方法。
implement 的 3 道门禁
implement.md 命令源码里写得很清楚，进 implement 之前要过 3 道门禁：
门禁 1：checklists 状态扫描
如果 checklists/ 目录存在：
Scan all checklist files in the checklists/ directory
For each checklist, count:
- Total items
- Completed items
- Incomplete items
Create a status table:
Checklist Total Completed Incomplete Status ux.md 12 12 0 ✓ PASS test.md 8 5 3 ✗ FAIL
任何 checklist 有 incomplete，命令会 STOP 并问用户：
"Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
AI 翻车点 1：用户答 "yes" 之后忘记 checklist 内容
我见过 AI 拿到 "yes" 后，直接进 implement，checklist 里那 3 个 incomplete 项被永久遗忘。半年后 PR review 时才被翻出来："咦，spec 里说要写并发安全 checklist，怎么没看到对应测试？"
正确做法 ：implement 启动前，先把 3 个 incomplete 项复制到 tasks.md 的 Final Phase。这样它们会跟着 task 一起被执行，不会丢。
门禁 2：5 份设计文档全部加载
implement.md 命令源码的"Load and analyze the implementation context"段：
- REQUIRED: Read tasks.md for the complete task list and execution plan
- REQUIRED: Read plan.md for tech stack, architecture, and file structure
- IF EXISTS: Read data-model.md for entities and relationships
- IF EXISTS: Read contracts/ for API specifications and test requirements
- IF EXISTS: Read research.md for technical decisions and constraints
- IF EXISTS: Read /memory/constitution.md for governance constraints
- IF EXISTS: Read quickstart.md for integration scenarios
注意 5 个 IF EXISTS ------AI 必须把所有可能存在的设计文档全部读 。不许挑着读。
AI 翻车点 2：只读 tasks.md 就开干
我看过的 AI session 一开始就只盯着 tasks.md，plan.md 里的 Phase 0 决策、research.md 里的 Alternatives 全部跳过。结果 ：AI 选了一个 tasks.md 没说但 plan 已经被否的方案，重蹈覆辙。
正确做法：在 constitution 里加一条治理规则：
markdown
### X. Implement Stage: Read All Design Docs
implement 阶段开始前必须显式列出已加载的设计文档：
- [ ] tasks.md
- [ ] plan.md
- [ ] data-model.md (if exists)
- [ ] contracts/ (if exists)
- [ ] research.md (if exists)
- [ ] constitution.md
- [ ] quickstart.md (if exists)
任意一份漏读即视为 implement 启动违规。这条写进 constitution 之后，AI 启动时必须先打一张表给你看。漏读哪份一眼看出。
门禁 3：Project Setup Verification
implement.md 命令源码第 4 步是 13 种技术栈对应 13 套 .gitignore / .dockerignore / .eslintignore / .prettierignore / .npmignore / .terraformignore / .helmignore 检测：
Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
Check if .eslintrc* exists → create/verify .eslintignore
Check if .prettierrc* exists → create/verify .prettierignore
...
这一步是 implement 阶段独有的 ------前四步不涉及 .gitignore 这种"项目级配置文件"。AI 必须先检测后创建，不许无脑追加。
AI 翻车点 3：检测到 .gitignore 后直接覆盖
我看过一个 implement session：
检测到项目有 .gitignore（包含 node_modules/、dist/、.env*）
AI 决定"重写"为标准模板
结果：项目自定义 的 patterns（
coverage/、vendor/、团队特定文件）被覆盖整个仓库的 build artifact 进了 git diff
正确做法：源码明文写：
If ignore file already exists : Verify it contains essential patterns, append missing critical patterns only
追加不覆盖 。这是 implement 阶段最容易忽略的细节------我把它写进 constitution 的硬规则里：
markdown
### XI. Implement Stage: Never Overwrite Project Files
implement 阶段对以下文件必须先检测再追加，禁止覆盖：
- .gitignore
- .dockerignore
- .eslintignore
- .prettierignore
- .env.example
- README.md
- .github/workflows/*.yml
追加位置用注释标 [SPEC-KIT APPENDED YYYY-MM-DD]。第一个关卡：阶段顺序不能跳
implement.md 命令的执行顺序是固定的：
- Phase-by-phase execution: Complete each phase before moving to the next
- Setup first: Initialize project structure, dependencies, configuration
- Tests before code: If you need to write tests for contracts, entities, and integration scenarios
- Core development: Implement models, services, CLI commands, endpoints
- Integration work: Database connections, middleware, logging, external services
- Polish and validation: Unit tests, performance optimization, documentation
Setup → Tests → Core → Integration → Polish。
AI 翻车点 4：Setup 还没跑通就进 Foundational
我看过的 AI session：
- T001 Create project structure per implementation plan
- T002 Initialize Go project with go.mod
- T004 Setup database schema and migrations framework ← Setup 阶段没跑通
- T005 Implement authentication/authorization framework ← 直接跳 Foundational
- T006 Setup API routing and middleware structure
T004 报"数据库连接失败"，AI 没停下，接着 T005 。结果 T005 写出来的 auth 框架基于一个不存在的数据库连接 ，全错。
正确做法 ：implement 阶段必须严格按 phase 切。每个 phase 完成时跑一次验证：
- Setup 完 ：能
make build/go build/npm run build - Foundational 完 ：能启动空服务（如
make serve跑通） - 每个 US 完：能跑 quickstart.md 的对应场景
- Final 完 ：能跑
make test+make lint+ quickstart.md 全场景
Source code 加 5 个 phase gate 命令：
makefile
.PHONY: gate-setup gate-foundational gate-us1 gate-us2 gate-polish
gate-setup:
@echo "[GATE 1] Setup phase validation"
@go build ./... || (echo "FAIL: build error" && exit 1)
@git status --short | grep -v "^\?\?" | head -1
gate-foundational:
@echo "[GATE 2] Foundational phase validation"
@go test -run TestBootstrap ./... || (echo "FAIL: bootstrap test" && exit 1)
@timeout 5 ./bin/server --version || (echo "FAIL: server won't start" && exit 1)每个 gate 是真命令，不是 echo 。AI 跑 gate 命令失败必须 halt，不能"接着试"。
第二个关卡：TDD 顺序不能反
implement.md 命令源码明文写：
- Follow TDD approach: Execute test tasks before their corresponding implementation tasks
AI 翻车点 5：先写实现再补测试
我看过的 AI session：
Tests for User Story 1
- T012 P US1 Contract test for upload CLI ← AI 直接跳过
- T013 P US1 Integration test for upload triggers album creation
Implementation for User Story 1
- T014 P US1 Create Photo model
...- T019 US1 Add error handling
- T020 US1 ← AI 自己加的 "Write tests for US1" ← TDD 顺序反了
T020 把测试写在实现之后 ------这是 TDD 的反面。测试是为了约束实现，不是为了"证明"实现。
正确做法：
- constitution 里写死 TDD（Principle III. Test-First NON-NEGOTIABLE 那种）
- tasks.md 的 Tests 段标
⚠️ REQUIRED (TDD per constitution Principle III) - implement 阶段每条 test task 必须 真的先跑失败一次 ------
make test跑出 FAIL，才能进 implementation
关键命令：
bash
# 每个 test task 完成时
go test -run TestUploadTriggersAlbum -v
# 预期输出:
# --- FAIL: TestUploadTriggersAlbum (test should fail first)
# PASS ← 不允许看到AI 看到 PASS 不能继续------必须 halt，告诉用户"测试已存在并通过，没遵循 TDD red-green-refactor"。
第三个关卡：每条 task 完成后必须标 X
implement.md 命令源码明文要求：
IMPORTANT For completed tasks, make sure to mark the task off as X in the tasks file.
这是 implement 阶段独有的"实时标记"机制 ------前四步不要求每条 task 完成时标 X，只有 implement 要。
AI 翻车点 6：批量标 X 而不是逐条标
我看过的 session：
Phase 3: User Story 1
- T012 P US1 Contract test ← AI 写完后没标
- T013 P US1 Integration test ← AI 写完后没标
- T014 P US1 Create Photo model ← AI 写完后没标
...- T019 US1 Add error handling ← 到这里 AI 一次标了 8 条 X
8 条 task 一次标 X ------你看不到哪条 task 中间失败过、哪条 task 跳过、哪条 task 重写过。事后回溯完全不可能。
正确做法：
- AI 写完一条 task → 立即标 X → 立即跑该 task 的 verification 命令
- verification 失败 → 标 （不标 X）→ halt
- verification 成功 → 标 X → 继续下一条
这条写进 constitution 硬规则：
markdown
### XII. Implement Stage: Per-Task Verification
每条 task 完成后必须立即：
1. 标 - [X] 在 tasks.md
2. 跑该 task 的 verification 命令（test / build / lint）
3. 输出 verification 结果
4. 失败时立即标回 - [ ] 并 halt
禁止批量标 [X] 或跳过 verification。审 implement 阶段最快的"过稿"方法 ：扫 tasks.md，任何一次 commit 里同时有 ≥3 条 X 标记得打回。
第四个关卡：错误处理------并行 vs 非并行
implement.md 命令的错误处理规则：
- Halt execution if any non-parallel task fails
- For parallel tasks P, continue with successful tasks, report failed ones
非并行 task 失败即 HALT 。并行 task 部分成功可以继续。
AI 翻车点 7：并行 task 失败不 halt
我看过的 session：
Implementation for User Story 1
- T014 P US1 Create Photo model ← 成功
- T015 P US1 Create Album model ← 成功
- T016 US1 Implement ExifParser ← 失败（EXIF 库找不到）
- T017 US1 Implement AlbumService ← 成功（但基于不存在的 ExifParser）
T016 失败，AI 继续 T017 。T017 写出来的代码引用了不存在的 ExifParser------T017 实际是失败的，但 AI 标了 X。
正确做法：
- T016 失败 → 立即 halt
- T016 标 （失败状态）
- 报告失败 + 失败原因 + 建议修复
- 用户确认后再继续 T017
审 implement 阶段最快的"过稿"方法 2 ：扫 git log，看到 X 的 task 接着 的 task，且中间没有"halt"或"failed"日志------打回。
第五个关卡：Completion Validation 三件套
implement.md 命令最后一步：
- Verify all required tasks are completed
- Check that implemented features match the original specification
- Validate that tests pass and coverage meets requirements
- Confirm the implementation follows the technical plan
4 项验证：
AI 翻车点 8：只看 1 就报完成
我看过的 completion report：
Completion Report
✅ All 47 tasks completed and marked X
✅ Implementation ready for review
就这两行 。spec 里的 FR-005 "相册不支持嵌套" 有没有被测试覆盖？plan 里的 "PG 用 JSONB 存 EXIF" 有没有被实现？------没说。
正确做法------给 implement 命令配一个收官 checklist 模板：
markdown
## Completion Report
### Task Completion
- Total tasks: 47
- Completed: 47 (100%)
- Failed: 0
### Spec Compliance
| Spec Section | FR | Implemented? | Test Coverage |
|--------------|----|----|----|
| User Scenarios & Testing | US1 (P1) | ✅ | contract + integration |
| Functional Requirements | FR-001 EXIF 拍摄日期 | ✅ | unit test |
| Functional Requirements | FR-002 年-月粒度 | ✅ | unit test |
| Functional Requirements | FR-003 倒序显示 | ✅ | integration |
| Functional Requirements | FR-004 拖拽重分组 | ⏳ | US2 task |
| Functional Requirements | FR-005 不嵌套 | ✅ | unit test |
| Success Criteria | SC-001 30s 上传 100 张 | ✅ | quickstart scenario 1 |
| Success Criteria | SC-002 5s 检索 | ✅ | quickstart scenario 2 |
| Success Criteria | SC-003 95% 首次用户 2min 完成 | ⏳ | needs UAT |
| Success Criteria | SC-004 拖拽反馈 1.5s | ⏳ | US2 + UAT |
### Constitution Compliance
| Principle | Status | Evidence |
|-----------|--------|----------|
| I. Library-First | ✅ | packages/photo-album-core/ 独立 |
| II. CLI Interface | ⚠️ | v1.1 计划（已记录在 Complexity Tracking）|
| III. Test-First (NON-NEGOTIABLE) | ✅ | Tests 段先于 Implementation 段，5/5 测试 task 先失败后通过 |
| IV. Integration Testing | ✅ | 6 个 integration test 通过 |
| V. Observability | ✅ | 所有服务调用都带 structured log |
### Test Coverage
- Unit: 87% (target ≥80%)
- Integration: 6 scenarios pass
- E2E: 3 scenarios pass (US1 only, US2/US3 待补)
### Plan Compliance
- Tech stack: Go 1.22 + PostgreSQL 16 + React 18 ✅
- Project structure: packages/ + apps/ ✅
- research.md 决策: PG 选型、JSONB 存 EXIF、单体 vs 微服务折中 ✅4 个表 + 覆盖率数字 + 决策引用 ------这就是一个合格的 completion report。任何缺一个表都打回。
事后补救：3 个"spec 漏了"的实用方法
implement 阶段最容易暴露 spec 阶段的遗漏。我用过的 3 个补救方法：
补救 1：发现 spec 漏了，立即写 ADR
implement 跑到一半发现------spec 里没规定错误处理策略。AI 停下来问你。
不要当场拍脑袋决定 。当场写 ADR：
markdown
# ADR-007: Photo Upload Error Handling Strategy
**Date**: 2026-06-15
**Status**: Accepted
**Context**: spec.md 未规定上传失败时的用户体验，
implement 阶段发现 P0 决策点。
**Decision**:
- 网络失败：3 次重试（指数退避），第 3 次失败后显示重试按钮
- EXIF 解析失败：fallback 到 uploaded_at，显示提示"无法读取拍摄日期，已用上传时间"
- 存储失败：上传中断，已上传部分保留为草稿
**Consequences**:
- 需在 US1 加 3 个 edge case 测试
- UI 组件需增加 retry 按钮和 toast 提示
- 需在 spec.md Assumptions 段补写"v1 网络重试上限 3 次"
**Reverts**: 任何重试次数变更需走 ADR 流程ADR 进 docs/adr/ ------这是和 spec 文档并列的项目级决策档案 。spec 写"做什么"，ADR 写"为什么这么做"。spec 补不到的就走 ADR。
补救 2：spec 漏写的"不做"加回 Assumptions
implement 跑到一半发现------spec 没禁止某件事，AI 自觉做了。例如 spec 没禁止"用户删除相册"，AI 加了删除功能。
不要 PR 时改 。当场加回 spec：
markdown
## Assumptions (amended 2026-06-15)
- ~~v1 不限制相册删除功能~~ (removed by implement)
- **v1 不支持相册删除**（amended 2026-06-15, ADR-008）:
- 误删风险高，UI 暂未设计二次确认
- 数据恢复机制 v2 引入
- 留作 v2.0 featurespec amend + ADR + tasks.md 同步删 task------三处同步。这才是真"规格驱动"。
补救 3：plan 阶段漏的"架构决策"补 Phase 1
implement 跑到 Phase 2 才发现------plan 阶段没说清楚 service 之间怎么通信 。AI 现场编了一个 HTTP REST，没经过 plan 阶段审。
不要接受 。当场回退：
- AI halt
- 写 ADR-009: Service Communication Strategy
- plan.md 加一段（同时改 Phase 0 research.md，加 Decision）
- tasks.md 补 task（T052: Implement gRPC clients in pkg/clients/）
- 回滚 implement 到 Phase 2 起点，重新跑
这一步成本高 ------但比"PR review 时发现架构混乱再重构"便宜 10 倍。spec-kit 工作流的意义就在这里：让遗漏在低成本阶段暴露。
写一个 30 分钟的"implement 启动清单"
我每次跑 implement 之前都先花 30 分钟做这一套：
[ ] 1. 加载所有设计文档，列一张表：
- [ ] tasks.md (xx tasks)
- [ ] plan.md (xx KB)
- [ ] data-model.md (xx entities)
- [ ] contracts/ (xx interfaces)
- [ ] research.md (xx decisions)
- [ ] constitution.md (xx principles)
- [ ] quickstart.md (xx scenarios)
任何缺漏立即 halt。
[ ] 2. 跑 checklist 状态扫描
任何 FAIL 项必须：
a) 立即补到 tasks.md 的 Final Phase
b) 给用户列出哪几项、为什么
[ ] 3. 跑项目级 setup verification
- [ ] git 仓库? (.git 存在)
- [ ] .gitignore 含必需 patterns? (按 plan.md tech stack 选)
- [ ] .dockerignore (有 Dockerfile 时)
- [ ] .eslintignore / .prettierignore (有对应配置时)
任何缺失先检测再追加，不许覆盖。
[ ] 4. 检查 phase gate 命令
- [ ] make gate-setup 命令存在
- [ ] make gate-foundational 命令存在
- [ ] make gate-us1 / us2 / us3 命令存在
- [ ] make gate-polish 命令存在
任何缺失先补 Makefile。
[ ] 5. 启动 implement
严格按 phase 顺序，每条 task 完成立即：
a) 跑该 task 的 verification 命令
b) 失败 halt，标 [ ]
c) 成功标 [X]，继续下一条
禁止批量标 [X]。30 分钟换 implement 阶段的稳定执行------值。
五部曲收官：一张表回顾
| 阶段 | 产出一份什么 | 翻车点 | 人该把关什么 |
|---|---|---|---|
| constitution | 项目宪法（≤2 页、≤7 条原则） | 太多、太软、不带 Sync Impact Report | 改完看 plan-template 是否强制检查 |
| specify | spec.md（无技术栈的 WHAT/WHY） | 写技术栈、堆功能、SC 是程序员视角 | 检查 NEEDS CLARIFICATION ≤ 3、PM 能验 SC |
| plan | plan.md + research.md + data-model.md + contracts/ + quickstart.md | 偷偷选型、Constitution Check 自审、DDL 进 spec、3 个 Option 全留 | Mechanical Check、真实路径、Alternatives 写 rejected |
| tasks | tasks.md（按 user story 拆的 task 清单） | 颗粒度爆炸、Story 串依赖、P 满天飞、Tests 段不该有 | 格式合规、依赖显式、Tests 段有据、Final Phase 克制 |
| implement | 真实代码 + tests + 配置文件 | 跳 phase、TDD 反、批量标 X、并行失败不 halt、completion report 缺项 | phase gate 真命令、逐条 verification、Completion Report 4 表 |
Spec Kit 工作流的核心思想：
人在最低成本阶段做最贵的决策 （spec 改一句话 = implement 改 50 行代码）
AI 在最低风险阶段做最多的活（生成文档比生成代码容易审）
写给正在考虑用 Spec Kit 的人
如果你看完了这 6 篇还没动手，只做一件事：
- 找一个 1 周能做完的小 feature（不是大项目）
- 跳过 constitution（直接用 Spec Kit 默认模板）
- 跑一遍 specify → plan → tasks → implement
- 记一篇博客------记"spec 阶段 AI 卡了你几次"、"implement 阶段一次通过率多少"
数据会说服你和你的团队。
如果你已经用了 1 个月以上，下一个进阶动作：
- 写自己项目的 constitution------把团队规范沉淀进去
- 把"硬规则"加到 plan-template 和 tasks-template------自动化检查
- 每次 implement 完做 retrospective------翻 spec 阶段漏了什么，写 ADR
Spec Kit 不是工具，是工作流 。用得越久，团队越离不开 ------因为你会被"spec 阶段改一句话" vs "implement 阶段改 50 行" 的成本差驯化。再也回不去了。