# spec-kit: viết đặc tả trước, AI code theo sau — hướng dẫn cài đặt và dùng

> 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ợ.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-01 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/spec-kit-bo-cong-cu-dac-ta-cho-ai-coding-agent

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.

```repo
- repo | github/spec-kit
- kind | CLI
- desc | 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.
- stars | 150k
- lang | Python
- license | MIT
```

## 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.

### 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 ý.

### 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.

### Đá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.

### 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:

- **Integration**: kết nối hoặc đổi giữa các coding agent.
- **Extension**: thê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.
- **Preset**: chỉnh mẫu, thuật ngữ, phương pháp, hoặc áp tiêu chuẩn của tổ chức.
- **Workflow**: tự động hoá chuỗi prompt, lệnh, cổng kiểm tra và tác vụ shell.
- **Bundle**: gói sẵn một bộ cấu hình cho một vai trò hoặc một nhóm.
- **Catalog**: kho để 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.

```note
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.
```

## Cần chuẩn bị gì

Theo README, bạn cần:

- **Python 3.11 trở lên** (file `pyproject.toml` cũ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.

## Cài đặt từng bước

```steps
- Cài uv và Python | Chuẩn bị Python 3.11+ và công cụ uv theo trang hướng dẫn của dự án
- Cài Specify CLI | Dùng uv để cài gói specify-cli
- Tạo dự án | Chạy specify init với agent bạn dùng
- Vào thư mục dự án | cd vào thư mục vừa tạo
- Mở coding agent | Chạy agent trong thư mục đó rồi gõ các lệnh /speckit-...
```

### 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:

```bash
python --version
```

Nế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ướ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:

```bash
uv tool install specify-cli
```

Chỗ 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ố.

### 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:

```bash
specify init my-project --integration copilot
```

Nế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ỳ.

### Bước 4: Đi vào thư mục dự án

```bash
cd my-project
```

Cá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-...`.

### 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.

### 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 đó.

## 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 init` chạy xong và thư mục `my-project` xuấ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-assess` dù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.

## 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

### 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):

```text
/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-converge
```

`constitution` 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`.

### 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:

```bash
specify extension add bug
```

Sau đó vào chat của agent:

```text
/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-crash
```

Kế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.

### 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á:

```bash
specify extension add assess
```

Rồi chạy trong chat của agent:

```text
/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-mode
```

Kế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`.

### 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:

```bash
specify extension search
specify preset search
specify workflow search
specify bundle search
```

README 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.

## Lỗi hay gặp và cách xử lý

### 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.

### 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.

### 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.

### 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.

### 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õ.

```note
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.
```

## 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 đó.
