GitHub Spec Kit — Spec-Driven Development: Viết đặc tả trước, để AI coding agent làm đúng việc

Chiều thứ Sáu, bạn giao cho Claude Code một yêu cầu nghe rất rõ ràng: “thêm tính năng đăng nhập cho app”. Một giờ sau, agent trả lại hệ thống đăng nhập hoàn chỉnh — JWT với Redis, tự viết lại middleware auth đang chạy tốt. Vấn đề: app của bạn dùng session cookie với PostgreSQL, và không có Redis nào trong hạ tầng.

Vấn đề không phải agent yếu, mà là thiếu bản đặc tả làm hợp đồng trước khi code. Không có tài liệu ghi rõ “đúng” nghĩa là gì, agent chỉ còn cách tự suy diễn — Spec Kit lấp khoảng trống đó.

Khi AI coding agent viết code rất nhanh — nhưng sai hướng

Một yêu cầu như “làm tính năng đăng nhập” chứa hàng chục quyết định ẩn: cơ chế nào, lưu ở đâu, validation ra sao, lỗi xử lý thế nào. Không ghi ra, agent tự chọn thay bạn.

Hệ quả: review tốn hơn viết tay, quyết định kiến trúc nằm rải rác trong lịch sử chat, team không có tài liệu chung về “đúng là gì”. Prompt dài hơn không khắc phục được — prompt biến mất sau phiên chat, không version hay review được như code. Thứ cần có là bản đặc tả lưu trong repo, làm tiêu chuẩn đối chiếu khi code xong: đó là Spec-Driven Development.

GitHub Spec Kit là gì?

Spec Kit, hay Specify CLI, là repo github/spec-kit, giấy phép MIT, đạt 147.881 stars và 13.270 forks tính đến ngày 2026-11-06. Bản mới nhất là v1.3.1 (2026-11-05); project cũng lọt top GitHub Trending ngày 2026-11-05 (theo bản tin trending).

Spec-Driven Development (SDD) nghĩa là: viết đặc tả trước, lập kế hoạch, chia task, để agent triển khai, rồi đối chiếu với spec cho tới khi hội tụ — Converged.

Cần phân biệt rõ: Spec Kit không phải AI model, không phải IDE, không tự chạy test thay bạn. Nó là bộ khung quy trình cộng template prompt cho agent bạn đã dùng, trong số hơn 40 integration.

Ba lối vào độc lập

• Xây tính năng (SDD): constitution → specify → plan → tasks → implement → converge.
• Sửa bug: cài extension specify extension add bug, rồi chạy trong chat của agent, ví dụ /speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash, tiếp theo /speckit-bug-fix slug=login-crash và /speckit-bug-test slug=login-crash. Báo cáo nằm trong .specify/bugs/login-crash/; verdict cuối: verified, partial hoặc failed.
• Đánh giá ý tưởng: cài extension specify extension add assess, rồi chạy chuỗi /speckit-assess-intake tới /speckit-assess-decide — quyết định go, needs-clarification hoặc kill.

Cả ba luồng chung một triết lý: ghi ra trước, kiểm chứng sau — một quyết định kill có ghi lý do cũng là kết quả hữu ích.

Spec Kit hợp với backend/full-stack developer, DevOps/SRE và bất kỳ ai đã dùng AI coding agent thường xuyên trên task vừa và lớn, đặc biệt khi làm việc nhóm cần spec chung để review trước khi code. Ngược lại, nó thừa cho script một lần 20 dòng hay lỗi vặt sửa trong năm phút. Về phương pháp làm việc với AI coding agent, xem thêm bài Superpowers; về chuyển provider, xem bài cc-switch.

Kiến trúc: đặc tả là file Markdown, agent là executor

specify-cli là một thin scaffolder: nó cài đặt template prompt và khởi tạo cấu trúc project, chứ không phải runtime thực thi code. Trạng thái của toàn bộ quy trình nằm trong các file Markdown dưới thư mục .specify/: nguyên tắc dự án dùng chung nằm ở .specify/memory/constitution.md; mỗi tính năng có thư mục riêng .specify/specs/<NNN>-<tên-tính-năng>/ chứa spec.md (WHAT và tiêu chí nghiệm thu đo được), plan.md (HOW — kiến trúc, tech stack) và tasks.md (checklist có thứ tự).

Vì các artifact này là file Markdown trong repo, chúng được version bằng Git và review được như code.

Các lệnh SDD chạy trong chat của agent, không phải terminal, chạy từng lệnh một, review kết quả trước khi sang bước tiếp theo.

Sơ đồ luồng dữ liệu và vòng lặp converge

flowchart TD
    A["Ý tưởng mơ hồ của người dùng"] --> B["Constitution<br/>.specify/memory/constitution.md"]
    B --> C["Specify<br/>.specify/specs/001-.../spec.md: WHAT + acceptance criteria"]
    C --> D["Plan<br/>plan.md: HOW, kiến trúc"]
    D --> E["Tasks<br/>tasks.md: checklist có thứ tự"]
    E --> F["Implement<br/>Agent sửa code theo từng task"]
    F --> G["Converge<br/>Đối chiếu code với spec"]
    G -->|Chưa Converged: ghi rõ điểm lệch| F
    G -->|Converged| H["Done: code + spec đã đối chiếu"]
    I["Bug-fix: spec → verify → verdict verified / partial / failed"]
    J["Idea-assessment: go / needs-clarification / kill"]
    I -. dùng chung cơ chế spec → verify → verdict .-> G
    J -. kết quả go thì chuyển thành spec .-> C

Mỗi bước sinh ra một artifact Markdown cụ thể; agent chỉ là executor, spec là source of truth; vòng lặp Implement ↔ Converge là vòng kiểm chứng, điểm dừng là Converged, không phải “agent bảo xong”.

Phụ thuộc kỹ thuật và giới hạn

Yêu cầu hệ thống: Python 3.11 trở lên, uv, và một AI coding agent được hỗ trợ, trên Linux, macOS hoặc Windows. Spec Kit hỗ trợ hơn 40 integration, gồm Claude Code (claude), GitHub Copilot (copilot), Codex CLI (codex), Cursor (cursor-agent), Gemini CLI (gemini), opencode, DeepSeek Harness (dsh), cộng thêm none và generic. Quản lý bằng specify integration install/switch/status <key>. Phụ thuộc thực sự nằm ở agent: cùng một spec, hai agent có thể cho hai implementation khác nhau.

Có ba giới hạn cần nói thẳng. Thứ nhất, Spec Kit không có sandbox thực thi, test runner hay CI tích hợp sẵn — converge đối chiếu implementation theo spec, nhưng không thay thế test suite của project và review của con người. Thứ hai, prompt là template Markdown nên cách diễn giải có thể drift theo agent và phiên bản agent. Thứ ba, release đổi rất nhanh (v1.2.6 → v1.3.1 trong ba ngày) — hãy đối chiếu docs của đúng phiên bản đang dùng.

Hướng dẫn cài đặt và chạy SDD lần đầu

Chuẩn bị: Python 3.11 trở lên, uv đã cài, một AI coding agent đã đăng nhập, cùng một project mới hoặc repo Git sạch để lưu spec.

Phần này mình chưa chạy thử, chỉ đối chiếu tài liệu chính thức của dự án ở phiên bản v1.3.1.

Cài đặt specify-cli và khởi tạo project

uv tool install specify-cli
specify init my-project --integration copilot
cd my-project

Lệnh đầu cài CLI dạng isolated tool qua uv; lệnh thứ hai scaffold project và cấu hình integration cho agent đã chọn.

Để kiểm chứng, chạy specify --help và kiểm tra thư mục .specify/ đã được tạo trong project, kèm template constitution.

Chạy quy trình SDD 6 bước trong agent chat

Mở agent trong thư mục project, chạy từng lệnh trong chat và review kết quả trước khi sang bước sau:

1. /speckit-constitution — ghi nguyên tắc dự án: ngôn ngữ, kiến trúc, bảo mật, chuẩn test.
2. /speckit-specify — mô tả tính năng bằng ngôn ngữ thường, kèm acceptance criteria đo được. Agent viết spec.md trong thư mục của tính năng đó.
3. /speckit-plan — agent đề xuất kiến trúc và stack; bạn duyệt plan trước khi code.
4. /speckit-tasks — chia plan thành checklist có thứ tự.
5. /speckit-implement — agent triển khai theo từng task trong checklist.
6. /speckit-converge — đối chiếu implementation với spec và plan; lặp lại implement + converge cho tới khi báo Converged. Điểm dừng có kiểm chứng: đọc lại spec, chạy test và lint, review diff.

Lỗi thường gặp

• Chạy /speckit-* trong terminal thay vì trong chat agent. Các lệnh này là skill của agent, không phải lệnh shell.
• Spec mơ hồ, thiếu acceptance criteria. Quay lại bước specify, bổ sung tiêu chí đo được trước khi plan.
• Agent lệch spec ở bước implement. Dừng lại, chạy converge, ghi rõ điểm lệch rồi sửa spec hoặc task.

Sao lưu và rollback

Spec Kit không có rollback tự động — nó chỉ sinh file Markdown và code trong project. Cơ chế an toàn của bạn là Git: trước khi chạy /speckit-implement, commit sạch trạng thái hiện tại gồm cả các artifact trong .specify/; sau mỗi bước implement, commit riêng. Nếu implementation lệch khỏi spec tới mức không cứu được, git revert commit chứa code đó, giữ lại spec rồi implement lại.

Đánh giá kỹ thuật

Ưu điểm. Spec trở thành tài liệu sống: version bằng Git, review được, quyết định không nằm rải rác trong lịch sử chat. Agent-agnostic với hơn 40 integration: đổi agent hay provider không mất quy trình, vì spec mới là thứ portable — không phải lịch sử chat hay cấu hình agent. Có điểm dừng kiểm chứng (converge) và checklist task, giảm drift trên task lớn; ba lối vào — build, bug, idea — phủ nhiều việc hơn một prompt lẻ.

Nhược điểm và chi phí ẩn. Overhead viết spec và plan là có thật với task nhỏ, và quy trình đòi hỏi kỷ luật duyệt spec và plan — bỏ bước duyệt thì SDD suy biến thành prompt dài hơn, vòng lặp converge chỉ còn là agent tự xác nhận với chính mình. Chất lượng cuối cùng vẫn phụ thuộc agent và độ rõ của spec. Cũng cần nói rõ: không có số liệu độc lập nào chứng minh SDD giảm bao nhiêu rework hay tăng tốc bao nhiêu; template Markdown dễ drift theo agent và phiên bản.

Bảo mật và vận hành. Spec, plan và tasks là file nằm trong repo: tuyệt đối không ghi secret, token, credential hay dữ liệu khách hàng vào spec. Review diff của artifact như review code — một connection string lọt vào plan.md cũng nguy hiểm như lọt vào source code. Extension và catalog cộng đồng không được audit: coi extension lạ như dependency lạ — chỉ dùng nguồn tin cậy và review code trước khi chạy specify extension add.

Về vận hành, artifact Markdown nhẹ, không cần server hay hạ tầng mới. Chi phí thực sự là token và thời gian chạy agent, cộng thời gian review spec và plan.

So sánh với các lựa chọn cùng phạm vi

Prompt trực tiếp nhanh nhất cho task nhỏ nhưng tệ nhất về kiểm soát và drift. Superpowers là methodology bổ trợ cho Spec Kit chứ không phải CLI thay thế (chi tiết ở bài Superpowers), còn plan mode trong từng agent tiện nhưng khóa bạn vào một agent. Các công cụ SDD khác vẫn tồn tại, nhưng mình chưa đối chiếu được tài liệu chính thức của chúng nên không đưa vào bảng.

Kết luận so sánh: Spec Kit thắng ở tính portable và artifact chuẩn; thua ở overhead khi task quá nhỏ.

Use case thực tế

Doanh nghiệp / team backend: thêm một API endpoint với spec ghi rõ contract, validation và acceptance criteria; reviewer review spec.md và plan.md trước.

DevOps / SRE: viết spec cho script hoặc manifest triển khai, plan ghi rõ rollback và biến môi trường; converge đối chiếu checklist vận hành trước khi áp lên production.

Homelab / self-host: spec cho một service self-host ghi rõ cổng, volume, backup và biến môi trường, lưu cùng repo và docker-compose.

AI workflow cá nhân: dùng luồng idea-assessment (go/needs-clarification/kill) để loại ý tưởng trước khi code; dùng bug-fix extension để sửa lỗi có verdict thay vì sửa mò.

IT admin: đặc tả một công cụ nội bộ — nhập/xuất, phân quyền, log — trước khi nhờ agent viết, để bàn giao không phụ thuộc người viết prompt.

Kết luận

Hợp với developer và team đã dùng AI coding agent thường xuyên, làm task vừa và lớn, cần tài liệu và điểm dừng kiểm chứng. Không hợp với task một lần, sửa vặt, người chưa dùng agent nào, hoặc team không có thời gian review spec.

Theo mình, giá trị lớn nhất của Spec Kit không nằm ở bước implement — agent nào cũng viết code được — mà ở bước constitution, specify và plan.

Bước tiếp theo trong 30 phút: cài specify-cli, init một project thử với agent bạn đang dùng, viết một constitution ngắn, rồi chạy SDD cho một tính năng nhỏ có acceptance criteria đo được, converge tới khi báo Converged. Bắt đầu từ task nhỏ để đo overhead thực tế của team mình.

Bài học rút ra

1. Spec phải có acceptance criteria đo được, nếu không converge không có gì để đối chiếu.
2. Duyệt plan trước khi implement: bỏ bước này thì SDD mất tác dụng kiểm soát.
3. Lệnh /speckit-* chạy trong chat của agent, không phải terminal.
4. Đổi agent được vì spec là Markdown portable, nhưng chất lượng cuối cùng vẫn theo agent.
5. Extension và catalog cộng đồng phải review code trước khi dùng — chúng không được audit.
6. Release đang đổi nhanh (v1.3.0 → v1.3.1 chỉ trong hai ngày) — đối chiếu docs theo đúng phiên bản đang dùng.

Phạm vi kiểm chứng

Ngày kiểm tra: 2026-11-06. Nguồn: README và docs chính thức của github/spec-kit phiên bản v1.3.1, cùng GitHub API. Đã xác minh: repo, giấy phép MIT, số stars/forks, yêu cầu Python 3.11+ và uv, lệnh cài đặt và khởi tạo, 6 lệnh SDD, hơn 40 integrations, ba lối vào cùng verdict và quyết định tương ứng. SDD 6 bước là luồng mặc định; bug-fix và idea-assessment là extension opt-in (specify extension add bug / assess). Các số liệu trong bài là số liệu cấu hình và điểm-thời-gian, không phải benchmark; không có số liệu về mức giảm rework hay tăng tốc. Chưa test: cài đặt và chạy quy trình SDD thực tế chưa được thực hiện ở bước này — phần hướng dẫn chỉ đối chiếu tài liệu.

Tham khảo

• Repo chính thức: github/spec-kit
• Tài liệu: github.github.io/spec-kit
• Lịch sử phát hành: github/spec-kit releases
• Danh sách integrations: github.github.io/spec-kit/integrations
• Bài liên quan trên phamnam.me: Superpowers — phương pháp lập trình cho AI coding agent, cc-switch — chuyển provider AI coding agent