Carlos Florêncio
2.6 KiB
Requirements
Purpose
Requirements define what an actor or consumer must observe. They explain the intent and the behavior without prescribing the implementation.
An actor can be a user, operator, agent, plugin, integration, or another Kandev system. Do not force a user story when no natural user story exists.
Document structure
A requirement document contains:
- An overview of the capability and its value.
- Terms that are necessary to interpret the requirements.
- One or more requirements with stable IDs.
- Acceptance criteria for every requirement.
- Explicit exclusions.
Add permissions, failure behavior, persistence, compatibility, or performance criteria when they affect observable behavior.
Requirement IDs
Use this form:
REQ-<SYSTEM>-<CAPABILITY>-<NNN>
Use uppercase letters, digits, and hyphens. Use a three-digit sequence. Do not reuse an ID after removal.
One requirement describes one cohesive capability or outcome. The title is a short noun phrase.
Acceptance criteria
AC means acceptance criterion. The plural term is acceptance criteria.
Use this form:
AC-<SYSTEM>-<CAPABILITY>-<NNN>.<N>
The part before the decimal point must match its requirement ID. Each criterion defines one independently testable behavior.
Use this sentence form when it fits:
When <condition>, the system shall <observable behavior>.
Use shall for required behavior, should for a recommendation, and can for
an allowed behavior. Avoid vague terms such as appropriate, fast, robust, or
user-friendly. Give an observable result or a measurable limit.
User stories
A user story gives useful intent when the capability has a natural actor and outcome. Use this form:
As a <role>, I want <action>, so that <outcome>.
A user story does not replace acceptance criteria. Omit it when it creates an artificial actor such as "the system."
Content boundary
Requirements can name a public API, event, or persisted concept when that name is part of the observable contract. Requirements do not define internal files, functions, database queries, or implementation sequences.
Put technical models, control flow, storage choices, and component ownership in the paired system design. Put design rationale and rejected alternatives in an ADR.
Splitting requirements
Split a document when its requirements have different actors, lifecycles, or contracts. Keep requirements together when they are necessary to complete one user or system outcome.
Use references instead of copied text when another system owns a requirement.