github/spec-kit: Chuẩn hóa quy trình làm việc với AI — 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à toolkit mã nguồn mở giúp AI coding agent làm việc theo quy trình có cấu trúc: đặc tả tính năng, lập kế hoạch, triển khai, sửa lỗi hoặc đánh giá ý tưởng. Công cụ dùng CLI Python, cần Python 3.11+, uv và một AI coding agent được hỗ trợ; cách cài cơ bản khá gọn.
github/spec-kit là toolkit mã nguồn mở giúp bạn đưa quy trình rõ ràng vào lúc làm việc với AI coding agent. Thay vì chỉ mô tả yêu cầu rồi để agent tự suy đoán, bạn có thể đi qua các bước đặc tả, lập kế hoạch, tạo nhiệm vụ, triển khai và kiểm tra kết quả.
Repo này phù hợp với lập trình viên mới, nhóm phát triển sản phẩm, chủ doanh nghiệp muốn thử nghiệm một ý tưởng, hoặc đội ngũ cần ghi lại lý do và kết quả của các quyết định kỹ thuật. Điểm đáng giá nhất là Spec Kit không chỉ hỗ trợ xây tính năng mới. Nó còn có quy trình riêng để sửa lỗi, đánh giá một ý tưởng có đáng đầu tư hay không, và mở rộng quy trình theo tiêu chuẩn của từng nhóm.
Repo hiện có khoảng 149611 sao và 13444 fork. Mã nguồn chính dùng Python, gói CLI có tên specify-cli, giấy phép MIT và repo vẫn còn được cập nhật gần đây.
github/spec-kit
Toolkit Python giúp dùng AI coding agent theo quy trình đặc tả, sửa lỗi, đánh giá ý tưởng và tùy biến workflow.
I.Spec Kit làm được gì
A.Làm tính năng theo đặc tả
Quy trình Spec-Driven Development bắt đầu bằng việc xác định cần xây gì và vì sao cần xây. Sau đó, AI coding agent chuyển đặc tả thành kế hoạch, danh sách nhiệm vụ và mã nguồn. Cách này hữu ích khi yêu cầu có nhiều chi tiết, nhiều bên liên quan hoặc dễ bị hiểu sai.
Bạn có thể dùng quy trình này cho một ứng dụng mới, một tính năng trong sản phẩm hiện có hoặc một thay đổi cần được ghi lại rõ ràng. Spec Kit khuyến khích tạo constitution một lần cho mỗi dự án để nêu các nguyên tắc như chất lượng mã, kiểm thử và khả năng bảo trì.
B.Sửa lỗi theo nguyên nhân và bằng chứng
Quy trình bug fixing giúp đánh giá nguyên nhân, giới hạn phạm vi sửa, thực hiện thay đổi rồi kiểm tra lại triệu chứng ban đầu. Bạn không cần chạy toàn bộ quy trình xây tính năng trước khi sửa một lỗi.
Kết quả cuối cùng được ghi thành báo cáo trong thư mục .specify/bugs/. Verdict có thể là verified, partial hoặc failed; chỉ verified mới xác nhận lỗi đã được sửa thành công theo tư liệu của repo.
C.Đánh giá ý tưởng trước khi đầu tư
Nếu bạn có một ý tưởng sản phẩm nhưng chưa biết có nên xây hay không, quy trình assessment giúp thu thập bằng chứng và đưa ra quyết định go, needs-clarification hoặc kill.
Điểm thực tế là quy trình này không yêu cầu mã nguồn hoặc quy trình SDD. Bạn có thể dùng nó trước khi giao việc cho đội phát triển, nhờ đó giảm nguy cơ đầu tư sớm vào một ý tưởng còn quá nhiều điều chưa rõ.
D.Kết nối nhiều AI coding agent
Spec Kit có lớp integration để kết nối hoặc chuyển đổi giữa các coding agent. README minh họa bằng GitHub Copilot và cú pháp skill mặc định của công cụ này. Với agent khác, bạn cần xem cú pháp invocation tương ứng trong tài liệu của repo.
E.Mở rộng bằng extension, preset và workflow
Extension có thể thêm một command, quality gate, quy trình hoàn chỉnh hoặc kết nối với công cụ bên ngoài. Preset cho phép thay đổi template, thuật ngữ hoặc phương pháp làm việc. Workflow dùng để tự động hóa prompt, command, gate và tác vụ shell.
Bạn cũng có thể dùng workflow overlay để chỉnh một workflow đã cài mà không cần fork, hoặc thêm workflow step khi các loại bước có sẵn chưa đủ. Bundle gom extension, preset, workflow và workflow step thành một bộ cài phù hợp cho một vai trò hoặc nhóm.
F.Dùng catalog và làm việc trong môi trường hạn chế
CLI có các lệnh tìm kiếm catalog như specify extension search, specify preset search, specify workflow search và specify bundle search. Tổ chức có thể thêm nguồn được quản lý riêng.
Repo cũng mô tả khả năng dùng nguồn cục bộ, catalog tự lưu trữ và làm việc offline hoặc sau firewall. Đây là điểm có ích cho nhóm cần kiểm soát nguồn component hoặc hạn chế truy cập mạng.
G.Kiểm tra nguồn của artifact
Artifact inventory giúp xem command, template hoặc script đang được cung cấp từ lớp nào. Tính năng này có thể giúp nhóm hiểu cấu hình hiện tại, nhất là khi dự án dùng nhiều extension, preset hoặc workflow cùng lúc.
II.Cần chuẩn bị gì
Bạn cần một máy chạy Linux, macOS hoặc Windows. Repo yêu cầu Python 3.11 trở lên và công cụ uv. README cũng yêu cầu một AI coding agent được hỗ trợ để thực hiện các skill trong thư mục dự án.
Bạn không chạy các lệnh /speckit-... trong terminal. Đây là cú pháp được nhập trong phần chat của coding agent. Terminal dùng để cài CLI, khởi tạo dự án và cài extension; agent chat dùng để chạy quy trình.
Ví dụ trong README dùng GitHub Copilot. Nếu chọn agent khác, bạn cần dùng integration và cú pháp invocation tương ứng của agent đó. Tư liệu được cung cấp không nêu một API key cụ thể cho cách bắt đầu cơ bản.
Repo có giấy phép MIT. Khi tìm component trong catalog, hãy nhớ catalog chỉ là danh sách cộng đồng hoặc nguồn được tổ chức tuyển chọn, không phải hoạt động kiểm toán hay chứng nhận. Nên xem mã nguồn của component trước khi cài hoặc chạy.
Không đưa key, thông tin mật hoặc quyền truy cập rộng vào prompt nếu dự án không cần. Trước khi cài component từ catalog, hãy kiểm tra nguồn và phạm vi quyền của nó.
III.Cài đặt từng bước
- Chuẩn bị môi trườngCài Python 3.11+, uv và một AI coding agent được hỗ trợ
- Cài CLICài gói specify-cli bằng uv
- Tạo dự ánKhởi tạo dự án và chọn integration cho agent
- Mở dự ánChuyển terminal vào thư mục dự án
- Chạy quy trìnhMở agent trong thư mục dự án và nhập từng skill trong chat
A.Chuẩn bị terminal và công cụ
Mở Terminal, PowerShell hoặc cửa sổ dòng lệnh phù hợp với hệ điều hành của bạn. Bạn cần chắc chắn Python đạt phiên bản tối thiểu 3.11 và đã có uv. README chỉ nêu các yêu cầu này, không cung cấp trong phần được trích một lệnh riêng để cài Python hoặc uv.
Nếu bạn chưa có uv, hãy xem phần Installation và hướng dẫn uv trong tài liệu của repo để chọn cách cài phù hợp với Linux, macOS hoặc Windows. Không nên tự đổi tên gói hay thay cờ lệnh khi chưa kiểm tra tài liệu tương ứng.
B.Cài Specify CLI
Chạy lệnh sau trong terminal:
uv tool install specify-cliLệnh này cài gói Python specify-cli bằng uv dưới dạng công cụ dòng lệnh. Người mới thường vấp ở chỗ terminal chưa nhận lệnh uv, hoặc đường dẫn chứa executable của uv chưa nằm trong PATH. Nếu terminal báo không tìm thấy uv, hãy kiểm tra lại bước cài uv rồi mở cửa sổ terminal mới.
C.Khởi tạo dự án với GitHub Copilot
Trong terminal, chạy:
specify init my-project --integration copilotLệnh này tạo dự án mới có tên my-project và thiết lập integration cho GitHub Copilot. Bạn có thể đổi my-project thành tên thư mục muốn dùng. README minh họa chính xác integration là copilot; với agent khác, hãy xem phần integration và cú pháp invocation của agent đó trước khi thay giá trị.
D.Đi vào thư mục dự án
Chạy:
cd my-projectLệnh này đưa terminal vào thư mục dự án vừa tạo. Đây là vị trí cần dùng khi cài extension và cũng là vị trí cần mở coding agent. Nếu chạy lệnh ở thư mục khác, Spec Kit có thể không tìm thấy cấu trúc dự án hoặc các file .specify đúng chỗ.
E.Mở coding agent và bắt đầu quy trình
Sau khi cài CLI và tạo dự án, hãy khởi chạy coding agent trong thư mục my-project. Các skill sau được nhập trong chat của agent, từng skill một, và bạn nên xem kết quả trước khi sang bước tiếp theo:
/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-convergeVí dụ trên tạo nguyên tắc dự án, viết đặc tả cho ứng dụng sắp xếp ảnh, lập kế hoạch kỹ thuật, tạo nhiệm vụ, triển khai rồi hội tụ kết quả. Lặp lại implement và converge cho đến khi bước hội tụ báo Converged.
F.Cài quy trình sửa lỗi
Nếu mục tiêu là sửa lỗi, bạn không cần chạy quy trình SDD trước. Từ thư mục dự án, chạy:
specify extension add bugSau đó nhập từng skill trong 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-crashThay phần mô tả lỗi và giá trị slug cho phù hợp. Báo cáo nằm trong .specify/bugs/login-crash/. Chỉ kết quả verified mới xác nhận việc sửa đã thành công.
G.Cài quy trình đánh giá ý tưởng
Từ thư mục dự án, chạy:
specify extension add assessSau đó nhập các skill sau 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-modeCác artifact được ghi trong .specify/assessments/offline-mode/. Kết quả quyết định là go, needs-clarification hoặc kill. Nếu cần làm rõ, bạn có thể sửa các file Markdown hiện có thay vì chạy lại toàn bộ stage.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra đầu tiên là chạy được lệnh cài uv tool install specify-cli, sau đó chạy được specify init my-project --integration copilot và đi vào thư mục bằng cd my-project. README không đưa ra một màn hình kiểm tra riêng, nên dấu hiệu thực tế là dự án được tạo và coding agent có thể mở trong đúng thư mục đó.
Với quy trình SDD, hãy kiểm tra từng kết quả sau khi nhập skill. Tiếp tục lặp implement và converge cho đến khi agent báo Converged.
Với quy trình sửa lỗi, mở thư mục .specify/bugs/login-crash/ hoặc thư mục slug bạn đã chọn. Verdict phải là verified; partial và failed chưa phải xác nhận thành công.
Với quy trình assessment, mở thư mục .specify/assessments/offline-mode/ hoặc thư mục tương ứng. Đọc quyết định cuối cùng và các artifact liên quan. go nghĩa là có thể tiếp tục, needs-clarification cần giải quyết điểm chưa rõ, còn kill là dừng ý tưởng với lý do được ghi lại.
V.Dùng vào việc thật
A.Chủ shop muốn thử một tính năng mới
Chủ một cửa hàng trực tuyến muốn thêm tính năng gom đơn theo khu vực giao hàng nhưng chưa muốn giao ngay cho dev. Bạn có thể tạo dự án, mở agent trong thư mục đó và bắt đầu bằng /speckit-constitution để ghi nguyên tắc về chất lượng, kiểm thử và khả năng bảo trì.
Tiếp theo, dùng /speckit-specify để mô tả nhóm đơn, điều kiện lọc và cách nhân viên xem kết quả. Agent sẽ giúp chuyển yêu cầu thành đặc tả, kế hoạch và nhiệm vụ. Kết quả có giá trị ở đây là đội ngũ có tài liệu chung trước khi viết mã.
B.Nhân viên văn phòng cần đánh giá một ý tưởng nội bộ
Một nhân viên muốn đề xuất công cụ đồng bộ dữ liệu khi mất mạng. Thay vì yêu cầu dev xây ngay, hãy cài extension assessment rồi nhập:
/speckit-assess-intake "Let users work offline and sync when they reconnect." slug=offline-modeSau đó chạy lần lượt các skill research, define, shape và decide. Bạn nhận được các artifact trong .specify/assessments/offline-mode/, cùng một quyết định go, needs-clarification hoặc kill. Cách này giúp cuộc họp có bằng chứng và câu hỏi cụ thể hơn.
C.Dev mới cần sửa lỗi đăng nhập
Một dev phát hiện việc gửi mật khẩu rỗng làm form đăng nhập bị crash. Sau khi chạy specify extension add bug, dev nhập:
/speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crashSau đó chạy fix và test với cùng slug. Dev đọc báo cáo trong .specify/bugs/login-crash/ và chỉ xem lỗi đã xử lý xong khi verdict là verified.
D.Nhóm phát triển muốn chuẩn hóa cách làm việc
Một nhóm có sẵn tiêu chuẩn kiểm thử và muốn thêm quality gate vào quy trình. Họ có thể dùng extension, preset và workflow để điều chỉnh command, template, thuật ngữ và các bước tự động hóa. Nếu cần chia sẻ cho nhiều vai trò, nhóm có thể đóng gói các thành phần thành bundle.
Khi đã có nhiều component, nhóm dùng các lệnh tìm kiếm catalog để tìm extension, preset, workflow hoặc bundle phù hợp. Trước khi cài, nhóm vẫn phải xem mã nguồn vì catalog không phải chứng nhận an toàn.
Mỗi lần AI làm việc, một quy trình rõ ràng giúp biến ý tưởng mơ hồ thành kết quả có thể kiểm tra.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Terminal không nhận lệnh uv
Nguyên nhân thường là uv chưa được cài hoặc terminal chưa nhận PATH mới. Hãy kiểm tra lại yêu cầu cài uv trong tài liệu của repo, mở terminal mới rồi thử lại. README được cung cấp không nêu lệnh sửa PATH cụ thể, nên không nên tự đoán thêm cờ hoặc biến môi trường.
B.Python thấp hơn phiên bản yêu cầu
Spec Kit yêu cầu Python 3.11 trở lên. Nếu môi trường dùng phiên bản thấp hơn, hãy cài hoặc chọn Python phù hợp trước khi cài specify-cli. Không nên bỏ qua yêu cầu phiên bản vì CLI có thể không hoạt động đúng.
C.Chạy skill trong terminal
Các dòng bắt đầu bằng /speckit- là lệnh dành cho chat của coding agent, không phải lệnh shell. Hãy mở agent trong thư mục dự án, nhập từng skill trong phần chat và xem kết quả trước khi tiếp tục.
D.Mở agent sai thư mục
Nếu agent không thấy cấu trúc dự án hoặc file .specify, hãy kiểm tra terminal đã chạy cd my-project chưa. Agent cần được khởi chạy trong thư mục dự án mà bạn vừa khởi tạo.
E.Cài component catalog mà chưa kiểm tra nguồn
Catalog không phải audit hay endorsement. Nếu extension, preset, workflow hoặc bundle đến từ nguồn cộng đồng, hãy xem mã nguồn và cân nhắc quyền truy cập trước khi cài hoặc chạy. Khi tổ chức cần kiểm soát chặt hơn, hãy cân nhắc nguồn được quản lý riêng hoặc nguồn cục bộ theo khả năng mà repo mô tả.
VII.Có nên dùng không
Nên dùng nếu bạn muốn AI coding agent làm việc theo quy trình có thể lặp lại, có tài liệu và có điểm kiểm tra. SDD phù hợp khi xây tính năng; bug fixing phù hợp khi cần truy nguyên nhân và xác minh lỗi; assessment phù hợp trước quyết định đầu tư. Extension, preset, workflow và bundle cũng tạo dư địa tùy biến cho nhóm có quy chuẩn riêng.
Điểm mạnh khác là CLI khá gọn, hỗ trợ Linux, macOS và Windows, dùng Python 3.11+, có giấy phép MIT và kết nối được với các coding agent được hỗ trợ. Repo cũng có nhiều lớp để tổ chức kiểm soát catalog, artifact và quy trình.
Giới hạn là Spec Kit không tự thay thế AI coding agent. Bạn vẫn cần một agent được hỗ trợ, phải xem kết quả sau từng skill và phải chọn cú pháp invocation phù hợp. Việc tùy biến extension, preset hoặc workflow cũng đòi hỏi nhóm hiểu quy trình hiện tại trước khi mở rộng.
Nếu bạn chỉ cần viết một script nhỏ, sửa một dòng mã hoặc hỏi AI một câu đơn giản, Spec Kit có thể là quá nhiều quy trình. Nếu nhóm chưa thống nhất yêu cầu, hãy bắt đầu bằng assessment hoặc một quy trình nhỏ, rồi mở rộng dần khi đã thấy lợi ích.
Câu hỏi thường gặp
Spec Kit có miễn phí không?
Repo được phát hành theo giấy phép MIT. Tư liệu được cung cấp không nêu chi phí vận hành của AI coding agent hoặc các dịch vụ bên ngoài, nên phần đó cần kiểm tra riêng.
Có cần GPU để chạy không?
Tư liệu không nói Spec Kit cần GPU. README chỉ yêu cầu Python 3.11+, uv, một AI coding agent được hỗ trợ và hệ điều hành Linux, macOS hoặc Windows.
Có chạy được trên Windows không?
Có. README nêu Linux, macOS và Windows là các hệ điều hành được hỗ trợ.
Có cần API key không?
Cách bắt đầu trong README không nêu API key cụ thể. Với agent hoặc integration khác, tài liệu integration có thể có yêu cầu riêng; tư liệu được cung cấp chưa nêu chi tiết các key đó.
Có thể dùng cho dự án đã có sẵn không?
Có hướng dẫn riêng cho existing projects trong tài liệu của repo. Phần README được cung cấp chỉ nói có thể bắt đầu với code đã có, chưa nêu các bước chi tiết.
Spec Kit có chỉ dùng cho GitHub Copilot không?
Không. README dùng GitHub Copilot làm ví dụ và nói Spec Kit có integration cho các coding agent khác. Với agent khác, bạn cần dùng integration key và cú pháp invocation tương ứng.
Dữ liệu và component cài từ catalog có an toàn không?
README cảnh báo catalog không phải hoạt động kiểm toán hay chứng nhận. Bạn nên xem mã nguồn community component trước khi cài hoặc chạy; tư liệu chưa đưa ra cam kết bảo mật chung cho mọi component.


