Phát triển Agent Skill hỗ trợ báo giá từ các yêu cầu mơ hồ

Khi bắt đầu một dự án, requirement từ khách hàng thường chỉ là vài câu mô tả khá ngắn.

Ví dụ:

Tôi muốn làm một ứng dụng mobile để người dùng có thể tìm sân cầu lông gần mình và đặt khung giờ còn trống. Chủ sân cũng có thể quản lý sân và booking.

Vấn đề là từ requirement này đến một plan đủ rõ để team estimate vẫn còn khá nhiều khoảng trống.

“Quản lý booking” cụ thể là xem, confirm, cancel hay reschedule?
Có payment hay không?
Có cần approval flow không?

Nếu AI tự suy đoán những phần này rồi break task luôn, estimate phía sau rất dễ dựa trên requirement mà khách hàng chưa từng xác nhận.

Để xử lý vấn đề đó, tôi xây dựng Requirement Blueprint, một bộ Agent Skill giúp AI đóng vai trò như BA / Pre-sales Analyst trước khi development bắt đầu.

Toàn bộ source code, hướng dẫn cài đặt, ví dụ đầu vào và kết quả benchmark của Requirement Blueprint được công khai tại repository bên dưới. Bạn có thể cài skill vào AI agent đang sử dụng hoặc chạy trực tiếp với một customer brief để kiểm tra cách skill phân tích requirement.

Xem source code và hướng dẫn sử dụng tại:
Requirement Blueprint trên GitHub

Requirement Blueprint làm được gì?

Từ một customer brief ngắn, skill có thể hỗ trợ AI tạo ra:

• Project scope
• Feature list
• Actor
• Scenario
• User flow và diagram
• Project phase
• Task breakdown
• Dependency
• Open question
• Estimation risk
• Estimate worksheet

Điểm quan trọng là skill cố gắng phân biệt rõ:

CONFIRMED
ASSUMED
NEED CLARIFICATION
OUT OF SCOPE

và với delivery:

READY
BLOCKED

Ví dụ khách hàng nói:

Court owners can manage bookings.

thì skill không tự suy ra ngay:

approve
reject
cancel
reschedule
refund

mà có thể giữ feature ở trạng thái:

CONFIRMED + BLOCKED

cho tới khi khách hàng làm rõ manage thực sự bao gồm những hành động nào.

Ngoài skill chính, repo còn có:

/generate-slide
/generate-estimate

để chuyển requirement plan thành slide PDF/PPTX và Excel worksheet cho team estimate.

Hiệu quả thực tế

Để kiểm tra Requirement Blueprint có thực sự giúp AI phân tích
requirement tốt hơn hay không, tôi tạo một benchmark gồm 10 yêu cầu dự
án khác nhau. Các yêu cầu này được cố tình viết ngắn hoặc còn một số
điểm chưa rõ, tương tự requirement thường nhận được ở giai đoạn đầu của
dự án.

Ví dụ benchmark bao gồm các bài toán như booking sân cầu lông,
e-commerce, đặt lịch khám, quản lý công việc và một số trường hợp đặc
biệt để kiểm tra AI có tự bổ sung requirement khi thông tin chưa đủ rõ
hay không.

Mỗi requirement được thử nghiệm trong 4 trường hợp:

Như vậy, mỗi requirement được chạy 4 lần. Với 10 requirement, tổng cộng
benchmark có:

10 requirements
× 2 agents
× 2 conditions
= 40 runs

Việc chạy cả trường hợp có skill và không có skill trên cùng một
requirement giúp so sánh trực tiếp xem Requirement Blueprint tạo ra
khác biệt gì, thay vì chỉ đánh giá output của skill một cách độc lập.

Kết quả được chấm như thế nào?

Mỗi output được đánh giá theo 10 tiêu chí, mỗi tiêu chí từ 0 đến 5 điểm, vì vậy điểm tối đa của một run là 50 điểm.

Chi tiết cách chấm điểm được định nghĩa trong Evaluation Rubric của benchmark.

Mỗi tiêu chí được chấm theo cùng một rubric cho cả Cursor và Codex, với
mục tiêu đánh giá chất lượng output dưới góc nhìn của một tài liệu
BA/pre-sales thay vì đánh giá cách viết.

Kết quả benchmark

Sau khi chấm toàn bộ 40 runs, điểm trung bình thu được là:

Như vậy, khi sử dụng Requirement Blueprint, điểm trung bình tăng 9,85
điểm trên thang 50, tương đương khoảng 26,9% so với baseline.

Ngoài điểm trung bình, benchmark còn có thể so sánh trực tiếp từng cặp
kết quả. Vì có 10 requirement × 2 agents, chúng ta có tổng cộng 20
cặp so sánh. Mỗi cặp là cùng một requirement được chạy trên cùng một
agent, một lần không dùng skill và một lần có dùng skill.

Trong cả 20/20 cặp, output sử dụng Requirement Blueprint đều đạt
điểm cao hơn output không sử dụng skill.

Nếu tách riêng theo agent:

Các tiêu chí cải thiện rõ nhất tập trung vào Task Breakdown, Estimate
Readiness, Scope Clarity và Hallucination Control.

Điều này khá đúng với mục tiêu ban đầu của repo. Requirement Blueprint
không được tạo ra để làm AI thông minh hơn, mà để đưa thêm một quy trình
rõ ràng vào cách AI phân tích requirement trước khi team bắt đầu
estimate.

Toàn bộ cách benchmark, raw output và kết quả chi tiết có thể xem tại
Requirement Blueprint Benchmark v0.3.

Cách sử dụng

Có hai cách sử dụng cho skill này với agent của bạn.

Cách 1: Cài Requirement Blueprint thành Agent Skill

Đây là cách nên dùng nếu bạn muốn sử dụng thường xuyên.

Clone repo:

git clone https://github.com/khanhvo1104/Requirement-Blueprint-Skill.git
cd Requirement-Blueprint-Skill

Ví dụ với Cursor:

mkdir -p .cursor/skills

ln -sf "$(pwd)/skills/requirement-blueprint"   .cursor/skills/requirement-blueprint

ln -sf "$(pwd)/skills/generate-slide"   .cursor/skills/generate-slide

ln -sf "$(pwd)/skills/generate-estimate"   .cursor/skills/generate-estimate

Sau đó trong Cursor có thể gọi trực tiếp:

/requirement-blueprint

rồi nhập requirement:

I want to build a mobile app where users can find badminton courts near them and book an available time slot.

Court owners should also be able to manage their courts and bookings.

Sau khi requirement đủ rõ, có thể tiếp tục:

/generate-slide

để tạo PDF/PPTX và:

/generate-estimate

để tạo Excel estimate worksheet.

Với các agent khác như Codex hoặc Claude Code, chỉ cần copy folder skill vào thư mục skills tương ứng của agent.

Cách 2: Không cài skill, yêu cầu agent chạy trực tiếp SKILL.md

Nếu chỉ muốn thử nhanh, không nhất thiết phải cài vào agent.

Bạn có thể clone repo hoặc tải file:

skills/requirement-blueprint/SKILL.md

sau đó đưa cho agent và yêu cầu:

Hãy đọc và làm theo toàn bộ instruction trong file:

skills/requirement-blueprint/SKILL.md

Sau đó phân tích requirement sau:

I want to build a mobile app where users can find badminton courts near them and book an available time slot.

Court owners should also be able to manage their courts and bookings.

Nếu agent có quyền đọc repository, có thể nói đơn giản:

Please use the Requirement Blueprint skill in:

skills/requirement-blueprint/

to analyze the following customer requirement:

...

Cách này phù hợp khi:

• Muốn test skill nhanh
• Không muốn setup agent
• Chỉ dùng một lần
• Muốn benchmark trên nhiều agent

Còn nếu dùng thường xuyên thì cài thành Agent Skill sẽ tiện hơn vì agent có thể gọi lại workflow trực tiếp.

Workflow đầy đủ

Sau khi setup, quy trình có thể đơn giản như sau:

Customer Requirement
        ↓
/requirement-blueprint
        ↓
Clarification
        ↓
Requirement Plan
        ↓
Validator
        ↓
/generate-slide
        ↓
PDF / PPTX
        ↓
/generate-estimate
        ↓
Excel worksheet

Repo cũng có example hoàn chỉnh về Badminton Court Booking, bao gồm requirement ban đầu, clarification, task breakdown, slide và estimate worksheet để có thể xem nhanh output thực tế.

Xem chi tiết example tại đây.

Kết luận

Requirement Blueprint được tạo ra để giải quyết một vấn đề khá đơn giản:

AI có thể hiểu requirement, nhưng không phải lúc nào cũng biết đâu là phần khách hàng đã xác nhận và đâu là phần nó đang tự suy đoán.

Bằng cách thêm một workflow BA trước development, AI có thể tạo ra project plan rõ ràng hơn, dễ thảo luận hơn và đặc biệt phù hợp hơn cho rough estimation.

Trong benchmark hiện tại, cùng một bộ requirement khi dùng skill đạt điểm trung bình cao hơn khoảng 26,9% so với baseline trên Cursor và Codex.

Nếu muốn thử trực tiếp, có thể xem repo tại:
https://github.com/vfa-khanhvl/Requirement-Blueprint-Skill/tree/main

Hoặc xem chi tiết mọi thông số đo đạc được tại benchmark của repo:
https://github.com/vfa-khanhvl/Requirement-Blueprint-Skill/blob/main/benchmark/reports/BENCHMARK_V03.md