🚀 Quick Specification

🚀 Context for Quick Specification Work

Maximally simplified prompt for creating specifications in short timeframes. Includes:

• Basic Standards - only the most essential principles
• Quick Methodology - accelerated processes
• Quick Specification - minimalist templates
• Steering Documents - only critical standards

Use when: You need to create a specification as quickly as possible for prototypes or MVP.

🚀 Quick Specification

Maximally simplified prompt for creating specifications in short timeframes for prototypes and MVP.

---

📚 Source Documents

📄️ 📋 Standards and Methodological References

Industry standards, methodologies, and best practices for SDD

📄️ 🔧 Methodology

Step-by-step processes for creating specifications

📄️ 🚀 Quick Specification

Minimalist templates for rapid development

📄️ 📊 Steering Documents

Standards and guiding principles

---

📋 Standards and Methodological References

This section systematically organizes key industry standards, methodologies, and best practices that form the foundation for a Software Design Document (SDD). Applying these approaches ensures:

• Clarity and unambiguity of requirements
• High quality of architecture and documentation
• Minimization of risks and ambiguities in development
• Compliance with international quality standards

---

EARS (Easy Approach to Requirements Syntax)

A structured approach to formulating requirements that ensures clarity, verifiability, and unambiguity through standardized templates.

Key EARS Templates

1. WHEN (Event-Driven Requirements)

Purpose: Describing the system’s response to specific events or triggers
Format: WHEN [event/trigger] THEN [system] SHALL [action]

Examples:

• WHEN the user clicks the "Save" button THEN the system SHALL validate all form fields
• WHEN a file upload exceeds 10 MB THEN the system SHALL display an error message
• WHEN the user’s session expires THEN the system SHALL redirect to the login page

2. IF (State-Driven Requirements)

Purpose: Describing system behavior under specific conditions
Format: IF [condition] THEN [system] SHALL [action]

Examples:

• IF the 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 the user has administrator privileges THEN the system SHALL display the admin panel

3. WHILE (Continuous Requirements)

Purpose: Describing persistent system behavior while in a specified state
Format: WHEN [state] THEN [system] SHALL [continuous behavior]

Examples:

• WHEN a file is uploading THEN the system SHALL display a progress indicator
• WHEN the user is typing THEN the system SHALL provide real-time validation feedback
• WHEN the system is processing a request THEN the system SHALL prevent duplicate submissions

4. WHERE (Context-Dependent Requirements)

Purpose: Constraining a requirement to a specific context or environment
Format: WHERE [context] THEN [system] SHALL [behavior]

Examples:

• WHERE the user is on a mobile device THEN the system SHALL use a responsive layout
• WHERE the application runs in production mode THEN the system SHALL log errors to an external service
• WHERE multiple users edit simultaneously THEN the system SHALL handle conflicts gracefully

EARS Application Guidelines

Category	Recommendations	Examples
Syntax	• Use active voice • Consistently use the term "system" instead of synonyms	❌ "Fields must be validated" ✅ "The system SHALL validate fields"
Specificity	• Avoid vague terms • Specify quantitative parameters	❌ "Fast response" ✅ "Response time under 300 ms"
Structure	• One requirement = one statement • Clear verification criteria	❌ "The system SHALL validate and save" ✅ Two separate requirements

EARS Anti-Patterns

🚫 Compound Requirements
Example: "WHEN the user enters data THEN the system SHALL validate and save"
Solution: Split into two distinct requirements with separate triggers

🚫 Ambiguous Conditions
Example: "WHEN data is entered THEN the system SHALL process"
Solution: Specify exact conditions ("WHEN all mandatory fields are filled")

🚫 Implementation Details
Example: "WHEN the form is submitted THEN the system SHALL use a REST API"
Solution: Focus on the outcome ("...the system SHALL save the data")

---

Industry Standards

IEEE 830-1998: IEEE Recommended Practice for Software Requirements Specifications

Standard Purpose: Providing a structured approach to documenting requirements through an SRS (Software Requirements Specification).

Key Characteristics of a High-Quality SRS

• Completeness: All functional and non-functional requirements are accounted for
• Unambiguity: No ambiguous or vague phrasing
• Verifiability: Each requirement includes verification criteria
• Consistency: No contradictions between requirements
• Traceability: Clear linkage to sources and lifecycle phases

Recommended SRS Structure

1. Introduction
   - Purpose of the document
   - Scope
   - Definitions, acronyms, and abbreviations
   - References to related documents

2. Overall Description
   - System context
   - User characteristics
   - Implementation constraints
   - Assumptions and dependencies

3. Specific Requirements
   - Functional requirements (FR-001, FR-002...)
   - Non-functional requirements (NFR-001...)
   - Interfaces
   - Data requirements

4. Appendices
   - Traceability matrix
   - Diagrams
   - Sample scenarios

Requirements Specification Format

Each requirement must include:

• Unique identifier (e.g., FR-001)
• Short title
• Detailed description
• Source (customer/document)
• Priority (Must/Should/Could)
• Acceptance criteria
• Dependencies

---

Architectural Principles and Methodologies

SOLID Principles

Principle	Description	Anti-Pattern
Single Responsibility	Each component should serve only one actor/user role	God Object
Open/Closed	Open for extension, closed for modification	Frequent changes to base code
Liskov Substitution	Subclasses must be substitutable for their base classes	Violation of inheritance contracts
Interface Segregation	Prefer specific interfaces over general-purpose ones	"Fat" interfaces
Dependency Inversion	Depend on abstractions, not concrete implementations	Tight coupling to concrete implementations of higher layers

Domain-Driven Design (DDD)

Key Concepts:

• Ubiquitous Language: Shared terminology between business analysts and developers
• Bounded Contexts: Clear separation of domain areas
• Aggregates: Grouping of objects within a transactional boundary
• Domain Events: Recording significant business occurrences

Implementation Recommendations:

1. Create a domain glossary
2. Identify the Core Domain
3. Apply design patterns (Entities, Value Objects, Repositories)
4. Implement an event bus for inter-context communication

---

Requirements Elicitation Methodologies

User Stories

Format:
As a [role], I want [functionality] so that [business value]

Quality Criteria (INVEST):

• Independent: Independent of other stories
• Negotiable: Open to refinement and discussion
• Valuable: Delivers tangible value
• Estimable: Can be sized or estimated
• Small: Fits within a single iteration
• Testable: Has clear acceptance criteria

Example:
As a sales manager, I want to filter orders by date so that I can analyze weekly revenue.
Acceptance Criteria:

• WHEN a date range is entered THEN the system SHALL display orders within that period
• WHEN an invalid date is selected THEN the system SHALL show a helpful hint

Use Cases

Standard Structure:

1. Name
2. Actors
3. Preconditions
4. Main Success Scenario (step-by-step sequence)
5. Alternative Flows
6. Postconditions
7. Exceptions

Recommendations:

• Limit the main flow to a maximum of 9 steps
• Number alternative flows (e.g., 3a, 3b)
• Each step must include an actor action and the system’s response

---

Documentation Standards

Technical Documentation Requirements

Element	Recommendations	Anti-Patterns
Structure	• Logical sequence • Consistent heading hierarchy	Mixing levels of detail
Style	• Active voice • Precise phrasing	Passive constructions ("must be done")
Terminology	• Glossary at the beginning • Consistent terminology	Synonymy within the same document
Visualization	• Diagrams for complex processes • Data schemas	Excessive graphics without explanations

Documentation Types and Their Standards

1. API Documentation

Required Elements:

• Description of all endpoints with HTTP methods
• Request/response examples in JSON/YAML
• Error codes with explanations
• Authentication parameters
• Rate limits

Recommendation: Auto-generate using Swagger/OpenAPI

2. User Documentation

Structure:

- Quick Start: 5-minute guide
- Core Scenarios: Step-by-step instructions
- Advanced Features: In-depth exploration
- FAQ: Solutions to common issues
- Community links

3. Architectural Documentation

Required Sections:

• Context diagram (C4 Model Level 1)
• Container diagram (C4 Model Level 2)
• Key architectural decisions (ADR)
• Technology matrix
• Architecture evolution roadmap

---

These standards and methodologies should be adapted to the specific needs of each project, maintaining a balance between formality and practical applicability. Regular documentation reviews involving all stakeholders ensure its relevance and quality throughout the project lifecycle.

🚀 Specification-Driven Development Methodology

Specification-driven development is a systematic approach to developing software features that emphasizes thorough planning, clear documentation, and structured implementation. This methodology transforms vague feature ideas into clearly defined, implementable solutions through a three-phase process that ensures quality, maintainability, and successful delivery.

Core Philosophy

Clarity Before Code

The fundamental principle of specification-driven development is that clarity of thought and purpose must precede implementation. This approach requires investing time upfront to thoroughly understand requirements, design solutions, and plan implementation before writing a single line of code.

When a team dedicates time to upfront planning:

• Uncertainty is reduced – developers clearly understand exactly what needs to be built and why
• Rework is minimized – the likelihood of discovering critical issues late in the process decreases significantly
• Implementation accuracy improves – the probability of delivering precisely the solution the business needs increases

This principle is especially critical in today’s environment, where software requirements grow increasingly complex while delivery timelines become tighter. The investment in initial planning pays dividends many times over during implementation and subsequent maintenance phases.

Iterative Refinement

Each phase of the specification process is designed for iterative refinement rather than a one-time pass. Unlike a linear progression from idea to implementation, the methodology encourages continuous revisiting of earlier stages to adjust and clarify.

This approach offers several key advantages:

• Early problem detection – technical complexities, requirement mismatches, or unforeseen dependencies are identified during the design phase when they are cheapest to fix
• Gradual confidence building – each iteration deepens understanding of the problem and increases confidence in the chosen direction
• Flexibility amid uncertainty – allows course correction as new information emerges without sacrificing a structured approach

Iterativity manifests at all process levels—from refining requirements through exploring technical alternatives to detailing the implementation plan. This creates a solid foundation for subsequent work.

Documentation as Communication

In this methodology, specifications serve not merely as formal planning documents but as key communication instruments that fulfill several critically important functions:

• Stakeholder alignment – documented requirements and designs become a common language for developers, managers, customers, and other project participants
• Decision rationale preservation – captures not only what was decided but why, which is crucial when making future changes
• Context provision for future maintenance – new team members can quickly understand the system through documented decisions
• Creation of long-term assets – well-written specifications retain value even after the initial implementation is complete

This philosophy treats documentation not as a necessary evil but as an investment in the project’s future, yielding returns through improved understanding, reduced risk, and simplified maintenance.

---

Benefits of Specification-Driven Development

Reduced Risk and Uncertainty

Through thorough planning before implementation, specification-driven development significantly reduces the risk of building incorrect functionality or encountering unexpected technical issues. The systematic approach helps identify and resolve problems early in the process when fixes require minimal effort.

Concrete manifestations of this benefit include:

• Preventing the delivery of features that don’t match what was requested
• Early identification of contradictory or unrealistic requirements
• Discovery of technical constraints before coding begins
• Elimination of stakeholder misunderstandings at an early stage

Improved Quality and Maintainability

Features developed through the specification process typically demonstrate higher quality and are easier to maintain. This stems from several factors:

• Clear requirements establish a foundation for more comprehensive testing and validation
• Thoughtful design leads to better architecture and separation of responsibilities
• Proactive error-handling planning reduces the number of bugs in production
• Documented decision rationale facilitates future modifications and enhancements

Collectively, these aspects result in more reliable, testable, and modifiable code—particularly valuable for long-term projects.

Enhanced Collaboration

Specifications provide a common language and shared understanding among all project participants:

• Developers gain a clear picture of what needs to be implemented
• Testers can prepare test cases in parallel with development
• Project managers see the complete picture of requirements and complexity
• Customers can confirm their needs have been correctly understood

This improved communication reduces misunderstandings, minimizes rework, and enables more effective collaboration among all stakeholders throughout the project lifecycle.

Better Estimation and Planning

The detailed planning inherent in specification-driven development enables more accurate estimation of time and resource requirements. When teams invest time in analyzing requirements and designing before implementation begins, project managers and developers can make better-informed decisions:

• More accurate effort estimates – understanding full complexity enables realistic timelines
• Efficient resource allocation – knowledge of dependencies helps optimally assign tasks
• Transparent expectation management – customers gain a clear understanding of what will be delivered and when
• Flexible scope management – enables prioritization based on clearly defined requirements

This is especially valuable under resource constraints and tight deadlines, where every minute of planning saves hours of implementation.

Knowledge Preservation

One of the most undervalued benefits is the ability of specifications to serve as living documentation that preserves critically important project knowledge:

• Design rationale – why specific architectural decisions were made
• Requirement context – how business needs translated into technical solutions
• Change history – how and why requirements evolved over time
• Warnings and pitfalls – known issues and recommendations for avoiding them

This knowledge remains accessible long after the original developers have moved on to other projects, significantly reducing "knowledge debt" and simplifying project handover to new team members.

---

Comparison with Other Development Methodologies

Traditional Waterfall Development

Similarities:

• Both approaches emphasize the importance of upfront planning and documentation
• Both follow a sequential, phase-based development approach

Key Differences:

• Iterativity within phases: Specification-driven development encourages refinement and validation at each stage, whereas the waterfall model assumes strictly sequential progression without returns
• Living documents: Specifications are designed to evolve as working documents, while waterfall documentation is often frozen after approval
• Scale of application: The methodology is optimized for feature-level development rather than entire projects, making it more flexible
• Integration with modern practices: Specification-driven development accounts for working with AI tools and contemporary agile practices

Agile Development

Similarities:

• Both approaches value working software and customer collaboration
• Both embrace iterative refinement and feedback as integral parts of the process

Key Differences:

• Depth of upfront design: Specification-driven development places greater emphasis on thorough design before implementation, whereas classic Agile often defers design until implementation time
• Documentation structure: The methodology prescribes more structured documentation requirements, while Agile traditionally focuses on "working software over comprehensive documentation"
• Compatibility: Specification-driven development is designed to work within agile frameworks rather than replace them, making it complementary to Agile rather than an alternative
• Scale of application: Can be applied to individual features within agile sprints, providing structure where needed

Test-Driven Development (TDD)

Similarities:

• Both approaches emphasize defining success criteria before implementation
• Both use iterative cycles (red-green-refactor in TDD corresponds to requirements-design-implementation in specification-driven development)

Key Differences:

• Level of abstraction: Specification-driven development operates at a higher level, covering not just individual modules but also system interactions
• Scope of coverage: Includes business requirements and system design, not just test cases
• Practice integration: Can incorporate TDD practices within its implementation phase as one of many tools
• Context: Provides broader context encompassing not only technical aspects but also business goals and user needs

Design-First Development

Similarities:

• Both approaches prioritize design and planning before actual coding
• Both create detailed technical specifications before implementation

Key Differences:

• Requirements gathering: Specification-driven development includes an explicit, structured requirements-gathering phase using techniques like EARS, whereas Design-First often assumes requirements are already defined
• Task planning: Provides a more structured approach to task decomposition and implementation planning
• AI optimization: Specifically designed with AI-assisted development workflows in mind
• Requirements standardization: Incorporates specific methodologies like EARS (Easy Approach to Requirements Syntax) for creating clear, testable requirements

---

The Three-Phase Approach

Phase 1: Requirements Gathering

Objective: Transform vague feature ideas into clear, testable requirements that can be unambiguously understood by all stakeholders.

Key Activities:

• Capturing user stories that express not only what needs to be done but also why, focusing on value to the user or business
• Defining acceptance criteria using the EARS (Easy Approach to Requirements Syntax) methodology, which helps create clear, unambiguous, and testable requirements
• Identifying edge cases and constraints, including non-functional requirements such as performance, security, and scalability
• Validating completeness and feasibility through checking for contradictions, gaps, and technical realism

Benefits:

• Ensures shared understanding among all stakeholders about what will be built
• Provides clear success criteria for subsequent implementation and testing phases
• Reduces the risk of scope creep and functionality drift during development
• Creates a foundation for test development and result validation even before coding begins

Phase 2: Design Documentation

Objective: Create a comprehensive technical implementation plan that defines architectural decisions, system structure, and key interactions.

Key Activities:

• Exploring technical approaches and constraints, including analysis of possible solution options and their comparison against criteria
• Defining system architecture and component interactions, with emphasis on interfaces and responsibility boundaries
• Specifying data models and interfaces, including formal API definitions, data schemas, and communication protocols
• Planning error-handling, testing, and monitoring strategies to ensure system reliability and maintainability

Benefits:

• Identifies potential technical problems and complexities before coding begins, when fixes are cheaper
• Enables more accurate effort and resource estimation through deep problem understanding
• Provides a clear roadmap for implementation, reducing cognitive load on developers
• Documents design decisions and their rationale, which is critical for future maintenance

Phase 3: Task Planning

Objective: Break down the design into executable, sequential implementation steps that can be distributed among developers and tracked throughout the cycle.

Key Activities:

• Transforming design elements into concrete coding tasks with clear inputs and outputs
• Sequencing tasks to ensure incremental progress and enable early validation
• Defining clear objectives and completion criteria for each task to enable objective progress assessment
• Linking to original requirements to ensure traceability and confirmation that all functionality aspects are covered

Benefits:

• Makes large features manageable through decomposition into logical, independent parts
• Enables parallel work by multiple developers with minimal conflicts
• Simplifies progress tracking and early bottleneck identification
• Reduces cognitive load on developers by allowing focus on one task at a time
• Facilitates code review and quality assurance through clear responsibility separation

---

Lightweight Specifications

Principles of Lightweight Specifications

Lightweight specifications represent an adapted approach to the methodology that preserves its key benefits when working with small features, bug fixes, and rapid iterations. The primary goal is to ensure sufficient planning without excessive bureaucracy, maintaining balance between thorough preparation and rapid implementation.

Key principles:

• Proportional effort – documentation volume corresponds to task complexity
• Minimalism – documentation is limited to what’s necessary for understanding and verification
• Flexibility – ability to expand specifications when unexpected complexity emerges
• Practicality – focus on what genuinely helps implementation rather than formal requirements

Specification Complexity Decision Tree

flowchart TD
    A[New work item] --> B{Effort > 1 day?}
    B -->|No| C[Micro-specification]
    B -->|Yes| D{Multiple components?}
    
    D -->|No| E{New patterns/technologies?}
    E -->|No| F[Rapid specification]
    E -->|Yes| G[Standard specification]
    
    D -->|Yes| G[Standard specification]
    
    C --> K[Minimal documentation]
    F --> L[Streamlined process]
    G --> M[Full three-phase process]
    I --> M

Types of Lightweight Specifications

Micro-Specification

Applied to: Bug fixes, text changes, configuration updates, minor UI changes (less than 1 day effort).

Characteristics:

• Minimal documentation focusing on the essence of changes, often as comments in the task tracking system
• Brief rationale and clear acceptance criteria sufficient for verification
• No formal design or detailed task planning – decisions are made directly during implementation
• Documentation limited to the minimum necessary for understanding and verification, often including only what and why without detailed how

Example: Fix typo in welcome message text

Rapid Specification

Applied to: Small features, API endpoint additions, database schema changes, component modifications (1-3 days effort).

Characteristics:

• Simplified requirements gathering focusing on key user stories and acceptance criteria
• Direct transformation of requirements into implementation tasks without a separate formal design phase – design is integrated into task planning
• Clear acceptance criteria and definition of "done" for each task
• Maintained traceability between requirements and tasks through explicit links

Example: As a user, I want to see my last login time

Dynamic Specification Level Adaptation

Indicators for Elevating Specification Level

For micro-specifications:

• Implementation takes significantly longer than initially estimated
• Non-obvious dependencies between components are discovered
• Complex edge cases emerge that weren’t considered in initial criteria
• Coordination with other teams or systems becomes necessary

For rapid specifications:

• Complex design questions arise during implementation requiring serious analysis
• Hidden dependencies on other systems or components are discovered
• Significant implications for performance, security, or scalability emerge
• Additional stakeholder alignment is needed due to scope expansion

Adaptation Process

1. Current state assessment: Analyze reasons for increased complexity and identify specific areas requiring additional elaboration

2. Identify missing elements: Determine which aspects need additional specification – requirements, design, or task details

3. Specification enhancement: Add necessary elements focused on solving identified problems without completely rewriting existing documentation

4. Change alignment: Discuss the expanded specification with stakeholders and obtain confirmation

5. Implementation continuation: Proceed with coding using the enhanced specification as guidance

This flexible approach ensures balance between necessary structure and operational speed, enabling specification efforts to scale according to actual project needs while preserving the core principles and benefits of specification-driven development.

---

Steering Documents

Steering documents are project working guidelines.

They contain project-specific standards and conventions that help teams work more cohesively. These documents aim to "guide" developers when working with the project and address two problems:

• Documenting information not related to specific specifications (e.g., GitFlow decisions)
• Documenting information that repeats across specifications (e.g., global testing strategy, technology stack, or code style)

Core principles:

• The list of steering documents is individual for each stack, team, and solution
• The list of steering documents may change during solution evolution
• Different steering documents are relevant at different stages of working with specifications
• Steering documents constitute the project’s shared context
• It’s recommended to create separate tasks in specifications for maintaining steering document currency
• It’s recommended to reference specific steering documents in specification designs
• It’s recommended to create multiple atomic steering documents rather than a few large ones
• You can have steering documents that apply to the entire solution as well as those specific to particular components or modules

Conclusion

Specification-driven development represents a balanced approach that combines the benefits of thorough planning with the flexibility required for modern software development. This methodology doesn’t require rigid adherence to formal processes but provides a structure that can be adapted to specific project needs.

By following the three-phase methodology and applying lightweight specifications where appropriate, development teams can achieve an optimal balance between preparation and implementation. This enables them to:

• Create higher-quality software with fewer bugs
• Reduce project risks through early problem detection
• Improve communication among all process participants
• Preserve project knowledge for long-term maintenance

The methodology is especially effective when combined with modern AI-assisted development tools, as the structured approach to requirements, design, and task planning provides the clear context that AI systems need for maximum effectiveness. AI assistants can better understand tasks and propose more accurate solutions when requirements and designs are clearly defined.

The adaptive nature of lightweight specifications makes the methodology universal—it can be applied in various contexts, from minor bug fixes to large projects, ensuring an optimal balance between preparation and implementation. This makes specification-driven development a powerful tool in the modern developer’s arsenal, helping create better software more efficiently and with lower risk.

🚀 Quick Specification Documentation

A Quick Specification is a document that provides development teams with a structured yet lightweight process for specifying small features, ensuring clarity, testability, and traceability while minimizing bureaucracy and excessive documentation.

Purpose and Objectives of the "Quick Specification":

• Transform an idea for a small feature into clear, testable acceptance criteria.
• Create a direct and understandable implementation plan in the form of a task list.
• Establish shared understanding among developers, testers, and product managers.
• Ensure traceability from user value down to specific coding tasks.
• Reduce cognitive load on developers by enabling them to focus on one task at a time.

Step-by-Step Process

Step 1: Formulate the User Story and Acceptance Criteria (EARS)

Objective: Define what needs to be done and why, establishing measurable success criteria.

Write the user story: Use the format "As a [role], I want [feature] so that [benefit]." Focus on business value.

Create acceptance criteria using the EARS format: Convert the story into 3–7 specific, unambiguous, and testable statements.

• Use templates: WHEN... THEN..., IF... THEN..., WHEN... AND... THEN..., WHEN... (error) THEN....
• Mandatory: Include at least one error-handling or edge-case scenario.
• Avoid implementation details (e.g., "use Redis").
• Avoid vague terms ("fast," "convenient").
• Each requirement must start with WHEN or IF and contain THEN the system SHALL.

Outcome: A clearly defined scope of work with measurable completion criteria.

Step 2: Convert Requirements into Implementation Tasks

Objective: Break down acceptance criteria into concrete, actionable steps for developers.

Analyze each acceptance criterion: Identify the exact coding actions required to fulfill it.

Formulate tasks: Each task should describe a specific activity (e.g., "Create endpoint /api/v1/user/status," "Add last_login field to the User model," "Write a unit test for email validation").

Establish sequence: Tasks should be logically ordered—typically starting with foundational elements (data models, API contracts), followed by business logic, then error handling and tests.

Ensure traceability: Each task must explicitly reference the acceptance criterion it implements (e.g., "Implements Criterion 3: WHEN the user submits the form...").

Outcome: A structured, ready-to-execute task list.

Step 3: Validation and Refinement

Objective: Ensure the specification is complete, clear, and implementable.

Self-check using the checklist below:

• The user story clearly defines the role, action, and value.
• All acceptance criteria are written in EARS format.
• Error-handling or edge-case criteria are included (minimum of one).
• Each implementation task has a clear, specific objective.
• Each task references its corresponding acceptance criterion.
• Tasks are ordered in a logical sequence.
• The specification enables the developer to begin implementation immediately.

Outcome: An approved, implementation-ready specification.

Document Template

# Quick Specification: "[Concise and clear feature/change title]"

**User Story:**

As a [user role], I want [feature/change description] so that [business value/benefit].

---

## Acceptance Criteria

### **[Name/Description of Criterion 1]**

WHEN [event] THEN the system SHALL [observable outcome].

### **[Name/Description of Criterion 2]**

IF [condition] THEN the system SHALL [observable outcome].

### **[Name/Description of Criterion 3 – ERROR HANDLING/EDGE CASE REQUIRED]**

WHEN [exceptional event] THEN the system SHALL [error-handling action].

### *[Add 1–4 more criteria if needed]*

---

## Implementation Plan

*Tasks are ordered according to implementation logic. Each task references the acceptance criterion it fulfills.*

### [Specific action, e.g., "Create API endpoint /api/v1/feature"]

  * *Implements criteria:* [Reference to criteria]
  * *Details:* [Which files/components to create/modify? Brief logic description.]
  * *Completion criterion:* [e.g., "Code written; API contract documented in Swagger."]

### [Specific action, e.g., "Add input data validation"]
  * *Implements criteria:* [Reference to criteria]
  * *Details:* [Which files/components to create/modify? Brief logic description.]
  * *Completion criterion:* [e.g., "Validation implemented; unit tests for validation pass."]

### [Specific action, e.g., "Write integration test"]
  * *Implements criteria:* [Reference to criteria]
  * *Details:* [Which files/components to create/modify? Brief logic description.]
  * *Completion criterion:* [e.g., "Test written and passes successfully."]

### [Specific action, e.g., "Update user documentation"]
  * *Implements criteria:* [Reference to criteria]
  * *Details:* [Which files/components to create/modify? Brief logic description.]
  * *Completion criterion:* [e.g., "User Guide section updated and published to the website."]

---

## 3. Quality Checklist (Completed by author before implementation begins)

| Criterion                                                                 | Done | Comment |
| ------------------------------------------------------------------------- | ---- | ------- |
| User story clearly defines role, action, and value                        | ☐    |         |
| All acceptance criteria are formulated in EARS format                     | ☐    |         |
| Error-handling/edge-case criteria included (minimum 1)                    | ☐    |         |
| Each implementation task has a clear, specific objective                  | ☐    |         |
| Each task references its corresponding acceptance criterion              | ☐    |         |
| Tasks are ordered in a logical sequence                                   | ☐    |         |
| Specification enables the developer to start implementation immediately  | ☐    |         |

🎯 Steering Documents

Objective: Ensure consistency, quality, and efficiency in development by creating and maintaining a set of living, atomic documents that serve as the project’s shared context and guide the team in implementing any work items—from micro-specifications to large features.

Core Principles

Steering documents are not static artifacts but dynamic knowledge management and quality assurance tools. Their creation and maintenance are governed by the following key principles:

1. Atomicity and Focus: Each document must focus on a single, specific topic (e.g., git_workflow, react_component_structure, postgres_naming_conventions). Avoid creating monolithic, all-encompassing manuals.
2. Living Documentation: Documents must be regularly updated as the project, technologies, and best practices evolve. Outdated documentation is worse than no documentation at all.
3. Practical Orientation: Content must be directly applicable by developers in their day-to-day work. Focus on the “how” and “why,” not abstract theories.
4. Contextuality: Documents may be global (applying to the entire solution) or local (specific to a particular module, microservice, or component). Clearly indicate the scope of applicability.
5. Integration into Workflow: Steering documents are an integral part of the specification-driven development process. They must be explicitly referenced in design specifications and considered during task planning.
6. Ownership of Currency: It is recommended to create dedicated tasks within specifications for maintaining the currency of steering documents, especially after significant changes to the codebase or infrastructure.

---

Primary Categories of Steering Documents

To ensure comprehensive coverage of the development lifecycle, steering documents are grouped into the following categories:

1. Development Environment and Infrastructure Standards

• Objective: Ensure consistency and reproducibility of local and CI/CD environments.
• Example Documents:
  • development_environment_setup: Local setup procedures, dependencies, IDE configuration.
  • environment_variables_management: Rules for naming, storing, and managing environment variables.
  • build_and_deployment_processes: Build scripts, CI/CD pipeline configurations, deployment procedures across environments.
  • infrastructure_as_code_standards: Standards for Terraform, CloudFormation, etc.

2. Code Quality Standards

• Objective: Maintain high code quality, readability, and maintainability.
• Example Documents:
  • language_style_guide_[language]: Style guides (e.g., python_style_guide, typescript_style_guide).
  • naming_conventions: Conventions for naming variables, functions, classes, files, and database objects.
  • code_organization_patterns: Patterns for structuring projects, modules, and components.
  • code_documentation_requirements: Requirements for comments, docstrings, and documentation generation.

3. Git Workflow Standards

• Objective: Ensure a predictable and efficient collaborative source code management process.
• Example Documents:
  • git_branching_strategy: Branch naming conventions (e.g., feature/, hotfix/, release/).
  • commit_message_format: Commit message format (e.g., Conventional Commits).
  • pull_request_process: Procedures for creating, reviewing, and merging PRs (description requirements, checklists).
  • code_review_guidelines: Guidelines for reviewers and authors (what to check, how to provide feedback).

4. Technology- and Architecture-Specific Standards

• Objective: Establish unified design and implementation rules for the project’s key technologies.
• Example Documents:
  • frontend_architecture_patterns: UI development patterns (e.g., React/Vue component structure, state management).
  • backend_api_design: Standards for designing REST/gRPC APIs (versioning, response structure, error codes, OpenAPI/Swagger documentation).
  • database_design_and_migration: Rules for database schema design, migration conventions, and indexing strategies.
  • testing_strategy_[level]: Global testing strategies (e.g., unit_testing_strategy, e2e_testing_strategy, framework selection, coverage requirements).

5. Security, Performance, and Observability

• Objective: Lay the foundation for building reliable, secure, and easily diagnosable systems.
• Example Documents:
  • security_practices: Applied security practices (input validation, session management, secret handling, dependency scanning).
  • performance_optimization_guidelines: Optimization guidelines (caching, asynchronous processing, profiling).
  • monitoring_and_alerting_standards: Standards for logging, metrics, tracing, and alert configuration.

6. Business Context and Architecture

• Objective: Ensure shared understanding of the domain and the system’s high-level structure.
• Example Documents (core documents, always create):
  • tech_stack: Explicit justification for each technology in the stack, including versions.
  • domain_glossary: Glossary of key business terms and concepts.
  • project_dataflow: High-level description of data flows within the system.
  • context_diagram_c4: C4 context diagram (Level 1; likec4 syntax recommended).
  • container_diagram_c4: C4 container diagram (Level 2; likec4 syntax recommended).

---

Step-by-Step Creation and Maintenance Process

Step 1: Needs Assessment and Planning

• Objective: Determine which steering document is needed and plan its creation.
• Process:
  1. Project Analysis: Review the current codebase to identify inconsistencies or areas where the absence of standards leads to errors.
  2. Gap Identification: Determine which standard category is missing or requires updating.
  3. Prioritization: Assess the potential impact of the document. Priority order: security > code quality > workflow > performance.
  4. Template and Scope Selection: Decide whether the document will be global or component-specific. Choose an appropriate level of detail (lightweight for small teams, comprehensive for enterprise solutions).
  5. Task Creation: Record the need to create or update the document as a distinct work item in the backlog.

Step 2: Content Development

• Objective: Produce a practical, clear, and useful document.
• Process:
  1. Research Best Practices: Use industry standards (e.g., Google Style Guides, 12-factor app) as a foundation.
  2. Project Contextualization: Adapt general practices to the project’s specific technologies, constraints, and goals.
  3. Include Examples: Always provide concrete, working code samples, configuration files, or diagrams. “Show, don’t tell.”
  4. Link Integration: Connect the new document to other steering documents and relevant sections of design specifications.
  5. Formalization: Use clear, unambiguous language. Avoid terms like “should” or “recommended” where “must” or “must not” can be used instead.

Step 3: Validation and Approval

• Objective: Ensure the document is useful, actionable, and error-free.
• Quality Criteria:
  • Actionability: Can a developer immediately apply these rules in practice?
  • Clarity: Is the document understandable to a new team member?
  • Consistency: Does it contradict other steering documents or approved design specifications?
  • Completeness: Does it cover all key aspects of the stated topic?
  • Relevance: Is it based on the current state of the project and technologies?
• Process: Conduct a document review with key developers and architects. Obtain formal approval from the technical lead.

Step 4: Maintenance and Evolution

• Objective: Keep the document current throughout the project’s lifecycle.
• Process:
  1. Regular Review: Periodically verify the currency of all steering documents.
  2. Update upon Changes: Any significant change to architecture, technology stack, or processes must be accompanied by updates to relevant steering documents. This may be handled as a separate task within the corresponding specification.
  3. Remove Obsolete Content: Do not hesitate to delete documents or sections that are no longer relevant. Maintain “minimal sufficiency.”

---

Steering Documents Quality Checklist

(Completed after document creation or update)

Criterion	Done	Comment
Document focuses on a single, specific topic (atomic)	☐
Content is practical and directly applicable by developers	☐
Includes concrete, working examples	☐
Provides justification for key rules and decisions	☐
Contains no confidential data or secrets	☐
No conflicts with other steering documents	☐
Language is clear, unambiguous, and uses “must”/“must not”	☐
Includes links to related steering documents and specifications	☐
Specifies scope (global/component) and owners	☐
Plans for regular review and updates	☐