GitHub Spec Kit: spec-driven development với Claude Code từ A đến Z

"Vibe coding" chạy tốt với prototype, nhưng với tính năng thật thì một prompt mơ hồ dẫn tới code đúng cú pháp mà sai yêu cầu, và không ai nhớ vì sao agent chọn cách đó. Spec Kit của GitHub (repo github/spec-kit, khoảng 149 nghìn sao) đặt thêm cấu trúc vào giữa: viết đặc tả trước, biến đặc tả thành kế hoạch, kế hoạch thành task, rồi mới cho agent viết code. Mọi bước để lại file Markdown có thể review như code. Spec Kit chạy được với Claude Code và nhiều coding agent khác.

GitHub: https://github.com/github/spec-kit · khoảng 149 nghìn sao · Python · MIT · Tài liệu: github.github.io/spec-kit

Ba quy trình dựng sẵn

Từ bản 1.0, Spec Kit không chỉ là Spec-Driven Development (SDD). README mô tả ba "cửa vào" độc lập, không bắt buộc đi theo thứ tự:

Cài đặt với Claude Code

Cần Python 3.11+, uv và Claude Code. Integration key cho Claude Code là claude:

uv tool install specify-cli
specify init my-project --integration claude
cd my-project && claude

Dự án đã có code: chạy specify integration install claude trong thư mục dự án. Spec Kit cài các lệnh dưới dạng skill tại .claude/skills/speckit-*/SKILL.md, gọi trong khung chat của Claude bằng /speckit-….

Luồng SDD tối thiểu

Chạy trong khung chat của agent (không phải terminal), từng lệnh một, review kết quả trước khi sang bước sau:

/speckit-constitution Nguyên tắc: chất lượng code, test bắt buộc, dễ bảo trì.
/speckit-specify Ứng dụng quản lý ảnh, gom album theo ngày, xem trước dạng lưới.
/speckit-plan Dùng Vite + JavaScript thuần, ảnh lưu local, metadata trong SQLite.
/speckit-tasks
/speckit-implement
/speckit-converge

1. constitution: tạo một lần cho mỗi dự án, ghi các nguyên tắc mà mọi kế hoạch sau phải tuân theo.
2. specify: mô tả cái gì và vì sao, chưa nói công nghệ.
3. plan: lúc này mới chọn stack và kiến trúc.
4. tasks: chia kế hoạch thành task cụ thể.
5. implement và converge: lặp lại cho tới khi converge báo Converged, tức code đã khớp đặc tả.

Ngoài ra có các lệnh làm rõ yêu cầu, checklist và phân tích nhất quán (xem SDD walkthrough trong tài liệu).

Sửa lỗi và đánh giá ý tưởng

specify extension add bug
# trong chat:
/speckit-bug-assess "Gửi mật khẩu rỗng làm sập form đăng nhập." slug=login-crash
/speckit-bug-fix slug=login-crash
/speckit-bug-test slug=login-crash

Báo cáo nằm ở .specify/bugs/login-crash/; chỉ verified mới xác nhận đã sửa xong. Extension assess đi qua năm bước intake → research → define → shape → decide, lưu tại .specify/assessments/; ý tưởng được go có thể chuyển thẳng phần tóm tắt sang /speckit-specify.

Tuỳ biến cho tổ chức

Spec Kit có nhiều cơ chế ghép được: preset (đổi template, thuật ngữ, ép chuẩn nội bộ hoặc yêu cầu truy vết theo quy định), extension (thêm lệnh, quality gate, kết nối công cụ ngoài), workflow (tự động chuỗi lệnh, gate, shell), bundle (gói thiết lập theo vai trò) và catalog riêng cho tổ chức, kể cả chạy offline. Tìm thành phần bằng specify extension search, specify preset search…

Rủi ro và lưu ý

• Nặng với việc nhỏ: sửa một dòng CSS không cần đi qua sáu bước. Dùng SDD cho tính năng nhiều file hoặc nhiều người cùng làm.
• Chiếm chỗ trong danh sách skill: tài liệu tích hợp Claude nêu rõ mỗi skill Spec Kit mặc định đều để model tự gọi, nên mô tả luôn nằm trong context và có thể đẩy skill khác ra khỏi danh sách. Thêm --integration-options="--no-model-invocation" khi init để các lệnh core chỉ chạy khi bạn gõ /speckit-….
• Đặc tả tệ thì code tệ: Spec Kit chỉ ép quy trình; chất lượng vẫn nằm ở việc bạn review spec và plan. Bỏ qua bước review là mất toàn bộ lợi ích.
• Catalog cộng đồng không được kiểm toán: README nhắc rõ phải đọc mã extension cộng đồng trước khi cài.

Áp dụng thế nào?

• Dev: Thử SDD cho tính năng kế tiếp có ước lượng từ 2 ngày trở lên. So sánh số lần phải yêu cầu agent làm lại với cách prompt thường.
• Tech Lead: Viết constitution chung và một preset nội bộ (chuẩn test, bảo mật, logging). File spec/plan trong repo trở thành tài liệu thiết kế được review cùng PR.
• PM: Bắt đầu bằng extension assess để có quyết định go/kill dựa trên bằng chứng, rồi tham gia review bước specify, nơi yêu cầu nghiệp vụ được chốt.

Muốn phương án nhẹ hơn? Xem OpenSpec, một công cụ spec-driven khác đã có bài trên binhAI.