Bài 3 — Viết spec chất lượng cao mà agent hiểu đúng

Đã đọc 0/8 mục · còn khoảng 3 phút

Cách chúng tôi ghi nhận

Một mục được tính là đã đọc khi nó nằm giữa màn hình đủ lâu so với độ dài của nó (bảng và sơ đồ tính một nửa), bạn vẫn đang cuộn hoặc bấm phím, và bạn đã thấy tới cuối mục. Lướt nhanh hoặc để tab mở không được tính. Chúng tôi chỉ lưu thời gian đọc từng mục — không lưu gì khác.

Spec tồi thì plan tồi, plan tồi thì code tồi. Đây là kỹ năng đòn bẩy lớn nhất. Một spec tốt vừa đủ chi tiết để agent không đoán bừa, vừa đủ thoáng để agent tự chọn cách hiện thực tốt nhất.

Nguyên tắc vàng: mô tả "cái gì", không mô tả "thế nào"

Sai (áp đặt cách làm):

"Tạo hàm validateEmail dùng regex ^[a-z]+@... trong file utils.js"

Đúng (mô tả hành vi):

"Hệ thống từ chối email sai định dạng với lỗi 400 và thông báo rõ ràng.
Email hợp lệ theo RFC 5322 ở mức thực dụng."

Cách thứ hai để agent chọn thư viện/regex phù hợp, và không khóa cứng cấu trúc file.

Trái tim của spec: Acceptance Criteria đo được

Mỗi tiêu chí phải trả lời được "đúng/sai" một cách khách quan. Dùng công thức Given–When–Then cho các case quan trọng:

### AC1: Đăng nhập sai quá nhiều
- Given người dùng nhập sai mật khẩu 5 lần trong 10 phút
- When họ thử đăng nhập lần 6
- Then hệ thống khóa tài khoản 15 phút, trả 429

### AC2: Đăng nhập thành công
- Given email + mật khẩu đúng
- When gọi POST /login
- Then trả 200 + JWT hết hạn sau 24h

Tiêu chí kiểu này chuyển thẳng thành test — agent viết test theo nó và bạn nghiệm thu theo nó.

Nêu rõ ràng buộc và bất biến (invariants)

Những điều luôn phải đúng, dù code thế nào:

## Ràng buộc
- Mật khẩu KHÔNG bao giờ lưu plaintext (bcrypt, cost >= 12).
- Mọi endpoint /admin/* yêu cầu role=admin.
- Không gọi API bên ngoài trong luồng request đồng bộ (dùng queue).

Ví dụ: nâng cấp một spec yếu thành mạnh

Spec yếu:

"Làm trang tìm kiếm sản phẩm, phải nhanh và tiện."

Spec mạnh:

# Spec: Tìm kiếm sản phẩm
## Mục tiêu
Người mua tìm sản phẩm theo từ khóa, lọc theo giá.
## Acceptance Criteria
- [ ] GET /search?q=&min=&max= trả tối đa 20 kết quả/trang
- [ ] Tìm theo tên + mô tả, không phân biệt hoa thường + dấu
- [ ] Rỗng kết quả trả mảng [] + gợi ý từ khóa
- [ ] P95 latency < 300ms với 100k sản phẩm
## Ngoài phạm vi
- Gợi ý AI, autocomplete (phase sau)
## Câu hỏi mở
- Có cần phân trang cursor hay offset là đủ?

Khung 5 câu hỏi trước khi coi spec là xong

Người đọc lạ có hiểu đích đến không?
Mỗi AC có kiểm chứng đúng/sai khách quan không?
Đã ghi rõ cái gì ngoài phạm vi chưa?
Ràng buộc bảo mật/hiệu năng đã nêu chưa?
Chỗ nào mình chưa chắc — đã đưa vào "Câu hỏi mở" chưa?

Các bước viết spec trong thực tế

Viết mục tiêu 1-2 câu, đọc lại xem có đúng vấn đề không.
Liệt kê 3-7 acceptance criteria dạng đo được.
Thêm case biên (lỗi, rỗng, quá tải) — nơi bug hay ẩn.
Ghi ràng buộc và bất biến.
Cắt phạm vi: chuyển thứ "hay ho nhưng chưa cần" xuống "ngoài phạm vi".
Nhờ agent "phản biện spec này, chỉ ra chỗ mơ hồ" trước khi lập plan.

Bước 6 cực giá trị: agent thường phát hiện lỗ hổng bạn không thấy, và bạn vá spec chứ chưa tốn công code.

Sai lầm thường gặp

Tiêu chí không đo được: "UX phải mượt". Đổi thành hành vi cụ thể quan sát được.
Quên case biên: Chỉ tả happy path; agent bỏ qua lỗi/rỗng, sinh bug production.
Áp đặt implementation: Ghi cứng tên file/hàm khiến agent không tối ưu được và code cứng nhắc.
Không cắt phạm vi: Spec ôm đồm khiến plan phình to, review đuối, drift tăng.
Không nhờ agent phản biện spec: Bỏ lỡ cơ hội sửa lỗi rẻ nhất — sửa trên giấy.

Bài 4: biến spec đã chốt thành một plan chia task mà agent thực thi được.

Học xong bài này rồi? Tạo tài khoản miễn phí để lưu lại — lần sau vào là biết ngay đang dở ở đâu, và học hết khóa thì có chứng chỉ. Lưu tiến độ của tôi