Skip to main content

⚡ Micro-specification

⚡ Context for Micro-specification Work​

Optimized prompt for quick creation of compact specifications. Includes:

  • Basic Standards - key EARS principles
  • Micro-specification Methodology - simplified processes
  • Micro-specification - templates for quick documentation
  • Steering Documents - minimally necessary standards

Use when: You need to quickly create a compact specification for small projects or individual modules.

⚡ Micro-specification

Optimized prompt for quick creation of compact specifications for small projects.

📚 Source Documents​

📋 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​

CategoryRecommendationsExamples
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​

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
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​

PrincipleDescriptionAnti-Pattern
Single ResponsibilityEach component should serve only one actor/user roleGod Object
Open/ClosedOpen for extension, closed for modificationFrequent changes to base code
Liskov SubstitutionSubclasses must be substitutable for their base classesViolation of inheritance contracts
Interface SegregationPrefer specific interfaces over general-purpose ones"Fat" interfaces
Dependency InversionDepend on abstractions, not concrete implementationsTight 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​

ElementRecommendationsAnti-Patterns
Structure• Logical sequence • Consistent heading hierarchyMixing levels of detail
Style• Active voice • Precise phrasingPassive constructions ("must be done")
Terminology• Glossary at the beginning • Consistent terminologySynonymy within the same document
Visualization• Diagrams for complex processes • Data schemasExcessive 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.

⚡ Micro-Spec Documentation

A micro-spec is a document that enables a minimalist approach to documenting small work items (e.g., bug fixes, minor UI changes, configuration updates) requiring minimal effort. Its purpose is to provide sufficient context for implementation and verification while avoiding excessive bureaucracy.

Applicability:

Use for tasks that:

  • Are estimated at less than 1 day of effort.
  • Do not affect multiple system components.
  • Do not require introducing new architectural patterns or technologies.
  • Are obvious and straightforward to implement (e.g., fixing a typo, changing a button color, updating a value in a configuration file).

Authoring Process​

Step 1: Define the Essence of the Change​

Goal: Clearly articulate what exactly needs to be changed or fixed.

Actions:

  • Briefly describe the current (incorrect/suboptimal) state.
  • Clearly describe the desired (correct/target) state.
  • Specify the exact location in the system where the change is required (e.g., file name, screen, line of code—if obvious).

Step 2: Provide Justification​

Goal: Explain why this change is necessary so any team member can understand its value or necessity.

Actions:

  • State the reason: is this a bug fix, a UX improvement, a client-requested update, compliance with a new guideline, etc.?
  • If it’s a bug fix, briefly describe how to reproduce the issue (or provide a link to the bug tracker ticket).

Step 3: Define Acceptance Criteria​

Goal: Establish objective, verifiable conditions that determine whether the task has been successfully completed.

Actions:

  • Use simple, active voice.
  • Phrase criteria as testable statements. Often, one or two criteria are sufficient.
  • Recommendation: For maximum clarity, you may use simplified EARS syntax (e.g., WHEN... THEN...), though this is optional if the criterion is already unambiguous.

Example of a poor criterion: "Fix the bug."
Example of a good criterion: "After clicking the 'Submit' button, the form no longer freezes and displays the message 'Data successfully submitted'."

Step 4: Validation and Finalization​

Goal: Ensure the micro-spec contains all necessary information and is free of ambiguity.

Actions:

  • Ask yourself: "Can a developer unfamiliar with this task pick up this document and immediately begin implementation?"
  • Ask yourself: "Can a tester (or the developer themselves) unambiguously verify task completion using only these acceptance criteria?"
  • If the answer to both questions is "yes," the specification is ready.

Micro-Spec Document Template​

# Micro-Spec: [Concise and clear task title]

**Current State:** 

[Description of what currently exists and what is wrong.]

**Desired State:** 

[Description of what should exist after the task is implemented.]

**Location of Change:** 

[Specific file, module, screen, URL, etc.—where exactly should changes be made?]

## Justification 

[Explanation of why the change is needed. Examples: "Fixing a critical bug preventing users from logging in," "Updating text per the new marketing guidelines," "Changing color to improve accessibility."]

## Testing Strategy

* [Test case]
   * Case description
* [Another test case]
   * Case description

---

## Micro-Spec Quality Checklist

*(Completed by the author after finishing the document)*

| Criterion                                                                                         | Done | Comment |
| ------------------------------------------------------------------------------------------------- | ---- | ------- |
| Specifies the exact location in the system where the change must be made                          | ☐    |         |
| Justification includes business or user value                                                    | ☐    |         |
| All acceptance criteria are phrased in active voice and use EARS (WHEN/IF)                        | ☐    |         |
| Each acceptance criterion is **verifiable** and **unambiguous**                                   | ☐    |         |
| The spec contains no compound requirements (each is split into separate items)                    | ☐    |         |
| Any developer can take this spec and start working on it 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)

CriterionDoneComment
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☐