Khi mới dùng AI coding agent (Claude Code, Cursor, Copilot Agent...), đa số chúng ta prompt kiểu "viết cho tôi API đăng nhập". Agent sinh ra một đống code, chạy được vài phút rồi lệch hoàn toàn khỏi ý định ban đầu. Đó gọi là vibe coding — nhanh lúc đầu, đau về sau.
Spec-Driven Development (SDD) với Agent đảo ngược thứ tự: bạn viết spec (đặc tả) trước, agent đọc spec để tạo plan (kế hoạch task), rồi code từng task một, và bạn review từng bước trước khi đi tiếp. Spec trở thành nguồn sự thật (source of truth), không phải câu prompt trong đầu bạn.
Ba tạo tác cốt lõi
- Spec — Mô tả cái gì và tại sao: mục tiêu, phạm vi, tiêu chí chấp nhận (acceptance criteria), ràng buộc. KHÔNG mô tả code như thế nào.
- Plan — Agent chia spec thành danh sách task nhỏ, có thứ tự, mỗi task kiểm chứng được.
- Implementation — Agent code theo từng task; bạn review diff sau mỗi task.
Ví dụ cụ thể
So sánh hai cách yêu cầu cùng một tính năng "reset mật khẩu":
Vibe coding:
"Làm chức năng quên mật khẩu cho tôi"
Spec-driven:
## Spec: Reset mật khẩu qua email
### Mục tiêu
Người dùng quên mật khẩu tự đặt lại mà không cần admin.
### Acceptance Criteria
- [ ] POST /forgot gửi email chứa token hết hạn sau 30 phút
- [ ] Token dùng 1 lần, hash trong DB (không lưu plaintext)
- [ ] POST /reset đổi mật khẩu nếu token hợp lệ + chưa hết hạn
- [ ] Rate limit: tối đa 3 yêu cầu / email / giờ
### Ngoài phạm vi
- SMS OTP (làm sau)
Với spec này, agent biết chính xác đích đến, còn bạn có thước đo để nghiệm thu.
Vì sao SDD giảm sai lệch (drift)
Mỗi lần agent tự "đoán" một chi tiết bạn chưa nói, xác suất lệch tăng lên. Spec loại bỏ phần lớn phỏng đoán đó. Ba cơ chế giúp giảm drift:
- Neo ngữ cảnh: Spec là văn bản agent đọc lại được ở mọi bước, không bị trôi khỏi cửa sổ ngữ cảnh như một câu chat cũ.
- Kiểm chứng từng bước: Task nhỏ + review sớm phát hiện lệch khi nó còn rẻ để sửa.
- Ranh giới rõ: Mục "Ngoài phạm vi" ngăn agent làm quá tay (over-engineering).
Các bước áp dụng lần đầu
- Chọn một tính năng nhỏ, đã hiểu rõ (ví dụ: 1 endpoint).
- Viết spec 1 trang: mục tiêu + acceptance criteria + ngoài phạm vi.
- Yêu cầu agent: "Đọc spec này, ĐỪNG code, hãy đề xuất plan chia task".
- Duyệt plan, chỉnh nếu cần.
- Yêu cầu agent làm task 1, dừng lại cho bạn review.
- Review diff, chạy test, rồi mới sang task 2.
Khung tư duy: "Spec → Plan → Task → Review → Lặp"
Ghi nhớ vòng lặp này như một hợp đồng: bạn giữ quyền quyết định ở mỗi ranh giới, agent làm phần cơ bắp.
Checklist một spec tối thiểu tốt
- [ ] Có mục tiêu (1-2 câu) và lý do.
- [ ] Có acceptance criteria kiểm chứng được (không mơ hồ).
- [ ] Có mục "ngoài phạm vi".
- [ ] Nêu ràng buộc quan trọng (bảo mật, hiệu năng, tech stack).
- [ ] Đủ ngắn để đọc trong 3 phút.
Sai lầm thường gặp
- Viết spec như viết code: Nhồi cả tên hàm, tên biến vào spec. Spec nói cái gì, để agent lo thế nào.
- Acceptance criteria mơ hồ: "Phải nhanh, phải an toàn" — không đo được. Hãy viết "P95 < 200ms", "token hash bằng SHA-256".
- Bỏ qua bước plan: Nhảy thẳng vào code khiến bạn mất điểm kiểm soát đầu tiên.
- Spec quá dài, cầu toàn: 10 trang không ai đọc; agent cũng loãng ngữ cảnh. Bắt đầu nhỏ, bổ sung dần.