Hướng dẫn viết Requirements Ticket làm đầu vào AI Agent Planning dễ dàng
Bạn đã bao giờ giao một task rồi bị dev hỏi lại 5–6 lần chưa? Hoặc dev nhận một task mà đọc xong vẫn không biết mình phải làm gì?
Hoặc cùng 1 task mà dev này xài AI (cùng là Cursor/ClaudeCode) thì code nhanh hơn dev kia.
Phân tích từ một ticket thực tế và rút ra 5 nguyên tắc áp dụng ngay
Bài này phân tích một requirements ticket thực tế từ một sản phẩm health-tech — để rút ra những nguyên tắc cụ thể giúp bạn viết requirements rõ đến mức dev đọc xong là làm được, không cần hỏi thêm.
Phần 1: Vấn đề phải cụ thể — không phải cảm nhận
Điểm đầu tiên và quan trọng nhất: mô tả vấn đề bằng hành vi cụ thể, không phải nhận xét chủ quan.
Task khách hàng viết:
Với những test có giá trị trung bình trên 100, user phải cuộn từ 0 lên hơn 100 — thao tác này cồng kềnh, trải nghiệm tệ.
Không phải "UX xấu". Không phải "user không thích". Mà là: từ 0 đến 100, phải cuộn từng bước một.
Dev đọc câu đó hình dung ngay được vấn đề. PO đọc câu đó xác định được ưu tiên với stakeholder. QA đọc câu đó biết test case nào cần viết.
Bài học: Mỗi khi bạn sắp viết "UX kém" hay "trải nghiệm không tốt", hãy dừng lại và hỏi: Cụ thể user phải làm gì? Mất bao nhiêu bước? Ở đâu họ bỏ cuộc?
Phần 2: ROI không cần con số chính xác — nhưng phải có lý luận
Nhiều team bỏ qua phần tác động kinh doanh vì nghĩ "cần gì viết, ai cũng biết UX tốt là quan trọng". Đây là sai lầm.
Task viết phần ROI ngắn gọn nhưng đủ ý:
Dịch: Công dev nhỏ, ảnh hưởng đến toàn bộ user, nên ROI cao.
Chỉ một câu, nhưng nó trả lời đủ ba câu hỏi mà bất kỳ ai phân bổ nguồn lực cần biết:
- Chi phí là bao nhiêu? Nhỏ.
- Ai được hưởng lợi? Toàn bộ user.
- Có đáng làm ngay không? Có, vì tỷ lệ cost/benefit cao.
Bạn không cần spreadsheet phân tích 10 trang. Bạn chỉ cần lý luận đủ để người đọc đồng ý hoặc phản bác được.
Bài học: Viết một câu giải thích tại sao ticket này nên được làm bây giờ thay vì để sau. Nếu bạn không thể viết nổi câu đó, có thể ticket này chưa đủ chín để implement.
Phần 3: Out-of-scope bắt buộc phải viết rõ
Đây là phần hay bị bỏ qua nhất — và gây hại nhiều nhất.
Task có một dòng rất đơn giản:
Các test do user tự thêm không nằm trong scope này — vì không có dữ liệu trung bình để tham chiếu.
Không có dòng này, dev có thể:
- Implement cho cả custom items → lỗi vì không có data
- Không biết mình có cần xử lý custom items không → hỏi lại
- Tự quyết định xử lý theo cách mình nghĩ → có thể sai
Với một dòng giải thích, ba kịch bản đó được loại bỏ hoàn toàn.
Out-of-scope không phải thừa — nó là phần định nghĩa ranh giới rõ ràng nhất của một ticket.
Bài học: Với mỗi ticket, hãy hỏi: "Có thứ gì trông giống như nằm trong scope nhưng thực ra không phải không?" Viết nó ra, kèm lý do.
Phần 4: Spec phải theo format "điều kiện → kết quả"
Ba điểm, ba tình huống khác nhau:
| # | Khi nào? | Xảy ra gì? |
|---|---|---|
| 1 | Mở input picker | Scroll đến vị trí trung bình |
| 2 | Đóng mà chưa chọn | Vẫn là trống |
| 3 | Lưu khi trống | Vẫn lưu là trống, không tự điền trung bình |
Ba điểm này cover đủ ba câu hỏi mà dev sẽ đặt ra khi implement. Đặc biệt điểm 2 và 3 cực kỳ quan trọng — nếu thiếu, dev rất dễ implement sai: tưởng rằng "mở input picker" = "điền giá trị trung bình vào ô nhập liệu".
Không phải vậy. Chỉ scroll đến đó để tiện chọn, không tự điền.
Bài học: Viết spec theo format: *"Khi [điều kiện] → [kết quả mong đợi]"*. Đặt câu hỏi: dev sẽ thắc mắc điều gì khi implement? Viết spec để trả lời trước những câu đó.
Phần 5: Acceptance test — mỗi dòng phải testable
Phần cuối của Task là danh sách acceptance test:
Mỗi dòng có thể trả lời câu hỏi: "Tôi làm gì để biết cái này pass?"
- - [] Mở input picker → nhìn xem scroll đang ở đâu.
- - [] Mở rồi đóng mà không chọn → nhìn xem ô có bị điền không.
- - [] Mở custom item input picker → confirm không bị ảnh hưởng.
Đối chiếu với acceptance test tệ: "Toàn bộ tính năng hoạt động đúng." — câu này không giúp ích gì cho QA.
Bài học: Test mỗi spec item, test mỗi edge case, test out-of-scope. Nếu bạn không hình dung được cách test một dòng trong spec, đó là dấu hiệu spec đó chưa đủ rõ.
Tổng kết: 5 nguyên tắc
| # | Nguyên tắc | Dấu hiệu làm tốt |
|---|---|---|
| 1 | Vấn đề cụ thể, có bằng chứng | Hành vi + số liệu/quote user |
| 2 | ROI có lý luận | Công × Impact = lý do ưu tiên |
| 3 | Out-of-scope rõ ràng | Viết cả IN và OUT, kèm lý do |
| 4 | Spec theo format điều kiện → kết quả | Mỗi số thứ tự = 1 tình huống |
| 5 | Edge case có lý do, test case có thể verify | Không chỉ "làm vậy" mà "tại sao" |
Template nhanh để dùng ngay
Yêu cầu mục tiêu
Problem
[Hành vi cụ thể đang xảy ra] → [Hậu quả cụ thể]
ROI & ảnh hưởng
[Quote thực hoặc số liệu]
Key Impact
Result
[Chỉ số bị ảnh hưởng] → [Cải thiện kỳ vọng]
Phạm vi ảnh hưởng
[N users/clients]
Risk nếu không implement
[Hậu quả cụ thể]
Độ ưu tiên
[Công nhỏ/lớn] × [Impact rộng/hẹp] = ROI
Implement point
Dev Screen
[URL hoặc tên màn hình]
Scope
IN: [Cái được thay đổi]
OUT: [Cái KHÔNG thay đổi — lý do]
Spec
- Khi [điều kiện A] → [kết quả A]
- Khi [điều kiện B] → [kết quả B]
- Khi [edge case] → [xử lý]
Data tham khảo
[Nguồn data + link ticket]
Điểm chú ý
- [Edge case] — lý do: [...]
- [Fallback khi data thiếu] — xử lý: [...]
Acceptance test
- [ ] [Happy path: action → expected result]
- [ ] [Boundary: chưa tương tác → state không đổi]
- [ ] [Data: giá trị đúng theo từng điều kiện]
- [ ] [Out-of-scope: không bị ảnh hưởng]
- [ ] [Regression: save/submit vẫn hoạt động]