🎯 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:

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.
Living Documentation: Documents must be regularly updated as the project, technologies, and best practices evolve. Outdated documentation is worse than no documentation at all.
Practical Orientation: Content must be directly applicable by developers in their day-to-day work. Focus on the “how” and “why,” not abstract theories.
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.
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.
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.”