Spec-driven development là gì? Viết spec trước, AI gen code sau

Hiểu đơn giản nhất

Bạn xây nhà. Cách SAI: gọi thợ đến, nói "xây cho tôi cái nhà đẹp" → 3 tháng sau nhà xong không đúng ý → đập đi xây lại. Cách ĐÚNG: vẽ bản thiết kế (blueprint) — chiều dài, số phòng, vị trí cửa, vật liệu — gửi thợ → thợ xây đúng → nghiệm thu theo blueprint.

Spec-driven dev y hệt vậy. Bạn viết spec (bản thiết kế phần mềm) cho 1 feature → AI đọc spec → gen code khớp spec → test tự động verify theo từng tiêu chí trong spec. Mất 30-60 phút viết spec, nhưng tiết kiệm 5-10 vòng "AI gen sai → bạn prompt lại" như vibe coding.

Spec-driven dev là gì? Định nghĩa chính xác

Spec-driven development (SDD — phát triển dựa trên đặc tả) = phương pháp viết tài liệu spec (specification — đặc tả) ngắn cho từng feature TRƯỚC khi code. Spec là input chính cho AI assistant (Claude Code, Cursor) gen code. Test tự động chạy theo acceptance criteria trong spec.

3 thành phần cốt lõi:

• Spec document — file Markdown 15-80 dòng mô tả: Why (mục tiêu), User stories, Acceptance criteria, Edge cases, Out-of-scope
• AI gen code — AI đọc spec, suy luận implementation, gen code
• Verify against spec — test theo từng acceptance criteria, KHÔNG vibe check

Khác với waterfall (1980s): SDD không yêu cầu spec toàn bộ system trước build — chỉ spec từng feature 1, vẫn agile. Khác với vibe coding: SDD có structure, repeatable, verifiable.

Origin: SDD lai giữa Behavior-Driven Development (BDD — Dan North, 2003 — đặc tả hành vi qua Given-When-Then), Domain-Driven Design (DDD — Eric Evans 2003), và AI-native workflows 2024-2026. Tháng 8/2025, GitHub launch Spec Kit (https://github.com/github/spec-kit) chuẩn hoá pattern này cho Claude Code.

Ví dụ thực tế: VietCodex methodology (xem methodology page) áp dụng SDD trong Phase /spec của 6-phase workflow. Trước khi viết 1 dòng code cho client, team viết spec document review với client → client sign-off → AI gen code → test theo spec. Tỷ lệ rewrite giảm từ 30% (vibe-only) xuống 5% (spec-driven).

So sánh Vibe coding vs Spec-driven dev

Cấu trúc 1 spec hoàn chỉnh — template

Đây là template VietCodex dùng cho mọi feature production. Copy → paste → fill in.

# Feature: User registration
 
## Mục tiêu (Why)
 
Cho phép guest visitor (khách chưa đăng ký) tạo tài khoản với email + password
để có thể đặt hàng và xem lịch sử order. Convert visitor → registered user.
 
## User stories
 
As a guest visitor đang xem dịch vụ
I want to create an account quickly (≤ 30 giây)
So that I can place order without re-entering info next time.
 
## Acceptance criteria
 
AC-1: Form fields
- Given user đang ở /register
- When form load xong
- Then thấy 3 field: email, password, name
- And nút "Đăng ký" disabled cho đến khi đủ 3 field valid
 
AC-2: Email validation
- Given user nhập email
- When email không match regex `^[^@]+@[^@]+\.[^@]+$`
- Then hiện inline error "Email không hợp lệ" dưới field
- And nút "Đăng ký" disabled
 
AC-3: Email already exists
- Given user submit form với email đã tồn tại trong DB
- When server check qua API POST /api/auth/check-email
- Then hiện toast error "Email đã có tài khoản"
- And focus về field email
- And user record KHÔNG được tạo
 
AC-4: Success registration
- Given form valid + email chưa tồn tại
- When user click "Đăng ký"
- Then user record tạo trong DB với password hashed (bcrypt cost 10)
- And session cookie set
- And redirect đến /dashboard
- And email confirmation sent qua SendGrid
 
AC-5: Password security
- Given user nhập password
- When length < 8 ký tự HOẶC không có ít nhất 1 số
- Then hiện strength indicator: weak/medium/strong
- And block submit nếu weak
 
## Edge cases
 
- Network error khi submit → retry với exponential backoff (3 lần)
- DB unique constraint violation (race condition) → return 409, hiện "Email đã có"
- Email service down → vẫn tạo user, queue email send job
- User submit form nhiều lần (double-click) → debounce 1000ms
 
## Out of scope (Phase 2)
 
- Social login (Google/Facebook/Zalo)
- Email verification trước khi cho login
- 2FA / MFA
- Password reset flow (sẽ spec riêng)
 
## Technical constraints
 
- Stack: Next.js 16 App Router + Drizzle ORM + Postgres
- Auth lib: better-auth (đã setup)
- Validation: zod schema
- Form: react-hook-form
- Test: Playwright E2E cho golden path + Vitest cho validation

6 phần cốt lõi:

1. Mục tiêu (Why) — 2-3 câu giải thích lý do feature tồn tại
2. User stories — góc nhìn user, format "As a... I want... So that..."
3. Acceptance criteria — Given-When-Then cụ thể, đo được
4. Edge cases — tình huống bất thường (network, race condition, double-click)
5. Out of scope — explicit liệt kê thứ KHÔNG làm phase này
6. Technical constraints — stack, lib, pattern bắt buộc

Workflow 5 bước với AI

Bước 1: Viết spec (30-60 phút)

Bạn (founder / PM / dev lead) viết spec qua template. Có thể dùng AI hỗ trợ:

Tôi muốn build feature [TÊN]. Mục tiêu: [WHY].
User: [PERSONA]. Constraints: [STACK].
Viết spec markdown theo template VietCodex.

AI gen spec draft → bạn review, sửa, finalize.

Bước 2: AI đọc spec + lập plan

Trong Claude Code, command:

/plan @specs/user-registration.md

Claude đọc spec, output plan:

Plan:
1. Create lib/auth/register.ts với function registerUser()
2. Add Drizzle schema: ALTER TABLE users (đã có)
3. Create app/api/auth/register/route.ts (POST handler)
4. Create app/(auth)/register/page.tsx với form
5. Add Zod schema validation
6. Add Playwright test specs/registration.spec.ts
7. Update middleware để protect /dashboard

Bạn review plan → confirm hoặc sửa.

Bước 3: AI gen code theo plan

Claude lần lượt implement từng bước, sau mỗi file ask "tiếp tục?". Bạn approve hoặc reject.

Bước 4: Test acceptance criteria

pnpm test specs/registration.spec.ts

Playwright chạy E2E test từng AC. Output:

✓ AC-1: Form fields (245ms)
✓ AC-2: Email validation (180ms)
✗ AC-3: Email already exists (failed: timeout)
✓ AC-4: Success registration (1240ms)
✓ AC-5: Password security (320ms)

Bước 5: Iterate nếu fail

Fail AC-3 → bạn paste log lỗi cho Claude:

AC-3 fail với timeout error. File: app/api/auth/register/route.ts.
Spec yêu cầu return 409 trong dưới 500ms.
Fix.

Claude fix → re-test → pass.

Ví dụ thực tế: Module thanh toán BTB v2 (2025) được build hoàn toàn theo SDD. Spec 75 dòng cho VNPay integration → Claude gen 380 dòng code → 8/8 AC pass lần 2 (lần 1 fail 2 AC, fix trong 20 phút). Tổng thời gian: 4h cho 1 feature critical. Vibe coding ước tính cùng feature: 12h + 3 ngày debug security.

Khi nào dùng SDD / khi nào KHÔNG

✅ Nên dùng SDD

• Production code với >100 user
• Team 2+ dev (cần shared understanding)
• Auth / Payment / Financial code
• Compliance (GDPR, PCI-DSS, HIPAA) — pháp lý yêu cầu audit-able
• API public (other devs depend on contract)
• Database migration không reversible
• Code maintain >1 năm
• Module mission-critical (vd: trừ tiền, gửi email transactional)

❌ Không hợp SDD

• Throwaway script (cron 1 lần) — overhead spec không worth
• Prototype test idea (chưa biết feature có cần không)
• Solo + short timeline (vd: hackathon 48h)
• UI polish thuần CSS/animation (vibe code OK)
• Exploration (chưa rõ requirements)
• Internal tool chỉ founder dùng

Tools 2026 cho SDD

1. GitHub Spec Kit (https://github.com/github/spec-kit) — chuẩn nhất

• Open-source, launch tháng 8/2025
• Template spec markdown chuẩn
• Slash command /spec, /plan, /build, /verify trong Claude Code
• CI check spec coverage (every PR phải có updated spec)
• Integration với Linear / Jira / Notion

2. Claude Code + custom slash command

• Dùng .claude/commands/spec.md để define custom workflow
• Lưu spec trong specs/ folder
• VietCodex methodology export tới .claude/ folder

3. Cursor + .specs/ folder

• Cursor đọc tự động mọi .md file trong .specs/
• Drag-drop spec vào Cursor chat → AI dùng làm context

4. Tooling phụ trợ

• Zod — validation schema, AI gen từ spec
• Playwright — E2E test từ Given-When-Then
• Vitest — unit test từng AC
• Linear / GitHub Issues — link spec → ticket

5 cảm bẫy phổ biến khi làm SDD

Bẫy 1: "Spec quá vague" — không đo được

❌ "Hệ thống phải nhanh và an toàn" — không test được ✅ "API response dưới 500ms cho 95% request" + "Password bcrypt cost ≥10"

Mitigation: Mỗi câu trong AC phải trả lời được "tester verify thế nào?". Nếu không → vague.

Bẫy 2: "Spec quá detail" — không có flexibility

❌ Spec 500 dòng định nghĩa mọi class + method name + variable ✅ Spec 50 dòng định nghĩa behavior, AI chọn implementation

Mitigation: Spec WHAT (hành vi user thấy), không spec HOW (code structure). HOW để AI/dev quyết.

Bẫy 3: "Skip spec for small feature"

"Feature này nhỏ, không cần spec" → 2 tuần sau không hiểu code mình viết.

Mitigation: Quy tắc cứng: nếu feature touch auth/payment/data sensitive → spec MANDATORY dù chỉ 5 dòng.

Bẫy 4: "Stale spec" — spec lỗi thời

Code đã update, spec vẫn cũ → spec gây hiểu lầm, dev mới đọc nhầm.

Mitigation: PR template require "spec updated" checkbox. CI check date last-modified của spec vs code.

Bẫy 5: "Spec viết sau code" — chỉ documentation

❌ Code xong, viết spec để document → không có giá trị design ✅ Spec viết TRƯỚC code → AI dùng làm input, force you to think

Mitigation: Process commit-time: spec PR merge trước code PR. PM/lead review spec, không phải code.

Ví dụ thực tế VN — VietCodex 6-phase workflow

VietCodex (xem methodology) áp dụng SDD trong Phase 2 của 6-phase production workflow:

Phase 1: /discover    → Hiểu business + user
Phase 2: /spec        → Viết spec từng feature (SDD)
Phase 3: /build       → AI gen code theo spec
Phase 4: /verify      → Test acceptance criteria + security audit
Phase 5: /ship        → Deploy với monitoring
Phase 6: /support     → Maintain với spec làm document

Real case study: Project SaaS booking salon cho 1 chuỗi 12 chi nhánh (2025). Phase /spec viết 8 spec document cho 8 feature core (auth / booking / staff schedule / payment / notification / report / admin / customer profile). Tổng 4 ngày spec. Phase /build với Claude Code: 12 ngày gen code (1.5 ngày/feature). Phase /verify: 2 ngày fix bug. Phase /ship: 1 ngày. Tổng 19 ngày từ spec đến launch với 0 bug critical sau 6 tháng vận hành.

So sánh: 1 agency truyền thống cùng project ước tính 6-8 tuần. SDD + AI tiết kiệm 3-5 tuần.

Tóm tắt 1 dòng

Spec-driven dev = viết spec markdown 15-80 dòng cho từng feature (Why + User stories + Acceptance criteria + Edge cases + Out-of-scope) TRƯỚC khi code → AI đọc spec → gen code → test theo AC. Đối cực vibe coding. Phù hợp production / team / auth-payment / maintain dài hạn. Tools 2026: GitHub Spec Kit, Claude Code + slash command, Cursor + .specs/. Mix 80/20: vibe cho periphery, SDD cho core.

Đọc tiếp

• Vibe coding là gì? — đối cực, dùng cho prototype/MVP
• Build MVP — MVP xong → SDD cho production
• TDD + Vertical Slicing — combine SDD với test-first (sắp có)
• Multi-agent cost routing — orchestrate agent theo spec (sắp có)
• Claude Code, Cursor, Copilot — tool nào hỗ trợ SDD tốt nhất
• Prompt Engineering — spec chính là prompt structure cao cấp
• 34 khái niệm cơ bản — tra cứu thuật ngữ

Cần build SaaS / web app / mobile app production-ready với SDD + AI Coding? VietCodex áp dụng 6-phase workflow (Discover → Spec → Build → Verify → Ship → Support) tiết kiệm 3-5 tuần so với agency truyền thống. Xem methodology hoặc đặt audit FREE 30 phút.