spec-kit: viết đặc tả trước, AI code theo sau — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về github/spec-kit — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: spec-kit: viết đặc tả trước, để AI code theo — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
Spec Kit là bộ công cụ mã nguồn mở của GitHub, gồm một công cụ dòng lệnh tên specify cùng các mẫu và quy trình dựng sẵn cho AI coding agent như GitHub Copilot. Bạn dùng nó để viết đặc tả trước rồi mới cho AI lập kế hoạch và viết code, thay vì ra lệnh rời rạc. Cài đặt khá gọn: cần Python 3.11 trở lên, công cụ uv và một AI coding agent được hỗ trợ.
Spec Kit là một bộ công cụ mã nguồn mở của GitHub, giúp AI coding agent (như GitHub Copilot) làm việc theo quy trình có cấu trúc thay vì nghe một câu lệnh rồi code ngay. Repo có công cụ dòng lệnh tên specify, cộng với các mẫu (template) và quy trình dựng sẵn để AI ghi lại mọi thứ thành tài liệu: đặc tả, kế hoạch, danh sách việc, kết quả kiểm tra.
Bạn nên xem qua nếu từng nhờ AI viết một ứng dụng, chạy được lần đầu rồi sa lầy vì AI hiểu sai ý hoặc quên mất yêu cầu ban đầu. Spec Kit bắt bạn (và AI) viết rõ «xây cái gì, vì sao» trước, rồi mới đến «xây thế nào». Người làm kinh doanh, người mới học lập trình hay dev lâu năm đều dùng được, miễn là có sẵn một AI coding agent.
Điểm đáng giá nhất: Spec Kit không chỉ có một quy trình. Ngoài cách làm theo đặc tả (Spec-Driven Development, viết tắt SDD), còn có quy trình sửa lỗi và quy trình đánh giá một ý tưởng có đáng làm hay không. Hiện repo có khoảng 149.548 sao và 13.437 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây.
github/spec-kit
Bộ công cụ mã nguồn mở của GitHub giúp AI coding agent làm việc theo quy trình rõ ràng: đặc tả, kế hoạch, tác vụ, code, kiểm tra lại.
I.Spec Kit làm được gì
Tác giả chia công cụ thành bốn lối vào độc lập. Bạn không phải đi hết lần lượt, cứ chọn cái mình cần.
A.Làm theo đặc tả để xây tính năng hoặc ứng dụng
Đây là quy trình có sẵn trong lõi. Bạn mô tả cái cần xây, AI biến nó thành đặc tả, kế hoạch, danh sách tác vụ rồi code. Lợi ích thực tế: mỗi bước có tài liệu để bạn đọc và sửa trước khi AI đi tiếp, nên đỡ cảnh code xong mới thấy lệch ý.
B.Sửa lỗi có kiểm chứng
Quy trình này là một extension (phần mở rộng) cài thêm khi cần. AI sẽ đánh giá nguyên nhân, sửa lỗi, rồi kiểm tra xem triệu chứng ban đầu đã hết chưa. Kết quả cuối là một trong ba mức: verified, partial hoặc failed. Chỉ verified mới coi là sửa thành công, nên bạn không bị AI «báo xong» khi chưa xong.
C.Đánh giá ý tưởng trước khi đầu tư
Quy trình này cũng là extension. Nó thu thập bằng chứng để ra quyết định go, needs-clarification hoặc kill. Không cần có mã nguồn. Chủ doanh nghiệp nhỏ có thể dùng để cân nhắc một tính năng mới trước khi bỏ tiền thuê làm. Dừng lại có lý do ghi rõ cũng được tác giả coi là một kết quả hữu ích.
D.Tự chỉnh hoặc tự tạo quy trình
Nếu quy trình có sẵn chưa vừa, bạn có các «viên gạch» để ghép:
- Integrationkết nối hoặc đổi giữa các coding agent.
- Extensionthêm lệnh, cổng kiểm tra chất lượng hoặc cả một quy trình, kể cả nối với công cụ bên ngoài.
- Presetchỉnh mẫu, thuật ngữ, phương pháp, hoặc áp tiêu chuẩn của tổ chức.
- Workflowtự động hoá chuỗi prompt, lệnh, cổng kiểm tra và tác vụ shell.
- Bundlegói sẵn một bộ cấu hình cho một vai trò hoặc một nhóm.
- Catalogkho để tìm thành phần do cộng đồng làm, hoặc tự dựng kho riêng trong công ty.
README cũng nói có thể dùng ở chế độ offline hoặc sau tường lửa. Chi tiết nằm ở trang tài liệu của dự án.
Catalog trong Spec Kit không phải là kiểm định hay bảo chứng. Tác giả khuyên bạn tự xem mã nguồn của thành phần cộng đồng trước khi cài hoặc chạy.
II.Cần chuẩn bị gì
Theo README, bạn cần:
- Python 3.11 trở lên (file
pyproject.tomlcũng yêu cầu>=3.11). - uv: công cụ quản lý gói Python. README dẫn tới một trang hướng dẫn cài uv riêng trong tài liệu của dự án. Phần này mình không chép lệnh vì README chính không ghi.
- Một AI coding agent được hỗ trợ. Ví dụ trong README dùng GitHub Copilot. Danh sách agent khác nằm ở trang Integrations trong tài liệu.
- Hệ điều hành: Linux, macOS hoặc Windows.
README không nhắc tới yêu cầu GPU hay phần cứng đặc biệt. Còn tài khoản hay khoá API nào, tuỳ vào coding agent bạn chọn, vì Spec Kit chỉ điều phối agent đó. README chính không nói rõ chuyện này.
III.Cài đặt từng bước
- Cài uv và PythonChuẩn bị Python 3.11+ và công cụ uv theo trang hướng dẫn của dự án
- Cài Specify CLIDùng uv để cài gói specify-cli
- Tạo dự ánChạy specify init với agent bạn dùng
- Vào thư mục dự áncd vào thư mục vừa tạo
- Mở coding agentChạy agent trong thư mục đó rồi gõ các lệnh /speckit-...
A.Bước 1: Chuẩn bị Python và uv
Mở terminal (trên Windows là PowerShell hoặc Terminal) rồi xem bạn đã có Python chưa. Lệnh dưới là lệnh phổ thông để xem phiên bản:
python --versionNếu ra số nhỏ hơn 3.11, bạn cần cài bản mới hơn. Với uv, README chỉ dẫn sang trang hướng dẫn cài uv của dự án (https://github.github.io/spec-kit/install/uv.html). Bạn làm theo trang đó rồi quay lại.
B.Bước 2: Cài Specify CLI
Lệnh sau cài công cụ specify thành một «tool» dùng được ở mọi thư mục:
uv tool install specify-cliChỗ người mới hay vấp: nếu terminal báo không tìm thấy uv, nghĩa là bước 1 chưa xong hoặc bạn cần mở lại terminal. README cũng có trang Installation cho bản cố định (pinned), cách cài khác, CI và xử lý sự cố.
C.Bước 3: Tạo dự án mới
Lệnh này tạo thư mục dự án tên my-project và gắn sẵn tích hợp với GitHub Copilot:
specify init my-project --integration copilotNếu bạn dùng agent khác, thay copilot bằng khoá tương ứng. Khoá của từng agent được liệt kê ở trang Integrations (README chính không liệt kê). Bạn có thể đổi my-project thành tên bất kỳ.
D.Bước 4: Đi vào thư mục dự án
cd my-projectCác lệnh sau này phải chạy trong thư mục này. Đây là chỗ nhiều người quên, rồi agent không thấy lệnh /speckit-....
E.Bước 5: Mở coding agent trong thư mục dự án
Khởi chạy coding agent của bạn ngay trong thư mục my-project. Từ đây, các lệnh /speckit-... bạn gõ vào khung chat của agent, không gõ vào terminal.
F.Dự án đã có sẵn code thì sao?
README có trang riêng «Existing projects» cho trường hợp này, nằm trong tài liệu. README chính chưa ghi lệnh cụ thể, nên bạn xem trang đó.
IV.Kiểm tra đã chạy được chưa
README chưa ghi một lệnh «kiểm tra phiên bản» riêng. Bạn có thể dựa vào các dấu hiệu sau, đều bám theo tư liệu:
- Lệnh
specify initchạy xong và thư mụcmy-projectxuất hiện. - Mở agent trong thư mục đó, gõ
/speckit-constitution(hoặc các lệnh/speckit-...khác) và agent nhận lệnh. Với GitHub Copilot, README dùng cú pháp skills mặc định như vậy. Agent khác có cú pháp gọi khác, xem trang Command invocation. - Sau khi cài extension, ví dụ
specify extension add bug, các lệnh như/speckit-bug-assessdùng được. Với quy trình sửa lỗi, báo cáo sẽ nằm trong.specify/bugs/<slug>/.
Nếu specify không chạy, xem phần lỗi hay gặp bên dưới.
V.Dùng vào việc thật
Một lưu ý chung của README: các lệnh /speckit-... chạy trong chat của agent, từng lệnh một, và bạn nên đọc kết quả mỗi bước rồi mới đi tiếp.
Đặc tả rõ ràng là chỗ bạn nói chuyện với AI, còn code chỉ là hệ quả.
Ông T
A.Chủ shop muốn có công cụ sắp xếp ảnh sản phẩm
Bạn là chủ shop, có nhiều ảnh sản phẩm lộn xộn. Bạn muốn một ứng dụng nhỏ gom ảnh thành album theo ngày. Trong thư mục dự án đã specify init, mở agent và chạy lần lượt (đây chính là ví dụ trong README):
/speckit-constitution Create principles focused on code quality, testing, and maintainability.
/speckit-specify Build a photo organizer with albums grouped by date and a tile preview of each album.
/speckit-plan Use Vite with vanilla JavaScript. Keep images local and store metadata in SQLite.
/speckit-tasks
/speckit-implement
/speckit-convergeconstitution chỉ cần làm một lần cho mỗi dự án. Các bước còn lại lặp lại cho mỗi tính năng. Kết quả: có đặc tả, kế hoạch, danh sách tác vụ và code. Bạn lặp implement rồi converge cho tới khi converge báo Converged.
B.Dev tìm và sửa lỗi form đăng nhập
Bạn là lập trình viên mới, form đăng nhập bị crash khi để trống mật khẩu. Trước hết cài extension sửa lỗi, chạy trong terminal, từ thư mục dự án:
specify extension add bugSau đó vào chat của agent:
/speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash
/speckit-bug-fix slug=login-crash
/speckit-bug-test slug=login-crashKết quả: các báo cáo nằm trong .specify/bugs/login-crash/. Kết luận cuối là verified, partial hoặc failed. Chỉ verified mới xác nhận lỗi đã được sửa.
C.Nhân viên văn phòng đánh giá ý tưởng trước khi trình sếp
Bạn muốn đề xuất tính năng làm việc offline cho một sản phẩm, và cần bằng chứng trước khi xin ngân sách. Cài extension đánh giá:
specify extension add assessRồi chạy trong chat của agent:
/speckit-assess-intake "Let users work offline and sync when they reconnect." slug=offline-mode
/speckit-assess-research slug=offline-mode
/speckit-assess-define slug=offline-mode
/speckit-assess-shape slug=offline-mode
/speckit-assess-decide slug=offline-modeKết quả: các tài liệu Markdown nằm trong .specify/assessments/offline-mode/ và một quyết định cuối: go, needs-clarification hoặc kill. Nếu còn điều chưa rõ, README khuyên sửa trực tiếp các file Markdown đó (tự sửa hoặc nhờ agent) thay vì chạy lại cả giai đoạn. Nếu quyết định là go và bạn muốn xây phần mềm, hãy đưa bản tóm tắt bàn giao trong decision.md cho /speckit-specify.
D.Trưởng nhóm muốn ép cả team theo một chuẩn
Bạn là trưởng nhóm kỹ thuật, muốn mọi kế hoạch đều phải có truy vết quy định. README nêu đúng ví dụ này: dùng preset để chỉnh quy trình hiện có, ví dụ yêu cầu truy vết quy định trong kế hoạch. Nếu chỉ cần đổi một mẫu cho một dự án, dùng project-local override. Muốn chia sẻ cả bộ cấu hình, gói chúng thành bundle. Để tìm thành phần có sẵn, bạn có thể thử các lệnh tìm kiếm trong catalog:
specify extension search
specify preset search
specify workflow search
specify bundle searchREADME chưa nói rõ cách điền từ khoá cho các lệnh này, bạn xem tài liệu CLI reference.
VI.Lỗi hay gặp và cách xử lý
A.Terminal báo không tìm thấy uv hoặc specify
Thường là chưa cài uv, hoặc terminal đang mở từ trước khi cài. Cài uv theo trang hướng dẫn của dự án, đóng terminal rồi mở lại và chạy lại lệnh. Nếu vẫn lỗi, xem mục xử lý sự cố ở trang Installation.
B.Python quá cũ
Gói specify-cli yêu cầu Python 3.11 trở lên. Nếu máy bạn dùng bản thấp hơn, việc cài có thể thất bại. Hãy kiểm tra bằng python --version và cài bản mới hơn trước.
C.Gõ lệnh /speckit-... vào terminal
Đây là lỗi người mới hay mắc nhất. Các lệnh này chạy trong khung chat của coding agent, không phải terminal. Chỉ các lệnh specify ... mới gõ ở terminal.
D.Agent không nhận lệnh
Có hai nguyên nhân dễ xảy ra. Một là bạn mở agent không đúng thư mục dự án, hãy mở lại trong my-project. Hai là agent của bạn dùng cú pháp gọi khác với ví dụ Copilot. README nói ví dụ dùng cú pháp skills mặc định của Copilot, còn agent khác xem trang Command invocation trong tài liệu.
E.Chạy specify extension add mà không thấy lệnh mới
README dặn cài extension từ thư mục dự án. Hãy kiểm tra bạn đang đứng đúng thư mục, sau đó mở lại phiên chat của agent. Phần «mở lại phiên chat» là suy đoán hợp lý của mình, README không nói rõ.
Thành phần cộng đồng trong catalog chưa được kiểm định. Hãy đọc mã nguồn trước khi cài hoặc chạy, nhất là khi dự án của bạn có dữ liệu thật hoặc khoá truy cập.
VII.Có nên dùng không
Điểm mạnh
- Quy trình rõ ràng, mỗi bước có tài liệu để bạn kiểm soát trước khi AI làm tiếp.
- Có ba quy trình dùng ngay (xây tính năng, sửa lỗi, đánh giá ý tưởng), lại còn tự tuỳ biến được.
- Mã nguồn mở, giấy phép MIT, repo còn được cập nhật và có cộng đồng lớn.
- Chạy được trên Linux, macOS và Windows.
Giới hạn
- Bạn vẫn cần một coding agent riêng. Spec Kit không thay thế agent đó.
- Phải làm quen với nhiều khái niệm (preset, extension, workflow, bundle). Hãy bắt đầu với thay đổi nhỏ nhất đủ dùng, đúng như README khuyên.
- Quy trình nhiều bước sẽ chậm hơn so với việc nhờ AI sửa nhanh một dòng code.
- README không nêu chi phí chạy. Chi phí phụ thuộc vào agent và gói dịch vụ bạn dùng.
Khi nào nên chọn cách khác
Nếu bạn chỉ cần sửa vặt hoặc viết một đoạn script ngắn, nhờ thẳng agent sẽ nhanh hơn. Spec Kit hợp với việc có nhiều bước, nhiều người cùng làm, hoặc cần lưu lại lý do vì sao làm như vậy. Mình gợi ý bạn thử trên một dự án nhỏ trước: cài, chạy hết một vòng SDD, rồi tự đánh giá xem nhịp làm việc này có hợp với mình không.
Câu hỏi thường gặp
Spec Kit có miễn phí không?
Bản thân Spec Kit là mã nguồn mở với giấy phép MIT. Chi phí của coding agent đi kèm (ví dụ GitHub Copilot) thì README không nói, bạn cần xem gói dịch vụ của agent đó.
Chạy Spec Kit có cần GPU không?
README không nhắc tới yêu cầu GPU hay phần cứng đặc biệt. Công cụ này yêu cầu Python 3.11 trở lên, uv và một AI coding agent được hỗ trợ.
Spec Kit chạy được trên Windows không?
Được. README nói công cụ chạy trên Linux, macOS và Windows. Bạn chạy các lệnh specify trong terminal, còn các lệnh /speckit-... gõ trong chat của coding agent.
Spec Kit khác gì việc nhờ AI viết code trực tiếp?
Spec Kit đưa vào một quy trình có cấu trúc: đặc tả, kế hoạch, tác vụ, code rồi kiểm tra lại. Mỗi bước tạo tài liệu để bạn xem và sửa. Nhờ vậy bạn kiểm soát được AI hơn so với một câu lệnh duy nhất.
Dữ liệu của tôi có an toàn không?
README không có phần nào nói chi tiết về xử lý dữ liệu, nên chưa có thông tin rõ ràng. Có hai điều README nói: repo có tài liệu cho trường hợp offline hoặc sau tường lửa, và thành phần cộng đồng trong catalog chưa được kiểm định nên bạn tự xem mã nguồn trước khi dùng.
Tôi dùng agent khác Copilot thì sao?
Spec Kit có cơ chế Integration để kết nối hoặc chuyển giữa các coding agent. Ví dụ trong README dùng GitHub Copilot. Với agent khác, bạn xem trang Integrations để lấy khoá tích hợp và cú pháp gọi lệnh tương ứng.
Tôi đã có dự án sẵn, dùng Spec Kit được không?
Được. README có trang hướng dẫn riêng cho dự án đã có code, tên là Existing projects. README chính không ghi lệnh cụ thể, nên bạn xem trang đó.


