Spec Kit là gì? Phân tích github/spec-kit và hướng dẫn sử dụng

Spec Kit là gì? Phân tích repo github/spec-kit và hướng dẫn sử dụng dễ hiểu

Ảnh trích xuất từ repo chính thức github/spec-kit, file media/logo_large.webp. Ảnh là WebP, không phải SVG.¹

Tóm tắt nhanh

Spec Kit là toolkit mã nguồn mở của GitHub giúp bạn bắt đầu với Spec-Driven Development hay SDD. Repo chính thức mô tả Spec Kit là công cụ giúp bạn tập trung vào product scenarios và predictable outcomes thay vì “vibe coding” từng phần từ đầu.²

Nói dễ hiểu: thay vì mở AI coding agent rồi nói “hãy code app này”, bạn dùng Spec Kit để đi theo quy trình có cấu trúc:

Constitution → Spec → Clarify → Checklist → Plan → Tasks → Analyze → Implement

Mỗi bước tạo ra tài liệu Markdown rõ ràng. Tài liệu này trở thành ngữ cảnh có tổ chức để AI coding agent như GitHub Copilot, Claude Code, Codex CLI, Gemini CLI, Cursor, Kiro, Windsurf hoặc các agent khác hiểu đúng yêu cầu trước khi viết code.³⁴

Spec-Driven Development là gì?

Spec-Driven Development đảo ngược cách phát triển phần mềm truyền thống. Thông thường, code là trung tâm; tài liệu yêu cầu, design doc hoặc checklist chỉ đóng vai trò phụ trợ và dễ bị bỏ quên. SDD xem specification là nguồn sự thật chính, còn code là kết quả được tạo ra, kiểm tra và cập nhật theo specification.⁵

Trong tài liệu spec-driven.md, GitHub giải thích rằng SDD làm cho specs và implementation plans trở thành các artifact có thể tạo implementation, giúp giảm khoảng cách giữa ý định sản phẩm và code thực tế.⁵

Cách hiểu ngắn:

Spec Kit giải quyết vấn đề gì?

AI coding agent rất mạnh, nhưng nếu yêu cầu mơ hồ, agent thường tự suy đoán. Nó có thể chọn sai architecture, thêm tính năng không cần, bỏ qua edge case, hoặc viết code trước khi hiểu rõ người dùng cần gì.

Spec Kit giải quyết bằng cách ép workflow đi qua các artifact:

• Constitution: nguyên tắc phát triển của dự án.
• Spec: yêu cầu người dùng, user stories, success criteria.
• Clarify: câu hỏi làm rõ phần còn mơ hồ.
• Checklist: kiểm tra chất lượng spec.
• Plan: kế hoạch kỹ thuật, tech stack, architecture.
• Tasks: danh sách việc cần làm có thứ tự.
• Analyze: kiểm tra độ nhất quán giữa spec, plan và tasks.
• Implement: để agent thực thi theo task list.

Quick Start chính thức khuyến nghị workflow production như sau:⁶

/speckit.constitution
  → /speckit.specify
  → /speckit.clarify
  → /speckit.checklist
  → /speckit.plan
  → /speckit.tasks
  → /speckit.analyze
  → /speckit.implement

Repo github/spec-kit có gì đáng chú ý?

Trang GitHub của github/spec-kit mô tả repo là toolkit giúp bắt đầu với Spec-Driven Development, license MIT, và có hơn 100k sao tại thời điểm truy cập.⁷ Tài liệu docs chính thức ghi rõ Spec Kit giúp “define what to build before building it” với bất kỳ AI coding agent nào.³

Repo có các phần chính:

Spec Kit không phải là gì?

Nói cách khác: Spec Kit không thay bạn thiết kế sản phẩm. Nó giúp bạn biến ý tưởng thành specs/plans/tasks đủ rõ để agent code có kiểm soát hơn.

Khi nào nên dùng Spec Kit?

Nên dùng khi:

• bạn đang dùng AI coding agent để tạo feature mới;
• yêu cầu có nhiều điều kiện, user flow, edge case;
• team muốn spec/plan/tasks được lưu trong Git;
• bạn muốn giảm tình trạng “AI tự bịa requirement”;
• dự án cần guardrails về test, security, UX, performance;
• bạn muốn nhiều agent/tool khác nhau cùng hiểu một workflow;
• bạn muốn chuẩn hóa cách viết spec trong team.

Không cần dùng hoặc chưa cần dùng khi:

• chỉ sửa một lỗi nhỏ;
• chỉ đổi text hoặc CSS đơn giản;
• bạn cần thử nghiệm cực nhanh không quan tâm documentation;
• team chưa sẵn sàng review spec/plan/tasks;
• bạn không dùng AI coding agent.

Cài đặt Spec Kit

Điều kiện cần

Installation Guide chính thức nêu các điều kiện:⁸

• Linux/macOS hoặc Windows; PowerShell scripts hiện được hỗ trợ không cần WSL.
• AI coding agent được hỗ trợ.
• uv được khuyến nghị, hoặc pipx cho cài đặt persistent.
• Python 3.11+.
• Git.

Cảnh báo quan trọng về package

Tài liệu Installation nhấn mạnh rằng các package chính thức, được maintain cho Spec Kit chỉ đến từ repo GitHub github/spec-kit. Các package cùng tên trên PyPI, ví dụ specify-cli, không liên quan đến dự án và không được maintain bởi Spec Kit maintainers.⁸

Vì vậy, với Spec Kit, không nên cài bằng:

pip install specify-cli

Trừ khi đó là wheel bạn tự build từ repo chính thức trong môi trường nội bộ.

Cài persistent bằng uv

Thay vX.Y.Z bằng tag release mới nhất:

uv tool install specify-cli --from git+https://github.com/github/[email protected]

Kiểm tra:

specify version

Lệnh specify version giúp xác nhận bạn đang chạy bản Spec Kit chính thức từ GitHub, không phải package trùng tên không liên quan.⁸

Dùng một lần bằng uvx

Nếu chưa muốn cài cố định:

uvx --from git+https://github.com/github/spec-kit.git specify init my-project

Hoặc khởi tạo trong thư mục hiện tại:

uvx --from git+https://github.com/github/spec-kit.git specify init .

Quick Start chính thức đưa hai mẫu lệnh này ở bước đầu tiên.⁶

Cài bằng pipx

pipx install git+https://github.com/github/spec-kit.git

Sau đó dùng trực tiếp:

specify init my-project
specify init .

Khởi tạo project

Tạo project mới với GitHub Copilot:

specify init my-project --integration copilot
cd my-project

Dùng Claude Code:

specify init my-project --integration claude
cd my-project

Dùng Codex CLI:

specify init my-project --integration codex
cd my-project

Dùng Gemini CLI:

specify init my-project --integration gemini
cd my-project

Nếu muốn khởi tạo trong thư mục hiện tại:

specify init . --integration copilot

Nếu thư mục đã có file và bạn muốn merge vào:

specify init . --force --integration copilot

Installation Guide nói trong terminal interactive, CLI sẽ hỏi bạn chọn integration; trong non-interactive session, ví dụ CI hoặc piped runs, mặc định là GitHub Copilot nếu không truyền --integration.⁸

Bash và PowerShell scripts

Spec Kit tạo automation scripts theo loại shell. Tài liệu Installation ghi rõ scripts hiện có cả Bash .sh và PowerShell .ps1.⁸

Mặc định:

• Windows: ps
• OS khác: sh

Ép dùng Bash:

specify init my-project --script sh

Ép dùng PowerShell:

specify init my-project --script ps

Sau khi init, scripts nằm trong:

.specify/scripts/bash/
.specify/scripts/powershell/

Workflow dễ hiểu cho người mới

Bước 1: Constitution

Constitution là “luật nền” của dự án. Nó nói cho agent biết nguyên tắc nào không nên vi phạm.

Ví dụ:

/speckit.constitution
Dự án ưu tiên bảo mật, test-first, code dễ đọc, không over-engineering.
Mọi tính năng phải có test. API phải có validation rõ ràng.

Lệnh này tạo hoặc cập nhật:

.specify/memory/constitution.md

README nói file constitution sẽ được agent tham chiếu trong các giai đoạn specification, planning và implementation.²

Bước 2: Specify

Specify mô tả cần xây cái gì và vì sao, chưa nói nhiều về tech stack.

Ví dụ:

/speckit.specify
Xây hệ thống quản lý công việc nhóm. Người dùng có thể tạo project,
tạo task, kéo thả task giữa To Do, In Progress, In Review và Done,
bình luận trong task và gán task cho thành viên.

Quick Start nhấn mạnh ở giai đoạn này nên tập trung vào “what” và “why”, không tập trung vào tech stack.⁶

Bước 3: Clarify

Clarify giúp agent hỏi hoặc xử lý phần chưa rõ.

Ví dụ:

/speckit.clarify
Tập trung làm rõ quyền chỉnh sửa comment, giới hạn thành viên,
và cách xử lý task chưa được gán.

Dùng bước này để giảm rủi ro agent tự đoán.

Bước 4: Checklist

Checklist kiểm tra spec đã rõ chưa.

/speckit.checklist

Nên chạy trước khi plan. Nếu checklist còn vấn đề, quay lại clarify/specify.

Bước 5: Plan

Plan là bước chuyển yêu cầu sản phẩm thành kế hoạch kỹ thuật.

Ví dụ:

/speckit.plan
Dùng Next.js, PostgreSQL, Prisma, REST API, Tailwind CSS.
Task board cần hỗ trợ drag-and-drop. Database cần lưu project, user,
task, comment và activity log.

Bước 6: Tasks

Tasks tạo danh sách việc có thể thực thi.

/speckit.tasks

Tasks thường được dùng để chia việc cho agent, lập PR hoặc tạo GitHub issues.

Bước 7: Analyze

Analyze kiểm tra spec, plan và tasks có mâu thuẫn không.

/speckit.analyze

Quick Start khuyên chạy /speckit.analyze trước implementation để bắt lỗi khi plan/tasks còn có thể sửa.⁶

Bước 8: Implement

Cuối cùng mới để agent code:

/speckit.implement

Với feature lớn, Quick Start khuyên triển khai theo phase để tránh quá tải context.⁶

Các lệnh chính

README liệt kê các core commands và optional commands:²

Tích hợp AI coding agent

Spec Kit hỗ trợ nhiều AI coding agent. Tài liệu integrations nói khi chạy specify init, CLI sẽ setup command files, context rules và directory structures phù hợp với agent bạn chọn.⁴

Một số integration key:

Liệt kê integration có trong bản CLI đang cài:

specify integration list

Cài thêm integration vào project đã init:

specify integration install claude

Chuyển integration mặc định:

specify integration switch codex

Dùng integration đã cài:

specify integration use copilot

Gỡ integration:

specify integration uninstall claude

Tài liệu integrations cũng nói một số integration là skills-based. Ví dụ Claude Code cài skills vào .claude/skills, Codex CLI cài skills vào .agents/skills và gọi theo dạng $speckit-<command>.⁴

Generic integration cho agent chưa hỗ trợ

Nếu agent bạn dùng chưa có trong danh sách, dùng generic:

specify init my-project --integration generic --integration-options="--commands-dir .myagent/cmds"

Hoặc trong project đã init:

specify integration install generic --integration-options="--commands-dir .myagent/cmds"

Dùng generic khi bạn có agent hỗ trợ prompt files/slash command files nhưng chưa được Spec Kit tích hợp chính thức.

Extensions và Presets

Spec Kit có hai cách mở rộng chính: extensions và presets.

Extensions

Extensions thêm năng lực mới, command mới hoặc phase mới vào workflow. README nêu ví dụ extension có thể thêm Jira integration, post-implementation code review, V-Model test traceability hoặc project health diagnostics.²

specify extension search
specify extension add <extension-name>

Dùng extension khi bạn muốn:

• thêm command mới;
• tích hợp hệ thống ngoài như Jira;
• thêm bước code review;
• thêm workflow riêng của team;
• thêm quality gate mới.

Presets

Presets thay đổi cách Spec Kit hoạt động mà không nhất thiết thêm command mới. README nêu preset có thể ép format compliance, đổi thuật ngữ domain, thêm security review gate, enforce test-first task ordering hoặc localize workflow sang ngôn ngữ khác.²

specify preset search
specify preset add <preset-name>

Dùng preset khi bạn muốn:

• tùy biến template spec/plan/tasks;
• áp dụng tiêu chuẩn tổ chức;
• đổi thuật ngữ theo domain;
• thêm yêu cầu compliance;
• chuẩn hóa workflow cho nhiều repo.

Nên dùng extension hay preset?

Cấu trúc file sau khi dùng Spec Kit

Một project dùng Spec Kit thường có:

.specify/
  memory/
    constitution.md
  scripts/
    bash/
    powershell/
  templates/
specs/
  001-feature-name/
    spec.md
    plan.md
    tasks.md
    research.md
    data-model.md
    contracts/
    quickstart.md

Không phải mọi file đều luôn có ngay từ đầu. Một số file xuất hiện sau /speckit.plan hoặc /speckit.tasks.

Ý nghĩa:

• .specify/ là cấu hình và template workflow.
• constitution.md là nguyên tắc dự án.
• specs/<feature>/spec.md là yêu cầu feature.
• plan.md là kế hoạch kỹ thuật.
• tasks.md là danh sách việc.
• contracts/ chứa API contract nếu workflow tạo ra.
• quickstart.md chứa cách validate feature.

Hướng dẫn triển khai cho cá nhân

Quy trình đơn giản:

# 1. Cài uv nếu chưa có
# 2. Cài Specify CLI từ repo chính thức
uv tool install specify-cli --from git+https://github.com/github/[email protected]

# 3. Kiểm tra đúng bản
specify version

# 4. Tạo project
specify init my-project --integration copilot
cd my-project

# 5. Mở AI coding agent bạn dùng
# 6. Chạy workflow trong chat
/speckit.constitution ...
/speckit.specify ...
/speckit.clarify ...
/speckit.checklist
/speckit.plan ...
/speckit.tasks
/speckit.analyze
/speckit.implement

Cách dùng nhanh không cài persistent:

uvx --from git+https://github.com/github/spec-kit.git specify init my-project --integration copilot

Hướng dẫn triển khai cho team

Giai đoạn 1: thử nghiệm một repo

• Chọn một feature vừa phải.
• Init Spec Kit trong repo.
• Chọn một integration chính, ví dụ copilot, claude hoặc codex.
• Tạo constitution ngắn, không quá lý thuyết.
• Chạy đủ spec → clarify → checklist → plan → tasks → analyze → implement.
• Review PR như bình thường.

Giai đoạn 2: chuẩn hóa constitution

Tạo constitution chung:

- Tất cả feature phải có test.
- Không thêm dependency mới nếu không có lý do.
- API phải validate input.
- Không lưu secret trong repo.
- Ưu tiên code đơn giản, dễ đọc.
- Performance-critical path phải có benchmark hoặc tiêu chí đo.

Sau đó dùng /speckit.constitution để đưa các nguyên tắc này vào .specify/memory/constitution.md.

Giai đoạn 3: chuẩn hóa branch/spec flow

Đề xuất:

main
  └── 001-user-auth
        ├── specs/001-user-auth/spec.md
        ├── plan.md
        ├── tasks.md
        └── PR implementation

Tài liệu Quick Start nói Spec Kit tự phát hiện active feature dựa trên Git branch hiện tại, ví dụ 001-feature-name; đổi branch là đổi spec đang làm.⁶

Giai đoạn 4: dùng analyze như quality gate

Trước khi agent implement:

/speckit.analyze

Team có thể yêu cầu PR chỉ được implement khi:

• spec không còn [NEEDS CLARIFICATION];
• checklist pass;
• plan rõ stack và constraints;
• tasks đủ nhỏ;
• analyze không phát hiện contradiction lớn.

Giai đoạn 5: thêm presets/extensions

Khi quy trình ổn định:

• dùng preset để enforce template của công ty;
• dùng extension để thêm Jira, security review, compliance, architecture guard;
• host catalog nội bộ nếu làm enterprise/air-gapped.

Docs home nói Spec Kit hoạt động offline, sau firewall, trên Windows/macOS/Linux và có thể host extension/preset catalogs riêng để tổ chức kiểm soát nội dung cài đặt.³

Lưu ý bảo mật khi dùng Spec Kit

Spec Kit tạo tài liệu và command files cho AI coding agent. Điều này không tự động làm workflow an toàn tuyệt đối. Nên áp dụng:

• Không đưa API key, token, private key vào spec/plan/tasks.
• Review .specify/, specs/, .claude/, .agents/, command files trước khi commit nếu có chứa nội dung nhạy cảm.
• Không để agent tự chạy lệnh production như deploy, migration, delete data nếu không có approval.
• Luôn dùng Git branch riêng cho feature.
• Không chạy package không rõ nguồn; Installation Guide cảnh báo package PyPI cùng tên không phải package chính thức.⁸
• Với extensions/presets cộng đồng, README nhắc rằng community contributions được tạo và maintain độc lập; nên review source code trước khi cài và tự chịu trách nhiệm khi dùng.²
• Dùng CI/test như bình thường; Spec Kit không thay thế test suite.
• Với enterprise, kiểm soát catalog nội bộ thay vì cho mọi người tự cài extension bất kỳ.

Khi nào workflow có thể quá nặng?

Spec Kit có thể tạo nhiều tài liệu. Với task rất nhỏ, quy trình đầy đủ có thể hơi dư.

Dùng workflow nhẹ:

/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement

Dùng workflow đầy đủ khi:

• yêu cầu mơ hồ;
• có security/performance concern;
• feature lớn;
• nhiều người cùng review;
• cần audit trail;
• cần tránh agent tự đoán.

Quick Start cũng phân biệt: quick experiments có thể dùng lean path, còn production features hoặc việc có ambiguity nên dùng clarify/checklist/analyze như quality gates.⁶

So sánh Spec Kit với cách dùng AI coding agent thông thường

So sánh Spec Kit với RTK, Headroom, MarkItDown

Spec Kit nằm ở tầng quy trình phát triển, không phải tầng nén token hay chuyển đổi tài liệu.

FAQ

Spec Kit là gì?

Spec Kit là toolkit mã nguồn mở của GitHub giúp thực hành Spec-Driven Development với AI coding agent. Nó tạo workflow spec → plan → tasks → implement để agent viết code theo yêu cầu rõ ràng hơn.⁷³

Spec-Driven Development là gì?

SDD là cách phát triển phần mềm trong đó specification là nguồn sự thật chính; code được tạo, kiểm tra và cập nhật theo specification thay vì để code là artifact duy nhất.⁵

Spec Kit có cần GitHub Copilot không?

Không bắt buộc. Spec Kit hỗ trợ nhiều AI coding agent, gồm GitHub Copilot, Claude Code, Codex CLI, Gemini CLI, Cursor, Kiro, Windsurf và nhiều agent khác.⁴

Cài Spec Kit bằng pip được không?

Tài liệu Installation cảnh báo package cùng tên trên PyPI không liên quan đến dự án chính thức. Cách khuyến nghị là dùng uv tool install hoặc uvx từ repo GitHub github/spec-kit.⁸

Spec Kit có chạy trên Windows không?

Có. Installation Guide nói Windows được hỗ trợ và PowerShell scripts hiện có thể dùng không cần WSL.⁸

Lệnh nào quan trọng nhất?

Các lệnh cốt lõi là /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks và /speckit.implement. Với production, nên thêm /speckit.clarify, /speckit.checklist và /speckit.analyze.²⁶

Kết luận

github/spec-kit là repo đáng chú ý vì nó đưa AI coding agent vào một quy trình có kiểm soát hơn. Thay vì prompt trực tiếp và hy vọng agent hiểu đúng, Spec Kit buộc ý tưởng đi qua constitution, spec, clarification, checklist, plan, tasks và analysis trước khi implement.

Với người mới, cách bắt đầu tốt nhất là cài Specify CLI từ repo chính thức, init project với integration phù hợp, rồi dùng workflow đầy đủ trên một feature nhỏ. Với team, giá trị lớn nhất nằm ở việc spec/plan/tasks được lưu trong Git, review được như code, và giảm tình trạng AI tự suy đoán yêu cầu.

Nguồn tham khảo

Footnotes

1. GitHub raw asset. github/spec-kit/media/logo_large.webp. https://github.com/github/spec-kit/raw/main/media/logo_large.webp ↩

2. GitHub Spec Kit README. https://raw.githubusercontent.com/github/spec-kit/main/README.md ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷

3. GitHub Spec Kit Documentation home. https://github.github.io/spec-kit/ ↩ ↩² ↩³ ↩⁴

4. Spec Kit Supported AI Coding Agent Integrations. https://github.github.io/spec-kit/reference/integrations.html ↩ ↩² ↩³ ↩⁴

5. spec-driven.md, Specification-Driven Development methodology. https://raw.githubusercontent.com/github/spec-kit/main/spec-driven.md ↩ ↩² ↩³

6. Spec Kit Quick Start Guide. https://github.github.io/spec-kit/quickstart.html ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸

7. GitHub. github/spec-kit. https://github.com/github/spec-kit ↩ ↩²

8. Spec Kit Installation Guide. https://github.github.io/spec-kit/installation.html ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸