AI Series Phỏng vấn 16: Một spec coding tốt nên như thế nào?

Một Spec Coding (lập trình dựa trên đặc tả) tốt, cốt lõi là biến "ý tưởng mơ hồ" thành "hợp đồng chính xác, có thể kiểm chứng và thực thi". Nó không chỉ là viết một tài liệu, mà là xây dựng một ngôn ngữ giao tiếp không mơ hồ giữa con người và AI (hoặc giữa người với người). Dưới đây, tôi sẽ trình bày một spec tốt từ bốn khía cạnh: cấu trúc nội dung, nguyên tắc viết, quy trình cộng tác với AI, và kiểm tra chất lượng.

I. Cấu trúc chuẩn của tài liệu đặc tả (ví dụ với module chức năng)

Mục	Nội dung bắt buộc	Ví dụ
1. Mục tiêu và phạm vi	Một câu mô tả làm gì, xác định rõ không làm gì	“Triển khai API đăng ký người dùng, không bao gồm xác thực email”
2. Hợp đồng đầu vào/đầu ra	Cấu trúc dữ liệu, kiểu dữ liệu, trường bắt buộc/tùy chọn, giá trị mẫu	`POST /register` request body `{email: string, password: string}`, response `201` hoặc `400` kèm mã lỗi
3. Hành vi và logic	Quy tắc nghiệp vụ, điều kiện biên, chuyển đổi trạng thái	“Mật khẩu dài 8-20 ký tự, chứa ít nhất một chữ số; email đã tồn tại trả về `409`”
4. Xử lý lỗi	Tất cả các kịch bản ngoại lệ và mã lỗi/thông báo tương ứng	“Kết nối cơ sở dữ liệu thất bại → trả về `503`, không hiển thị stack trace”
5. Yêu cầu phi chức năng	Hiệu năng (thời gian phản hồi < 200ms), bảo mật (truy vấn tham số hóa), log, khả năng quan sát	“Tất cả SQL phải sử dụng biên dịch trước; ghi lại `email` nhưng không ghi `password`”
6. Test case (quan trọng)	Ít nhất 3 đầu vào điển hình + 2 đầu vào biên/ngoại lệ, đưa ra đầu ra mong đợi	Xem bảng dưới
7. Phụ thuộc và ràng buộc	Sử dụng thư viện nào, phiên bản, biến môi trường	“Python 3.10+, FastAPI, biến môi trường `DB_URL`”

Ví dụ về test case (được nhúng trong spec)

Kịch bản	Đầu vào	Đầu ra mong đợi
Đăng ký bình thường	email: `a@b.com`, pwd: `Pass1234`	`201`, trả về `user_id`
Mật khẩu quá ngắn	pwd: `Ab1`	`400`, mã lỗi `WEAK_PASSWORD`
Email đã tồn tại	email giống như trên	`409`, mã lỗi `EMAIL_EXISTS`

Spec tốt phải viết test case trước, vì AI có thể dựa vào chúng để tạo unit test trực tiếp và tự động xác thực sau khi hoàn thành.

II. Nguyên tắc cốt lõi khi viết Spec (biến thể SMART)

Nguyên tắc	Giải thích	Phản ví dụ
Chính xác (Precise)	Sử dụng số cụ thể, kiểu dữ liệu, điều kiện boolean, tránh “càng nhiều càng tốt”, “thông thường”	❌ “Mật khẩu phải đủ an toàn” → ✅ “Mật khẩu ít nhất 8 ký tự, gồm chữ hoa, chữ thường, chữ số”
Có thể kiểm chứng (Verifiable)	Mỗi yêu cầu có thể được xác định đạt/không đạt thông qua kiểm thử tự động hoặc kiểm tra thủ công	❌ “Mã nguồn phải thanh lịch” → ✅ “Độ phức tạp vòng lặp của hàm ≤ 10, không có khối mã trùng lặp”
Không mơ hồ (Unambiguous)	Cùng một thuật ngữ phải nhất quán trong toàn văn bản, nếu cần thì có glossary	❌ “Nếu người dùng không tồn tại, trả về lỗi” → ✅ “Người dùng không tồn tại → trả về `404` và `{code: 'USER_NOT_FOUND'}`”
Hoàn chỉnh (Complete)	Bao phủ happy path, tất cả đường dẫn ngoại lệ, yêu cầu phi chức năng	❌ Chỉ viết kịch bản thành công → ✅ Bao gồm timeout cơ sở dữ liệu, thiếu quyền, v.v.
Nguyên tử hóa (Atomic)	Một spec chỉ mô tả một tính năng có thể giao độc lập (dễ dàng cho AI hoàn thành một lần)	❌ Dùng một spec để viết “toàn bộ hệ thống thanh toán” → ✅ Tách thành “tạo lệnh thanh toán”, “xác thực callback”, “hoàn tiền”

III. Quy trình Spec Coding khi cộng tác với AI

Người viết spec (cấu trúc như trên, đặc biệt viết test case và chữ ký hàm).
Đưa spec một lần cho AI (không thêm yêu cầu dạng hội thoại, tránh nhiễu vibe).
AI xuất ra mã nguồn + unit test (AI phải tạo test có thể thực thi dựa trên test case trong spec).
Chạy kiểm thử: Nếu tất cả đều qua, chuyển bước tiếp; nếu không, sửa spec hoặc trực tiếp sửa mã (lúc này có thể vào vòng lặp nhỏ, nhưng cần ghi lại thay đổi).
Kiểm tra thủ công: Kiểm tra xem có đưa vào chức năng ngoài spec không (scope creep), kiểm tra bảo mật/hiệu năng.
Cố định: Gửi tài liệu spec và mã cuối cùng vào kho lưu trữ như tài liệu vĩnh viễn.

Thực hành quan trọng: Spec được mã hóa — sử dụng spec.md + test_spec.py, trong đó file test trực tiếp đến từ các ví dụ trong spec, để sau này khi sửa mã chỉ cần chạy test là có thể xác thực spec có bị phá vỡ không.

IV. Hiệu quả của Spec tốt (có thể dùng làm tiêu chí chấp nhận)

Tính xác định: Cùng một spec cho các AI (hoặc người) khác nhau cho ra triển khai tương tự.
Khả năng kiểm thử: Sau khi viết mã, có thể tự động xác thực 90% tính đúng đắn ngay lập tức.
Khả năng bảo trì: Sau nửa năm, bất kỳ ai xem spec đều hiểu được ý đồ thiết kế ban đầu.
Chi phí giao tiếp thấp: Khi thảo luận nhóm, chỉ thảo luận spec, không thảo luận từng dòng mã cụ thể.
Bảo mật/chất lượng được tích hợp: Yêu cầu bảo mật (như truy vấn tham số hóa) và điều kiện biên được ghi rõ trong spec, AI phải tuân thủ.

V. Ví dụ về một Spec tốt (phiên bản tối giản)

# Spec: API đăng ký người dùng

## Phạm vi
- Nhận email, password
- Không gửi email xác thực, không kiểm tra tính xác thực của email

## Hợp đồng
POST /register
Content-Type: application/json
Request: { "email": string, "password": string }
Response 201: { "user_id": string }
Response 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Response 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Hành vi
- Email phải tuân theo định dạng cơ bản RFC 5322 (a@b.c)
- password: độ dài 8-20, chứa ít nhất một chữ số và một chữ hoa
- Sử dụng bcrypt để mã hóa lưu trữ, salt cost 10
- Nếu phát hiện email đã tồn tại trước khi lưu vào cơ sở dữ liệu → 409

## Test case (đầu vào -> mã trạng thái mong đợi + trường response)
| Đầu vào email | password | Mong đợi |
|------------|----------|------|
| test@x.com | Pass1234  | 201, user_id tồn tại |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (email đã tồn tại) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Phi chức năng
- SQL phải sử dụng truy vấn tham số hóa (chống injection)
- Ghi log IP nguồn đăng ký, không ghi password
- Thời gian phản hồi 95% request < 100ms (không bao gồm bcrypt)

## Phụ thuộc
- Python 3.10+, FastAPI, bcrypt, asyncpg

Spec Coding tốt = Biến "quyết định thiết kế" của con người thành "test case + chữ ký kiểu dữ liệu + ràng buộc hành vi" của máy, để AI chỉ chịu trách nhiệm điền phần triển khai, còn con người luôn kiểm soát chất lượng và hướng đi.