DESIGN.md
Agent product design
Design the human experience around bounded outcomes, visible system state, calibrated uncertainty, approval moments, recovery, and accessibility rather than treating the agent as an unrestricted chat box.
Fillable structure
Replace prompts with project evidence.
Remove any field that does not apply. A smaller maintained file is more useful than generic documentation that agents and reviewers cannot trust.
- 01
Users, jobs, and outcomes
Anchor the experience in a real user job and an observable, verifiable measure of success.
Primary user: Describe role, expertise, incentives, and constraints
Job: State the workflow and current pain without prescribing a solution
Outcome: Define what the user can verify when the experience succeeds
- 02
Interaction and system state
Show what the system knows, plans, is doing, and needs from the user.
Entry points: List triggers, inputs, defaults, and required context
State model: Define idle, preparing, running, waiting, failed, canceled, and completed states
Feedback: Describe progress, evidence, uncertainty, and tool activity shown to the user
- 03
Control and trust
Place human judgment where authority or consequence changes.
Approvals: Name actions requiring preview, confirmation, or a second reviewer
Corrections: Explain edit, retry, undo, cancel, and feedback behavior
Disclosure: State how sources, sponsorship, limitations, and automation are labeled
- 04
Edge states and accessibility
Design realistic failure and alternate-access paths before polish.
Empty and partial states: Describe missing context, no results, incomplete outputs, and degraded dependencies
Failure recovery: Define actionable messages, retained work, escalation, and safe fallback
Accessibility: Record keyboard, screen-reader, contrast, motion, focus, and language requirements
Related field guides
Next template
SPEC.md · Feature specification