3 minutes

28. Implement Architecture Scoring via Spec-Driven Development (SDD)

Date: 2026-04-15

Status

Accepted

Context and Problem Statement

The Unicorn Project currently lacks an objective, automated method to evaluate the technical debt and structural complexity of its evolving architecture. While Archimate models are maintained, there is no feedback loop to “score” the architecture against complexity metrics (like coupling) or to ensure that the implementation stays true to the recorded Architecture Principles. We need a tool that bridges the gap between high-level modeling and measurable architectural governance.

Decision Drivers

  • Objective Governance: Provide data-driven insights into architectural complexity.
  • Spec-Driven Alignment: Ensure the scoring logic is derived directly from formal specifications (SDD).
  • Interoperability: Must work with existing tooling (Archi, coArchi2, GitHub).
  • Automated Metrics: Focus on C4 Model Container dependencies (Afferent/Efferent coupling).

Considered Options

  1. Option 1: Manual architectural reviews (Status Quo).
  2. Option 2: A custom Python Architecture Scoring Component using SDD (speckitplus, opencode, Big Pickle).
  3. Option 3: Generic off-the-shelf Static Analysis tools (e.g., SonarQube for code, but not for architecture models).

Decision Outcome

Chosen Option: Option 2. We will develop a Python-based Architecture Scoring Component.

This component will be built using a Spec-Driven Development (SDD) approach. By utilizing speckitplus and opencode alongside the Big Pickle model, we ensure that the scoring logic is generated from machine-readable specifications. This allows the SDD convention to automatically integrate our recorded Architecture Principles and ADRs directly into the validation logic.

Technical Implementation Details

  • Input: The component consumes Archimate Models exported via Archi.
  • Collaboration: The models are hosted and versioned on GitHub using the coArchi2 plugin to allow distributed architectural contribution.
  • Logic: The component parses the Archimate XML/JSON to extract C4-level Container relationships.
  • Metrics:
    • Afferent Coupling (Ca): Measures how many components depend on a container (Responsibility).
    • Efferent Coupling (Ce): Measures how many components a container depends on (Instability/Complexity).
    • Instability Index: Calculated as $I = Ce / (Ca + Ce)$.

Component Schematic

--- config: look: handDrawn theme: neutral --- graph TD subgraph "Modeling Environment" A[Archi Tool] -->|coArchi2| B[GitHub Repository] end subgraph "Architecture Scoring Component (Python)" B -->|Archimate Model| C[Model Parser] C -->|Complexity Analysis| I[C4 Container Metrics] end subgraph "Output" I --> J[Afferent/Efferent Report] I --> K[Architecture Health Score] end

Pros and Cons of the Chosen Option

Pros

  • Consistency: Using SDD ensures the “Scoring Code” never deviates from the “Architecture Principles” defined in the specifications.
  • Automation: Reduces manual governance overhead by pulling directly from the source of truth (GitHub/coArchi2).
  • Granularity: Focusing on C4 Containers provides a pragmatic view of system boundaries and dependencies that code-level analysis often misses.
  • Extensibility: The Big Pickle model allows for evolving the scoring logic as the project’s complexity grows.

Cons

  • Initial Setup: Requires configuring the SDD pipeline (speckitplus and opencode) which has a learning curve.
  • Model Strictness: The scoring is only as good as the Archimate model; requires architects to maintain high-quality, up-to-date models in Archi.