title: Spec Kit — README type: landing audience: người mới / mọi role ssot_for: [cài đặt, bản đồ tài liệu] update_when: khi thêm/xoá/đổi vai trò một tài liệu gốc, hoặc đổi cách cài đặt related: [01-architecture.md, 02-artifacts.md, 03-skills.md, 04-brownfield.md, 05-concepts.md, 06-testing.md]

Spec Kit

Bộ skills spec-driven development cho Claude Code — phỏng vấn có cấu trúc để xây dựng PRD, kiến trúc hệ thống, và integration specs. Domain knowledge và component/feature artifacts mọc dần qua cascade — từ pha mô tả (/spec-frd), pha thiết kế (/spec-sad), lẫn integration (/spec-new).

Tên: sản phẩm là Spec Kit (dùng trong toàn bộ tài liệu); gói npm để cài đặt là spec-lite (xem Cài đặt).

Lưu ý: Được đóng gói & kiểm thử cho Claude Code (cài vào thư mục .claude/). Nhưng kit là 100% skills-based — chỉ gồm skill + template dạng Markdown thuần, không phụ thuộc runtime riêng của Claude Code — nên về nguyên tắc có thể chạy với bất kỳ coding agent nào hỗ trợ skill/slash-command, chỉ cần trỏ agent đó vào đúng thư mục skill.

Cài đặt

npx spec-lite@latest install

Lệnh này copy skills/ và templates/ vào thư mục .claude/ của project.

Bản đồ tài liệu

File này chỉ chứa hướng dẫn cài đặt + bản đồ điều hướng. Mọi nội dung khác sống ở các tài liệu dưới đây — mỗi tài liệu một vai trò riêng, mỗi khái niệm có đúng một file sở hữu (nguồn sự thật); file khác chỉ tóm tắt rồi link về, không chép lại.

5 tài liệu gốc — đọc theo thứ tự số:

| Tài liệu | Vai trò (sở hữu điều gì) | Đọc khi bạn cần | |---|---|---| | 01-architecture.md | Tổng quan / triết lý + LUẬT vận hành (nguồn sự thật) — spec graph, WHAT/HOW, long-lived vs short-lived, cascade, lịch sử & bảo lưu ID (id_counters), template versioning, quy ước, workflow | Onboarding, hiểu "vì sao kit vận hành như vậy" + quy tắc vận hành chính xác | | 02-artifacts.md | Danh mục & mô tả artifact (nguồn sự thật) — cấu trúc .specs/, từng artifact main/integration/test-execution gồm section nào | Biết một artifact là gì, gồm section nào, nằm đâu | | 03-skills.md | Hành vi chi tiết từng skill — Reads/Writes, các bước, thứ tự chạy | Biết một skill đọc/ghi gì, hoạt động ra sao | | 04-brownfield.md | Onboarding code có sẵn — entry-path tuỳ chọn, song song 03 (không phải bước sau) | Đưa một project đã có code vào SDD | | 05-concepts.md | Khái niệm dễ nhầm — component vs feature, functional vs e2e, FAC/NFR/DM, test-exec buckets, func 100% automation | Gặp thuật ngữ/phân biệt chưa rõ khi author/thiết kế test |

(01–05 là nguồn sự thật. 06 dưới đây là how-to — dẫn đường, không sở hữu khái niệm nào, trỏ về 03/05.)

| Tài liệu | Vai trò | Đọc khi bạn cần | |---|---|---| | 06-testing.md | How-to: retrofit test (đi qua từng skill) — feature đã có code → test-design → test-exec → trilogy validation/functional/e2e → test-report | Có một feature đã implement, muốn dựng test cho nó |

Tài liệu bổ trợ:

| Tài liệu | Vai trò | Đọc khi bạn cần | |---|---|---| | guide/ | Hướng dẫn theo vai trò (BA / QC / chung) | Bạn là BA/QC, muốn biết quy trình hằng ngày |

Tóm gọn: tổng quan + luật → 01 · artifact → 02 · skill → 03 · code có sẵn → 04 · khái niệm → 05 · test feature đã có code → 06.