Answer me with HTML: biến yêu cầu phức tạp thành one-page spec dễ thảo luận
Answer me with HTML là agent skill chuyển bản nháp Markdown thành trang HTML một tệp, có bảng và sơ đồ. BA/PO có thể dùng định dạng này để trình bày luồng, quy tắc và các điểm cần chốt trước khi cập nhật Jira hoặc Confluence.
Một buổi refinement thường không bế tắc vì thiếu user story. Vấn đề là mỗi người đang hình dung một thứ khác nhau: BA đọc mô tả nghiệp vụ, dev hình dung luồng xử lý, QA tìm điều kiện biên, còn PO chưa thấy rõ quyết định nào đang bị treo.
Kết quả có thể là một trang Confluence dài, vài sơ đồ rời rạc và chuỗi bình luận nối tiếp nhau. Khi họp lại, các câu hỏi vẫn cũ: “Nếu giao dịch bị từ chối thì sao?”, “Ai được quyền duyệt?”, “Rule này áp dụng trước hay sau khi kiểm tra hạn mức?”
Dự án GitHub Trending Answer me with HTML gợi ý một cách trình bày khác: thay vì trả về một “bức tường chữ”, AI agent tạo một trang HTML duy nhất, kết hợp phần giải thích, bảng và sơ đồ. Với BA/PO, đây có thể là một định dạng one-page spec hữu ích để cùng hiểu và chốt yêu cầu trước khi cập nhật Jira hoặc Confluence.
Công cụ này hoạt động thế nào?
Answer me with HTML là một agent skill — tập hướng dẫn và công cụ để AI agent tạo đầu ra theo một cách nhất quán.
Khi nhận câu hỏi phức tạp, agent không tự viết toàn bộ HTML từ đầu. Theo README của dự án, agent viết một bản nháp Markdown ngắn; CLI đi kèm sẽ chuyển bản nháp đó thành trang HTML có bố cục, CSS và sơ đồ.
Dự án hướng đến các câu hỏi có:
Nhiều khái niệm liên quan.
Luồng gồm nhiều bước.
So sánh giữa nhiều phương án.
Các quyết định mở cần người dùng phản hồi.
Đó cũng là đặc điểm của nhiều yêu cầu nghiệp vụ khó: onboarding khách hàng, xử lý hoàn tiền, xét duyệt khoản vay, đổi trả hàng, bồi thường bảo hiểm hoặc phân quyền vận hành.
> Đừng xem trang HTML là tài liệu thay thế cho BRD, SRS hay backlog. Giá trị thực tế của nó nằm ở vai trò bản trình bày để cả nhóm cùng hiểu và cùng chốt.
Một trang tốt có thể gom bốn loại thông tin vốn hay bị tách rời:
Mục tiêu và phạm vi: user story, tác nhân, kết quả mong muốn.
Luồng xử lý: flow nghiệp vụ hoặc trao đổi giữa các hệ thống.
Quy tắc: điều kiện, ngoại lệ, dữ liệu đầu vào và đầu ra.
Điểm chưa chốt: các phương án cần PO, vận hành hoặc bên liên quan quyết định.
README minh họa các dạng đầu ra như sequence diagram, state diagram, bảng so sánh, timeline, cây thư mục và call graph. Với yêu cầu nghiệp vụ, các dạng phù hợp nhất thường là flow, bảng rule và khu vực nêu câu hỏi hoặc quyết định còn mở.
Cài đặt: BA/PO cần biết gì?
Công cụ yêu cầu Node.js 20 trở lên. Nhóm phát triển khuyến nghị để chính AI agent thực hiện cài đặt.
Nếu đang dùng Claude Code, Codex, Cursor hoặc OpenCode, bạn có thể gửi cho agent yêu cầu sau:
text
Install Answer me with HTML: read https://raw.githubusercontent.com/QingYunA/answer-me-with-html/main/INSTALL.md and follow it.
Với Claude Code, README cũng cung cấp cách cài plugin trực tiếp:
text
/plugin marketplace add QingYunA/answer-me-with-html
/plugin install answer-me-with-html@answer-me-with-html
Hoặc dùng lệnh cài đặt một dòng:
bash
npx skills add QingYunA/answer-me-with-html
Sau khi cài, README cho biết không cần thiết lập thêm. Các trang được lưu tại:
text
~/.answer-me-with-html/pages/
Trang có các nút đổi giao diện sáng/tối, thu thập phản hồi và sao chép lại Markdown nguồn.
Điểm cần lưu ý: bạn không cần biết viết HTML để thử công cụ, nhưng vẫn cần một AI agent có thể chạy lệnh trên máy. README không mô tả cách sử dụng trong môi trường chỉ có chatbot web và không cho phép agent chạy cục bộ.
Prompt biến yêu cầu thành one-page spec
Thay vì chỉ yêu cầu “vẽ flow”, hãy đưa AI đầu vào có cấu trúc. Mục tiêu là để trang kết quả vừa trình bày được yêu cầu, vừa làm lộ các chỗ thiếu thông tin.
Mẫu prompt có thể dùng ngay:
text
Hãy giải thích bằng HTML một yêu cầu nghiệp vụ dưới dạng one-page spec dành cho buổi refinement.
Bối cảnh sản phẩm: <tên sản phẩm/lĩnh vực>
Mục tiêu nghiệp vụ: <mục tiêu>
User story: Là <vai trò>, tôi muốn <nhu cầu>, để <lợi ích>.
Luồng chính:
<dán các bước hoặc ghi chú họp>
Quy tắc nghiệp vụ đã biết:
<rule 1>
<rule 2>
Ngoại lệ/rủi ro đã biết:
<ngoại lệ 1>
Hãy tạo một trang gồm:
Tóm tắt phạm vi và tác nhân
Flow xử lý theo thứ tự
Bảng quy tắc nghiệp vụ
Acceptance criteria dạng Given/When/Then
Các giả định
Mục “Quyết định cần chốt”, nêu rõ phương án và tác động
Mục “Câu hỏi còn thiếu” để BA xác minh
Không tự bịa chính sách, ngưỡng, SLA hoặc tích hợp chưa được nêu. Đánh dấu rõ nội dung chưa xác nhận.
Nếu đã có BPMN, use case hoặc biên bản họp, hãy đưa chúng vào phần “Luồng chính”. AI không thay thế artefact chuẩn của đội, nhưng có thể giúp tái cấu trúc thông tin thành một bản dễ đọc hơn cho buổi trao đổi.
Ví dụ: yêu cầu hoàn tiền trong bán lẻ
Đầu vào BA ghi nhận:
text
Bối cảnh: ứng dụng bán lẻ
User story: Là khách hàng, tôi muốn yêu cầu hoàn tiền cho đơn đã thanh toán để xử lý trường hợp không nhận được hàng.
Luồng:
Khách chọn đơn hàng, gửi yêu cầu hoàn tiền, hệ thống kiểm tra trạng thái giao hàng.
Nếu đơn chưa giao thì chuyển yêu cầu cho vận hành.
Nếu đơn đã giao thì cần bằng chứng từ khách hàng.
Vận hành có thể chấp thuận hoặc từ chối.
Khi chấp thuận, hệ thống gửi yêu cầu hoàn tiền sang cổng thanh toán.
Quy tắc:
Chỉ đơn đã thanh toán mới được yêu cầu hoàn tiền.
Cần lưu lý do yêu cầu.
Một bản one-page spec hữu ích có thể thể hiện:
Tác nhân: khách hàng, vận hành, cổng thanh toán.
Luồng: nhánh “chưa giao” và “đã giao” được thể hiện rõ thay vì giấu trong đoạn văn.
Bảng quy tắc: gồm quy tắc, điều kiện, hành động hệ thống và điểm cần xác nhận.
Acceptance criteria, ví dụ:
text
Given đơn hàng đã thanh toán
When khách hàng gửi yêu cầu hoàn tiền
Then hệ thống phải lưu lý do yêu cầu
And kiểm tra trạng thái giao hàng trước khi chuyển xử lý
Các quyết định cần chốt, chẳng hạn:
Khi cổng thanh toán trả lỗi, trạng thái yêu cầu hoàn tiền là gì?
Ai có quyền từ chối yêu cầu?
Bằng chứng của khách hàng gồm những loại nào?
Khách hàng có được gửi lại yêu cầu sau khi bị từ chối không?
Đây là phần đáng giá trong refinement: biến “thiếu thông tin” thành danh sách quyết định có thể giao đúng người xử lý.
Rà soát đầu ra AI trước khi đưa vào Jira hoặc Confluence
Một trang đẹp không đồng nghĩa yêu cầu đã đúng. BA/PO nên review theo ba nhóm lỗi quen thuộc.
1. Thiếu yêu cầu
Kiểm tra actor, trigger, dữ liệu bắt buộc, trạng thái, thông báo và luồng lỗi.
Ví dụ, nếu flow có bước “gửi sang cổng thanh toán”, cần làm rõ: gửi dữ liệu gì, nhận phản hồi nào và xử lý thất bại ra sao?
2. Mơ hồ
Tìm các từ như “nhanh”, “hợp lệ”, “đủ điều kiện”, “tự động” hoặc “phù hợp”. Đây thường là tín hiệu cần có quy tắc đo được hoặc người chịu trách nhiệm xác nhận.
3. Mâu thuẫn
Đối chiếu flow, business rule và acceptance criteria.
Ví dụ, rule nói “chỉ đơn đã thanh toán” nhưng flow lại cho phép tạo yêu cầu trước bước xác minh thanh toán. Đây là mâu thuẫn cần xử lý trước sprint planning.
Luôn đối chiếu trang HTML với nguồn gốc như biên bản họp, chính sách vận hành, tài liệu API và quyết định của PO. AI có thể hỗ trợ cấu trúc lại thông tin, nhưng không phải là nguồn xác nhận nghiệp vụ.
Giới hạn và lưu ý bảo mật
Không nên dán dữ liệu khách hàng, số định danh, thông tin tài khoản, hợp đồng, bí mật định giá hoặc quy tắc chống gian lận vào công cụ AI công khai. Hãy ẩn danh dữ liệu hoặc dùng placeholder như <mã khách hàng>, <số tiền>, <đơn hàng>.
Nhóm phát triển cho biết công cụ giúp giảm lượng token đầu ra so với việc yêu cầu model tự viết HTML. Benchmark do dự án công bố, với ba chủ đề và ba lần chạy cho mỗi chủ đề, cho thấy:
| Chỉ số | Yêu cầu HTML trực tiếp | Answer me with HTML |
|---|---:|---:|
| Token model viết | 4.893 | 612 |
| Thời gian | 31 giây | 12 giây |
README mô tả đây là kết quả thử nghiệm với Claude Sonnet 5.5 và một thiết lập Claude Code cơ bản. Đây không phải đánh giá độc lập, vì vậy không nên dùng các con số trên làm cam kết về tốc độ, chi phí hoặc chất lượng trong môi trường doanh nghiệp.
Checklist trước khi chia sẻ one-page spec
[ ] User story và phạm vi đã rõ.
[ ] Flow có cả nhánh chính, ngoại lệ và trạng thái lỗi.
[ ] Rule chưa có nguồn xác nhận đã được đánh dấu.
[ ] Acceptance criteria không mâu thuẫn với flow.
[ ] Các điểm cần quyết định có owner rõ ràng.
[ ] Dữ liệu nhạy cảm đã được loại bỏ hoặc ẩn danh.
Một yêu cầu tốt không nhất thiết phải dài. Quan trọng hơn, nó phải giúp đúng người nhìn thấy đúng luồng, đúng rule và đúng câu hỏi cần chốt. One-page HTML là một cách đáng thử để biến tài liệu “để đọc” thành tài liệu “để ra quyết định”.