skills-requirements-analyzer
Kỹ năng phân tích trang web/module/tài liệu và sinh ra tài liệu Yêu cầu (Requirements Document/User Stories) chuẩn mực — có gán mã REQ ID truy vết được, phát hiện Ambiguity/Risk, kèm ma trận phân quyền và trạng thái.
anhtester · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add anhtester/claude-testing-kit --skill skills-requirements-analyzerAbout this skill
name: skills-requirements-analyzer description: Kỹ năng phân tích trang web/module/tài liệu và sinh ra tài liệu Yêu cầu (Requirements Document/User Stories) chuẩn mực — có gán mã REQ ID truy vết được, phát hiện Ambiguity/Risk, kèm ma trận phân quyền và trạng thái.
Kỹ năng Phân tích Yêu cầu (Requirements Analyzer)
Kỹ năng này cung cấp các hướng dẫn chi tiết để AI (Claude Code) có thể chuyển đổi giao diện UI, cấu trúc DOM/HTML, hoặc tài liệu (Jira ticket, .doc, user story) thành tài liệu Yêu cầu rõ ràng, chi tiết, truy vết được, phục vụ trực tiếp cho QA, Tester và Developer.
1. Mục tiêu cốt lõi
- Xây dựng tài liệu yêu cầu bám sát thực tế hệ thống đang chạy hoặc tài liệu gốc.
- Mọi yêu cầu đều có mã REQ ID — để test cases, automation và RTM truy vết ngược được.
- Đảm bảo tính bao quát: Happy Path, Edge Cases, phân quyền, trạng thái, thông báo lỗi.
- Phát hiện và ghi nhận có hệ thống các điểm mơ hồ (Ambiguity) và rủi ro (Risk).
2. Quy Ước Đánh Mã (BẮT BUỘC — dùng xuyên suốt toàn chuỗi)
| Loại | Format | Ví dụ | Dùng ở đâu |
|---|---|---|---|
| Requirement | REQ-<MODULE>-<SỐ> | REQ-LOGIN-01 | Từng yêu cầu chức năng, business rule, validation rule |
| Story | STORY-<MODULE>-<SỐ> | STORY-PRJ-03 | Nhóm REQ thành đơn vị công việc (backlog view) — xem mục 5 |
| Ambiguity | AMB-<SỐ> | AMB-03 | Điểm mơ hồ cần clarify với PO/BA |
| Risk | RISK-<SỐ> | RISK-02 | Rủi ro kiểm thử |
Quy tắc:
- Mỗi yêu cầu đủ nhỏ để test được độc lập — nếu 1 câu chứa nhiều rule, tách thành nhiều REQ
- REQ ID không đổi sau khi đã phát hành tài liệu (chỉ thêm mới, không đánh lại số)
- Test cases sinh ra ở bước sau PHẢI ghi REQ ID vào cột
REQ ID— đây là mắt xích để kiểm chứng "đủ case" giữa requirements và test cases
Phân vai REQ vs STORY (quan trọng):
REQlà lớp truy vết duy nhất — bất biến, mọi test case / automation / RTM đều neo vào đâySTORYchỉ là lớp nhóm việc — được phép đổi tên, gộp, tách lại theo cách team vận hành mà không ảnh hưởng tới REQ ID hay test case đã viết- ❌ TUYỆT ĐỐI KHÔNG đánh lại số REQ khi tách file hay gom Story. REQ ID gắn với hành vi, không gắn với vị trí trong tài liệu
2.1. Nối tiếp mã REQ giữa các lần chạy (BẮT BUỘC — chống đụng mã)
Cùng một module có thể được phân tích nhiều lần bằng nhiều workflow khác nhau (/generate_requirements_from_website từ UI, /analyze_requirement_document từ Jira ticket, /fetch_jira_requirements…). Nếu mỗi lần đều đánh lại từ 01, các dải mã sẽ đụng nhau và RTM map sai hoàn toàn.
Quy trình bắt buộc TRƯỚC KHI gán REQ ID đầu tiên:
- Đọc danh mục toàn hệ thống — LUÔN LÀM ĐẦU TIÊN:
Bảng danh mục cho biết: module nào đã có tài liệu · prefix nào đã bị chiếm · mã kế tiếp của từng module. Module mới phải chọn prefix chưa có trong danh sách.docs/requirements/README.md⚠️ File không tồn tại (dự án mới) → tạo ngay theo mục 5.7.1 trước khi đi tiếp. KHÔNG bỏ qua bước này rồi ghi thẳng tài liệu module.
- Kiểm tra tài liệu module:
docs/requirements/<module>/requirements_<module>.md - Nếu CHƯA có → đánh số từ
01. - Nếu ĐÃ có → tìm số REQ lớn nhất đang dùng và đánh tiếp từ số kế tiếp. Ví dụ module đã dùng tới
REQ-PRJ-65→ yêu cầu mới bắt đầu từREQ-PRJ-66. - Ghi rõ nguồn vào cột
Nguồncủa mỗi REQ mới:Ticket ABC-123/UI thực tế/AC#2— để biết mã đến từ đợt phân tích nào. - Cập nhật ngược 2 nơi (thiếu một trong hai là lần chạy sau đánh sai số):
- Bảng metadata của tài liệu module:
| Dải mã đã dùng | REQ-PRJ-01 → REQ-PRJ-78 (đợt 1: UI recon 01→65 · đợt 2: ticket ABC-123 66→78) | | Mã kế tiếp | REQ-PRJ-79 — KHÔNG đánh lại từ 01 | - Bảng danh mục trong
docs/requirements/README.md: cộtREQ đã dùng,Mã kế tiếp,AMB treo,Cập nhật
- Bảng metadata của tài liệu module:
Ràng buộc bổ sung:
- ❌ Không "tái sử dụng" mã của REQ đã bị xoá — mã đã cấp là vĩnh viễn chết, kể cả khi yêu cầu đó không còn
- ✅
<MODULE>phải giống hệt giữa các đợt (PRJthì mãi làPRJ, không lúcPRJlúcPROJECT) - ✅ Cùng nguyên tắc này áp cho
AMB-XXvàRISK-XX— đánh tiếp, không đánh lại - ⚠️ Nếu yêu cầu mới thay đổi hành vi của một REQ cũ (không phải thêm mới): giữ nguyên mã cũ, sửa nội dung, và ghi chú
Cập nhật bởi ticket ABC-123— không cấp mã mới cho cùng một hành vi
3. Quy trình trích xuất thông tin
Skill có 2 nhánh trích xuất tuỳ theo nguồn đầu vào. Xác định nhánh trước khi bắt đầu:
| Nguồn đầu vào | Nhánh | Đặc điểm |
|---|---|---|
| Website/ứng dụng đang chạy | 3.1 — UI Recon | Sự thật nằm ở hệ thống; xác minh bằng tương tác thật |
| Jira ticket, .docx, .pdf, .xlsx/.csv, .xml, user story | 3.2 — Document Analysis | Sự thật nằm ở văn bản; xác minh bằng trích dẫn nguyên văn |
| Có cả hai | Chạy 3.2 trước (nắm ý định) → 3.1 sau (đối chiếu thực tế) | Mọi lệch pha giữa 2 nguồn là ambiguity, xem 3.3 |
3.1. Nhánh UI Recon — phân tích website/ứng dụng thực tế
- Phân tích Khung giao diện (Layout): Header, Footer, Sidebar, Main Content, Breadcrumb
- Thu thập Form & Inputs: tất cả
input,select,textarea— ghi nhậntype,required,maxlength,minlength,pattern, giá trị mặc định - Thu thập Actions: chức năng từng nút (Save, Submit, Cancel, Delete, Edit), alerts/toasts/validation messages khi tương tác lỗi
- Trích xuất Workflows: sự phụ thuộc giữa các thành phần (VD: nút Submit chỉ enable khi tích Checkbox)
- Thu thập Phân quyền (nếu có nhiều role): đăng nhập từng role (nếu được cung cấp account) — ghi nhận role nào thấy gì / làm được gì
- Thu thập Trạng thái (nếu entity có status): các trạng thái quan sát được và hành động cho phép ở từng trạng thái
- Thu thập Thông báo lỗi: trigger từng validation để ghi nhận nguyên văn error message