Nguyên tắc 1: Requirements-Driven

Spec dẫn dắt code, không phải code dẫn dắt spec.

Nếu một khái niệm mới xuất hiện trong code, nó nên xuất hiện trong spec trước hoặc ít nhất cùng lúc.

Tình huống

Dev Hùng thêm trường is_premium vào Order, PO gật đầu, merge. Ba tháng sau: bug - một số khách thường vẫn nhận thông báo “đơn ưu tiên”. Không có quyết định nào rõ trong Slack, Hùng đã chuyển team, dev mới thấy cột is_premium set ở bốn chỗ, mỗi chỗ một điều kiện hơi khác. Không ai nhớ vì sao field tồn tại → Code không có ngữ cảnh.

Cách áp dụng

Khi bạn hoặc AI định thêm field/status/flow/permission/policy, dừng lại 2 phút và ghi vào spec:

## Entity: Order
- field `is_premium` (boolean): set TRUE khi customer.tier = "VIP"
  tại thời điểm tạo order. Không thay đổi sau đó. Phục vụ BR-012.

• Đưa “Spec updated” vào Definition of Done.
• PR thêm field/status/flow mà không link tới spec → gắn label needs-spec.
• Commit message có UC/BR ID: feat(UC-042): add QR expiry validation.

Quan trọng: đừng biến nguyên tắc này thành thủ tục nặng. Với thay đổi nhỏ, một dòng spec là đủ. Mục tiêu là giữ ý định lại, không phải viết văn bản cho đẹp.

Liên quan

• Sáu nguyên tắc Spec-Driven - nguyên tắc số 1
• Code không có ngữ cảnh - hậu quả khi code dẫn dắt spec
• Traceable - cần UC/BR ID trong commit để truy ngược