Skip to content

Contract-First Architecture

Intent

Make system relationships and dependencies explicit through defined contracts, reducing the "lost" feeling that comes from implicit coupling rather than system complexity.

Context

Applies when: - A system has grown from isolated components to an interconnected platform - Teams struggle to understand component relationships without shared mental models - Changes in one layer unexpectedly break other layers - System evolution is hindered by fear of unknown dependencies

This pattern emerged from the Ideas to Life platform evolution where individually correct components created confusion due to unclear sequence and dependencies.

Problem

Without explicit contracts: - Component relationships are difficult to reason about - Implicit coupling causes hidden dependencies that break unexpectedly - Changes require deep system knowledge to assess impact - System feels "lost" even when components are simple - Knowledge of how things connect exists only in individual minds

Forces

  • Explicitness vs flexibility
  • Upfront design vs iterative discovery
  • Documentation overhead vs runtime clarity
  • Team coordination vs individual autonomy

Solution

Establish clear contracts between system layers before and during implementation:

  1. Contract Definition: Define interfaces between layers (governance, templates, prompts, artefacts, rendering)

  2. Dependency Visualization: Map how components rely on each other using diagrams with explicit dependency cues

  3. Lifecycle Contracts: Standardize vocabulary and states across components (e.g., exploring → validating → shipping → archived)

  4. Governance as First-Class: Treat governance artefacts (charters, runbooks) as system components, not documentation

  5. Single Responsibility: Separate concerns clearly (intent from execution, generation from deployment, narrative from artefacts)

Implementation approach:

  • Metadata headers on all contracts to make them explicit
  • Visual dependency diagrams that evolve with the system
  • Clear separation between templates (intent) and prompts (execution)
  • Constitutional artefacts (EXPERIMENTS.md) with enforcement status

Implementation Signals

  • Explicit metadata headers on templates, prompts, and governance files
  • Visual diagrams showing component dependencies
  • Clear separation between intent (templates) and execution (prompts)
  • Governance artefacts treated as system components
  • Standardized lifecycle vocabulary across components
  • Single-responsibility prompts that don't mix generation and deployment

Evidence

  • threads/system-with-contracts: "Explicit contracts matter more than individual correctness"
  • Key signal: "The feeling of being 'lost' was not due to system complexity, but to the absence of a map"
  • Visual process diagram iteration showing dependencies and governance
  • Separation established: governance → templates → prompts → artefacts → website

Consequences

Benefits: - System becomes navigable and understandable - Changes can be made with confidence about impacts - New team members can understand relationships faster - Architectural drift becomes visible - Governance is enforceable because it's explicit

Trade-offs / Limitations: - Upfront investment in contract definition - Contracts must be maintained as system evolves - Over-specification can reduce flexibility - Visualization requires ongoing effort

Failure Modes: - Contracts become stale and misleading - Over-engineered contracts create bureaucracy - Teams bypass contracts when they feel restrictive - Visualization becomes decoration rather than active tool

Anti-Patterns

  • Implicit contracts that exist only in tribal knowledge
  • Mixing concerns in single components (prompts that generate AND deploy)
  • Governance as afterthought documentation
  • Diagrams that show ideal state rather than actual dependencies

Reuse Notes

Applies to: - ideas-to-life: Platform with multiple interconnected experiments - runner-agentic-intelligence: Multi-agent system with clear boundaries - Any system evolving from isolated components to integrated platform

Expected reusability: High

This pattern is essential for platform-scale systems where component relationships matter more than individual component quality.

Agentic Profile

  • Contract-aware agents that validate against defined interfaces
  • Agents that consume and produce according to explicit schemas
  • Orchestration agents that respect layer boundaries
  • Prompt–Schema Contracts as First-Class Architecture: Complements this pattern by specifying how contracts are technically enforced
  • Architecture Workflow Loop: Provides mechanism for maintaining contracts over time