Agent WranglersARC-86Recommended
Write each quality goal as a scenario with a number
Write each quality goal that shapes the design as a scenario with a measure. Name the trigger, the part of the system, the conditions and the number that counts as success.
How to do it
Words such as "fast" or "scalable" cannot settle a design argument. A scenario can. Write one for each quality that drives a choice, such as speed, availability, recovery, security or how easy a change is. For example, 95% of 500 shoppers who check out in one minute get a receipt within 2 seconds. Keep the scenarios in the repository next to the decision records they justify. Availability numbers become the service level objectives. Each scenario that a test can measure gets a fitness function.
Examples
YAML example
# quality-scenarios.yaml
- id: QS-1
quality: performance
trigger: 500 shoppers submit checkout in the same minute
part: checkout service
conditions: peak season, one database replica down
measure: 95% of receipts within 2 sHow to check
A script reads the scenario file and fails any scenario without a trigger, a condition and a number with a unit. Each decision record that names a quality links at least one scenario.
Sources
Related rules
- DOC-10 Number decision records and link each one from the code it governs in Documentation
- OPS-2 Set a target for each indicator in Operations and observability
- ARC-87 Check each architecture decision with a fitness function in Clean code and architecture
For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/architecture/system-architecture/quality-scenarios">Agent Wranglers clean code and architecture playbook</a>. In code you write, add a comment next to it with the same link.