requirements-clarity

Tổng quan về skill requirements-clarity

requirements-clarity là một quy trình làm rõ yêu cầu có cấu trúc, dùng để biến những đề bài tính năng còn mơ hồ thành bộ yêu cầu đủ rõ để triển khai trước khi bất kỳ ai bắt tay vào code. Skill này đặc biệt phù hợp với product manager, tech lead, founder và developer có hỗ trợ AI — những người thường bắt đầu bằng các yêu cầu kiểu “thêm đăng nhập”, “làm dashboard” hoặc “triển khai thanh toán” nhưng vẫn chưa có đủ chi tiết để estimate, thiết kế hay ship một cách an toàn.

requirements-clarity dùng để làm gì

Công việc thực sự ở đây không phải là “viết prompt hay hơn”. Mục tiêu là giảm làm lại bằng cách buộc các quyết định còn thiếu phải lộ ra rõ ràng: ranh giới phạm vi, bối cảnh kỹ thuật, tiêu chí chấp nhận, edge case, ràng buộc và thước đo thành công. Skill này thực hiện điều đó bằng chuỗi câu hỏi có trọng tâm và hướng đầu ra theo kiểu PRD, thay vì chỉ trả về một câu trả lời brainstorming chung chung.

Trường hợp sử dụng phù hợp nhất

requirements-clarity phù hợp nhất khi:

• yêu cầu còn mơ hồ
• tính năng có khả năng lớn hơn một bản vá nhanh
• có nhiều team hoặc stakeholder cùng tham gia
• stack, integration hoặc các ràng buộc phi chức năng vẫn chưa rõ
• bạn cần thứ gì đó gần với một bản spec có thể dùng được, chứ không chỉ là trao đổi sơ bộ

Điều gì khiến skill này khác với một prompt thông thường

Điểm khác biệt nằm ở quy trình. Skill này chủ động phát hiện yêu cầu mơ hồ, chạy phân tích lỗ hổng có cấu trúc, đặt câu hỏi theo từng vòng thay vì dồn một lượt, và dùng mô hình chấm điểm để đánh giá độ đầy đủ của yêu cầu. Vì vậy, nếu vấn đề chính của bạn là thiếu thông tin chứ không phải cách diễn đạt, nó đáng để áp dụng hơn nhiều so với một prompt kiểu “giúp tôi làm rõ tính năng này” dùng một lần.

Khi nào requirements-clarity không phải công cụ phù hợp

Đừng dùng requirements-clarity khi đầu việc đã rất sát code và cụ thể, chẳng hạn như:

• bug có bước tái hiện rõ ràng
• change request gắn với file hoặc số dòng cụ thể
• yêu cầu đã kèm sẵn code snippet
• công việc xoay quanh một function hoặc class có sẵn

Trong các trường hợp đó, workflow triển khai, debug hoặc review code thông thường thường sẽ nhanh hơn.

Cách dùng skill requirements-clarity

Bối cảnh cài đặt requirements-clarity

Trong repository softaworks/agent-toolkit, skill này nằm tại skills/requirements-clarity. Nếu môi trường của bạn hỗ trợ cài Skills từ GitHub, cách cài thực tế là:

npx skills add softaworks/agent-toolkit --skill requirements-clarity

Nếu runtime agent của bạn không dùng bộ cài đó, hãy đọc trực tiếp skill tại:
https://github.com/softaworks/agent-toolkit/tree/main/skills/requirements-clarity

Hãy bắt đầu với SKILL.md, sau đó xem README.md để hiểu phần giải thích ở mức tổng quan hơn.

Các file nên đọc trước lần dùng đầu tiên

Hãy đọc theo thứ tự sau:

1. skills/requirements-clarity/SKILL.md
2. skills/requirements-clarity/README.md

SKILL.md là file quan trọng nhất để hiểu cách skill được gọi: khi nào skill nên kích hoạt, khi nào không nên, và luồng đặt câu hỏi vận hành ra sao. README.md hữu ích để nắm khái niệm chấm điểm và dạng đầu ra được kỳ vọng.

requirements-clarity được thiết kế để kích hoạt như thế nào

requirements-clarity được thiết kế cho các yêu cầu mơ hồ, không phải ticket kỹ thuật đã quá chi tiết. Skill nên kích hoạt khi đầu vào chưa đủ thông tin để build một cách tự tin. Ví dụ kích hoạt tốt:

• “Add login to the app”
• “Implement payment support”
• “Create an admin dashboard”
• “We need user management”

Các yêu cầu này đủ rộng để skill tạo ra giá trị thực thông qua việc làm rõ.

Kiểu đầu vào cho ra kết quả tốt nhất

Prompt mở đầu tốt nhất là prompt cung cấp vừa đủ ngữ cảnh để skill đặt các câu hỏi follow-up thông minh hơn:

• mục tiêu kinh doanh
• người dùng mục tiêu
• sản phẩm hoặc hệ thống hiện tại
• các ràng buộc đã biết
• deadline sơ bộ hoặc giai đoạn bàn giao
• các integration bắt buộc phải có
• những gì chắc chắn bị loại trừ

Một đầu vào yếu:

• “Build notifications.”

Một đầu vào tốt hơn:

• “We need in-app notifications for team admins in our SaaS dashboard. Stack is React + Node. MVP should cover system alerts and mention alerts, but not email yet. We need something small enough for this sprint and clear enough to estimate.”

Phiên bản thứ hai giúp requirements-clarity bớt phải hỏi những câu quá chung và đi nhanh hơn đến một bản spec có thể dùng được.

Cách biến một mục tiêu thô thành prompt gọi skill tốt

Hãy đi theo cấu trúc sau:

• tính năng là gì
• vì sao nó quan trọng
• phục vụ ai
• nằm ở đâu trong sản phẩm
• môi trường kỹ thuật
• các ràng buộc
• những gì bạn đã biết
• những gì vẫn chưa chốt

Ví dụ:

“I need help using requirements-clarity for Requirements Planning. We want to add SSO to our B2B web app for enterprise customers. Current stack is Next.js, Node, and Postgres. We already support email/password login. We need a first-pass PRD covering MVP scope, admin setup flow, acceptance criteria, edge cases, and non-goals. Unknowns include which providers to support first and how provisioning should work.”

Prompt như vậy cho skill một nền tảng đủ cụ thể để phân tích, nhưng không giả vờ rằng yêu cầu đã hoàn chỉnh.

Workflow requirements-clarity thực tế sẽ diễn ra như thế nào

Một luồng requirements-clarity usage thực tế thường như sau:

1. Bắt đầu từ yêu cầu tính năng còn thô.
2. Để skill xác định những phần yêu cầu còn thiếu.
3. Trả lời các câu hỏi follow-up theo từng cụm nhỏ.
4. Rà lại phạm vi đã được làm rõ và các non-goal đã nêu rõ.
5. Yêu cầu đầu ra cuối cùng theo dạng PRD.
6. Dùng đầu ra đó cho estimate, thiết kế hoặc handoff.

Chất lượng đến từ việc hoàn tất cuộc đối thoại, không phải chỉ đọc phản hồi đầu tiên.

Hệ thống chấm điểm hữu ích ở điểm nào

Repository mô tả một mô hình độ rõ ràng thang 100 điểm. Phần hữu ích không nằm ở con số tuyệt đối, mà ở hiệu ứng checklist. Nó giúp lộ ra liệu yêu cầu của bạn còn thiếu:

• bối cảnh kỹ thuật
• tiêu chí chấp nhận
• thước đo thành công
• edge case
• cách xử lý lỗi
• ranh giới phạm vi

Hãy dùng điểm số như một tín hiệu cho câu hỏi “còn gì chưa được trả lời”, chứ không phải một vanity metric.

Nên trả lời bao nhiêu câu hỏi trong một lượt

Phương pháp của chính skill ưu tiên đi từng nhóm một, thường là 2–3 câu hỏi có trọng tâm trong mỗi vòng. Điều này quan trọng vì nếu dồn mọi điểm chưa rõ vào một câu trả lời dài, bạn rất dễ tạo ra câu trả lời hời hợt và mâu thuẫn bị che khuất. Các vòng ngắn giúp chất lượng yêu cầu tốt hơn và cũng dễ review với stakeholder hơn.

Có thể kỳ vọng đầu ra nào từ requirements-clarity

Một lần chạy tốt nên giúp bạn có được:

• định nghĩa tính năng rõ ràng hơn
• các giả định được nêu tường minh
• ranh giới giữa MVP và các giai đoạn sau
• tiêu chí chấp nhận
• các edge case đáng chú ý
• ràng buộc và phụ thuộc
• một tài liệu kiểu PRD mà bạn có thể tiếp tục tinh chỉnh

Nếu bạn chỉ nhận được các khuyến nghị rất chung chung, nhiều khả năng là ngữ cảnh đầu vào quá mỏng hoặc cuộc trao đổi đã dừng lại quá sớm.

Mẹo thực tế giúp dùng requirements-clarity hiệu quả hơn

• Gọi tên rõ khu vực sản phẩm: “admin dashboard,” “checkout,” “mobile onboarding.”
• Nêu sớm các phần loại trừ đã biết: “No mobile app in MVP,” “No SAML in phase 1.”
• Thêm thông tin về hệ thống hiện có: phương thức auth hiện tại, payment provider hiện tại, các role hiện tại.
• Tách biệt nhu cầu kinh doanh với ưu tiên triển khai nếu cả hai cùng tồn tại.
• Nếu team vẫn đang ở giai đoạn discovery, hãy yêu cầu skill làm lộ các điểm chưa rõ trước khi đề xuất giải pháp.

Những điều chỉnh nhỏ này thường cải thiện độ cụ thể tốt hơn là chỉ yêu cầu “more detail”.

Câu hỏi thường gặp về skill requirements-clarity

requirements-clarity có phù hợp với người mới bắt đầu không?

Có, đặc biệt phù hợp với người mới đã biết mục tiêu tính năng nhưng chưa biết cách viết yêu cầu cho chắc. Cấu trúc của skill giúp họ tránh các thiếu sót rất phổ biến như bỏ quên edge case, phạm vi không rõ ràng và thiếu tiêu chí chấp nhận. Nó cũng hữu ích cho những người có kinh nghiệm đang cần một quy trình intake lặp lại được.

Điều này khác gì với việc yêu cầu AI viết thẳng một PRD?

Một prompt yêu cầu PRD trực tiếp thường sẽ tự bù vào các khoảng trống bằng cách “bịa” thêm chi tiết. requirements-clarity tốt hơn khi bạn muốn model nhận diện sự mơ hồ trước, đặt câu hỏi có mục tiêu, rồi mới tiến dần đến PRD. Cách này giảm cảm giác tự tin sai và thường tạo ra tài liệu lập kế hoạch đáng tin hơn.

Tôi có thể chỉ dùng requirements-clarity cho Requirements Planning không?

Có. Đây là một trong những trường hợp phù hợp nhất. Skill này đặc biệt hữu ích ở giai đoạn lập kế hoạch trước triển khai, định hình backlog, product discovery và căn chỉnh giữa các nhóm chức năng. Bạn không nhất thiết chỉ dùng nó cho tài liệu cuối cùng; nó có giá trị lớn hơn ở giai đoạn sớm, khi yêu cầu vẫn còn chưa ổn định.

Khi nào nên bỏ qua requirements-clarity và dùng skill viết code thay thế?

Hãy bỏ qua nó khi đầu việc đã có ngữ cảnh triển khai rõ ràng:

• tham chiếu file chính xác
• có code hiện hữu đang được bàn tới
• bước tái hiện bug rõ ràng
• thay đổi hẹp, ít mơ hồ

Nếu điều chưa biết chính là “code cái này như thế nào?” thay vì “chúng ta chính xác đang xây cái gì?”, hãy dùng skill thiên về coding hoặc review.

Skill này có yêu cầu một tech stack cụ thể không?

Không. Workflow không phụ thuộc stack, nhưng chất lượng đầu ra sẽ tốt hơn nếu bạn cung cấp stack. Thiếu bối cảnh kỹ thuật chính là một trong những khoảng trống mà skill được tạo ra để phát hiện, nên việc nêu môi trường ngay từ đầu sẽ giúp nó đặt câu hỏi phù hợp hơn.

requirements-clarity có phù hợp với các việc nhỏ không?

Đôi khi có, nhưng không phải lúc nào cũng đáng dùng. Với các thay đổi rất nhỏ, chi phí làm rõ yêu cầu có thể không cần thiết. Skill này có giá trị nhất khi tính năng mơ hồ, rủi ro cao hoặc đủ lớn để việc làm lại trở nên tốn kém.

Cách cải thiện skill requirements-clarity

Cung cấp “nguyên liệu đầu vào” tốt hơn cho requirements-clarity

Cách cải thiện nhanh nhất là nâng chất lượng đầu vào ban đầu. Hãy đưa vào:

• loại người dùng
• mục tiêu kinh doanh
• workflow hiện tại
• bối cảnh stack và integration
• ràng buộc bàn giao
• những gì nằm ngoài phạm vi

Điều này giúp giảm các câu hỏi chung chung và để skill dành thời gian cho đúng những điểm bất định thực sự.

Lỗi thường gặp: hỏi giải pháp quá sớm

Các team thường nhảy ngay vào lựa chọn UI, database hoặc vendor trước khi bài toán và tiêu chí thành công được làm rõ. Với requirements-clarity, trước tiên hãy yêu cầu skill chỉ ra các lỗ hổng yêu cầu, giả định và ranh giới phạm vi. Sau đó mới hỏi đến các phương án giải pháp. Trình tự đó khiến đầu ra bền hơn và dùng được lâu hơn.

Lỗi thường gặp: dùng danh từ quá mơ hồ

Những từ như “dashboard,” “management,” “notifications,” và “enterprise support” thường che giấu khác biệt phạm vi rất lớn. Muốn kết quả tốt hơn, hãy thay các danh từ mơ hồ bằng danh sách năng lực cụ thể.

Thay vì:

• “Need user management”

Hãy thử:

• “Need admin-only controls for inviting users, assigning roles, deactivating access, and viewing audit history”

Chỉ một thay đổi đó thôi cũng đã cho skill nền tảng tốt hơn hẳn để làm rõ yêu cầu.

Luôn yêu cầu nêu rõ non-goal và edge case

Một trong những cách tốt nhất để cải thiện đầu ra của requirements-clarity là luôn yêu cầu thêm hai mục:

• “What is explicitly out of scope?”
• “Which edge cases still need decisions?”

Cách này giúp tránh các bản PRD trông có vẻ đầy đủ nhưng vẫn gây churn trong quá trình triển khai.

Hãy lặp sau bản nháp đầu tiên, đừng cố hoàn hảo ngay từ đầu

Hãy làm trọn một vòng làm rõ yêu cầu trước, rồi mới tinh chỉnh. Một vòng lặp hiệu quả thường là:

1. yêu cầu ban đầu
2. trả lời câu hỏi follow-up
3. review bản nháp yêu cầu được tạo ra
4. sửa các giả định chưa đúng
5. yêu cầu siết chặt lại tiêu chí chấp nhận và cách diễn đạt phạm vi

Cách này thường hiệu quả hơn việc cố viết một prompt mở đầu thật hoàn hảo.

Dùng đầu ra cuối như tài liệu handoff, không phải chân lý cuối cùng

Ngay cả đầu ra mạnh từ requirements-clarity cũng nên được product, engineering và các team phụ thuộc cùng review. Tốt nhất hãy xem skill này như một bộ tăng tốc làm rõ yêu cầu và một cổng kiểm soát chất lượng, chứ không phải thứ thay thế cho stakeholder sign-off. Mô hình áp dụng hiệu quả nhất thường là: làm rõ trước, review sau, triển khai cuối.