📍 You are here: Main Guide → Resources → Standards
- 📋 Apply EARS: Requirements Phase - Use EARS format in practice
- 📝 Use Template: Requirements Template - EARS-formatted template
- 📖 See Examples: Simple Feature Specs - EARS in action
- 🔧 More Tools: Tools & Resources - Additional helpful resources
This section provides detailed information about industry standards, methodologies, and best practices that inform the spec-driven development approach.
EARS is a structured approach to writing requirements that makes them clear, testable, and unambiguous. It uses specific keywords to define different types of requirements.
Used for requirements triggered by specific events or conditions.
Format: WHEN [event/trigger] THEN [system] SHALL [response]
Examples:
- WHEN a user clicks the "Save" button THEN the system SHALL validate all form fields
- WHEN a file upload exceeds 10MB THEN the system SHALL display an error message
- WHEN a user session expires THEN the system SHALL redirect to the login page
Used for requirements that depend on specific system states or conditions.
Format: IF [condition] THEN [system] SHALL [response]
Examples:
- IF a user is not authenticated THEN the system SHALL deny access to protected resources
- IF the database connection fails THEN the system SHALL display a maintenance message
- IF a user has admin privileges THEN the system SHALL show the admin panel
Used for requirements that must be maintained during ongoing operations.
Format: WHILE [condition] [system] SHALL [continuous behavior]
Examples:
- WHILE a file is uploading the system SHALL display a progress indicator
- WHILE a user is typing the system SHALL provide real-time validation feedback
- WHILE the system is processing a request the system SHALL prevent duplicate submissions
Used for requirements that apply only in specific contexts or locations.
Format: WHERE [location/context] [system] SHALL [behavior]
Examples:
- WHERE the user is on a mobile device the system SHALL use responsive layout
- WHERE the application runs in production mode the system SHALL log errors to external service
- WHERE multiple users edit simultaneously the system SHALL handle conflicts gracefully
- Use Active Voice: Write requirements using active voice for clarity
- Be Specific: Avoid vague terms like "user-friendly" or "fast"
- One Requirement Per Statement: Each EARS statement should contain exactly one requirement
- Testable Outcomes: Every requirement should be verifiable through testing
- Consistent Terminology: Use the same terms throughout all requirements
- Compound Requirements: Avoid multiple SHALL statements in one requirement
- Vague Conditions: Don't use unclear triggers like "when appropriate"
- Implementation Details: Focus on what, not how
- Untestable Requirements: Avoid subjective terms that can't be measured
IEEE 830 provides guidelines for writing software requirements specifications (SRS). Key principles include:
- Correct: Accurately describes the intended functionality
- Unambiguous: Has only one interpretation
- Complete: Includes all necessary information
- Consistent: No conflicts with other requirements
- Ranked: Prioritized by importance and stability
- Verifiable: Can be tested or inspected
- Modifiable: Can be changed without excessive impact
- Traceable: Can be linked to design and implementation
- Introduction (Purpose, Scope, Definitions)
- Overall Description (Product Perspective, Functions, User Characteristics)
- Specific Requirements (Functional, Non-functional, Interface)
- Appendices (Supporting Information)
ISO/IEC 25010 defines quality characteristics for systems and software:
- Functional Completeness: All specified functions are present
- Functional Correctness: Functions provide correct results
- Functional Appropriateness: Functions facilitate specified tasks
- Time Behavior: Response times and processing speeds
- Resource Utilization: CPU, memory, storage usage
- Capacity: Maximum limits and scalability
- Co-existence: Can operate with other systems
- Interoperability: Can exchange and use information
- Appropriateness Recognizability: Users can recognize suitability
- Learnability: Easy to learn and understand
- Operability: Easy to operate and control
- User Error Protection: Protects against user errors
- User Interface Aesthetics: Pleasing user interface
- Accessibility: Usable by people with disabilities
- Maturity: Meets reliability needs under normal operation
- Availability: Operational when required
- Fault Tolerance: Operates despite hardware/software faults
- Recoverability: Can recover from failures
- Confidentiality: Ensures data access only by authorized users
- Integrity: Prevents unauthorized modification
- Non-repudiation: Proves actions or events have taken place
- Accountability: Traces actions to entities
- Authenticity: Proves identity of subjects or resources
- Modularity: Composed of discrete components
- Reusability: Assets can be used in other systems
- Analysability: Easy to assess impact of changes
- Modifiability: Can be modified without defects
- Testability: Test criteria can be established
- Adaptability: Can be adapted to different environments
- Installability: Can be installed in specified environments
- Replaceability: Can replace other software for same purpose
- Single Responsibility: Each module has one reason to change
- Open/Closed: Open for extension, closed for modification
- Liskov Substitution: Subtypes must be substitutable for base types
- Interface Segregation: Clients shouldn't depend on unused interfaces
- Dependency Inversion: Depend on abstractions, not concretions
- Creational: Factory, Builder, Singleton
- Structural: Adapter, Decorator, Facade
- Behavioral: Observer, Strategy, Command
- Layered Architecture: Separation of concerns through layers
- Microservices: Distributed system of small, independent services
- Event-Driven: Components communicate through events
- Hexagonal: Isolates core logic from external concerns
- Ubiquitous Language: Shared vocabulary between technical and domain experts
- Bounded Contexts: Clear boundaries around domain models
- Aggregates: Consistency boundaries for business rules
- Domain Events: Capture important business occurrences
- Independence: Framework, database, and UI independent
- Testability: Business rules can be tested without external elements
- UI Independence: UI can change without changing business rules
- Database Independence: Business rules not bound to database
- Codebase: One codebase tracked in revision control
- Dependencies: Explicitly declare and isolate dependencies
- Config: Store config in the environment
- Backing Services: Treat backing services as attached resources
- Build, Release, Run: Strictly separate build and run stages
- Processes: Execute as one or more stateless processes
- Port Binding: Export services via port binding
- Concurrency: Scale out via the process model
- Disposability: Maximize robustness with fast startup and graceful shutdown
- Dev/Prod Parity: Keep development, staging, and production as similar as possible
- Logs: Treat logs as event streams
- Admin Processes: Run admin/management tasks as one-off processes
Format: As a [role], I want [feature], so that [benefit]
Characteristics:
- Independent: Can be developed separately
- Negotiable: Details can be discussed and refined
- Valuable: Provides value to users or business
- Estimable: Can be sized for planning
- Small: Can be completed in one iteration
- Testable: Has clear acceptance criteria
- Define when a user story is complete
- Written in Given-When-Then format or EARS format
- Should be testable and specific
- Agreed upon by team and stakeholders
Feature: User Authentication
As a user
I want to log into the system
So that I can access my personal data
Scenario: Successful login
Given I am on the login page
When I enter valid credentials
Then I should be redirected to the dashboard- Discovery: Explore and understand requirements
- Formulation: Document examples and scenarios
- Automation: Create executable specifications
- Actors: External entities that interact with the system
- Use Cases: Specific interactions or functions
- Relationships: Include, extend, and generalization
- Entity-Relationship Diagrams: Data relationships
- State Diagrams: System behavior over time
- Sequence Diagrams: Interaction between components
- Activity Diagrams: Workflow and process flow
- Test Planning: Strategy and approach
- Test Design: Test cases and procedures
- Test Execution: Running tests and recording results
- Test Monitoring: Progress tracking and reporting
- Red: Write a failing test
- Green: Write minimal code to pass
- Refactor: Improve code while keeping tests green
- Meaningful Names: Use intention-revealing names
- Small Functions: Functions should do one thing well
- Comments: Code should be self-documenting
- Error Handling: Handle errors gracefully
- Formatting: Consistent code formatting
- Functionality: Does the code do what it's supposed to do?
- Design: Is the code well-designed and appropriate?
- Complexity: Is the code more complex than it needs to be?
- Tests: Does the code have correct and well-designed tests?
- Naming: Are names clear and appropriate?
- Comments: Are comments clear and useful?
- Logical Flow: Information presented in logical order
- Consistent Format: Uniform structure across documents
- Clear Headings: Descriptive section and subsection titles
- Cross-References: Links between related information
- Active Voice: Use active voice for clarity
- Concise Language: Eliminate unnecessary words
- Consistent Terminology: Use same terms throughout
- Audience Awareness: Write for your intended audience
- Endpoint Descriptions: Clear explanation of each endpoint
- Request/Response Examples: Sample inputs and outputs
- Error Codes: Comprehensive error handling information
- Authentication: Security requirements and implementation
- Getting Started: Quick start guides and tutorials
- Feature Guides: Detailed explanations of functionality
- Troubleshooting: Common issues and solutions
- FAQ: Frequently asked questions and answers
- IEEE (Institute of Electrical and Electronics Engineers): ieee.org
- ISO (International Organization for Standardization): iso.org
- W3C (World Wide Web Consortium): w3.org
- "Software Requirements" by Karl Wiegers and Joy Beatty
- "Writing Effective Use Cases" by Alistair Cockburn
- "User Stories Applied" by Mike Cohn
- "Specification by Example" by Gojko Adzic
- "Clean Architecture" by Robert C. Martin
- "Domain-Driven Design" by Eric Evans
- "Building Microservices" by Sam Newman
- "System Design Interview" by Alex Xu
- "Clean Code" by Robert C. Martin
- "The Art of Software Testing" by Glenford Myers
- "Continuous Delivery" by Jez Humble and David Farley
- "Release It!" by Michael Nygard