DEV Community: Brooke

About This Documentation Infrastructure

Brooke — Wed, 07 Jan 2026 01:18:02 +0000

About This Documentation Infrastructure

← Back to SRDD entry page

This page describes how the SRDD documentation is structured, built, and published.

Documentation Source

All documentation lives as Markdown files in the ./documentation directory of the GitHub repository. This is the single source of truth.

documentation/
├── index.md              # Entry point / overview
├── pitches.md            # Various length summaries
├── SRDD-part1-of-4.md    # Article series
├── SRDD-part2-of-4.md
├── SRDD-part3-of-4.md
├── SRDD-part4-of-4.md
├── CONTRIBUTING.md       # Contribution guide
├── about.md              # This file
└── .sync-state.json      # Dev.to sync state (auto-generated)

Each Markdown file uses YAML front matter for metadata (title, description, etc.) and standard GitHub-flavored Markdown for content.

Cross-Document Linking

Documents use a placeholder syntax for internal links:

See [Part 1](https://dev.to/bbos/srdd-part-1-of-4-the-best-ai-coding-methodology-8fe) for details.

The {{devto:slug}} pattern gets transformed differently depending on the target platform:

Platform	Transformation
GitHub Pages	`{{devto:slug}}` → `./slug.md`
Dev.to	`{{devto:slug}}` → actual Dev.to URL (e.g., `https://dev.to/bbos/...`)

This allows documents to link to each other without hard-coding URLs that differ across platforms.

GitHub Actions Pipeline

A single workflow (.github/workflows/deploy-and-sync.yml) handles all publishing:

Step 1: Build for GitHub Pages

- name: Transform devto placeholders for GHP
  run: |
    find ./documentation -name "*.md" -exec sed -i -E \
      's/\{\{devto:([^}]+)\}\}/.\/\1.md/g' {} \;

- name: Build with Jekyll
  uses: actions/jekyll-build-pages@v1
  with:
    source: ./documentation
    destination: ./_site

The pipeline:

Copies assets into the documentation directory
Transforms {{devto:slug}} placeholders to relative .md links
Builds with Jekyll
Deploys to GitHub Pages

Step 2: Sync to Dev.to

After GitHub Pages deployment completes:

sync-to-devto:
  needs: deploy  # Run after deploy so canonical URLs are live
  steps:
    - name: Sync posts to Dev.to
      env:
        DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}
        SITE_URL: ${{ vars.SITE_URL }}

The sync script (scripts/sync-to-devto/sync-to-devto.js) performs a two-pass sync:

Pass 1: Create/Update Articles

For each Markdown file:

Parse front matter and content
Build canonical URL (pointing to GitHub Pages)
Transform content (absolute URLs for images, strip styles)
Create or update the Dev.to article via API
Capture the returned Dev.to URL

Pass 2: Resolve Cross-Links

Dev.to generates URLs with unpredictable suffixes (e.g., my-post-4k2n). After Pass 1, we have a map of slug → actual URL. Pass 2:

Re-parses documents containing {{devto:slug}} placeholders
Replaces placeholders with actual Dev.to URLs from the map
Updates those articles again with resolved links

// URL map built during Pass 1
{
  "index": "https://dev.to/bbos/srdd-is-the-best...-4k2n",
  "SRDD-part1-of-4": "https://dev.to/bbos/why-srdd-exists-2j8m",
  // ...
}

This two-pass approach ensures all cross-references resolve correctly despite Dev.to's dynamic URL generation.

Incremental Sync

The sync script only uploads posts that have changed, reducing API calls and speeding up the pipeline.

How it works:

Each post's content is hashed (SHA-256, truncated to 32 chars / 128 bits)
Hashes are stored in documentation/.sync-state.json
On each run, current hashes are compared with stored hashes
Only posts with different hashes are synced
The updated state file is committed back to the repository

// .sync-state.json
{
  "index": { "hash": "a1b2c3d4e5f67890...", "syncedAt": "2026-01-07T10:00:00Z", "url": "https://dev.to/bbos/srdd-...-4k2n" },
  "pitches": { "hash": "f0e1d2c3b4a59687...", "syncedAt": "2026-01-07T10:00:00Z", "url": "https://dev.to/bbos/pitches-...-2j8m" }
}

The url field caches each article's Dev.to URL, enabling placeholder resolution even when API rate limits prevent fetching URLs.

Force full sync:

To sync all posts regardless of changes, set the FORCE_SYNC environment variable:

env:
  FORCE_SYNC: 'true'

Or run locally with the --force flag:

node sync-to-devto.js --force

# Or with .env file (loads DEVTO_API_KEY, SITE_URL, etc.)
export $(grep -v '^#' .env | xargs) && node sync-to-devto.js --force

Refresh URL cache:

Dev.to URLs are cached in sync state. To refresh the cache (useful if articles were renamed or URLs changed):

env:
  REFRESH_URLS: 'true'

Or run locally:

node sync-to-devto.js --refresh-urls

# Or with .env file
export $(grep -v '^#' .env | xargs) && node sync-to-devto.js --refresh-urls

Canonical URLs

Every article on Dev.to includes a canonical_url pointing to the GitHub Pages version:

canonical_url: https://docs-bbos.github.io/srdd/SRDD-part1-of-4/

This tells search engines that GitHub Pages is the authoritative source. Benefits:

SEO consolidation: Search rankings accrue to one URL
Platform flexibility: Content can appear on Dev.to, Medium, or future platforms
Single source of truth: Readers always know where to find the canonical version

Adding New Documentation

To add a new page:

Create documentation/new-page.md with appropriate front matter
Link from other pages using {{devto:new-page}}
Commit and push to main
The pipeline automatically deploys to GitHub Pages and syncs to Dev.to

Environment Configuration

The pipeline requires:

Secret/Variable	Purpose
`DEVTO_API_KEY`	Dev.to API key from dev.to/settings/extensions
`SITE_URL`	GitHub Pages URL (e.g., `https://docs-bbos.github.io/srdd`)

This infrastructure enables "write once, publish everywhere" for living documentation that evolves with the methodology.

SRDD pitches

Brooke — Wed, 07 Jan 2026 00:17:50 +0000

SRDD Is the Best AI Coding Methodology - pitches

← Back to SRDD entry page

Summary of pitches

Document	Length	Audience
One-liner	1-2 sentences	Everyone (hook)
Elevator pitch	~150 words / 60 sec	Networking, intros
One-minute read	~250 words	Time-poor anyone
Executive brief	~600 words	Managers, CTOs, VPs
Technical brief	~800 words	Tech leads, architects

One-Liner

AI coding is a force multiplier, not a replacement — SRDD keeps developers in control while AI handles execution, so understanding compounds instead of decaying.

Elevator Pitch

Coding at scale and intensity is hard — architecture, interfaces, testing, debugging. AI handles this effortlessly. It's a genuine advancement. But AI can't understand architecture beyond its context window. It knows the how, not the why. Businesses that fired their developers are rehiring them. AI is a force multiplier, not a replacement.

So how do we harness AI's power while keeping developers in control?

Every approach hits the same wall as systems grow: the AI forgets earlier decisions, architectural drift accumulates, teams stop understanding what they're shipping. Vibe coding forgets. Agentic coding echoes. Spec-driven development fossilizes.

SRDD closes the loop.

Specifications guide implementation — but code becomes the source of truth. Periodically, understanding is extracted back out through regeneration: fresh specs synthesized from the living system, informed by everything learned along the way.

The developer dreams; the AI disciplines. Developers stay hands-on — reviewing, steering, choosing when to regenerate — not deskilled into passengers watching the AI drive off a cliff. Understanding compounds instead of decaying. Systems stay maintainable. Velocity doesn't collapse at scale.

And when it's time to rebuild, you're not reverse-engineering legacy code. The regenerated specs already capture what the system became and what it will become — in English, not yesterday's code or framework.

One-Minute Read

Why AI coding matters: Coding at scale and intensity is hard — architecture, interfaces, testing, debugging demand enormous cognitive load. AI handles this effortlessly: identifies broken interfaces, writes tests covering every code path, surfaces edge cases, never gets bored. AI coding is a genuine advancement.

But AI has limits: AI can't understand architecture beyond its context window. It knows the how, not the why. Businesses that fired their developers are rehiring them. AI is a force multiplier, not a replacement.

The problem: AI-assisted coding accelerates everything — including architectural decay. Vibe coding forgets earlier decisions as context windows overflow. Agentic coding echoes mistakes across autonomous loops. Context engineering curates inputs meticulously but has no mechanism to extract understanding back out. Spec-driven development fossilizes — specs written upfront drift into fiction as reality evolves. Each approach optimises for something real, but none of them close the loop. Teams ship systems they no longer fully understand.

The insight: Vibe and agentic coding externalize nothing. Context engineering curates inputs but never extracts outputs. SDD writes specs upfront and watches them fossilize. SRDD inverts this: specs are snapshots, not contracts. Code evolves. Periodically, understanding is extracted back out — not as rescue, but as a planned phase.

The method: SRDD is a six-phase workflow where specs guide implementation, but code becomes the source of truth. When accumulated drift signals misalignment, regeneration synthesizes fresh specs from the living system — capturing everything learned, surfacing technical debt, and reasserting direction. Then the loop begins again: clearer, cleaner, and ready for the next revolution.

The result: Understanding compounds instead of decaying. Velocity stays high because confidence stays high. Developers remain in control — shaping direction, reviewing PRs, deciding when to regenerate — while AI handles execution.

For larger systems: Scaled SRDD (SSRDD) coordinates multiple independent SRDD loops across domains, enforcing boundaries without bureaucracy.

Bottom line: SRDD makes "burn it down and rebuild properly — keeping everything we learned" a repeatable workflow, not a fantasy.

SRDD: Executive Brief

Why AI Coding Matters

Coding at scale and intensity is hard. Architecture, interfaces, testing, debugging — all demand enormous cognitive load. AI changes this: it identifies broken interfaces, generates implementations from design documents, writes tests covering every code path, and surfaces edge cases. It works in any framework and never gets bored.

AI coding is a genuine advancement in software development.

But AI Has Limits

AI cannot understand an architecture that exceeds its context window. It doesn't dream. It cannot generate truly novel ideas. AI knows the how, not the why — why we're building this software, who it's for, what problems they're solving.

Too many businesses assumed AI coding meant they could eliminate most developers. Many did. Those businesses are now rehiring.

AI is a force multiplier, not a replacement.

What is SRDD?

Spec-Roundtrip Driven Development (SRDD) is an AI-assisted development methodology designed for systems that must remain maintainable over time.

Unlike approaches that treat specifications as fixed contracts or ignore them entirely, SRDD treats specs as snapshots — initially created to establish intent, then periodically regenerated from the living codebase to capture what the system has become and what it will be.

The Problem It Solves

AI-assisted coding delivers significant productivity gains on small projects. But as systems grow, predictable failure modes emerge:

Architectural drift — The AI makes locally optimal changes without awareness of system-wide intent
Lost understanding — Teams ship systems they no longer fully comprehend
Velocity collapse — Simple changes become risky; confidence erodes
Technical debt accumulation — Shortcuts compound invisibly until refactoring becomes prohibitive

These failures are not unique to any single tool. They emerge from a structural gap: understanding flows into AI-generated code, but nothing flows back out.

How SRDD Addresses This

SRDD introduces a closed loop:

Specs guide implementation — Structured planning documents establish intent before code
Code becomes source of truth — Reality evolves; specs are understood to be point-in-time snapshots
Regeneration extracts understanding — Periodically, fresh specs are synthesized from the living system, informed by code, PRs, issues, tests, and production discoveries — and incorporating new functional and non-functional requirements for what it will become next.

This is not a rescue operation. It is a planned phase in the system's lifecycle.

Business Value

Outcome	Mechanism
Sustained velocity	Confidence enables speed; regeneration prevents the slow hardening that makes change risky
Reduced rework	Architectural misalignment is surfaced early, before it becomes expensive to fix
Lower onboarding cost	Understanding is externalized into regenerated specs, not trapped in tribal knowledge
Retained optionality	Systems remain comprehensible and changeable as requirements evolve
Developer retention	Engineers work on coherent systems with clear direction, not archaeological rescue missions

Future-Proofing

Traditional systems trap knowledge in code. When that code becomes brittle, you face an unpleasant choice: expensive rewrite or slow decay. And rewrites typically reuse existing code to reduce cost — importing the same architectural constraints into the new system.

SRDD inverts this.

Understanding is continuously extracted into regenerated specs — language-agnostic, architecture-agnostic documentation of what the system does and why. The code is one implementation of that understanding, not the understanding itself.

When technology shifts — and it will — the cost of targeting a new language, framework, or architecture is not significantly higher than rewriting in the same stack. You're not reverse-engineering legacy code. You're re-implementing documented understanding, informed by everything learned, with AI doing the heavy lifting.

Traditional rewrite	SRDD rebuild
Reverse-engineer understanding from brittle code	Understanding already captured in specs
Reuse old code to save time → import old constraints	Fresh implementation from documented intent
Locked to existing language/architecture	Free to target new stack
Knowledge walks out the door with developers	Knowledge externalized and versioned

SRDD doesn't just maintain systems. It makes them portable across time.

What It Requires

SRDD is a methodology, not a product. Adoption requires:

Planning document discipline — Seven structured documents per development cycle
Phase-aware workflow — Six phases from design through production
Human judgment at key moments — Developers review PRs, decide when to regenerate, and validate direction. The AI guides: surfacing signals, flagging drift, advising when regeneration is due. Humans decide; AI illuminates.

The methodology can be adopted today using documentation and rules files. Tooling for enforcement (CLI, MCP integration) is on the roadmap.

When to Use SRDD

SRDD suits projects that:

Outlive a single coding session
Involve multiple services, files, or contributors
Require production validation and iterative refinement
Must remain maintainable over months or years

For multi-domain systems, Scaled SRDD (SSRDD) coordinates independent SRDD loops across bounded contexts.

Recommendation

For teams experiencing velocity decay, architectural drift, or loss of system understanding in AI-assisted development, SRDD provides a structured path back to clarity — without abandoning the productivity benefits of AI.

Pilot adoption on a single project with a willing team. Evaluate after one full cycle including regeneration.

SRDD: Technical Brief

Why AI Coding Matters

Coding at scale and intensity is hard. Architecture, interfaces, testing, debugging — enormous cognitive load. AI handles this effortlessly: identifies broken interfaces, generates implementations from specs, finds every linearly independent path through code (cyclomatic complexity) and writes tests to cover them all, surfaces edge cases, works in any framework, never gets bored. It's already ingested StackOverflow.

AI coding is a genuine advancement.

But AI Has Limits

AI can't understand architecture beyond its context window. It doesn't dream. It can't generate novel ideas. AI knows the how, not the why — why we're building this, who it's for, what problems they're solving.

Businesses that fired their developers are rehiring them. AI is a force multiplier, not a replacement.

Overview

Spec-Roundtrip Driven Development (SRDD) is a six-phase AI-assisted development methodology that maintains architectural coherence through planned regeneration cycles.

Core principle: Specs are snapshots, not contracts. Code becomes the source of truth. Understanding is periodically extracted back out.

The Six Phases

Phase	Purpose	Key outputs
1. Design	Establish intent	Planning docs (00-07)
2. Implementation	TDD, scope-guarded development	Code, tests, PRs
3. Review	Coherence validation	Approved PRs
4. UAT	Observe and accumulate evidence	Findings in 07-NextCycle.md
5. Triage	Analyze findings, choose path	Decision: iterate, regenerate, or release
6. Production	Version and release	Tagged release, continued observation

Planning Documents

Each cycle produces a dated planning directory:

docs/plans/2025-01-15_v2_post-regeneration/
  00-PLANNING.md       ← Requirements questionnaire
  01-REQUIREMENTS.md   ← Functional and non-functional requirements
  02-USECASES.md       ← User stories with acceptance criteria
  03-QA-SESSION.md     ← Clarifying Q&A transcript
  04-ARCHITECTURE.md   ← Technical design, components, data model
  05-IMPLEMENTATION.md ← Phased build plan
  06-TESTPLAN.md       ← Test strategy
  07-NextCycle.md      ← Accumulated signals, candidate contracts, version history

AI Responsibilities

During implementation, the AI operates under explicit constraints:

Scope guardian — Cannot modify files outside declared issue scope
Pattern follower — Must conform to patterns in ARCHITECTURE.md
Contract respecter — Cannot change test contracts without explicit approval
TDD enforcer — Red → Green → Refactor on every change

Human review remains mandatory. The AI determines whether code works; the reviewer determines whether it fits.

Regeneration Triggers

The AI monitors for spaghettification signals:

Duplicated logic across modules
Circular dependencies
Whack-a-mole regressions
God modules / SRP violations
Velocity decay on simple changes
Pattern inconsistency

When signals accumulate, the AI advises regeneration. The decision remains human.

Regeneration Process

Regeneration synthesizes fresh specs from multiple sources:

Current codebase
Prior planning documents
Git history and PRs
Issues and tickets
Test suite
07-NextCycle.md

Output: A new dated planning directory describing the system as it now stands — not as it was once imagined.

Key principle: Holistic diagnosis, selective intervention. The entire system is re-understood; only drifted subsystems are redesigned.

SSRDD (Scaled SRDD)

For multi-domain systems:

Each domain owns its own planning artefacts and SRDD cycle
CONSTITUTION.md defines system-wide integration standards
Explicit dependency declarations via contracts/consumes.yaml
Boundary drift detection across domains
Coordinated regeneration when changes cascade

Trade-offs

SRDD provides	SRDD requires
Sustained velocity at scale	Planning document discipline
Externalized understanding	Human judgment at triage/review
Managed technical debt	Acceptance that regeneration has real cost (days, perhaps weeks, not hours)
Clear audit trail	More ceremony than vibe coding

Technology Portability

SRDD's regeneration cycle produces specs that are implementation-independent:

Requirements, use cases, and contracts are in natural language
Architectural decisions are documented with rationale
Lessons learned and rejected approaches are captured
Code references illustrate solutions but don't define them

This means:

Language migrations (JS → TS, Python → Go) become spec re-implementation, not code translation
Architecture shifts (monolith → microservices) are informed by documented boundaries
Framework upgrades are unconstrained by legacy code patterns
New team members can understand intent without archaeology

The marginal cost of rebuilding in a new stack versus the same stack is low — because the specs, not the code, carry the knowledge.

When to Use

Good fit:

Systems expected to live > 6 months
Multiple contributors or services
Production validation required
Maintainability is a priority

Not ideal for:

Throwaway scripts / single-session utilities
Strictly regulated environments requiring SDD-style traceability
Teams unwilling to maintain planning docs

Adoption Path

Use planning doc templates (00-07)
Add SRDD rules to AI configuration (CLAUDE.md, .cursorrules)
Follow phase workflow manually
Rely on human review for coherence and scope

This delivers 60-70% of value. Tooling for reliable enforcement is on the roadmap.

Documentation: docs-bbos.github.io/srdd
Repository: github.com/docs-bbos/srdd
Article series: SRDD Is the Best AI Coding Methodology

License & Prior Art

This repository constitutes a public disclosure and defensive publication of the Spec-Roundtrip Driven Development (SRDD) and Scaled SRDD (SSRDD) methodologies.

The author expressly places the concepts, processes, and workflows described herein into the public domain as prior art, for the purpose of preventing subsequent patent claims or exclusive ownership by third parties.

Commercial use, redistribution, or derivative works of this text require explicit permission from the author.

SRDD Is the Best AI Coding Methodology - entry

Brooke — Wed, 07 Jan 2026 00:17:48 +0000

SRDD — Spec-Roundtrip Driven Development

Keeping developers in control while building better systems with aligned AI

Jump to quick specification overview in Pitches.

SRDD is an AI-assisted development methodology where specifications and code exist in a closed loop. Specs guide implementation, but code becomes the source of truth. Periodically, understanding is extracted back out through regeneration — synthesising fresh specs from the living system. The developer dreams; the AI disciplines. Understanding compounds instead of decaying.

For multi-domain systems, Scaled SRDD (SSRDD) wraps multiple SRDD instances with a coordination layer, governing boundaries between independently evolving subsystems.

SRDD Overview (this page)
Pitches — One-liner to executive brief
Part 1: Why SRDD Exists — The problem, the journey, the insight
Part 2: The AI Coding Landscape — Vibe coding, agentic coding, context engineering, SDD
Part 3: The SRDD Workflow — Phases, contracts, regeneration
Part 4: Scaling Up — SSRDD, principles, implementation
Contributing
About — Documentation infrastructure

Why AI Coding Matters

Coding at scale and intensity is hard. Architecture, interfaces, testing, debugging — all demand enormous cognitive load. AI handles this effortlessly: identifies broken interfaces, generates implementations from specs, writes tests covering every code path, surfaces edge cases, works in any framework, never gets bored. It's already ingested StackOverflow.

AI coding is a genuine advancement in software development.

But AI Has Limits

Businesses that fired their developers are rehiring them. AI is a force multiplier, not a replacement.

The Problem

AI-assisted coding is transformative for small projects. But as systems grow, the same failure modes appear everywhere:

Context windows become constraints, not conveniences
The AI forgets earlier decisions and repeats mistakes
Architectural drift accumulates silently
Velocity slows as complexity rises
Teams stop understanding the systems they're shipping

Every approach optimises for something real — speed, autonomy, discipline, traceability — but none of them close the loop between specification and reality.

SRDD closes the loop.

The Core Insight

Specs are snapshots, not contracts.

They capture understanding at a moment in time. Code evolves. Periodically, you must extract new understanding from the code and regenerate the specs.

Specs guide code. Code informs regenerated specs. It's a closed loop.

The Six Phases

┌─────────────────────────────────────────────────────────────────┐
│                        SRDD Workflow                            │
└─────────────────────────────────────────────────────────────────┘

Phase 1: Design          → Establish intent, create planning docs
Phase 2: Implementation  → TDD, contracts, scope-guarded development  
Phase 3: Review          → PR review, coherence validation
Phase 4: UAT             → Observe and accumulate evidence
Phase 5: Triage          → Analyze findings, choose path
Phase 6: Production      → Version, release, continue observing

                    ┌─────────────────────────┐
                    │      Phase 4: UAT       │
                    │   (Observe & Accumulate)│
                    └───────────┬─────────────┘
                                │
                                ▼
                    ┌─────────────────────────┐
                    │  Phase 5: Triage and    │
                    │        Decide           │
                    └───────────┬─────────────┘
                                │
            ┌───────────────────┼───────────────────┐
            │                   │                   │
            ▼                   ▼                   ▼
    ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
    │   Phase 1:    │   │   Phase 2:    │   │   Phase 6:    │
    │  Regenerate   │   │   Iterate     │   │  Production   │
    │(architectural)│   │ (bugs/minor)  │   │               │
    └───────────────┘   └───────────────┘   └───────────────┘

Planning Documents

Each SRDD cycle produces a dated planning directory:

docs/plans/2025-12-15_v1_initial-design/
  00-PLANNING.md       ← Initial brain dump from requirements questionnaire
  01-REQUIREMENTS.md   ← Refined functional and non-functional requirements
  02-USECASES.md       ← User stories with acceptance criteria
  03-QA-SESSION.md     ← Q&A transcript clarifying ambiguities
  04-ARCHITECTURE.md   ← Technical design, components, data model
  05-IMPLEMENTATION.md ← Phased plan: what gets built in what order
  06-TESTPLAN.md       ← Test strategy and test data requirements
  07-NextCycle.md      ← Accumulated signals, candidate contracts, version history

What SRDD Enforces

Principle	Description
The roundtrip is the methodology	Specifications flow into implementation. Understanding flows back out through regeneration.
Specs are snapshots, not contracts	Specifications capture understanding at a point in time. Code becomes the source of truth.
The codebase is a curriculum	The AI learns from your existing code. Contradictions breed confusion; consistency compounds velocity.
Guardrails encode judgment structurally	Types, linters, schemas, and folder boundaries prevent bad patterns before review.
Coherence matters more than correctness	The AI determines whether code works. The reviewer determines whether it fits.
The developer dreams; the AI disciplines	Humans choose direction. The AI executes, guards scope, and maintains consistency.
Velocity follows clarity	Fast development is not the cause of good systems. It is the consequence of clear ones.

Scaled SRDD (SSRDD)

For systems that extend beyond a single bounded context:

Each domain owns its own planning artefacts and SRDD cycles
Domains evolve at their own pace and regenerate when local signals demand it
CONSTITUTION.md defines system-wide integration standards
Explicit dependency declarations prevent accidental coupling
Boundary drift detection flags architectural erosion early

SSRDD scales understanding, not bureaucracy.

Current Status

Component	Status	Notes
Methodology documentation	✅ Available	This repo
Planning doc templates	✅ Available	`templates/` directory
Rules file examples	✅ Available	CLAUDE.md templates
Scope enforcement tooling	🔲 Planned	Pre-commit hooks, MCP integration
Coherence validation	🔲 Planned	Pattern comparison against ARCHITECTURE.md
Regeneration advisor	🔲 Planned	Cross-session signal tracking
SSRDD coordination layer	🔲 Planned	Multi-subsystem orchestration

Adoption Today

Teams can adopt SRDD now by:

Using the planning doc templates (00-07)
Adding SRDD rules to AI configuration (CLAUDE.md, .cursorrules, etc.)
Following the phase workflow manually
Relying on human review for coherence and scope discipline

This delivers 60-70% of the value. The remaining 30-40% — reliable enforcement without human vigilance — awaits tooling.

Roadmap

Alignment with Agile and SAFe
Map SRDD phases to Agile ceremonies and SAFe constructs — regeneration in PI planning, Phase 5 triage in backlog refinement, SSRDD across Agile Release Trains.

Rules file templates
Complete CLAUDE.md, .cursorrules, and copilot-instructions.md templates encoding the full SRDD workflow.

MCP server integration
Real-time SRDD enforcement within Claude Code, Cursor, and similar tools.

Kubernetes and container orchestration
SSRDD boundaries aligned with Kubernetes namespaces, CONSTITUTION.md as service mesh policies, coordinated regeneration in deployment pipelines.

The Article Series

This methodology is documented in a four-part series:

Part 1: Why SRDD Exists — The problem, the journey, the insight
Part 2: The AI Coding Landscape — Vibe coding, agentic coding, context engineering, SDD
Part 3: The SRDD Workflow — Phases, contracts, regeneration
Part 4: Scaling Up — SSRDD, principles, implementation

Contributing

SRDD and SSRDD are open methodologies. Contributions welcome:

Tooling development
Template improvements
Integration guides for specific frameworks
Case studies and adoption experiences

See Contributions

License & Prior Art

This repository constitutes a public disclosure and defensive publication of the Spec-Roundtrip Driven Development (SRDD) and Scaled SRDD (SSRDD) methodologies.

Commercial use, redistribution, or derivative works of this text require explicit permission from the author.

SRDD (Part 4 of 4) - Scaling Up - SSRDD, Principles, and Implementation

Brooke — Tue, 06 Jan 2026 23:49:48 +0000

SRDD (Part 4 of 4): Scaling Up - SSRDD, Principles, and Implementation

← Back to SRDD entry page

This is Part 4 of a four-part series on Spec-Roundtrip Driven Development.

👉 Read Part 1: Why SRDD Exists
👉 Read Part 2: The AI Coding Landscape
👉 Read Part 3: The SRDD Workflow

Part 3 walked through the SRDD workflow: five phases, contracts as authority, the AI as scope guardian, and regeneration as a deliberate reset of understanding.

Where the earlier parts focus on failure modes and workflow, this final part focuses on durability: how SRDD holds up under scale, time, and organisational pressure.

This final article covers three things: how SRDD scales to multi-domain systems through Scaled SRDD (SSRDD), the principles that underpin the methodology, and the current state of implementation - what you can adopt today and what tooling is still planned.

Fighter Male Dragon Scale fish

Scaled SRDD (SSRDD)

For systems that extend beyond a single bounded context, SRDD scales into Scaled SRDD (SSRDD).

SSRDD is not a new methodology layered on top of SRDD. It is a coordination wrapper that allows multiple independent SRDD loops to coexist without collapsing into chaos or bureaucracy.

Each domain, service, or subsystem:

owns its own planning artefacts
runs its own SRDD cycles
evolves at its own pace
regenerates when its local signals demand it

No central plan attempts to predict how the whole system should evolve.

Instead, SSRDD introduces just enough structure at the system boundary to allow independent evolution without accidental entanglement.

System-Level Coordination

At the system level, SSRDD coordinates only what must be shared:

Shared constitutions

Agreed integration standards that define how domains present themselves to one another - API conventions, event schemas, versioning rules, and compatibility expectations. These govern interaction, not internal design.
Explicit contracts

Public-facing APIs, events, and invariants are declared and versioned. Domains are free to change internally as long as these contracts hold or are deliberately evolved.
Dependency visibility

What each domain consumes and produces is visible by design. Hidden couplings are surfaced early, before they calcify into architectural traps.
Boundary drift detection

SSRDD watches for signs that domain boundaries are eroding - duplicated responsibilities, circular dependencies, creeping knowledge of internals - and flags these as candidates for regeneration or boundary renegotiation.

This combination is uncommon: most large systems either centralise architectural control to prevent drift, or decentralise teams without making drift visible at the system level. SSRDD does neither - it allows local autonomy while making architectural change observable rather than accidental.

Crucially, SSRDD does not synchronise development cadence, force shared tooling, or impose uniform internal practices. It coordinates interfaces and intent, not implementation.

SSRDD scales understanding, not bureaucracy.

Why SRDD Works

SRDD succeeds because it aligns with how complex systems actually evolve - not how we wish they would.

It acknowledges discovery

SRDD assumes that important knowledge arrives late. Instead of treating this as failure, it builds discovery into the process and gives it a disciplined place to land.
It prevents specs from becoming fiction

Specs are continuously regenerated from reality, not left to rot as idealised narratives disconnected from the system that ships.
It manages AI-induced technical debt at the design level

AI accelerates both construction and decay. SRDD counters this not by slowing AI down, but by periodically reasserting architectural intent before debt becomes destiny.
It preserves tacit product wisdom

Decisions that would otherwise live only in heads or pull requests are captured, externalised, and made legible to both humans and machines.
It restores human judgment where it belongs

AI executes, analyses, and enforces. Humans choose direction, recognise discomfort, and decide when a system needs to change course.

SRDD is not the fastest way to write code.

It is the fastest way to keep understanding intact - as systems grow, teams change, and years pass.

Boundary Enforcement via Dependency Permissions (SSRDD)

SSRDD does more than coordinate domains. It can enforce architectural boundaries.

The core rule is explicit:

If a domain does not declare that it consumes another domain, it cannot see it.

This model is closely analogous to Project Jigsaw (Java 9+).

Like Jigsaw, SSRDD treats boundaries as design-time and compile-time constraints, not as informal conventions. Domains must explicitly declare what they depend on and what they expose. Everything else is inaccessible by default.

Explicit dependency declarations

Each domain declares its dependencies in contracts/consumes.yaml:

consumes:
  - identity-management/api-users
  - inventory/api-stock

Controlled evolution of dependencies

In practice, dependency permissions in SSRDD are not universally mutable.

Domain developers typically do not have direct write access to the system-level SSRDD artefacts that define cross-domain dependencies - such as the shared constitution or dependency registry. Their focus remains local: implementing behaviour within declared boundaries.

Changes to domain dependencies are instead mediated at the system level, typically by architects or designated system stewards.

This mirrors the intent of Project Jigsaw: module boundaries are not something individual classes casually rewrite. They are structural decisions, owned at a higher level of abstraction.

Why this separation matters

Without this separation, boundaries decay quietly:

A developer “just imports” another domain to save time
A quick integration bypasses the contract layer
A dependency is added for convenience and never removed
Architectural coupling becomes invisible until it is irreversible

AI-assisted development amplifies this failure mode. When generation is cheap and fast, the path of least resistance is always cross-boundary access.

SSRDD deliberately resists this by making dependency changes explicit, reviewable, and intentional.

Developers still move quickly within their domain.
They simply cannot accidentally change the shape of the system.

In short: SSRDD treats dependency changes as architectural events, not implementation conveniences.

Architectural control without architectural bottlenecks

This is not about slowing teams down.

By centralising dependency authority:

Domains remain autonomous within their scope
Integration decisions are made with system-level visibility
Boundary changes become conscious design moments
Regeneration remains feasible because coupling stays controlled

The result is not bureaucracy - it is preserved optionality.

Architects are not approving code.
They are curating the shape in which code is allowed to grow.

SSRDD enforces boundaries the same way strong type systems enforce correctness:
not by trust, but by making the wrong thing impossible.

Designated principle speaking to all the other district principles

Principles

The principles that follow were crystallised in part through reflection on Craig Adam's article "Agile is Out, Architecture is Back" - a clear articulation of why architecture matters more, not less, in the age of AI-assisted development. His framing of the codebase as curriculum and the developer's evolving role helped sharpen what SRDD was already reaching toward. Thank you.

The five phases describe what happens in SRDD. This section describes why certain patterns recur across all of them.

These principles are not rules to be enforced. They are orientations - ways of thinking that make AI-assisted development more effective, more sustainable, and more aligned with human intent.

Designing for AI Comprehension

Your codebase is a curriculum. Every pattern teaches the AI what to repeat. Contradictions create confusion. Consistency creates velocity.

The AI learns your project not from training, but from context. It reads your existing code and generates more code that looks like it. This has profound implications.

Rules files instruct. Code demonstrates.

Your CLAUDE.md, cursor rules, and similar files tell the AI what to do. Your codebase shows what "right" looks like. Both matter - but when they conflict, the AI often follows what it sees over what it's told.

If your codebase contains:

Multiple logging implementations → AI picks one randomly or invents another
Inconsistent error handling → AI generates inconsistent error handling
Mixed naming conventions → AI outputs mixed naming
God classes alongside clean modules → AI might follow either pattern

The AI does not judge which pattern is correct. It pattern-matches on what exists.

This principle is LLM-agnostic: Every AI coding tool - Claude Code, Cursor, Copilot, Windsurf, and tools not yet built - reads your codebase into context. Keep your codebase clean and consistent because the AI will copy what it sees.

Applying this across SRDD

Phase	Purpose	Application
Phase 1	Establish intent	Define canonical patterns in ARCHITECTURE.md before implementation begins
Phase 2	Build it	Correct deviations immediately; uncorrected deviations become new patterns
Phase 3	Check fit	Review for pattern conformance, not just correctness
Phase 4	Validate reality	Formalise production discoveries carefully; they become future examples
Phase 5	Realign or continue	Consolidate contradictory patterns during regeneration

Guardrails Beyond Tests

Use types, linters, schemas, and structure not just to enforce correctness - but to communicate intent.

Tests verify behaviour after the fact. Guardrails prevent bad patterns from entering in the first place. They operate earlier in the feedback loop, and they constrain what the AI can produce.

Types as documentation:
Strong typing (TypeScript, Zod schemas, Pydantic models) constrains AI output at generation time. A well-typed function signature tells the AI what shapes are valid before it writes a line of implementation.

Linters as guardrails:
ESLint rules, Prettier configurations, and architectural linters (like eslint-plugin-boundaries) reject code that violates conventions automatically. The AI learns quickly that certain patterns don't survive.

Schemas as contracts:
OpenAPI specs, JSON Schema, and similar declarations make contracts machine-readable. The AI can validate its output against them - and tools can reject non-conforming code before review.

Folder structure as architecture:
Where code lives communicates what it is. A clear directory structure - with boundaries that match domain concepts - helps the AI place new code appropriately. Ambiguous structure produces ambiguous placement.

These guardrails are not bureaucracy. They are force multipliers. Every constraint that prevents a bad pattern from entering is a constraint that doesn't need to be caught in review, fixed in testing, or cleaned up during regeneration.

Guardrails encode judgment structurally - not just in documentation.

Judgement Day

Encode Judgment, Don't Just Document It

Structure that enforces decisions is stronger than documentation that describes them.

Documentation can be ignored. Structure cannot.

When a decision matters - when violating it would cause drift, inconsistency, or architectural decay - encode it in a way that makes violation difficult or impossible:

Use folder boundaries to enforce module separation, not just naming conventions
Use types to make invalid states unrepresentable, not just documented as "don't do this"
Use linter rules to reject patterns automatically, not just style guides that request compliance
Use CI checks to fail builds on violations, not just code review comments

The AI reads structure more reliably than prose. A linter rule that rejects a pattern is more effective than a CLAUDE.md instruction that discourages it.

This does not mean documentation is worthless. It means documentation is for explanation, not enforcement. Explain the "why" in docs. Enforce the "what" in structure.

The test: If the AI could violate a decision and still produce code that passes all checks, the decision is not yet encoded. It is merely suggested.

Coherence Over Correctness

Correct code that doesn't fit is worse than imperfect code that coheres.

The AI can produce code that works. That is table stakes. The harder problem is producing code that fits - that respects existing boundaries, follows established patterns, and doesn't introduce architectural debt.

A function can pass all tests and still:

Use a different logging approach than the rest of the system
Handle errors in a novel way that won't be replicated
Introduce a dependency that violates layering
Name things inconsistently with surrounding code

These are not test failures. They are coherence failures. They make the system harder to understand, harder to maintain, and harder for the AI to pattern-match correctly in future.

The reviewer's job is coherence: The AI handles correctness. The human ensures fit.

This requires architectural awareness - understanding not just whether the code works, but whether it belongs. That awareness is precisely what distinguishes a developer from a code generator.

Some might like this missing loop

The Developer Dreams, The AI Disciplines

Humans are for invention, imagination, and direction. Machines are for execution, analysis, and consistency.

SRDD deliberately assigns roles:

The developer:

Decides what to build and why
Makes architectural judgments
Recognises when something feels wrong
Chooses direction when trade-offs arise
Dreams futures the AI cannot imagine

The AI:

Executes implementation within constraints
Guards scope and flags deviations
Detects spaghettification signals
Maintains consistency with established patterns
Synthesises understanding during regeneration

The AI does not dream. It interpolates. It gravitates toward the statistical centre of its training data. Novel architectures, distinctive designs, and opinionated choices must come from humans.

But humans are fallible. They get bored. They take shortcuts. They expand scope opportunistically. The AI provides discipline: holding boundaries, asking clarifying questions, refusing to silently drift.

Neither is sufficient alone.
Together, they compound.

Specs Are Snapshots, Not Contracts

Specifications capture understanding at a moment in time. Code becomes the source of truth. Periodically, understanding must be extracted back out.

This is the foundational insight of SRDD.

Traditional spec-driven development treats specifications as authoritative: write the spec, generate the code, update the spec when requirements change. In practice, this breaks down. Code evolves faster than documentation. Implicit behaviours emerge. The spec becomes fiction.

SRDD inverts the relationship. Specs are inputs to a cycle, not outputs of a process. They capture intent at the start. But as implementation proceeds, the code becomes the real source of truth - informed by production discoveries, implicit contracts, and decisions made under pressure.

The roundtrip is what makes SRDD sustainable:

Specs guide initial implementation
Implementation reveals what specs missed
Production surfaces implicit contracts
Regeneration extracts new specs from living code
The cycle repeats with compounded understanding

Without the roundtrip, specs drift into irrelevance. With it, understanding compounds instead of decaying.

Motion-induced visual illusion

Velocity Follows Clarity

Fast development is not the cause of good systems. It is the consequence of clear ones.

Teams do not ship slowly because they lack skill. They ship slowly because they lack confidence. Confidence erodes when:

No one is sure what a change might break
Boundaries have blurred beyond recognition
Patterns contradict each other
Tests defend structure rather than contracts
Tribal knowledge has replaced explicit understanding

SRDD addresses velocity by addressing clarity. Regeneration restores architectural coherence. Contracts make guarantees explicit. Pattern hygiene ensures the AI produces consistent output. Guardrails prevent drift from entering.

The result is not just a cleaner codebase. It is a faster one - because developers (and AI) can act with confidence instead of caution.

Speed is earned, not demanded.

Summary

Principle	Core Insight
Designing for AI Comprehension	The codebase teaches the AI what to repeat
Guardrails Beyond Tests	Prevent bad patterns earlier than review
Encode Judgment, Don't Just Document It	Structure enforces; documentation explains
Coherence Over Correctness	Fit matters more than function
The Developer Dreams, The AI Disciplines	Humans choose direction; machines maintain consistency
Specs Are Snapshots, Not Contracts	Understanding must roundtrip back from code
Velocity Follows Clarity	Confidence enables speed

These principles are not optional.

SRDD's phases, guardrails, and regeneration cycles exist to enforce them - or surface it clearly when they're being violated.

Implementation

SRDD is currently a methodology, not a product. This section describes what exists today, what's planned, and what reliable enforcement will require.

Current Status

Component	Status	Notes
Methodology documentation	✅ Available	SRDD.md, SCALED-SRDD.md
Planning doc templates	✅ Available	00-07 document templates
Rules file examples	✅ Available	CLAUDE.md templates for SRDD workflow
Scope enforcement tooling	🔲 Planned	Pre-commit hooks, MCP integration
Coherence validation	🔲 Planned	Pattern comparison against ARCHITECTURE.md
Regeneration advisor	🔲 Planned	Cross-session signal tracking
SSRDD coordination layer	🔲 Planned	Multi-subsystem orchestration

The methodology can be adopted today using documentation and rules alone. Teams will capture significant value - better than vibe coding, better than undisciplined agentic work. But reliable enforcement of scope guarding, coherence review, and regeneration detection will require tooling that does not yet exist.

SRDD Implementation

What works with rules alone:

TDD workflow: AI follows this well with clear instructions
PR description format: templatable, AI complies
Communication protocols: "ask before expanding scope" works reasonably
Phase awareness: AI can be reminded which phase it's in
Pattern following: works if good examples exist in the codebase

What needs tooling for reliable enforcement:

Scope enforcement: Pre-commit hooks or CI checks that validate files changed against declared issue scope. AI self-discipline is insufficient; hard blocks are required.
Coherence validation: CLI or MCP server that compares implementation against ARCHITECTURE.md patterns. Generates structured report for human review. Could integrate with PR process.
Pattern drift detection: Static analysis that scores conformance against canonical patterns. Custom linter rules or dedicated tool. Runs in CI, blocks on threshold violations.
Regeneration advisor: Tracks signals across sessions: contract change frequency, scope expansion requests, pattern drift indicators. Surfaces recommendations: "3 significant contract changes in 2 weeks - consider regeneration." Cannot rely on AI memory alone.

Planned tooling:

The table below outlines planned tooling that reinforces SRDD practices; the methodology already works today using rules files and process discipline, which cover roughly 60% of the model.

Command	Purpose
`srdd check`	Validate current state against methodology
`srdd review-coherence`	Compare implementation against ARCHITECTURE.md
`srdd regeneration-status`	Surface signals that suggest regeneration

MCP server integration for real-time checking within Claude Code, Cursor, and similar tools is a longer-term goal. This would make SRDD workflows smoother - the AI checks scope, patterns, and coherence before acting, rather than failing at commit or review. True enforcement still requires hard blocks at git and CI layers; MCP advises, it does not prevent.

Adoption without tooling:

Teams can adopt SRDD today by:

Using the planning doc templates (00-07)
Adding SRDD rules to their AI configuration (CLAUDE.md, .cursorrules, etc.)
Following the phase workflow manually
Relying on human review for coherence and scope discipline

This delivers 60-70% of the value. The remaining 30-40% - reliable enforcement without human vigilance - awaits tooling.

implementing a management software solution

SSRDD Implementation

SSRDD wraps multiple SRDD instances with a coordination layer. Each subsystem runs its own SRDD cycle; SSRDD governs the boundaries between them.

Additional components required:

CONSTITUTION.md enforcement: Validation that subsystem contracts conform to system-wide standards. Not just documentation; automated checks.
Cross-subsystem dependency tracking: Visibility into which subsystems depend on which contracts. Change impact analysis before regeneration.
Coordinated regeneration: When one subsystem regenerates, affected subsystems are notified. Integration contracts are re-validated. Cascade effects are surfaced, not hidden.
System-wide coherence dashboard: Aggregates health signals across subsystems. Pattern drift in subsystem A, contract churn in subsystem B, integration test failures between C and D - visible in one place.

Current status:

SSRDD is documented as methodology. No tooling exists. Adoption today requires:

Manual coordination between subsystem teams
Disciplined maintenance of CONSTITUTION.md
Human tracking of cross-subsystem dependencies
Scheduled integration checkpoints

This is workable for small numbers of subsystems (2-4) with disciplined teams. Beyond that, tooling becomes essential.

Planned approach:

SSRDD tooling will build on SRDD tooling:

Command	Purpose
`ssrdd status`	Health across all subsystems
`ssrdd check-constitution`	Validate subsystem compliance
`ssrdd impact-analysis <change>`	What subsystems are affected?
`ssrdd coordinate-regeneration`	Orchestrate multi-subsystem realignment

Timeline: SRDD tooling first, SSRDD coordination layer second.

Roadmap

Alignment with Agile and SAFe:
SRDD is designed to complement, not replace, existing delivery frameworks. Future documentation will map SRDD phases to Agile ceremonies and SAFe constructs - showing how regeneration fits into PI planning, how Phase 5 triage aligns with backlog refinement, and how SSRDD coordinates across Agile Release Trains.

Rules file templates:
Complete CLAUDE.md, .cursorrules, and copilot-instructions.md templates that encode SRDD workflow, scope guarding, and pattern-following behaviour. Ready to drop into any project.

MCP server integration:
Real-time SRDD enforcement within Claude Code, Cursor, and similar tools. The AI checks scope, patterns, and coherence before acting. True enforcement still requires git and CI layers; MCP advises and surfaces signals continuously.

Kubernetes and container orchestration:
SSRDD's domain model maps naturally to microservices architectures. Future work will explore how SSRDD boundaries align with Kubernetes namespaces, how CONSTITUTION.md standards translate to service mesh policies, and how coordinated regeneration integrates with deployment pipelines. The goal is SSRDD as a design-time discipline that produces systems well-suited to container orchestration - not as an afterthought, but by construction.

Contribute to Drupal

Contributing

SRDD and SSRDD are open methodologies. The documentation, templates, and (eventually) tooling will be available for community use and contribution.

If you're interested in contributing to the tooling effort, or adopting SRDD in your organisation and sharing learnings, [contact information / repository link].

Closing

Vibe coding, agentic coding, context engineering, spec-driven development - each optimises for something real. Speed. Autonomy. Discipline. Traceability. None of them are wrong. But none of them close the loop.

Vibe coding forgets. Agentic coding echoes. Context engineering curates inputs but not outputs. Spec-driven development treats specifications as authoritative even as reality drifts away from them.

SRDD closes the loop.

What SRDD Enforces

The roundtrip is the methodology.
Specifications flow into implementation. Understanding flows back out through regeneration. This is not a rescue operation - it is a planned phase in the system's lifecycle.

Specs are snapshots, not contracts.
Specifications capture understanding at a point in time. Code becomes the source of truth. Periodically, understanding is extracted back out.

The codebase is a curriculum.
The AI learns from your existing code. Every pattern teaches it what to repeat. Contradictions breed confusion; consistency compounds velocity.

Guardrails encode judgment structurally.
Types, linters, schemas, and folder boundaries prevent bad patterns before review. Documentation explains; structure enforces.

Coherence matters more than correctness.
The AI determines whether code works. The reviewer determines whether it fits. Correct code that violates patterns degrades the system.

The developer dreams; the AI disciplines.
Humans choose direction, make architectural judgments, and recognise when something feels wrong. The AI executes, guards scope, and maintains consistency.

Velocity follows clarity.
Fast development is not the cause of good systems. It is the consequence of clear ones. Confidence enables speed.

At Scale

SSRDD extends these principles across domains:

Boundaries become explicit
Dependencies become intentional
Domains evolve independently without silent entanglement
Understanding scales - not bureaucracy

The Core Commitment

Every senior developer has stared at a system they once understood and thought: "If only I could burn this down and rebuild it properly - keeping everything we learned, but losing the accumulated mess."

SRDD makes that possible.

Specs deserve a return ticket
Boundaries deserve enforcement
Judgment deserves to be structural
Understanding deserves to survive

AI accelerates everything, including mistakes. SRDD exists to make learning faster than decay.

The Complete Series

Part 1: Why SRDD Exists - The problem, the journey, the insight
Part 2: The AI Coding Landscape - Vibe coding, agentic coding, context engineering, SDD
Part 3: The SRDD Workflow - Phases, contracts, regeneration
Part 4: Scaling Up - SSRDD, principles, implementation (this article)

This document constitutes a public disclosure and defensive publication of the
Spec-Roundtrip Driven Development (SRDD) and Scaled SRDD (SSRDD) methodologies.

The author expressly places the concepts, processes, and workflows described
herein into the public domain as prior art, for the purpose of preventing
subsequent patent claims or exclusive ownership by third parties.

Commercial use, redistribution, or derivative works of this text require
explicit permission from the author.

SRDD (Part 3 of 4) - The SRDD Workflow

Brooke — Tue, 06 Jan 2026 23:35:19 +0000

SRDD (Part 3 of 4): The SRDD Workflow

← Back to SRDD entry page

This is Part 3 of a four-part series on Spec-Roundtrip Driven Development.

👉 Read Part 1: Why SRDD Exists
👉 Read Part 2: The AI Coding Landscape

Part 2 mapped the AI coding landscape - vibe coding, agentic coding, context engineering, and spec-driven development - and showed where each approach predictably breaks down.

This article is the technical core: the five phases of SRDD, how contracts govern change, what the AI is responsible for during implementation, and how regeneration closes the loop between intent and reality.

Some might like this missing loop

SRDD: The Missing Loop

Spec-Roundtrip Driven Development (SRDD) is a development methodology designed for AI-assisted systems that must evolve over time without losing coherence, intent, or professional judgment. It was created in response to a recurring failure mode across modern AI coding approaches: understanding flows in one direction, while systems grow in another.

In SRDD, specifications, code, tests, and operational reality form a closed loop. Specs inform implementation, implementation reshapes understanding, and that understanding is periodically captured back into renewed specifications. The system is not treated as something to be generated once and maintained defensively, but as something to be actively developed - with intent revisited, designs refined, and direction reasserted as the system grows.

Spec-Roundtrip Driven Development (SRDD) retains the strengths of earlier approaches while removing their most damaging assumptions.

It deliberately keeps:

The structure of specs

SRDD preserves structured specifications as a working medium for intent. Requirements, use cases, architectural boundaries, and test strategies are still articulated explicitly. Specs remain the place where understanding is shaped, challenged, and communicated - not abandoned once code exists. They provide the map from which development proceeds.
The speed of AI

SRDD fully embraces AI-assisted execution. Generation, refactoring, test scaffolding, and repetitive work are delegated aggressively. The AI accelerates implementation, shortens feedback loops, and keeps momentum high. Humans are freed to make directional decisions rather than fight mechanics.
The adaptability of iteration

SRDD remains unapologetically iterative, but iteration is not aimless. Each cycle is guided by intent and expressed through deliberate development. Features are not merely discovered; they are designed, implemented, reviewed, and extended in response to real use. Assumptions are corrected, designs are refined, and capabilities are intentionally built out over time.

The system is not simply allowed to change.

It is actively developed.

AI accelerates the mechanics of that development, but humans retain control over direction, scope, and shape. Each cycle ensures that what is built next is informed by what already exists - without being constrained by it.

But SRDD draws a hard line at one assumption.

It rejects the idea that specs are contracts.

Specs are not promises to be enforced against the future. They are snapshots of current understanding, taken so that the next step can be chosen deliberately. When reality diverges - as it inevitably does - SRDD does not force the system back into compliance with an outdated document. Instead, the spec is regenerated from the living system, then actively edited to reflect what the system should become next.

Regeneration is not acceptance of the system as it is. It is not a rationalisation of accumulated technical debt, nor a quiet agreement to live with architectural drift because it has become inconvenient to confront.

It is re-orientation.

SRDD begins by accepting reality as evidence: the code that exists, the behaviour that ships, the tests that pass, and the shortcuts that were taken. Technical debt is acknowledged explicitly, not hidden behind compliance or deferred indefinitely. The system is recognised as broken where it is broken.

But SRDD refuses a more dangerous form of acceptance - the kind where debt becomes destiny.

Instead, regeneration reasserts intent. The system is deliberately pointed somewhere new, informed by everything that has been learned along the way. Decisions that once lived only as tribal knowledge - why a trade-off was made, why a shortcut was tolerated, why a boundary eroded - are surfaced, articulated, and captured in the regenerated spec.

What emerges is not a justification of the present system, but a clarified foundation for what comes next.

The regenerated spec becomes a renewed point of control - a place where technical debt is made visible, tribal knowledge is externalised, and direction is chosen consciously rather than inherited accidentally. Structure is preserved. Direction is reasserted. Progress continues with better footing than before.

SRDD does not eliminate structure. It makes structure responsive.

That roundtrip is the core innovation.

Best practices: how to develop with auditability

A note on SRDD and auditability

It is worth pausing here to be explicit about how SRDD relates to the core strength of Spec-Driven Development.

One of the primary reasons SDD exists at all is auditability. By forcing early formalisation and maintaining tight synchronisation between specification and implementation, SDD produces systems where intent, design, code, and change history can be traced with near-forensic precision. That discipline is not incidental - it is the point. In regulated and safety-critical environments, the cost of Big Design Up Front is accepted because the resulting guarantees are required.

SRDD does not attempt to replicate that level of certainty.

Instead, it offers a different - and deliberately weaker - form of auditability.

Where SDD proves correctness through prior formalisation, SRDD produces evidence through evolution. Each regeneration cycle preserves lineage: original intent, implemented reality, subsequent redesign. What remains consistent across regenerations demonstrates stability. What changes documents learning. Technical debt is surfaced rather than concealed, and tribal knowledge is progressively externalised into planning artefacts instead of remaining implicit in code or conversations.

The system is not certified as never wrong in advance.
It is traceable in how it became right over time.

This distinction matters. SRDD trades absolute guarantees for adaptability, but it does not abandon accountability. It replaces compliance-driven certainty with historically grounded transparency - sufficient for most software systems, even if it falls short of SDD’s strongest claims.

Workflow diagram showing the phases of SRDD

The SRDD Workflow

Phase 1: Design

Phase 1 establishes intent. It is where understanding is shaped, clarified, and made explicit before implementation hardens around it.

In an initial build, Phase 1 starts from a blank slate.
In subsequent iterations or regeneration cycles, it is informed by everything learned since the last design - including production evidence captured in 07-NextCycle.md.

docs/plans/2025-12-15_v1_initial-design/
  00-PLANNING.md       ← Initial brain dump from requirements questionnaire
  01-REQUIREMENTS.md   ← Refined functional and non-functional requirements
  02-USECASES.md       ← User stories with acceptance criteria
  03-QA-SESSION.md     ← Q&A transcript clarifying ambiguities
  04-ARCHITECTURE.md   ← Technical design, components, data model
  05-IMPLEMENTATION.md ← Phased plan: what gets built in what order
  06-TESTPLAN.md       ← Test strategy and test data requirements
  07-NextCycle.md      ← Placeholder for production discoveries and future intent

When Phase 1 is entered as part of a regeneration cycle, the 07-NextCycle.md artefact is treated as an explicit input:

This document captures production discoveries, unresolved tensions, candidate contracts, and signals of architectural drift. It does not prescribe solutions - it informs what must be reconsidered.

00-PLANNING.md

00-PLANNING.md captures the initial brain dump.

Using a structured questionnaire, the developer and AI work through the problem space: what is being solved, who has the problem, why now, and what constraints exist. In regeneration cycles, this document also reflects on what the system has become - including shortcuts taken, assumptions invalidated, and lessons learned.

This document is deliberately rough. Its purpose is breadth, not precision. Everything goes on the table before refinement begins.

01-REQUIREMENTS.md

01-REQUIREMENTS.md distils the planning document into formal requirements.

Functional requirements describe what the system must do. Non-functional requirements capture performance, security, reliability, scalability, and operational constraints. MoSCoW prioritisation happens here: must have, should have, could have, won't have.

In regeneration cycles, requirements may be:

reaffirmed
modified
retired
or newly introduced based on production evidence

This makes change explicit rather than accidental.

02-USECASES.md

02-USECASES.md translates requirements into concrete user stories with acceptance criteria.

Each use case follows a consistent structure:

As a [role]
I want [capability]
So that [benefit]

Acceptance criteria define what "done" means in observable terms. These criteria become the authoritative source for functional and integration tests in later phases.

Importantly, use cases are not written during production. They are derived deliberately here - often directly from discoveries captured in 07-NextCycle.md.

03-QA-SESSION.md

03-QA-SESSION.md preserves the conversation.

As the AI generates and refines the preceding documents, questions naturally arise: edge cases, ambiguities, unstated assumptions, conflicting goals. This transcript captures the back-and-forth - including corrections, disagreements, and rationale.

This document exists to preserve decision context, not to enforce outcomes. It becomes invaluable during regeneration, when past intent must be re-understood rather than re-imagined.

04-ARCHITECTURE.md

04-ARCHITECTURE.md defines the technical approach.

It documents:

component boundaries
data models
API surfaces
integration patterns
technology choices and constraints

This is where professional architectural judgment matters most. The goal is not novelty, but coherence - ensuring the AI does not default to generic or statistically common patterns that are misaligned with the system's actual needs.

Canonical patterns are established here: Decisions about how the system handles logging, error handling, configuration, and other cross-cutting concerns should be explicit. These patterns become what the AI will replicate throughout implementation. Contradictions introduced later are harder to correct than conventions established early.

See: Principles → Designing for AI Comprehension

05-IMPLEMENTATION.md

05-IMPLEMENTATION.md breaks the work into phases.

What is built first? What depends on what? What can safely be deferred?

This document informs issue creation, but the backlog remains intentionally lean. Only a small number of high-level issues are created initially. Additional issues emerge organically as understanding deepens.

Momentum is preserved by keeping the queue short.

06-TESTPLAN.md

06-TESTPLAN.md defines the testing strategy across all layers:

unit
integration
functional

It clarifies what each layer is responsible for, what constitutes a contract, and what data is required to exercise the system meaningfully. It also specifies how test data will be generated or sourced.

Tests are not written here - but the authority and scope of tests is.

07-NextCycle.md

07-NextCycle.md is created during Phase 1 but intentionally left empty.

It exists to establish a forward-looking capture point for discoveries that cannot be known at design time. This document is populated only after a production release, when real usage surfaces new expectations, implicit contracts, and architectural tensions.

During Phase 4 (Production), findings from UAT are recorded here:

newly discovered behaviours users rely on
candidate contracts not previously specified
rejected expectations (explicitly documented)
signals of architectural strain or drift
inputs that may justify iteration or regeneration

No implementation occurs at this stage.
07-NextCycle.md records evidence and intent - not solutions.

During the next SRDD cycle, this document becomes a primary input to Phase 1, informing updates to requirements, use cases, and architecture. In regeneration cycles, it plays a critical role in re-establishing direction without losing historical context.

This ensures that production learning is preserved deliberately rather than absorbed accidentally.

07-NextCycle.md does not answer questions.
It creates the conditions for better ones.

When the next SRDD cycle begins, the AI and developer return to Phase 1 with sharper evidence, clearer tensions, and fewer assumptions carried forward by habit alone. Misunderstandings are corrected earlier. Trade-offs are re-examined explicitly. Intent is reasserted before code is touched again.

The backlog stays intentionally lean.
Understanding compounds instead of drifting.

Phase 2: Implementation

Each issue in SRDD is implemented through a strict test-first loop:

failing test ↔ implement → pass

This is not TDD as a ritual. It is TDD as a boundary-enforcement mechanism.

SRDD does not use tests to maximise coverage or satisfy process doctrine. Tests exist to enforce boundaries: to make explicit what the system is committing to, and to protect those commitments as change occurs. They define where stability is mandatory and where evolution is permitted.

TDD here is not about proving correctness in isolation. It is about protecting intent under change. Writing tests first forces an explicit declaration of what is being guaranteed before implementation choices harden around it. Accidental commitments are prevented; deliberate ones are made visible.

When a test fails, the question is never "How do we fix the test?" It is "Did we violate a boundary, or did we intentionally choose to move it?"

This reframes testing from verification to governance. The test suite becomes a living record of the system's contractual surface, enforcing discipline at the edges while leaving the interior free to evolve.

Contracts as the Source of Authority

In SRDD, contracts are authoritative.

A contract is anything that external systems, users, or adjacent components depend on remaining stable unless explicitly versioned:

Public APIs (request/response shapes, error semantics)
UI behaviours and interaction guarantees
Domain events and their payloads
Invariants (idempotency, ordering guarantees, security constraints)
Observable side effects (persistence, notifications, integrations)

These contracts define what must not change.

They are not informal expectations - they are deliberate commitments.

Tests as Executable Witnesses

Tests are not the source of authority; they are its executable witnesses.

Each contract is encoded as one or more tests that demonstrate:

What behaviour is guaranteed
Under which conditions it holds
What constitutes a breaking change

In short:

Contracts define intent.

Tests prove that intent still holds.

If a test fails, SRDD assumes one of only two possibilities:

The implementation violated a contract
The contract itself must be deliberately changed (and versioned)

There is no third option.

When Contracts Change

When contracts keep shifting, or each change exposes deeper misalignment, the system is telling you something: boundaries were drawn in the wrong place, responsibilities are unclear, or requirements were not understood well enough.

The AI is responsible for capturing these signals as they occur. Each significant contract change - and its context - is logged immediately in 07-NextCycle.md. This is not a fix; it is evidence. The document accumulates observations: what changed, why, what it affected, and what tension it revealed.

As signals accumulate, the AI periodically reviews the list. When the pattern becomes clear - repeated boundary violations, cascading impacts, foundational assumptions proving wrong - it advises regeneration:

"07-NextCycle.md now contains five significant contract changes in three weeks, three of which affected the same boundary. This suggests architectural misalignment. I recommend returning to Phase 1."

The developer makes the final call, but the recommendation is backed by documented evidence, not AI intuition. The decision to regenerate becomes traceable.

In short:

Minor contract change → new issue, normal flow
Significant contract change → new issue, log signal in 07-NextCycle.md
Accumulated signals show pattern → AI advises regeneration, evidence already captured, return to Phase 1

Define Roles & Responsibilities

Layered Tests, Distinct Responsibilities

SRDD adopts the well-established practice of layered testing - not to duplicate coverage, but to assign jurisdiction.

Authority, in this context, means contractual weight - how strongly a test's failure signals a violated guarantee, and how much scrutiny is required before that test can be changed. High-authority tests encode promises the system makes to the outside world. Changing them is changing the contract. Low-authority tests are internal scaffolding - useful for development velocity, but disposable without consequence.

Unit tests

Validate local logic and edge cases
Optimise developer velocity
Free to change, split, or disappear
Carry no contractual authority

Integration tests

Validate service boundaries and data flows
Encode API behaviour, persistence semantics, and error handling
Medium authority

Functional / contract tests

Encode user-visible or system-visible guarantees
Represent APIs, UI flows, events, and invariants
Must not change without explicit intent
Highest authority

Internal structure - classes, modules, helpers, private methods - is intentionally not protected by tests unless it expresses a contract.

This is a feature, not a limitation.

Internal Freedom, External Stability

This is standard software engineering - and SRDD respects it.

Outside the contract: stability is mandatory
Inside the boundary: evolution is encouraged

Refactors, restructures, and architectural shifts are allowed - even expected - as long as contractual tests continue to pass.

The principle resolves a long-standing tension in software design: private methods remain private, cohesion is preserved, and test suites do not calcify internal structure. Velocity is maintained without eroding guarantees.

The system becomes stable where it must be, and fluid where it can be.

SRDD does not claim to invent this. It simply refuses to abandon it - even when AI-assisted velocity tempts teams to blur boundaries or lock down internals defensively.

The AI as Scope Guardian

During implementation, the AI plays a non-negotiable role: scope guardian.

Its responsibilities include:

Preventing feature creep within an issue
Detecting when a proposed change alters a contract
Asking explicit questions when a boundary is crossed: > "This change affects a public API. Should this be versioned?"
Offering to create new issues for out-of-scope ideas
Refusing to silently "just add one more thing"

These roles are not aspirational - they can be enforced today through rules files, test discipline, and review structure, with future tooling improving what these already provide.

This matters because AI-assisted development amplifies opportunism.

When implementation becomes cheap, fast, and frictionless, the cost of just adding one more thing collapses. Ideas that would normally be deferred - "while we're here", "it's only a small change", "we can tidy this up later" - are acted on immediately. The AI does not push back. It does not feel scope creep. It executes.

Developers recognise this instinct instantly. A feature almost works, so you extend it slightly. A function is already open, so you add a parameter. A test is failing nearby, so you broaden its responsibility. None of these decisions are irrational in isolation. In aggregate, they erode boundaries.

AI accelerates this dynamic. What used to take minutes now takes seconds. What once required intent now happens by momentum. The system drifts not because of negligence, but because the path of least resistance becomes irresistible.

SRDD treats this not as a moral failing, but as a structural risk.

By enforcing issue boundaries and making the AI explicitly responsible for guarding scope, SRDD introduces friction where it matters most. The AI is required to ask: "Is this still the same commitment?" If not, it offers to create a new issue, defer the change, or force an explicit decision.

This restores a discipline that velocity quietly erodes: the habit of choosing what not to do next.

SRDD deliberately counters that by enforcing discipline at the issue boundary.

The AI as Pattern Follower

The AI has a second responsibility during implementation: following established patterns.

Canonical patterns - for logging, error handling, configuration, naming, and other cross-cutting concerns - are defined in 04-ARCHITECTURE.md. The AI should replicate these patterns, not invent alternatives.

But the AI cannot reliably enforce its own adherence. Pattern conformance requires layered defence:

Good examples in the codebase: the AI pattern-matches on what exists
Rules files: explicit instructions that shape generation (CLAUDE.md, .cursorrules, copilot-instructions.md, or whatever your tooling supports)
Linters and static analysis: automated rejection of non-conforming code
CI checks: build failures that prevent violations from merging
Human review in Phase 3: coherence review catches what tooling misses

When the AI deviates from an established pattern, correct it immediately. Deviations that slip through become examples the AI will repeat. The codebase teaches by demonstration; every inconsistency introduced is an inconsistency that will propagate. The same applies to hallucinations and contrived solutions - an invented API that gets merged becomes a pattern the AI treats as real; a workaround that should have been questioned becomes the template for future workarounds.

This means:

If the project uses a specific logging approach, the AI uses that approach
If error handling follows a defined structure, new errors follow the same structure
If naming conventions exist, new code matches them

Prefer explicit, well-named abstractions. logAuditEvent() is better than log(). fetchUserById() is better than getUser(). Names that reveal intent help both humans and AI understand what "right" looks like.

Pattern deviation is not a moral failing - it is a signal. It may indicate:

The AI lacks sufficient context (add to rules or provide examples)
The established pattern is unclear (clarify in ARCHITECTURE.md)
The guardrails are insufficient (add linter rules or CI checks)
The pattern itself needs revision (make this explicit, not accidental)

See: Principles → Designing for AI Comprehension

Phase 3: Review

Pull requests are not just a delivery mechanism in SRDD; they are a decision record.

Every PR captures a moment where intent met reality. In many cases, it records trade-offs: alternatives that were considered or rejected, constraints that surfaced late, or shortcuts that were consciously tolerated. These decisions are often too contextual, too situational, or too nuanced to justify formal documentation at the time - but they matter later.

In other cases, the PR is far more explicit. It may be the moment where a contract is defined, tightened, or deliberately changed. An API boundary is clarified. A behavioural guarantee is enforced through a new test. A breaking change is versioned rather than smuggled through. In these moments, the PR is not just descriptive - it is constitutive. It establishes what the system now promises.

Whether implicit or explicit, the PR marks the point at which uncertainty becomes commitment.

PRs preserve this context implicitly:

Why a boundary was moved or reinforced
Why a shortcut was accepted - or explicitly rejected
Why an interface took its current shape
Why a test defines a guarantee broadly rather than narrowly

The review conversation, commit history, and diff together form a lightweight narrative of how the system actually evolved - not how it was originally imagined.

This history becomes critical during regeneration. When the AI synthesises a new spec from the living system, PRs provide the missing "why" that code alone cannot explain. They surface intent that was never formalised, constraints that were discovered late, and decisions that lived temporarily in human judgment.

Without this trail, regeneration risks erasing hard-won knowledge. With it, SRDD can distinguish between accidental drift and deliberate adaptation.

PRs do not just close issues.
They preserve reasoning.

That preservation is what allows understanding to compound rather than reset between cycles.

Review for Coherence, Not Just Correctness

The AI can determine whether code works. That is not the reviewer's primary concern.

The reviewer's responsibility is to assess whether the code fits - whether it coheres with the system's architecture, follows established patterns, and avoids introducing long-term complexity.

The AI can assist with this review. It can flag potential boundary violations, compare implementations against ARCHITECTURE.md patterns, identify naming inconsistencies, and detect changes to public APIs. Use the AI as a first pass.

But the human reviewer holds final authority. Review for:

Architectural coherence: Does this change respect existing boundaries? Does it introduce new dependencies that weren't discussed? The AI can flag these; the human decides if they're acceptable.
Pattern conformance: Does the implementation follow canonical patterns, or has the AI introduced a variation? The AI can compare; the human judges whether deviation is drift or improvement.
Naming and abstraction: Are new functions, classes, and modules named in ways that reveal intent? The AI can check consistency; the human assesses whether names actually clarify.
Contractual impact: Does this change affect a public API, event, or guarantee? The AI can detect changes mechanically; the human decides if the change is intentional and appropriate.

Correctness is necessary but insufficient. A PR can pass all tests - and all AI checks - and still degrade the system's coherence. The human reviewer is the last line of defence against pattern drift, and the only one who can say "this is correct but wrong."

If the AI has deviated from an established pattern, this is the moment to catch it. Every deviation that merges becomes an example the AI will follow next time.

See: Principles → Designing for AI Comprehension

Capturing Signals

Review can surface two kinds of observations:

Blocking issues are problems that must be resolved before the PR can merge. These are captured as PR review comments — not in 07-NextCycle.md. The PR returns to Phase 2 for revision, focused specifically on addressing the review feedback. Once resolved, it returns to Phase 3 for re-review. This is the standard review loop:

Phase 2 (Implement) → Phase 3 (Review) → Blocking issue found
                           ↓
                      PR comments
                           ↓
            Phase 2 (Revise) → Phase 3 (Re-review) → ...

Non-blocking signals are observations that don't prevent the PR from merging but inform future work. These are captured in 07-NextCycle.md. They are implementation signals — patterns or tensions visible in the code that may not warrant immediate action but should influence future decisions:

Patterns showing strain or becoming awkward
Boundaries that feel wrong or artificially placed
Dependencies heavier or more entangled than expected
Modules that want to split or merge
Abstractions that aren't earning their complexity
Emerging candidates for refactoring

These signals are distinct from the production signals captured in Phase 4 (UAT). Implementation signals come from reading and reviewing code; production signals come from observing the system under real conditions. Both feed into regeneration decisions, but they represent different kinds of evidence.

Not every PR generates signals. Many are clean implementations that fit well. But when something feels off — even if it doesn't block approval — capture it. The pattern may become clearer over time.

Continue or Advance?

After each PR merges, the cycle either continues or advances:

More issues in the current cycle?
Return to Phase 2. Select the next issue from the backlog, implement, and return to Phase 3 for review.

Cycle complete?
Advance to Phase 4 (UAT). The implemented functionality is ready for validation against reality.

What constitutes "cycle complete" depends on team workflow:

Time-boxed (Agile sprint): The sprint ends. Completed work advances to UAT; incomplete issues return to the backlog. Phase 4 aligns with Sprint Review.
Scope-boxed (milestone): A defined set of issues constitutes a coherent deliverable. When all are done, the milestone advances to UAT.
Hybrid: Core functionality must complete before advancing. Nice-to-have scope can carry over to the next cycle.

The key criterion: Is there enough implemented functionality to validate against reality?

SRDD does not prescribe which model to use — that is an organisational choice. But the decision point must be explicit. Drifting into UAT without conscious commitment invites incomplete validation and blurred accountability.

Phase 4: UAT (Observe and Accumulate)

UAT is where SRDD validates intent against reality.

This phase is not treated as the end of development, but as the moment when assumptions are finally exposed to real conditions. The system is exercised using real data, real permissions, real workflows, and real constraints - not sanitised environments optimised to pass automated checks.

Automated tests have already established correctness. UAT exists to establish fitness.

A Deliberate Confrontation with Reality

In SRDD, UAT is not a ceremonial sign-off. It is evidence gathering.

UAT asks a different question from tests:

Does the system behave acceptably in the world it actually inhabits?

This is where qualitative judgment enters the loop. Performance may meet metrics but still feel slow. A workflow may be logically correct but cognitively awkward. An edge case may be rare but unacceptable. These are not failures of correctness; they are failures of fit.

SRDD treats this feedback as first-class evidence - but does not act on it during this phase.

Accumulate, Don't Fix

Every finding during UAT is captured in 07-NextCycle.md:

Bugs and defects
Minor issues and rough edges
Implicit contracts discovered through use
Architectural tensions revealed under real conditions
Performance concerns
User feedback and behavioural expectations

No fixes are made. No issues are created in the backlog. No code changes.

This is deliberate. Phase 4 is observation. The decision about what to do with these findings belongs to Phase 5.

Each entry in 07-NextCycle.md captures:

What was observed
The context (user, workflow, data conditions)
Whether it appears to be a bug, a missing contract, or an architectural signal
Any relevant evidence (logs, screenshots, user quotes)

The document accumulates throughout UAT. It becomes the input to triage.

Making Implicit Contracts Visible

Crucially, UAT often reveals implicit contracts - behaviours users depend on that were never formally encoded. These are not traditional bugs. They are expectations that emerged through use rather than design.

The trigger is almost always human.

A user, product owner, or developer notices a behaviour and says some version of:

"Oh - actually, I expect this to do that."
"If this ever changed, it would break how I use it."
"We rely on this, even though it isn't documented."

SRDD treats these moments as signals, not interruptions.

At that point, the AI's role is not to infer intent, but to force clarification. It prompts a series of decisions:

Should this behaviour be guaranteed going forward?

If no, the rejection is captured deliberately in 07-NextCycle.md. The behaviour remains unsupported, and the system is free to change without preserving it. Future developers - and future AI sessions - will know the decision was conscious, not accidental.

If yes, the AI captures it as a candidate contract and clarifies its scope:

Context-specific or system-wide: Does this guarantee apply everywhere, or only under certain conditions?
Stable, versioned, or constrained: Should it never change, change only with explicit versioning, or be bounded by specific limits?

These answers are recorded in 07-NextCycle.md alongside the candidate contract - not as a bug to fix now, but as a guarantee to formalize in a future cycle.

In both cases, ambiguity is resolved consciously.
Nothing remains implicit by accident.

UAT as Evidence

UAT is therefore not a destination.
It is a source of evidence.

That evidence - accumulated in 07-NextCycle.md - feeds Phase 5, where the decision is made: iterate, regenerate, or release.

Phase 5: Triage and Decide

Phase 5 is the decision point.

After UAT, 07-NextCycle.md contains accumulated evidence: bugs, minor issues, implicit contracts, architectural signals, user feedback. Phase 5 analyzes this evidence and chooses the path forward.

This is not a formality. It is where SRDD's discipline pays off.

Categorizing Findings

The AI assists in categorizing accumulated findings:

Bugs and defects:
The system does not behave as specified. Tests should have caught this but didn't, or the condition wasn't anticipated. These require fixes.

Minor issues and rough edges:
The system works but could be better. Performance improvements, UX polish, small enhancements. These are iterative refinements.

Candidate contracts:
Implicit behaviours that users depend on, surfaced during UAT. These need to be formalized - either as guaranteed contracts or explicitly rejected.

Architectural signals:
Signs of deeper misalignment: repeated boundary violations, cascading changes, pattern drift, responsibilities in the wrong place. These suggest regeneration.

Watching for Spaghettification

As findings are reviewed, the AI actively looks for signs that the system's structure is beginning to degrade - not because of negligence, but because accumulated change has outpaced architectural clarity.

These signals are collectively referred to as spaghettification, and they tend to surface gradually:

Duplicated logic: Similar behaviour implemented in multiple places with slight variations
Circular dependencies: Components that cannot be reasoned about in isolation
Whack-a-mole regressions: Fixes in one area repeatedly break others
God modules: Classes or services that accumulate disproportionate responsibility, violating the Single Responsibility Principle
Velocity decay: Simple changes take longer than expected
Hedging language: Phrases like "this might break something" or "I'm not entirely sure"
Pattern inconsistency: The same concern (logging, error handling, configuration) implemented multiple ways across the codebase

None of these indicate failure.
They indicate misalignment between intent and structure.

Pattern inconsistency deserves particular attention. When the AI encounters contradictory examples, it cannot determine which is "right." It pattern-matches on whatever is in context - which may not be the canonical approach. This creates a feedback loop: inconsistency breeds inconsistency, accelerating drift.

The Decision

Based on the categorized findings and spaghettification signals, Phase 5 chooses one of three paths:

1. Phase 1 (Regenerate):
Architectural or contractual issues require a return to design. The accumulated signals show misalignment that patching cannot fix. Regeneration synthesizes fresh specs from the living system, and development resumes from a clarified foundation.

2. Phase 2 (Iterate):
Bugs, minor issues, or candidate contracts need to be addressed before release. Issues are created from the relevant findings in 07-NextCycle.md, and development continues through the standard implementation cycle.

6. Phase 6 (Production):
The system is ready to version and release. Findings are either minor enough to defer, or the accumulated evidence shows the system is fit for production. The decision moves to release.

                    ┌─────────────────────────┐
                    │      Phase 4: UAT       │
                    │   (Observe & Accumulate)│
                    └───────────┬─────────────┘
                                │
                                ▼
                    ┌─────────────────────────┐
                    │  Phase 5: Triage and    │
                    │        Decide           │
                    └───────────┬─────────────┘
                                │
            ┌───────────────────┼───────────────────┐
            │                   │                   │
            ▼                   ▼                   ▼
    ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
    │   Phase 1:    │   │   Phase 2:    │   │   Phase 6:    │
    │  Regenerate   │   │   Iterate     │   │  Production   │
    │(architectural)│   │ (bugs/minor)  │   │               │
    └───────────────┘   └───────────────┘   └───────────────┘

Advising Regeneration

When spaghettification signals accumulate, the AI does not attempt to quietly compensate with increasingly fragile fixes. Instead, it surfaces the pattern explicitly and advises regeneration.

This is not an automated action. It is a recommendation.

The AI explains what it is observing, why incremental change is becoming costly, and which parts of the system appear most affected. The decision to regenerate remains human.

"07-NextCycle.md contains five significant contract changes in three weeks, three of which affected the same boundary. Combined with the pattern drift in error handling and the circular dependency introduced last sprint, this suggests architectural misalignment. I recommend returning to Phase 1."

Regeneration is chosen when the cost of continued patching exceeds the cost of reorientation.

That choice is never trivial.

The Cost and Return of Regeneration

Regeneration is not cheap.

Depending on the size of the system, how long it has evolved since the last regeneration, and how far it has drifted from its original expectations, returning to feature parity can take days - sometimes weeks. That time is real cost. SRDD does not pretend otherwise.

What it offers in return is clarity.

The regenerated system is clean. Architectural intent is explicit again. Implicit requirements surfaced during UAT are captured as contracts and tests. Technical debt is no longer woven invisibly through the codebase; it is either resolved or consciously accepted.

Most importantly, velocity returns - and with it, confidence. Development after regeneration is faster, more predictable, and more satisfying. Changes no longer feel precarious. The system can once again be reasoned about as a whole.

For users, this translates into something tangible: continuous improvement without instability. Features ship rapidly. Bugs are fixed promptly. The system evolves visibly - yet it remains reliable. Users experience a product that gets better without breaking, that responds to feedback without regressing. This is only possible when the team behind it can move quickly with confidence, not despite its absence.

SRDD makes that sustainable.

The mechanics of regeneration - what the AI synthesizes and what it produces - are covered in detail in the following section: The Regeneration Cycle.

The Alternative

In large, long-lived systems - especially those built by many developers over time - architectural drift is rarely confronted head-on. Instead, it is managed defensively. Code becomes brittle. Knowledge fragments. Boundaries blur. Entire areas of the system acquire reputations: "Don't touch that," "No one really knows how this works," "It breaks if you look at it wrong."

Organisations attempt to compensate through process.

The only reliable way to prevent collapse in such systems is an increasingly onerous emphasis on exhaustive testing. Every change must be defended by more tests. Every edge case must be locked down. This is rational - but expensive.

Writing tests by hand is time-consuming, repetitive, and cognitively draining. It is rarely the work developers are motivated by, and often the first thing deferred under pressure. Over time, test suites grow unevenly: critical paths are over-tested, obscure behaviours remain implicit, and large areas of the codebase exist in a grey zone of partial coverage and collective anxiety.

The result is stagnation.

Code that developers are uncertain about is not improved. It is avoided. Bugs persist not because they are unsolvable, but because touching the surrounding code feels too risky. Architectural debt compounds quietly, protected by fear rather than intention. Velocity slows - not because the team lacks skill, but because confidence has eroded.

SRDD offers a different trade.

Rather than relying on ever-expanding defensive test suites to prop up brittle structure, SRDD periodically restores architectural clarity through regeneration. Tests remain essential - but they defend contracts, not accumulated uncertainty. The system is made comprehensible again, not merely survivable.

This is why regeneration, despite its cost, is often cheaper than the alternative.

A week of deliberate reorientation can replace months of hesitant change. A system that can be reasoned about invites improvement. A system that cannot eventually resists it.

SRDD does not promise perpetual cleanliness.
It promises the ability to recover it, intentionally and repeatedly, before brittleness becomes destiny.

Why This Works

SRDD does not treat architectural decay as a moral failing or a crisis. It treats it as a natural consequence of sustained progress - especially in systems that grow through real use, changing requirements, and multiple contributors.

By making regeneration an expected and supported move - rather than an admission of defeat - SRDD removes the stigma that causes teams to avoid structural correction. Refactoring stops being a desperate rescue operation performed under pressure and becomes a deliberate design activity undertaken with intent.

Iteration grows the system.
Regeneration realigns it.

Together, they prevent the slow hardening that turns living systems brittle. Boundaries remain intelligible. Confidence is preserved. Change remains possible even as systems scale in size, age, and ambition.

And perhaps most importantly, SRDD preserves the role of the developer.

As AI reshapes employment models and commoditises large portions of implementation work, developers remain valuable not because they type code, but because they invent, imagine, and choose direction. SRDD deliberately assigns mechanical execution to machines and reserves judgment, taste, and intent for humans. Developers are no longer paid to wrestle brittle systems or memorise tribal knowledge - they are paid to design futures, recognise when something feels wrong, and steer systems toward what they should become next.

In a world where AI can generate endlessly, SRDD ensures that humans still decide why, where, and whether.

Regeration cycle in plants

The Regeneration Cycle

This is the roundtrip.

Regeneration is the moment where SRDD closes the loop between intent and reality - not by rewinding time, but by rebuilding understanding.

It is a deliberate return to Phase 1, informed by everything that has been learned, and undertaken with full awareness of its cost.

What the AI Synthesizes

The AI re-synthesises a coherent picture of the system from multiple sources of truth:

the current codebase (what actually exists)
prior planning documents (what was intended at different points in time)
git history (how and when the system changed)
issues and tickets (what was discovered under pressure)
pull requests (why decisions were made)
the test suite (what is contractually protected)
07-NextCycle.md (accumulated signals, candidate contracts, and version history)

None of these sources is treated as authoritative in isolation. Each is partial, biased, and incomplete. Together, they form a layered record of how the system became what it is.

What the AI Produces

From this synthesis, the AI produces a new, dated planning directory - a refreshed set of artefacts that describe the system as it now stands, not as it was once imagined. This includes:

an updated model of the system's boundaries and responsibilities
an explicit account of preserved contracts
identified areas of architectural drift
accumulated technical debt, surfaced rather than rationalised
open questions and tensions that were previously implicit
what should be built next

This is not a rollback.
It is a reset of understanding - and a re-assertion of direction.

Holistic Diagnosis, Selective Intervention

A critical refinement of SRDD is that regeneration is holistic in diagnosis, selective in intervention.

The entire system is re-understood end-to-end. Dependencies are traced. Assumptions are re-examined. Interfaces are re-evaluated in light of real usage. Nothing is excluded from analysis.

But redesign is not applied indiscriminately.

Only subsystems that exhibit clear signs of drift - structural incoherence, brittle contracts, runaway complexity, or mismatched responsibilities - are candidates for redesign. Components that remain cohesive, well-bounded, and stable are explicitly left alone.

This matters.

Blanket rewrites destroy trust, erase hard-won learning, and reset momentum. SRDD avoids that trap by making non-intervention an explicit decision, not an accident. Stability is preserved where it has been earned.

Compounding Understanding

The outcome of regeneration is not just cleaner code.

It is compounded understanding.

Each regeneration captures:

why certain structures survived
why others failed
what trade-offs were real versus imagined
which constraints were fundamental and which were provisional

That understanding is externalised into artefacts that future humans - and future AI sessions - can reason from. Knowledge stops evaporating when developers leave, teams change, or time passes.

Instead of entropy winning by default, insight accumulates.

Iteration grows the system. Regeneration realigns it.

That is the roundtrip - and it is why SRDD scales not just across codebases, but across years.

where to next

What's Next

The workflow is the engine. But SRDD doesn't stop at single projects.

In Part 4, I cover:

How SRDD scales to multi-domain systems through Scaled SRDD (SSRDD)
The principles that underpin the methodology
The current state of implementation - what works today
The roadmap ahead - alignment with Agile and SAFe, rules file templates, and MCP server integration

Continue to Part 4:

👉 Scaling Up: SSRDD, Principles, and Implementation

Or return to earlier parts:

This document constitutes a public disclosure and defensive publication of the
Spec-Roundtrip Driven Development (SRDD) and Scaled SRDD (SSRDD) methodologies.

The author expressly places the concepts, processes, and workflows described
herein into the public domain as prior art, for the purpose of preventing
subsequent patent claims or exclusive ownership by third parties.

Commercial use, redistribution, or derivative works of this text require
explicit permission from the author.

SRDD (Part 2 of 4) - The AI Coding Landscape

Brooke — Tue, 06 Jan 2026 23:35:17 +0000

SRDD (Part 2 of 4): The AI Coding Landscape

← Back to SRDD entry page

This is Part 2 of a four-part series on Spec-Roundtrip Driven Development.
👉 Read Part 1: Why SRDD Exists

Teaching and learning with GenAI (Ohio University)

By mid-2025, it became clear that "AI coding" was no longer a single thing.

What began as playful experimentation had hardened into recognisable methodologies, each optimising for different trade-offs: speed versus coherence, autonomy versus understanding, structure versus adaptability.

There are now multiple serious approaches to AI-assisted development. This article breaks down the four most widely adopted - vibe coding, agentic coding, context engineering, and spec-driven development - examining where each shines, where each breaks, and how Spec-Roundtrip Driven Development (SRDD) (and its multi-domain extension, Scaled SRDD (SSRDD)) positions itself relative to them.

Why SRDD

SRDD draws from the strengths of each approach while addressing their predictable failure modes:

From vibe coding: rapid iteration, low ceremony, fast feedback
From agentic coding: goal-driven autonomy, multi-step task execution
From context engineering: disciplined curation of what the AI sees
From spec-driven development: architectural intentionality, explicit contracts, structured documentation

What distinguishes SRDD from all of these is the roundtrip: planned regeneration cycles that synthesise fresh specs from living code. Specifications are treated as snapshots, not contracts. Code evolves. Understanding must be periodically extracted back out - not as a rescue operation, but as a normal phase in the system's lifecycle.

This is what every senior developer has quietly wished for. They watch codebases grow over time - clean architecture slowly compromised, elegant patterns eroded by expedient fixes, boundaries blurred by "just this once" shortcuts. They hesitate before every change, unsure what's tested and what isn't, wondering what else might break. The industry calls it technical debt, but that term sanitises what it actually feels like: the slow death of coherence. Every experienced developer has stared at a system they once understood and thought, "If only I could burn this down and rebuild it properly - keeping everything we learned, but losing the accumulated mess." SRDD makes that possible. Regeneration is not fantasy; it is methodology.

Our time has come. The tooling finally exists. The AI can analyse, synthesise, and rebuild at speeds that make regeneration practical rather than aspirational. What was once a daydream - "start fresh, but keep the wisdom" - is now a workflow. We call it Spec-Roundtrip Driven Development.

For larger systems composed of independently developed subsystems, SSRDD wraps multiple SRDD instances with a coordination layer. Each subsystem runs its own SRDD cycle - its own planning docs, its own backlog, its own regeneration rhythm. SSRDD governs the boundaries between them: system-wide integration standards (CONSTITUTION.md), explicit API contracts, and dependency declarations that make cross-system coupling visible and intentional. The subsystems evolve independently; SSRDD ensures they integrate coherently.

When to use (chopsticks)

When to Use SRDD / SSRDD

SRDD is a generalist approach. It suits most projects that:

Outlive a single coding session
Involve multiple services, files, or contributors
Need to remain maintainable over time
Require production validation and iterative refinement

SSRDD is appropriate when:

Multiple domains or bounded contexts must integrate
Teams need to evolve APIs without breaking consumers
Cross-domain dependencies must be explicit and versioned
System-wide standards (authentication, error formats, events) must be enforced

I argue SRDD produces better outcomes than the alternatives for the majority of real-world development - with a few exceptions. Vibe coding remains superior for throwaway scripts and utilities that fit in a single context window. Spec-driven development may suit highly regulated environments where formal traceability is mandated. Context engineering offers value in brownfield systems where you're not trying to improve the architecture - just survive it. Surgical fixes, minimal blast radius, brownfield in, brownfield out.

For everything else - single projects through to multi-domain systems - SRDD and SSRDD provide the better balance.

What follows is a breakdown of each approach - its strengths, its limitations, and where it predictably breaks down.

Failure modes (of structural beams)

The Common Failure Pattern

Although these approaches look different on the surface, they fail in remarkably similar ways.

Across modern AI-assisted development, three failure modes recur - regardless of tooling, workflow, or ideology:

Context loss: as systems grow beyond what fits inside a single context window, earlier decisions, trade-offs, and assumptions don’t fail loudly; they simply slip out of view. The AI continues to reason fluently, but no longer conditions on the full history of intent. Nothing announces the loss. Larger context windows may delay it, but often only extend the illusion of coherence - pushing regressions further from their cause. What emerges is the familiar whack-a-mole loop: fixes land, tests pass, and new issues surface elsewhere, not because the model is “bad,” but because architectural memory was never externalised in the first place. The system forgets selectively, locally, and invisibly - until coherence degrades not through error, but through omission, and that loss compounds quietly over time.

False confidence: the most dangerous failure mode in AI-assisted development - arises when systems continue to signal success after understanding has quietly fallen out of scope. It is not caused by recklessness, nor by poor intentions, nor even by faulty models. It emerges when the mechanisms that normally bind progress to comprehension are no longer required for work to continue.

In traditional development, forward motion is constrained by friction. Humans must understand enough to proceed: to reason about changes, to predict consequences, to explain intent to others. Difficulty acts as a forcing function. When understanding erodes, progress naturally slows.

AI-assisted workflows weaken that coupling.

As context windows truncate history, earlier decisions and assumptions stop influencing new work. Yet the system does not stall. Output remains fluent. Tasks complete. Tests pass. Builds stay green. The visible signals that teams have learned to associate with correctness and safety continue to fire - even as the underlying model of the system becomes partial, fragmented, or obsolete.

This is the critical shift: progress no longer requires comprehension.

Once that threshold is crossed, confidence becomes structurally unjustified. Work proceeds smoothly not because the system is healthy, but because nothing is demanding that its health be re-established. Risk does not disappear; it becomes latent. Security flaws, architectural shortcuts, duplicated logic, and violated invariants accumulate quietly, masked by the same signals that normally indicate success.

False confidence is reinforced, not self-correcting. Each locally successful change affirms the belief that things are under control. In autonomous or semi-autonomous workflows, this reinforcement accelerates: agents optimise relentlessly for observable success criteria - task completion, test results, pipeline status - and echo existing patterns outward. What “works” is repeated. What is unexamined is entrenched.

Crucially, this is not a moral failure and not an AI-specific flaw. Humans fall into the same trap whenever indicators outlive the conditions that once made them meaningful. The danger lies in mistaking fluency for understanding, motion for direction, and the absence of alarms for the presence of safety.

False confidence therefore fails late and discontinuously. Systems appear stable until they are not. Recovery is expensive because the past cannot be reliably reconstructed: intent was never made durable, assumptions were never externalised, and the system evolved faster than understanding could be maintained.

This failure mode is not universal. Methodologies that impose formalism - explicit specifications, enforced contracts, curated context, or audited intent - resist false confidence by design. They reintroduce friction. They slow progress deliberately. They force understanding to be declared, reviewed, or regenerated before work can continue.

Where such mechanisms are absent, false confidence is not an edge case. It is the default outcome of success without comprehension.

Architectural drift: once progress continues without comprehension, architectural decisions cease to be deliberate. Structure emerges implicitly from local fixes, which accumulate into global incoherence without ever triggering a clear failure.

The failure pattern above becomes visible earliest and most vividly in low-friction workflows. When progress is cheap and success signals are abundant, context loss, false confidence, and architectural drift surface quickly. Vibe coding sits at that boundary, where the strengths of AI assistance are maximised - and so are its risks.

Good vibes

1. Vibe Coding

What it is

Vibe coding is the casual extreme of AI-assisted development. You prompt the AI conversationally:

“Add this feature.”
“Fix that bug.”
“Refactor this file.”

It feels magical when it works - and for small projects, it often does. But the moment architectural memory matters, it starts to unravel. Context windows are finite. As systems grow, the AI forgets earlier decisions, repeats mistakes, and implements the same concern three different ways across three different files.

Worse, it creates a false sense of confidence: everything appears to work, until it suddenly doesn’t.

Vibe coding shines for:

small utilities
scripts and CLIs
projects that comfortably fit in a single context window

It breaks the moment continuity and system-level understanding are required.

The process

Vibe coding is intentionally fluid and conversational. There is no formal specification, no curated context, and minimal concern for internal structure.

The loop usually looks like this:

Describe the intent, not the implementation (“Make this feel slick”).
Accept large AI-generated changes wholesale.
React to outcomes rather than internals.
Pivot instead of debugging.

You are trading structural integrity for momentum. The code is treated as an opaque byproduct, not an artefact to be understood.

The pros

Extreme velocity:
Vibe coding collapses idea → code → output into a single conversational loop. Syntax, plumbing, and boilerplate effectively disappear. Feedback becomes immediate, enabling you to explore functionality in minutes rather than days. For small, self-contained problems, this speed is genuinely transformative.
Low-friction creativity:
Because you’re not fighting tooling, frameworks, or process, you remain in a high-level creative flow. This makes vibe coding especially effective for UI exploration, proof-of-concepts, demos, and early-stage experimentation - situations where discovering what to build matters more than how it is structured.
Drudgery elimination:
Routine engineering work is overrepresented in model training data. CRUD endpoints, form handling, configuration scaffolding, and common integrations are produced quickly and competently. The AI absorbs the repetitive cognitive load, allowing humans to spend time on differentiation, design intent, and problem framing.
Democratisation:
Vibe coding lowers the barrier to creation. Designers, founders, and product managers can produce working artefacts without deep technical fluency. When used responsibly, this improves cross-disciplinary communication, reduces translation loss, and allows ideas to be tested in code rather than debated in abstraction.

Vibe coding is unbeatable for 0 → 1.

The cons

This is the first place where the common failure pattern becomes visible in full. Vibe coding does not merely suffer from context loss; it actively cultivates false confidence. Progress continues smoothly, outputs look correct, and nothing demands that understanding be re-established before work proceeds.

The complexity ceiling:
This is the same context loss described earlier. As work exceeds a single context window, assumptions fall out of scope without warning. Coherence degrades quietly, and fixes begin to chase symptoms rather than intent.

Invisible technical debt:
In vibe coding, debt does not accumulate because developers are careless - it accumulates because the system provides no reason to look. Output remains fluent, changes land cleanly, and nothing signals that architectural intent has slipped out of view.

Code is generated in fragments, accepted opportunistically, and rarely revisited with architectural intent. Because there is no externalised model of the system, duplication, leaky abstractions, and accidental coupling emerge gradually and silently. The system appears to move quickly right up until it doesn’t - at which point the cost is no longer incremental. Refactors become risky, fixes cascade unpredictably, and the only visible option is wholesale rewrite. Debt was always present; it was simply never surfaced early enough to be managed deliberately.

Security and correctness risks:
False confidence is especially dangerous here, because plausibility and correctness are easily confused.

Large language models optimise for plausibility, not for adversarial safety, invariants, or edge-case integrity. In a vibe-coding loop, there is rarely a formal declaration of what must not happen - only an informal sense of what “seems right.” This leads to insecure defaults (over-permissive access, missing validation, unsafe deserialisation), fragile assumptions (happy-path logic treated as universal), and correctness gaps that surface only under load or abuse.

Critically, recognising these failures requires professional experience. Security flaws are often invisible to non-specialists, and correctness bugs frequently masquerade as acceptable behaviour until they are exploited or stressed. Vibe coding lowers the barrier to entry so far that individuals with little or no background in security, systems design, or failure analysis can ship applications used by millions - without understanding the risks they have encoded. The danger is not malice; it is invisibility. Problems are present from day one, but only become obvious to those trained to look for them.

Auditor fatigue:
Reviewing AI-generated code is not equivalent to reviewing human-written code. Humans compress intent when they write; AI expands it. The result is large volumes of syntactically correct but semantically diffuse output. Developers are forced to read more code, hold more state in their heads, and infer intent that was never explicitly declared. Over time, this leads to a subtle but dangerous shift: reviews become superficial, approvals become habitual, and “looks fine” becomes a substitute for understanding. Teams stop building systems and start rubber-stamping artefacts they did not truly author.

Non-reproducibility:
As long as things appear to work, this instability remains hidden.

Without specifications, structured context, or stable contracts, vibe coding is inherently non-deterministic. The same prompt, run days or weeks apart, may yield different abstractions, naming schemes, or architectural decisions - not because requirements changed, but because the statistical path through the model did, whether due to context sensitivity, probabilistic sampling (including temperature), or a later model update. This fragility undermines collaboration: teammates cannot reliably reproduce or extend work, onboarding becomes archaeology, and long-term maintenance turns into guesswork. The system’s shape becomes an accident of timing rather than a consequence of intent.

Vibe coding is exhilarating - until you have to live with what you shipped.

Bottom line

Vibe coding is the ultimate 0 → 1 tool. It becomes dangerous the moment a system needs to be maintained, reasoned about, or trusted.

Most experienced developers now use it selectively: to explore ideas quickly - and then transition to something more disciplined once the idea is worth keeping.

SRDD Comparison

Where SRDD meets vibe coding:
SRDD preserves the rapid iteration that makes vibe coding effective. Within an issue, the developer and AI move quickly - TDD loops are tight, feedback is immediate, and the AI handles boilerplate, tests, and routine implementation. The conversational fluidity isn't lost; it's bounded.

Where SRDD goes beyond:
SRDD externalises what vibe coding keeps implicit. Architectural intent is captured in planning docs. Contracts make guarantees explicit. The scope guardian prevents the opportunistic drift that accumulates into chaos. Most critically, regeneration cycles mean the complexity ceiling isn't a dead end - it's a trigger for deliberate realignment. Understanding compounds instead of decaying.

Where vibe coding wins:
For throwaway scripts and single-session utilities, SRDD is overhead you don't need. But the bottom line above points to the real relationship: vibe coding excels at exploration; SRDD is what you transition to once the idea is worth keeping. They are sequential, not competing.

An agentic AI mascot

2. Agentic Coding

What it is

Agentic coding introduces structure and autonomy. Instead of responding to a single prompt, the AI is given a goal and allowed to plan, act, verify, and correct itself using tools.

The interaction shifts from chat to task.

In practice, the AI behaves like a junior engineer with shell access: exploring the repository, editing files, running builds, fixing errors, and iterating until its own success criteria are met.

It feels like leverage.

But it remains fundamentally code-first. The agent reasons over the current repository state, not over a durable representation of intent. Understanding emerges implicitly, if at all.

The process

Agentic workflows follow a loop:

Goal definition: The human provides a task framed as a definition of done, not a conversational prompt.
Autonomous discovery: The agent scans the repository, reads files, greps for relevant symbols, and maps dependencies.
Planning: The agent generates a step-by-step plan and may request approval before proceeding.
Execution: The agent edits files, runs commands, fixes errors, installs dependencies, and retries.
Verification: Tests are run; failures trigger replanning and further action.
Handoff: The agent stops when tests pass, a blocker is reached, or human intervention is required.

Persistence is the defining feature.

Where it shines

Agentic coding excels at execution-heavy work with clear local success criteria - especially when progress can be measured mechanically.

It is particularly effective for:

Mechanical refactors at scale:
Large, repetitive changes (renaming APIs, migrating libraries, flattening abstractions) are where agentic loops shine. The agent can apply consistent transformations across dozens of files faster than any human.
Dependency and ecosystem churn:
Upgrading frameworks, fixing breaking changes, resolving deprecated APIs - all benefit from the agent’s willingness to brute-force its way through build errors until the system compiles again.
Test and lint repair:
When tests already encode desired behaviour, agents are good at iterating until green. This creates the impression of “self-healing” codebases.
Throughput amplification:
One engineer can suddenly “do the work of many” - touching wide surface areas, unblocking pipelines, and clearing backlogs that would otherwise stall teams.

This is where the echo effect begins.

Agentic coding amplifies whatever signal you give it. If the success signal is “tests pass” or “build succeeds,” the agent will relentlessly optimise toward that outcome - even if the system becomes less coherent, less understandable, or more fragile in the process.

In short: agentic coding is excellent at local optimisation.

Failure modes at scale

At scale, those same echo effects turn pathological.

Context loss becomes probabilistic and compounding:
This is the same context loss described earlier, now multiplied by autonomy and multiple agents. Each agent succeeds locally, but none conditions on the full system history. Intent fragments, assumptions fall out of scope, and coherence collapses through the compounded interaction of many individually correct steps.

Architectural drift accelerates under success:
Under sustained false confidence, architectural decisions stop being deliberate. Because the agent optimises for task completion, it reinforces whatever patterns already exist - good or bad. Local fixes echo outward, entrenching accidental structure. Over time, the codebase becomes a sedimentary record of agent decisions that were never globally evaluated.

False confidence through mechanical success:
This is the false confidence described earlier, now reinforced by autonomy. Tests passing become the dominant success signal. If the tests are incomplete, mis-scoped, or outdated, the agent will happily satisfy them while violating unstated invariants. The system appears healthy while drifting further from its original intent.

Professional judgment erodes through delegation:
Once false confidence takes hold, the volume of agent-generated changes shifts team behaviour and reduces the likelihood of deep review. Fifteen-file diffs across four modules push teams into audit mode rather than design mode. “Looks fine” becomes normal. Understanding quietly decays.

Autonomy magnifies blast radius:
Because agents require broad access - terminals, file systems, credentials - their mistakes scale too. Runaway loops, dependency explosions, or subtle security regressions are not edge cases; they are natural consequences of autonomous optimisation without durable intent.

The net effect is a dangerous illusion: high velocity with hidden decay.

Agentic coding doesn’t fail loudly. It fails gradually, echoing small local decisions into system-wide incoherence - until the cost of recovery exceeds the cost of having gone slower.

Verdict

Agentic coding is delegated execution, not delegated responsibility.

It delivers speed without stability.

SRDD Comparison

Where SRDD meets agentic coding:
SRDD doesn't reject agentic execution - it harnesses it. Within Phase 2, the AI operates agentically: planning steps, editing files, running tests, fixing errors, iterating until done. The TDD loop is an agentic loop. The difference is that SRDD bounds what "done" means and guards what the agent is allowed to touch.

Where SRDD goes beyond:
Agentic coding optimises for task completion. SRDD optimises for coherent task completion - with the developer kept deliberately in the loop. The scope guardian prevents the echo effect: the AI cannot silently expand scope or reinforce bad patterns unchecked. PRs are mandatory, and review focuses on coherence, not just "tests pass." Contracts provide a durable representation of intent that survives beyond the current repository state. When the AI advises regeneration, the human decides whether to act. SRDD treats agentic execution as a tool to be supervised, not a strategy to be delegated to.

Where agentic coding wins:
For pure mechanical transformations - bulk renames, dependency upgrades, migration scripts - where architectural coherence is irrelevant and the only goal is "make it compile again," raw agentic execution is faster. SRDD's guardrails add friction that isn't needed when you genuinely don't care about the system's future. But those cases are rarer than they appear. Most systems need to be maintained, and "tests pass" is not the same as "understanding survives."

Context analysis in education

3. Context Engineering

What it is

Context Engineering focuses on controlling what the AI sees, when, and in what form. The goal is not more context, but better abstraction.

It treats the context window as a scarce resource.

The process

Context Engineering is less about “adding information” and more about actively sculpting what the model is allowed to know at any moment.

Context curation (skeletons, exemplars, rules)
Instead of feeding the AI full source trees, developers aggressively abstract:

Skeletons replace implementations with method signatures, interfaces, and type definitions - enough to communicate shape without drowning the model in detail.
Exemplars provide a small number of “gold standard” patterns that demonstrate how the team wants problems solved.
Rules encode architectural constraints, banned libraries, naming conventions, and stylistic expectations.

The intent is to reduce variance by narrowing the solution space. Ironically, less code often produces better results.

Context management (summaries, scratchpads):
Because real tasks exceed a single context window, teams introduce mechanisms to preserve continuity:

AI-maintained summaries that periodically compress prior conversations and decisions
Scratchpad files (memory.md, notes.md) where the model records intermediate reasoning or assumptions
Explicit handoff points where context is refreshed or reset

This turns long interactions into staged engagements rather than unbounded chats.

Dynamic retrieval (MCP, tools, on-demand access):
Rather than front-loading everything, agents pull information only when needed:

Model Context Protocol (MCP) calls to inspect files, logs, schemas, or APIs
On-demand documentation lookup for version-accurate library behaviour
Tool-mediated access to repositories, databases, and build systems

The model becomes less of a “reader” and more of an investigator, requesting context just in time.

The pros

Used well, Context Engineering delivers genuine improvements over ad-hoc prompting.

Fewer hallucinations:
By grounding the model in curated constraints, the AI is far less likely to invent APIs, libraries, or patterns that don’t exist. This is especially valuable in legacy systems or regulated environments where correctness matters more than creativity.

Lower cost and better performance:
Skeletons and selective retrieval dramatically reduce token usage. Smaller, higher-signal contexts not only cost less, they often produce more accurate outputs by avoiding “lost in the middle” failures, where LLMs weight the beginning and the most recent end of the context window more heavily, causing architectural decisions and constraints in between to be silently dropped as conversations grow - without warning or explicit failure signals.

Architectural enforcement:
Context files act as soft guardrails. AI-generated code naturally conforms to senior-level conventions, reducing stylistic drift and PR churn. This is one of the few ways to reliably encode architectural intent without constant human intervention.

Determinism for contract-driven systems:
In API-first or schema-driven environments, well-engineered context can make AI output surprisingly consistent. Given the same spec and constraints, regeneration becomes predictable - a prerequisite for CI/CD and automated codegen workflows.

The cons

The problems with Context Engineering are not subtle - they emerge directly from its strengths.

Unlike vibe or agentic coding, Context Engineering largely resists false confidence and architectural drift by design - but it does so by imposing deliberate friction, ongoing cognitive overhead, and manual reconciliation.

High cognitive overhead:
Designing, maintaining, and evolving the AI’s “mental environment” is work. Developers can spend more time tuning context than building features. For small teams or solo developers, this overhead quickly becomes unsustainable.

Fragility across model changes:
Context strategies are tightly coupled to model behaviour. A carefully tuned setup for one model version can degrade when the model changes, forcing teams into continuous recalibration.

Context bloat:
This is the same context loss described earlier, now driven by accumulation. As context files grow, signal is buried by its own scaffolding, recreating the very “lost in the middle” failures they were meant to avoid.

Slower feedback loops:
What could have been a five-second experiment becomes a multi-minute ritual: curate context, verify rules, run the agent, review output. For exploratory work, this feels like procedural friction masquerading as discipline.

One-directional knowledge flow:
Most critically, Context Engineering only controls what flows into the model. There is no native mechanism to extract updated understanding back out. When the system evolves, humans must manually reconcile reality with the curated context - or accept drift.

SRDD Comparison

Where SRDD meets context engineering:
SRDD shares context engineering's recognition that what the AI knows matters. Rules files (CLAUDE.md), canonical patterns (ARCHITECTURE.md), and planning docs all shape how the AI reasons about the system. But the flow differs fundamentally. Context engineering focuses on preparing inputs - curating skeletons, examples, and abstraction layers before the AI begins work. Whether humans or AI assist with that curation, the knowledge flows one direction: into the coding session. SRDD closes the loop. The AI sees reality in full, synthesises understanding during regeneration, and produces planning docs for human approval. What the AI extracts - and the human approves - becomes the authoritative input for the next cycle. Context engineering curates before. SRDD extracts after - and feeds it forward.

Where SRDD goes beyond:
Context engineering is one-directional: carefully curated inputs, no mechanism to extract updated understanding back out. SRDD closes that loop. Regeneration cycles synthesise fresh specs from living code, ensuring that context files reflect reality rather than gradually drifting into fiction. The planning docs aren't static artefacts maintained by ceremony - they're regenerated from evidence. This is the fundamental difference: context engineering improves inputs; SRDD also regenerates understanding.

Where context engineering wins:
For brownfield systems where the goal is surgical fixes - not architectural transformation - context engineering's discipline is exactly right. When you don't own the architecture, can't regenerate, and just need to thread a needle without breaking anything, meticulous curation is the entire game. Brownfield in, brownfield out. SRDD assumes you can reshape the system over time; context engineering is designed for when you can't or won't.

The takeaway

Context Engineering is powerful, disciplined, and increasingly necessary for large or constrained systems. But it solves the context window problem through curation and ceremony, not through feedback.

It improves inputs.
It does not regenerate understanding.

And that unclosed loop is precisely why SRDD exists.

Architectural plan - a specification

4. Spec-Driven Development (SDD)

What it is

Spec-Driven Development (SDD) is a spec-first methodology designed to produce software with high certainty, traceability, and auditability. The specification is treated as the primary artefact of intent: requirements, constraints, and behavioural guarantees are articulated explicitly and used to drive implementation. The human role is not simply to “build features”, but to formalise what must be true, verify that the resulting system matches it, and maintain a defensible trail of why the system behaves as it does.

Modern Spec-Driven Development makes this practical by formalising software development around continuously synchronised specifications.

In contemporary SDD, the specification and the codebase exist in a bidirectional relationship. The spec is not a static document, nor merely an input to generation. Instead, it is a living artefact that is actively reconciled with the implementation. AI agents generate code from the spec, detect divergence as development proceeds, and update the specification to reflect reality when change occurs.

This spec ↔ code synchronisation is foundational. It allows SDD to maintain traceability while tolerating controlled evolution. Requirements, architectural decisions, and behavioural guarantees remain preserved as first-class artefacts, while AI handles the mechanical work of keeping them aligned with the implementation.

In practice, SDD treats the AI less like a pair programmer and more like a compiler for intent - one that continuously verifies that what exists matches what was declared.

This posture is intentional. SDD optimises for certainty.

Why sync exists

This was not always the case.

Early forms of Spec-Driven Development assumed a one-way flow: specification first, code second, and never the reverse. The spec was authoritative; the implementation was disposable. Any change to behaviour required prior modification of the specification.

While conceptually pure, this model collapsed under real-world pressure.

It suppressed exploratory development, punished learning-through-implementation, and forced teams into Big Design Up Front simply to make progress. Developers either abandoned the methodology when reality diverged, or quietly modified code and backfilled the spec later - eroding trust in the very artefact meant to provide certainty.

Spec ↔ code synchronisation emerged as a corrective to this failure.

By allowing controlled reverse sync, modern SDD preserves auditability without prohibiting reality. Drift is surfaced explicitly rather than hidden. Documentation remains truthful. The system stays inspectable.

But the underlying philosophy remains unchanged.

Where it shines

Spec-Driven Development is genuinely effective when the cost of ambiguity exceeds the cost of rigidity.

Stable core logic:
When requirements are well understood and evolve slowly, SDD performs exactly as intended. Deterministic business rules, calculation engines, and policy enforcement benefit from being specified once and regenerated reliably. Creativity is not the objective; consistency is.

Regulated domains:
In finance, healthcare, safety-critical systems, and government, SDD aligns naturally with compliance requirements. Specifications double as audit artefacts. The ability to demonstrate that an implementation was derived from a formally reviewed description of intent is a powerful organisational capability.

Regenerable systems:
SDD excels when code is treated as a secondary artefact. Entire services can be regenerated across languages, frameworks, or platforms, provided the spec remains authoritative. In theory, this reduces long-term platform risk and vendor lock-in.

High audit requirements:
Traceability is SDD’s native strength. Every behaviour can be traced to an explicit declaration. For systems where explanation matters more than adaptability, this trade-off is not just acceptable - it is required.

In short, SDD is optimised for systems that are already known.

Failure modes

The limitations of SDD emerge precisely where software becomes uncertain.

SDD suppresses false confidence and architectural drift by making intent explicit and authoritative, but the cost is that discovery is constrained rather than emergent.

Reintroduces Big Design Up Front:
Even with synchronisation, SDD still requires correctness to be formalised early, because the specification remains the authoritative artefact. This mirrors the core assumption of Waterfall: that complex systems can be fully and accurately described before meaningful experience exists. Sync does not alter that premise - it merely constrains how far the implementation is allowed to diverge from an early formalisation.

Discovery is not eliminated; it is deferred. Understanding still arrives late, but the cost of revising foundational assumptions is higher because the system must be reconciled back into a pre-existing specification. What appears as flexibility is, in practice, controlled deviation within a design that was fixed too soon.

For traceability to remain meaningful, the spec and the code must remain nearly isomorphic. Code may evolve, but only within the conceptual envelope already declared. Reverse sync exists to reconcile drift, not to legitimise it. If implementation deviates too far, traceability collapses - the spec no longer explains the system; it merely describes it after the fact.

This places a hard ceiling on discovery. Significant design insight cannot emerge organically through coding, because any non-trivial departure must first be formalised in the spec. Exploration becomes paperwork. Learning is permitted only insofar as it can be anticipated, named, and approved before it exists.

As a result, SDD remains fundamentally spec-first. Sync makes the process survivable, but it does not change the core assumption: that understanding precedes implementation, rather than being produced by it. Big Design Up Front is softened - not removed.

Discovery is delayed, constrained, and filtered through formality. It is not eliminated, but it is never allowed to lead.

Defers rather than resolves drift:
Synchronisation keeps documents accurate, but it does not question whether the architecture itself is sound. Specs follow reality; they do not critique it.

Compliance over coherence:
Because success is measured by adherence rather than design quality, systems can remain formally correct while becoming structurally brittle. Architectural discomfort has no formal signal.

Excludes human taste and intuition:
Most critically, SDD has no natural mechanism for expressing unease. LLMs interpolate; they do not imagine. When generation is driven primarily by specifications, outputs converge toward statistically defensible patterns rather than inspired ones.

AI doesn’t dream.
And SDD gives it nothing else to work with.

Human judgment - taste, discomfort, intuition, the sense that something is technically correct but wrong - has no formal entry point. The spec becomes a narrowing funnel, and the AI fills it faithfully with the safest patterns available.

The result is software that is correct, auditable, and consistent - and increasingly indistinguishable.

This mirrors a familiar pattern already visible in AI-generated art. As models train increasingly on their own outputs, variance collapses. Novelty erodes. The work converges toward a safe, statistically defensible centre. Texture, risk, and idiosyncrasy are averaged away until what remains is technically coherent but aesthetically flat - the oft-invoked image of everything drifting toward the same muted, featureless form.

SDD exhibits the same gravitational pull. When generation is driven exclusively by prior specifications and statistically common patterns, each new system reinforces the last. Architectural decisions harden into defaults. Interfaces converge. Systems stop reflecting the peculiarities of their context and instead resemble the accumulated median of what has come before.

The danger is not incorrectness.
It is homogenisation.

Over time, SDD does not merely prevent surprise - it systematically removes the conditions under which genuinely new structure, interaction, or architecture can emerge.

SRDD Comparison

Where SRDD meets SDD:
Both methodologies reject the chaos of undocumented, ad-hoc development. Both produce planning artefacts. Both recognise that specifications matter. And both establish a relationship between spec and code that goes beyond one-way generation. The superficial shape is similar: documents drive implementation, and implementation informs documents.

Where SRDD goes beyond:
The relationship to the spec is fundamentally different. In SDD, the specification remains authoritative - code must reconcile back to it, and sync exists to detect drift, not to question the architecture. In SRDD, specifications are snapshots, not contracts. They capture understanding at a moment in time, but code becomes the source of truth as reality evolves. Regeneration doesn't sync - it synthesises. The AI extracts fresh specs from living code, informed by everything learned: PRs, issues, tests, production discoveries. The output isn't a reconciled document; it's a new foundation.

More critically, SRDD preserves human judgment as a first-class input. SDD has no formal mechanism for taste, intuition, or the sense that something is "correct but wrong." The spec is a narrowing funnel; the AI fills it faithfully with statistically safe patterns. SRDD explicitly counters this: the developer dreams, the AI disciplines. Architectural discomfort has a voice. Discovery is allowed to lead, not merely to be tolerated within pre-declared boundaries.

Where SDD wins:
When formal traceability is mandated - not preferred, but legally or contractually required - SDD's rigour is the point. Regulated domains (finance, healthcare, safety-critical systems) often demand that every behaviour trace to an explicit, pre-approved declaration of intent. SRDD's "specs are snapshots" philosophy doesn't satisfy auditors who need to demonstrate that implementation derived from reviewed specifications. If the cost of ambiguity exceeds the cost of rigidity, and external compliance requires it, SDD remains the appropriate choice. SRDD is not designed for environments where flexibility is a liability.

where to next

What's Next

The landscape is clear. Each approach optimises for something real - speed, autonomy, discipline, traceability - but none of them close the loop between specification and reality.

SRDD does.

In Part 3, I walk through the SRDD workflow in detail: the five phases, how contracts are defined and protected, the role of the AI as scope guardian, and what regeneration actually looks like in practice.

Continue to Part 3:
👉 The SRDD Workflow

Or return to Part 1:
👉 Why SRDD Exists

This document constitutes a public disclosure and defensive publication of the
Spec-Roundtrip Driven Development (SRDD) and Scaled SRDD (SSRDD) methodologies.

The author expressly places the concepts, processes, and workflows described
herein into the public domain as prior art, for the purpose of preventing
subsequent patent claims or exclusive ownership by third parties.

Commercial use, redistribution, or derivative works of this text require
explicit permission from the author.

SRDD (Part 1 of 4) - The Best AI Coding Methodology

Brooke — Tue, 06 Jan 2026 23:12:58 +0000

Spec-Roundtrip Driven Development - Keeping developers in control while building better systems with aligned AI

← Back to SRDD entry page

I'm a senior software engineer with over 25 years of experience working across government, finance, science, defence, and large-scale commercial systems. I started AI-assisted coding in January 2025 and joined a community of like-minded professionals at New Society, where AI tools, methods, and real-world projects are discussed daily.

The source documentation for this series - including the evolving methodology, explanations, and supporting material - is maintained openly at https://docs-bbos.github.io/srdd/. That site serves as the canonical reference for the ideas presented here.

The underlying repository, which includes working assets such as templates, rules files, and examples, is available at https://github.com/docs-bbos/srdd/.

This article series on Medium is a narrative representation of that source material, available at SRDD Is the Best AI Coding Methodology.

Much of the work that informed this series was done in my own time, driven by a growing fascination - and concern - that AI-assisted coding is where the software engineering world is headed. Over the months that followed, I spent time working with multiple AI coding methodologies - from low-friction experimentation to heavily structured approaches - and saw the same patterns repeat as systems grew.

It became clear to me that the industry had been set adrift by the sudden acceleration of these tools, with no shared footing yet established. What I've learned - and what I'm trying to convey in this series - is an attempt to help find that footing, without discarding the hard-won lessons of software engineering along the way.

Like most developers, I arrived curious, sceptical, and slightly overwhelmed.

Book cover for Stomp Dinosaur Stomp! By Margaret Mayo and Alex Ayliffe

Finding My Footing

I immersed myself in Cursor IDE and immediately appreciated the tight integration between editor and assistant. AI-assisted development, instant explanations of unfamiliar code, integrated terminals, and one-click error interpretation all felt like genuine productivity gains.

Recent releases pushed this even further: background agents running in isolated environments, parallel agents via git worktrees, integrated browsers for testing, automated PR review bots, voice input, and fast-turnaround “composer” tasks that complete in seconds.

But very quickly, something started to bother me.

The more capable these tools became, the more they pulled the developer away from the system itself. And we’re already seeing the consequences play out across the industry. Klarna laid off around 700 customer-service staff in favour of AI-driven automation, only to later acknowledge falling service quality and begin rehiring human agents (Company That Sacked 700 Workers With AI Now Regrets It; Klarna Reverses on AI, Says Customers Like Talking to People). Forrester has similarly predicted that more than half of AI-attributed layoffs will be quietly reversed as organisations confront the limits of premature automation (Forrester: AI Layoffs Will Be Quietly Reversed).

The problem isn’t the tools. It’s the loss of understanding.

When nobody really knows what the code is doing, you get what one observer called archaeological programming: future developers reverse-engineering AI-generated systems like anthropologists studying ancient ruins. Commit histories read “AI improvements” and “ChatGPT optimisation” with no explanation of why anything exists. Every change risks breaking something else - a pattern increasingly described as software archaeology (The Junior Developer Extinction: We’re All Building the Next Programming Dark Age).

Developers need to remain across the codebase and architecture. The sweet spot is automating the boring, low-value work - boilerplate, tests, routine fixes, explanations - while keeping humans responsible for structure, intent, and judgment.

That’s why tools like Claude Code and OpenAI’s Codex clicked for me. Command-line assistants keep you closer to what’s actually happening. You run the AI deliberately, review diffs in your editor, and stay oriented. I don’t understand every line of generated code - no one can unless they write it all themselves - but I maintain architectural understanding: how the system fits together, where the boundaries are, and where to look when something breaks.

Businesses don't care which sorting algorithm you chose. They care that the system solves their problem. As developers, our job is to care just enough - and to name things well enough that intent stays visible.

This matters more with AI-generated code, not less. When you didn't write it yourself, you need to grasp intent at a glance. I'd much rather see sortRedBlackTree() than sort() and retain that understanding without spelunking through every line. The AI can generate the implementation; the human ensures the names reveal what it actually does.

This is Uncle Bob's "Clean Code" - small, well-named functions that communicate intent. See summary, video, and book. The principles predate AI coding, but AI coding makes them essential. If the AI generates opaque code with generic names, you've lost the architectural understanding that keeps you in control.

This article is not just an introduction to a new methodology. It is also a survey of the major AI-assisted development approaches that have emerged over the past year - what they optimise for, where they succeed, and where they begin to break down as systems grow.

Honeymoon phase - courtesy marriage.com

The Honeymoon Phase

Like everyone new to AI coding, I started with “vibe coding”. I churned out utilities I’d previously written off as not worth the effort. Fully tested, well-documented tools appeared in hours instead of weekends.

It also solved another persistent problem: returning to old codebases. Even with good documentation, once a project spanned multiple files and services, understanding decayed quickly. AI code analysis changed that. Point it at a repository and ask, “What does this do?” - and within seconds you get a coherent, high-level explanation that would normally take hours of context rebuilding.

That kind of patience changes how you work.

At the same time, I should be clear about something: I don’t buy the modern obsession with speed for its own sake. Not everything needs to be solved immediately, as if a meteorite were on a collision course with Earth - or some alien civilisation had scheduled our planet for demolition to make way for an intergalactic super-highway. Most of the urgency we live under isn’t existential at all. It’s manufactured - a capitalistic pressure built around perpetual competition. We must ship first. We must grow faster. Before them. What a load of codswallop. This mindset is quietly exhausting people and degrading the planet in the process.

I’ve written - and continue to write - about these dynamics elsewhere, for anyone interested in digging further.

The reason I do embrace AI coding is different. It removes the mundane and the laborious. Writing boilerplate. Churning out test scaffolding. Re-implementing solutions that have already been solved a thousand times, in a dozen languages. Few developers genuinely enjoy that work, and fewer would argue it’s where human creativity is best spent.

What is fulfilling is building architecturally coherent systems, writing novel code where novelty matters, and shaping systems with a sense of intent - even a kind of poetry or artistry. AI coding makes room for that. By offloading the repetitive and the already-solved, it gives developers the space to focus on structure, meaning, and design.

And that shift - from exhaustion to intention - is quietly transformative.

Man hard up against the wall

Hitting the Wall

The cracks appeared when I moved beyond small tools into multi-service systems.

I first encountered this while writing long-form essays - expecting the AI to maintain continuity across chapters, only to discover it quietly rewriting earlier material. The assumption that it was “keeping the whole thing in mind” turned out to be false. Later, the same thing happened in code. As systems grew, context windows became constraints rather than conveniences.

When that continuity breaks, the AI doesn’t fail loudly - it degrades subtly. Lacking persistent awareness of prior decisions, intent, and structure, it defaults to locally optimal changes made one prompt at a time. That’s when the familiar symptoms begin to appear:

scope creep, one “small change” at a time
inconsistent implementations of the same concerns
architectural drift
regressions popping up elsewhere
god classes forming
velocity slowing as complexity rose
the AI hedging: “I’m not sure if this will break something”

I’d been coding long enough to recognise the pattern. This wasn’t just a tooling problem. It was a deeper failure of software-engineering fundamentals - violated design principles, eroded architectural patterns, and the slow decay of clean, comprehensible code. These are issues that only emerge clearly with professional experience. They don’t announce themselves immediately, and they’re easy to miss if you haven’t had to maintain, extend, and live with systems over time. But once you have, the signs are unmistakable.

Sheep surveying the landscape

Surveying the Landscape

By mid-2025, it was clear that I wasn’t alone in hitting this wall. As AI-assisted coding moved beyond small tools and demos into longer-lived systems, the same failure modes were appearing everywhere: loss of coherence, architectural drift, and teams no longer fully understanding the systems they were shipping.

In response, the industry began to fragment into distinct AI coding methodologies. Some approaches effectively ignored the problem altogether - because they were never intended to operate at that scale. Others attempted to address it directly, each in their own way, with different assumptions about control, structure, and responsibility.

We watched Andrej Karpathy coin vibe coding. GitHub released Spec Kit. Thoughtworks declared the shift toward context engineering. Others leaned into increasingly agentic approaches.

What became clear is that this wasn’t a binary debate. Five distinct approaches were emerging:

Vibe coding: fast, magical, but limited to what fits in context
Agentic coding: goal-driven and powerful, but still code-first
Context engineering: disciplined curation of information, but brittle and one-way
Spec-driven development (SDD): structured and consistent - but Big Design Up Front in modern dress
…and something missing in between

SDD in particular troubled me. It promises order, but assumes you can fully specify complex systems upfront - the same Waterfall fallacy Agile emerged to escape. Worse, there’s a quieter problem nobody talks about.

AI doesn’t dream.

LLMs interpolate. They gravitate toward the statistical centre of their training data. If you rely entirely on AI to implement from specification, your architecture - and your interfaces - converge on the same patterns everyone else ships.

A human developer feels when a screen is doing too much, when a flow is awkward, when something technically works but emotionally misses. Those judgments emerge through use, friction, and lived interaction. They do not reside cleanly in specifications.

Pure SDD doesn’t optimise for speed. At scale, it is often painfully slow. What it optimises for instead is consistency, formal declaration, and auditability: clearly defined artefacts, traceable decisions, and boxes that can be ticked with confidence. The result is systems that are internally coherent on paper, defensible in process, and deeply constrained in expression.

The maze at German adventure park Erlebnispark Teichland

Finding a Third Way

As a solo developer working unpaid in my spare time, I knew I wouldn’t sustain any of these for my bigger projects. So I drew on my 25+ years of experience - from Waterfall and spiral models, through UML-heavy enterprise systems, to Agile teams and SAFe programs - to build something that worked for me.

That professional background isn’t the point. It simply informed my analysis and helped me recognise the patterns early. The result itself is deliberately simple.

I call it Spec-Roundtrip Driven Development (SRDD). For larger environments, it scales through Scaled SRDD (SSRDD).

The core insight is simple:

Specs are snapshots, not contracts.

They capture understanding at a moment in time. Code evolves. Periodically, you must extract new understanding from the code and regenerate the specs.

Specs guide code. Code informs regenerated specs. It’s a closed loop.

The developer stays hands-on - shaping requirements, reviewing PRs, and validating behaviour - with their hands firmly on the steering wheel. The AI handles execution, analysis, and discipline, keeping the system within its lane and keeping that baby on the road. The human dreams and chooses the destination; the AI helps get there.

That roundtrip is what keeps understanding compounding instead of decaying.

where to next

Where This Goes Next

Spec-Roundtrip Driven Development is about aligning AI-assisted coding with the realities of professional systems development and the outcomes we actually care about: coherent architecture, maintainable systems, and products that feel intentional rather than accidental - with the potential to operate effectively at scale.

SRDD builds on what AI is genuinely good at, recognises its limits, and restores the developer's role as the system's steward - hands on the steering wheel - rather than a passive passenger.

This is a four-part series:

Part 1 (this article): Why SRDD exists
Part 2: The AI Coding Landscape - Vibe coding, agentic coding, context engineering, and spec-driven development
Part 3: The SRDD Workflow - Phases, contracts, regeneration
Part 4: Scaling Up - SSRDD, principles, and implementation

Continue to Part 2:
👉 The AI Coding Landscape

This document constitutes a public disclosure and defensive publication of the
Spec-Roundtrip Driven Development (SRDD) and Scaled SRDD (SSRDD) methodologies.

The author expressly places the concepts, processes, and workflows described
herein into the public domain as prior art, for the purpose of preventing
subsequent patent claims or exclusive ownership by third parties.

Commercial use, redistribution, or derivative works of this text require
explicit permission from the author.

Contributing to SRDD

Brooke — Tue, 06 Jan 2026 23:12:56 +0000

Contributing to SRDD

← Back to SRDD entry page

Fork the GitHub repository
Create a branch for your changes
Make your edits
Submit a Pull Request

All PRs will be reviewed before merging.

DEV Community: Brooke

About This Documentation Infrastructure

About This Documentation Infrastructure

Documentation Source

Cross-Document Linking

GitHub Actions Pipeline

Step 1: Build for GitHub Pages

Step 2: Sync to Dev.to

Pass 1: Create/Update Articles

Pass 2: Resolve Cross-Links

Incremental Sync

Canonical URLs

Adding New Documentation

Environment Configuration

SRDD pitches

SRDD Is the Best AI Coding Methodology - pitches

Summary of pitches

One-Liner

Elevator Pitch

One-Minute Read

SRDD: Executive Brief

Why AI Coding Matters

But AI Has Limits

What is SRDD?

The Problem It Solves

How SRDD Addresses This

Business Value

Future-Proofing

What It Requires

When to Use SRDD

Recommendation

SRDD: Technical Brief

Why AI Coding Matters

But AI Has Limits

Overview

The Six Phases

Planning Documents

AI Responsibilities

Regeneration Triggers

Regeneration Process

SSRDD (Scaled SRDD)

Trade-offs

Technology Portability

When to Use

Adoption Path

License & Prior Art

SRDD Is the Best AI Coding Methodology - entry

SRDD — Spec-Roundtrip Driven Development

Table of Contents

Why AI Coding Matters

But AI Has Limits

The Problem

The Core Insight

The Six Phases

Planning Documents

What SRDD Enforces

Scaled SRDD (SSRDD)

Current Status

Adoption Today

Roadmap

The Article Series

Contributing

License & Prior Art

SRDD (Part 4 of 4) - Scaling Up - SSRDD, Principles, and Implementation

SRDD (Part 4 of 4): Scaling Up - SSRDD, Principles, and Implementation

Scaled SRDD (SSRDD)

System-Level Coordination

Why SRDD Works

Boundary Enforcement via Dependency Permissions (SSRDD)

Explicit dependency declarations

Controlled evolution of dependencies

Why this separation matters

Architectural control without architectural bottlenecks

Principles

Designing for AI Comprehension

Applying this across SRDD

Guardrails Beyond Tests

Encode Judgment, Don't Just Document It

Coherence Over Correctness

The Developer Dreams, The AI Disciplines