Nguyên tắc 6: Traceable

Từ code tìm được spec. Từ spec tìm được test. Từ test tìm được requirement.

Traceability cần đi được ba chiều: Business Requirement (BR) ↔ Use Case (UC) ↔ Code/Test.

Tình huống

3 giờ sáng, production incident: khách đặt hàng nhưng không nhận email. On-call là Quân, mới vào 2 tháng.

Không traceability: grep send_email ra nhiều chỗ, đọc mãi không biết đây là bug hay hành vi đúng theo quyết định cũ. Senior đang ngủ → patch tạm và hy vọng.
Có traceability: alert/log chỉ tới UC-042 / AC-2. Quân mở spec (“Email gửi trong 10 giây sau payment success”), mở test AC-2 (pass), check log → webhook thành công nhưng email service crash. Vấn đề không phải AC-2 sai, mà spec thiếu AC về retry email. Quân mở ticket rất rõ: “Bổ sung AC-5: retry email khi provider fail.” Thời gian “không biết phải hỏi gì” giảm rất mạnh.

Folder soi chiếu spec:

/specs/use-cases/checkout/UC-042-place-order-qr.md
/src/use-cases/checkout/place-order-qr/
/tests/use-cases/checkout/place-order-qr/

Chỉ riêng convention tên file + commit message đã giúp rất nhiều, kể cả khi chưa có IDE/plugin click qua lại.