6.2 KiB
Hướng dẫn sử dụng — ba-traceability (xuyên suốt)
Skill này làm gì
Trả lời đúng một câu hỏi: "có cái gì bị rơi giữa các tài liệu không?"
Nó đọc toàn bộ artifact của một project, trích mọi ID (RQ, US, BR, AC, NFR…), rồi
đối chiếu chéo để tìm bốn loại lỗ hổng:
| Loại lỗ hổng | Nghĩa là |
|---|---|
| Yêu cầu bị bỏ quên | Khách yêu cầu, không ai làm |
| Scope creep | Team làm, không ai yêu cầu |
| AC không được test | Yêu cầu không được kiểm chứng |
| Tham chiếu gãy | Spec nhắc BR-021, tìm không ra ⇒ dev tự quyết |
Nó có quyền chặn Gate G2, G3, G4.
🔴 Nó không sửa tài liệu
Skill này chỉ phát hiện và báo cáo, kèm chỉ dẫn skill nào cần chạy để sửa. Tự sửa sẽ che mất vấn đề thay vì giải quyết nó.
Khi nào gọi
| Tình huống | Có nên gọi |
|---|---|
| Vừa chạy xong một skill giai đoạn | ✅ Nên thành thói quen |
| Chuẩn bị họp duyệt gate | ✅ Bắt buộc |
Vừa sửa một BR hoặc AC |
✅ Để biết chỗ nào phải sửa theo |
| Nhận bàn giao dự án từ BA khác | ✅ Cách nhanh nhất để biết tài liệu thiếu gì |
| Sếp hỏi "đã phủ hết yêu cầu chưa" | ✅ |
| Lần đầu chạy vào hôm trước ngày họp duyệt | 🟠 Được, nhưng phát hiện lúc đó chỉ để hoãn họp |
Cú pháp
/ba-traceability <PROJECT|US-id> [--gate g2|g3|g4] [--out <path>] [go]
| Tham số | Ý nghĩa |
|---|---|
--gate |
Chỉ chạy các phép kiểm liên quan tới một gate cụ thể |
go |
Bỏ bước dừng xác nhận input |
Bạn sẽ nhận được gì
File ba-output/<PROJECT>/00-index/RTM_<PROJECT>.md + năm phần in ra màn hình:
① Bảng coverage — sáu phép kiểm, mỗi cái một con số
| Phép kiểm | Tổng | Đã phủ | Coverage | Ngưỡng | ☐/✅ |
| RQ → US | 12 | 11 | 91,7% | 100% | 🔴 |
| US → RQ | 18 | 16 | 88,9% | 100% | 🔴 |
| US → AC (đủ 4 nhóm) | 18 | 12 | 66,7% | 100% | 🔴 |
② Chi tiết từng lỗ hổng — kèm lệnh để sửa:
🔴 RQ-005 chưa có US nào phủ
Định nghĩa tại: BRIEF_Settlement_v1.0.md §6
Sửa bằng: /ba-2-analysis Settlement
③ Bảng nhất quán — version lệch, ràng buộc lệch, mã lỗi lệch, trạng thái lệch
④ OQ/CR tồn đọng — sắp theo số ngày quá hạn
⑤ Kết luận gate — gate nào bị chặn và vì sao
Hai chiều, hai loại lỗi
Đây là điểm quan trọng nhất cần hiểu về skill này:
chiều xuôi RQ → US → AC → test case bắt: BỎ SÓT
chiều ngược test case → AC → US → RQ bắt: LÀM THỪA
Hầu hết công cụ traceability chỉ chạy chiều xuôi. Chiều ngược mới trả lời được câu hỏi "cái này ai yêu cầu?" — và scope creep là thứ làm dự án trễ mà không ai giải thích được vì sao.
Ví dụ hội thoại
Bạn: /ba-traceability Settlement --gate g3
Claude: [Bước 0]
Quét được:
| BRIEF_Settlement_v1.0.md | 12 RQ, 3 GOAL | ✅ Baselined |
| BACKLOG_Settlement_v1.0.md | 18 US | ✅ Baselined |
| BR_Settlement_v1.2.md | 24 BR | ✅ Baselined |
| SRS_US011_v1.2.md | 8 AC, 12 field | 🟠 In Review |
| SRS_US012..018 | Không tìm thấy | — |
⚠️ Chỉ có SRS cho 1/18 US. Phép kiểm "US → AC" sẽ báo coverage rất thấp —
đúng thực tế, không phải lỗi quét.
Test case: chưa tìm thấy ⇒ phép kiểm 5 (AC → test case) không chạy được.
Xác nhận giúp tôi trước khi chạy.
Bạn: Đúng rồi, mới viết SRS cho US011 thôi. Chạy đi.
Claude: [báo cáo]
G3: 🔴 CHẶN
- 17/18 US chưa có SRS
- US-011: thiếu AC nhóm "lỗi hệ thống" và "phân quyền"
- 4 TBD trong bảng field US-011 (F01 độ dài, F04 nguồn dropdown…)
- BR-021 tham chiếu ở SRS_US011 §1.3 nhưng không có trong BR_v1.2
→ có thể BR bị đổi số ở v1.1
Lỗi thường gặp
"Coverage 99%, làm tròn lên 100% được không?" Không. Cái 1% đó là một yêu cầu thật, của một người thật, và nó sẽ lọt ra sản phẩm mà không ai kiểm chứng.
"BR-021 được nhắc trong SRS rồi, tính là đã phủ chứ?" Không. Nhắc tới không có nghĩa là đã hiện thực hoá. Phải xem nó được áp vào field/AC nào. Đếm số lần xuất hiện là phép đo sai.
"Tham chiếu gãy chắc do đánh nhầm số thôi, bỏ qua." Tham chiếu gãy nghĩa là dev đọc spec, thấy "theo BR-021", đi tìm không ra, rồi tự quyết. Đó là cách một business rule bốc hơi khỏi sản phẩm mà không ai biết.
"US-013 đã có AC rồi mà sao báo chưa phủ?" Phép kiểm 3 đòi đủ bốn nhóm: thành công · validation · lỗi hệ thống · phân quyền. US chỉ có AC nhóm 1 tính là chưa phủ, không phải "phủ một phần" — vì phần thiếu chính là phần dev sẽ tự bịa.
"Skill tự sửa giúp luôn được không?" Không, và cố ý như vậy. Nó báo cáo kèm lệnh để sửa. Tự sửa sẽ che mất vấn đề, và nguyên nhân gốc (đặc tả thiếu chỗ nào) không bao giờ được ghi nhận để cải thiện.
"Chỉ cần chạy trước gate là đủ." Chạy sau mỗi giai đoạn thì lỗ hổng được phát hiện lúc còn rẻ. Chạy lần đầu vào hôm trước ngày họp duyệt thì phát hiện cũng chỉ để hoãn họp.
Liên quan
- Quy ước ID:
../README.md§4 - Tiêu chí gate:
../ba-lifecycle/references/workflow.md§2 - Quan hệ phụ thuộc giữa artifact (sửa cái này thì phải sửa tiếp cái nào):
../ba-lifecycle/references/artifact-map.md§5 - Template:
templates/rtm.md