Use Case Writing & Acceptance Criteria

Delivery

Use case, user story và acceptance criteria từ beginner đến advanced: actor, goal, flows, edge cases, Given/When/Then, QA/UAT, templates và case studies.

Roadmap — Cách học và đạt kỹ năng

Use Case & Acceptance Criteria là gì?

Use Case mô tả cách một actor tương tác với system để đạt một goal. Nó giúp team hiểu behavior end-to-end: trigger, precondition, happy path, alternate path, exception, postcondition và system boundary.

Acceptance Criteria (AC) định nghĩa điều kiện cụ thể để biết story/feature đã đúng, đủ, testable và có thể release. AC là contract giữa Product/BA, Engineering, QA, Design và stakeholder. Nếu AC mơ hồ, team sẽ build theo assumption, QA test theo cảm giác, và UAT dễ tranh cãi.

Nguyên tắc: Use case trả lời “actor đạt goal như thế nào?”, user story trả lời “value là gì?”, acceptance criteria trả lời “làm sao biết đã đúng?”.

Flow từ evidence sang use case, user story, acceptance criteria và QA/UAT — Artifact flow: bắt đầu từ evidence/user pain, viết use case để hiểu behavior, split thành story, viết AC để QA test và stakeholder UAT.

Core concepts và keyword definitions

Keyword	Định nghĩa	Good example	Weak example
Actor	Người, role, hoặc external system tương tác với product.	Recruiter, Candidate, Payment Gateway, Compliance Reviewer.	User.
Goal	Kết quả actor muốn đạt, không phải button họ muốn bấm.	Submit return request with required evidence.	Click submit.
Scope/System boundary	Phần system chịu trách nhiệm và phần nằm ngoài system.	App validates return eligibility; payment provider processes refund.	Everything works.
Precondition	Điều kiện phải đúng trước khi flow bắt đầu.	Order is delivered, user is logged in, return window is open.	User is on page.
Trigger	Sự kiện bắt đầu use case.	Customer clicks “Request return”.	Start.
Main success scenario	Happy path chính để đạt goal.	Validate order -> collect reason/photo -> submit -> create return case -> notify customer.	Return works.
Alternate flow	Đường đi khác nhưng vẫn có thể đạt goal.	Payment callback timeout -> system polls provider before showing final status.	Error handled.
Exception flow	Đường đi thất bại hoặc bị block.	File over 10MB -> block upload and show max size message.	Show validation.
Postcondition	Trạng thái system sau khi flow kết thúc.	Return case status = Submitted and audit log created.	Done.
Given/When/Then	Format AC testable: context, action, expected outcome.	Given order is in return window, when user submits valid request, then return case is created.	User can submit.

Template 1: Use case format đầy đủ

Field	Cần viết gì?	Ví dụ
Use case name	Verb + noun + goal, ngắn và rõ.	Submit return request, Upload candidate CV, Approve discount request.
Primary actor	Role chính muốn đạt goal.	Customer, Recruiter, Sales Manager.
Supporting actors	System/team tham gia nhưng không phải actor chính.	Payment Gateway, Email Service, Finance Approver.
Business goal	Why behind the flow.	Reduce support tickets and shorten refund cycle time.
Preconditions	Điều kiện trước khi bắt đầu.	User logged in; order delivered; return window still valid.
Trigger	Event/action bắt đầu flow.	User clicks “Request return”.
Main flow	Step-by-step happy path.	System validates order -> user selects reason -> uploads photo -> submits -> system creates case.
Alternate flows	Valid branch khác happy path.	Photo optional for low-value item; pickup unavailable in region.
Exception flows	Invalid/error/blocked cases.	Return window expired; duplicate request; file too large; permission denied.
Postconditions	State sau khi flow kết thúc.	Return case created, status = Submitted, customer notified.
Business rules	Policy/decision/calculation.	Auto-approve refund under 200k if delivered within 7 days and no fraud flag.
Non-functional needs	Performance, security, audit, accessibility.	Submit response under 2 seconds; audit log stores user, timestamp and decision.

Template 2: Acceptance Criteria bằng Given / When / Then

Gherkin format giúp AC rõ vì nó tách context, trigger và expected result. Không phải mọi AC bắt buộc dùng Gherkin, nhưng với behavior phức tạp, validation, workflow, permission, payment, notification hoặc integration, Given/When/Then giúp giảm hiểu nhầm mạnh.

Given When Then acceptance criteria map — Given là context, When là action/trigger, Then là expected outcome, And dùng cho outcome phụ như audit log, analytics event, email hoặc data update.

Given [initial context / data / permission]
When [actor or system action occurs]
Then [observable expected result]
And [secondary result: data, event, email, audit, notification]

AC type	What to cover	Example
Happy path	Successful expected flow.	Given a valid PDF under 10MB, when recruiter uploads it, then candidate profile is created with parsed name, email and skills.
Validation	Required fields, format, limits.	Given file is over 10MB, when user uploads it, then system blocks upload and shows “Maximum file size is 10MB”.
Permission	Who can/cannot perform action.	Given user is not assigned to the job, when they open candidate detail, then salary expectation is hidden.
Duplicate	Existing records or repeated action.	Given candidate email already exists for this job, when recruiter uploads CV, then system shows duplicate warning and offers merge/cancel.
Integration	External callback, retry, timeout.	Given payment callback is not received within 60 seconds, when checkout is pending, then system polls provider status every 15 seconds for 2 minutes.
Analytics	Events/properties needed for measurement.	Given filter is applied, when candidate list refreshes, then event candidate_filter_applied records filter_type and result_count.

Template 3: User story + AC card ready for Jira/Linear

Title	[Actor] can [action] to [goal]. Example: Recruiter can upload CV to create candidate profile.
User story	As a recruiter, I want to upload a candidate CV so that I can create a candidate profile without manual data entry.
Business context	Manual candidate entry takes 8 minutes per CV and causes missing phone/email fields.
Scope	PDF/DOCX upload, file validation, parsing, profile creation, duplicate warning. Excludes ranking model improvements.
Design/link	Figma screen, flow, prototype or wireframe.
Use case link	UC-12 Upload candidate CV.
Acceptance criteria	Happy path, validation, duplicate, low-confidence parsing, permission, analytics.
Open questions	What fields are mandatory? How should password-protected PDF behave? Who can merge duplicates?
Definition of done	AC pass, tests added, analytics verified, UAT accepted by recruiter lead.

From requirement to user story: ví dụ thực tế

Input	Bad version	Better version
Pain	“Need better upload.”	Recruiters spend 8 minutes manually entering candidate data after receiving CVs.
Requirement	“System parses CV.”	System shall extract name, email, phone, skills and work history from PDF/DOCX CV under 10MB.
User story	“As a user I upload CV.”	As a recruiter, I want to upload a candidate CV so that I can create a review-ready profile without manual data entry.
AC	“Upload should work.”	Given recruiter uploads a valid PDF under 10MB, when parsing succeeds, then candidate profile is created with parsed fields and original CV link.
Edge case	“Show error.”	Given PDF is password-protected, when recruiter uploads it, then system blocks parsing and asks recruiter to upload an unlocked file.

Case study 1: Checkout payment bằng MoMo / payment gateway

Business context: E-commerce checkout có nhiều đơn bị stuck ở “pending payment”. Customer nghĩ đã trả tiền, support không biết nên retry hay cancel, finance lo double-charge.

Payment use case flow với customer, system, payment gateway, happy path và alternate timeout flow — Payment use case phải thể hiện external gateway, callback, timeout, polling và trạng thái pending/failed để tránh double-charge hoặc confirm sai.

Use case	Customer pays order through payment gateway.
Actor	Customer.
Supporting actor	Payment Gateway, Email/SMS Service.
Precondition	Order exists, amount is calculated, inventory reserved, customer is on checkout page.
Main flow	Customer selects MoMo -> system creates payment request -> customer authenticates -> gateway callback success -> system marks order paid -> confirmation sent.
Alternate flow	Callback timeout -> system shows pending -> polls gateway -> resolves paid/failed without duplicate charge.
Exception	Gateway declines payment, amount mismatch, duplicate callback, inventory no longer available.

Acceptance Criteria examples:

Given customer has an order with reserved inventory, when they select MoMo, then system creates a payment request with order_id, amount and callback_url.
Given gateway returns success callback, when signature is valid and amount matches, then order status changes to Paid and payment transaction is stored.
Given callback is not received within 60 seconds, when customer returns to checkout, then system shows Pending Payment and polls gateway status.
Given duplicate success callback is received, when order is already Paid, then system does not create a second payment and writes duplicate callback to audit log.
Given gateway returns failed status, when status is confirmed, then order remains Unpaid and customer can choose another payment method.

Case study 2: Hiring pipeline - CV upload and duplicate candidate

Evidence: Recruiters upload the same candidate multiple times because agencies send duplicate CVs. Hiring managers see duplicate profiles and interview history is fragmented.

Artifact	Content
Use case	Recruiter uploads candidate CV to create or update candidate profile.
Business rule	Email is primary duplicate key within same job; phone is secondary confidence signal.
User story	As a recruiter, I want duplicate warnings during CV upload so that I do not create fragmented candidate records.
AC 1	Given uploaded CV email matches existing candidate in same job, when parsing completes, then system shows duplicate warning with existing candidate link.
AC 2	Given recruiter chooses merge, when they confirm, then parsed fields update empty fields only and preserve interview notes.
AC 3	Given recruiter does not have permission to merge, when duplicate is detected, then merge action is disabled and manager approval message appears.

Case study 3: Internal procurement approval

Problem: Employee says “approval is too slow”. A weak story says “User can approve faster”. A strong use case reveals missing budget code, security review, vendor tax info, and approval threshold.

Use case step	Requirement/AC detail	Why it matters
Submit request	Given vendor handles customer data, when employee submits request, then security review is added before finance approval.	Prevents compliance risk.
Budget validation	Given budget code has insufficient funds, when request is submitted, then system blocks submission and shows budget owner.	Avoids approval ping-pong.
Approval routing	Given amount is over 50M VND, when request is valid, then department head approval is required.	Encodes business policy.
Status visibility	Given request is pending, when employee views status, then current owner, due date and missing action are shown.	Reduces status-chasing messages.

How to split stories from one use case

Một use case có thể lớn hơn một user story. Split story theo risk và value, không split tùy tiện theo technical layer nếu user không nhận được value.

Split method	Khi nào dùng	Example
Happy path first	Flow phức tạp, cần release nhanh.	Upload valid CV and create profile before adding duplicate merge.
Business rule	Policy nhiều threshold.	Discount under 15%, over 15%, custom legal clause.
User role	Different permissions/needs.	Recruiter uploads CV; Hiring Manager reviews parsed candidate; Admin merges duplicates.
Data source	Integration risk lớn.	Manual upload first, ATS import later.
Exception path	Error case quan trọng nhưng có thể phase sau.	Valid payment first, timeout/polling next if gateway risk manageable.

Common pitfalls và no-nos

AC quá mơ hồ: “System should be fast” không testable. Viết “Search results return under 2 seconds for 95% of queries under 10k records”.
Không viết alternate/error flow: Payment, upload, permission, approval mà thiếu error flow sẽ gây bug production.
Mix UI design với behavior: AC nên nói expected behavior. UI detail nên link Figma, trừ khi UI behavior là requirement.
Không có actor rõ: “User” quá rộng. Hãy dùng actual role: recruiter, hiring manager, finance approver, candidate.
Không có traceability: AC nên trace về use case step, business rule, risk hoặc evidence.
Story quá lớn: Nếu AC có quá nhiều unrelated outcomes, split story.
Quên non-functional: Audit log, security, accessibility, performance, analytics thường bị quên nhưng rất quan trọng.

Review checklist before sending to Engineering / QA

Actor, goal, trigger, preconditions and postconditions are clear.
Main flow, alternate flow and exception flow are documented.
Business rules and data rules are explicit.
Acceptance criteria are observable and testable.
Permission, validation, duplicate, empty state and error cases are covered.
Analytics, audit, notification and reporting requirements are included when needed.
Open questions have owners and due dates.
Design, API, data source and dependency links are attached.
QA can convert AC into test cases without asking for expected behavior.
Stakeholder can use AC for UAT sign-off.

30-day practice plan

Week 1: Rewrite 5 weak requirements into actor-goal use cases. Add preconditions, trigger and postconditions.
Week 2: For each use case, add main flow, alternate flow and exception flow. Review with QA.
Week 3: Convert 3 use cases into user stories with Given/When/Then AC. Ask Engineering to estimate and identify ambiguity.
Week 4: Run UAT with a stakeholder using your AC as sign-off criteria. Capture gaps and improve your template.