Implementation worksheet · 2 min read
Acceptance criteria for an AI-built client portal
Write acceptance criteria as observable outcomes for a named user, record and action. For a client portal, define who can view a project, submit a file, approve work and recover from an error. A generated screen is ready for review when those outcomes work with persistent data and the intended permissions.
Use this worksheet before asking an AI builder to implement a portal. The example has a client, an account manager and two unrelated client organizations. Use synthetic projects in a test environment. The worksheet describes what to verify; it does not claim that a particular builder has passed these checks.
Put it into practice
1. Define the records
Start with organizations, memberships, projects, files and approvals. Give each record an owner. Decide whether an approval refers to an immutable file version or the current file; otherwise a later upload can silently change what the client approved.
2. Describe the happy path
Write one scenario from invitation to approval. Include the invitation state, the first page the client sees, the action they take and the stored record that proves it worked. Avoid requirements such as ‘make it seamless’ that cannot be checked.
3. Add negative paths
Try an expired invitation, an upload that exceeds the chosen limit and an approval by a user outside the project. Define a useful error message and the expected unchanged database state for each rejection.
4. Require persistence
Refresh the browser after submitting an approval. Sign out and return. The approved version and timestamp should still agree with the audit record. A success toast alone does not demonstrate persistence.
5. Record acceptance evidence
For each scenario, save the build identifier, role, test data, observed result and reviewer. Link the failing scenario to a fix. Keep unresolved permission or data-loss failures visible in the release decision.
Example acceptance matrix
Copy this structure into your review document and record your observed result for each row.
| Scenario | Expected result | Evidence |
|---|---|---|
| Client A opens Project A | Project A is visible | Page and record identifier |
| Client B requests Project A | Access is denied by the server | Response plus unchanged records |
| Manager uploads version 2 | Version 1 approval stays attached to version 1 | Version history |
| Client repeats an approval | No contradictory approval records | Audit log |
| Session expires before submit | No silent write; user can recover | Response and subsequent sign-in |
A failure worth checking
A portal can look correct while every client receives the same project list. Do not accept a filtered interface as proof of authorization. Request the underlying record using the second test account and verify the server's decision.
Common questions
How detailed should the brief be?
Detailed enough that two reviewers agree whether the result passes. Name the actor, starting state, action and expected stored outcome.
Can the AI builder write the tests?
Yes, but review the expected outcomes yourself. A generated test that repeats the implementation's assumptions can miss the same mistake.
Basis and scope
This is a proposed implementation method using illustrative examples, not a measured benchmark or a customer case study. Prepared with AI assistance. Validate product-specific behavior against current documentation and your own test environment.