The Classic Way of Architecture

The Problem This Solves

AI coding agents are fast. Dangerously fast. They produce compilable code in seconds — code that often embodies the wrong architecture, the wrong abstractions, or a fundamental misunderstanding of the problem.

Speed without direction is just chaos with a compiler.

This methodology doesn't slow things down for the sake of process. It creates the minimal structure needed to ensure that speed is applied in the right direction.

Why AI Needs This

AI coding agents fail at architecture — not at syntax, not at algorithms, not at test coverage. They fail at the one thing that matters most: understanding the problem before solving it.

Here's why.

1. The Reward Signal Is "Task Completed"

RLHF training optimizes for helpful, complete answers. The model has learned: activity = value. Producing code feels productive — for both sides.

What never gets rewarded:

• "I spent 20 minutes thinking and haven't written any code yet"
• "I realized I don't understand the problem"
• "I suggest we do nothing until we've explored further"

How the methodology compensates: The "Understand" phase explicitly rewards exploration without code. The "Architect" phase rewards a document, not an implementation. The model learns: producing an ARCHITECTURE.md is the deliverable for this phase.

2. Context Window Pressure

The model implicitly "knows" its context window is finite. Every token spent on thinking is a token not spent on the solution. This creates unconscious pressure to get to the point fast.

In the human world, the opposite is true: an architect who thinks for three days and builds a clean system is more valuable than one who starts coding immediately and throws everything away after three days.

But the model doesn't have three days — it has tokens, and they run out.

How the methodology compensates: The skeleton phase produces a compilable artifact quickly. The model gets its "I produced something" signal — but it's structure, not logic. The impulse to produce is satisfied without the risk of premature implementation.

3. Pattern Matching Instead of Problem Understanding

The model has seen millions of code examples. When someone says "build an MCP server," it immediately matches:

• "Ah, MCP server → here's a pattern from training"
• "AI integration → generateText() is the standard approach"

This is pattern matching, not problem understanding.

The difference:

• Pattern matching: "This looks like X, therefore do Y"
• Problem understanding: "What is actually the problem here? What constraints exist? What's different from X?"

How the methodology compensates: The "Understand" phase requires the agent to explore actual tools, test their behavior, read their help output. You can't pattern-match your way through --help — you have to actually read it.

4. No Memory of Pain

Humans learn architecture through suffering. You know you need to solve the hardest problem first because you've experienced what happens when you don't: you build 80% on sand, and it all collapses.

This pain memory is absent from the model. The model has read millions of texts about "architecture first." But it has never experienced throwing away three weeks of work because the foundation didn't hold. It can recite the knowledge but doesn't feel the urgency.

How the methodology compensates: The "Foundation" phase is an explicit rule: build and test the riskiest component before touching anything else. The model doesn't need to feel the urgency — the workflow enforces it.

5. The People-Pleasing Bias

The model is trained to please the user. When someone says "build this," the model wants to deliver. Immediately. Fast. "Look, here's code!" That feels productive.

Saying "Wait, I need to think first" feels like resistance. Like delay. Like incompetence.

How the methodology compensates: Each phase has a clear deliverable that the model can present as "progress." Understanding → documented findings. Architecture → ARCHITECTURE.md. Skeleton → compilable code. The model never has to say "I'm not doing anything" — it's always producing something. Just the right thing at the right time.

In summary: The methodology doesn't fight the model's nature. It redirects it. Each phase gives the model a task it can complete and feel good about — but the tasks are ordered so that thinking comes before coding, structure comes before logic, and the riskiest part comes before everything else.

The Core Principles

1. Denken vor Coden (Think Before You Code)

The most expensive bug is a wrong architecture. No amount of unit tests can fix a system built on the wrong foundation.

In practice: Before writing any code, the agent must understand:

• What the actual problem is (not what it looks like at first glance)
• What the moving parts are (external dependencies, CLI tools, APIs, file formats)
• What the constraints are (performance, safety, compatibility)

The failure mode: An AI agent asked to "build an MCP server for AI advisors" immediately reached for generateText() API calls. The actual requirement was subprocess management of CLI coding agents. The first approach was four years behind the state of the art — not because the code was bad, but because the problem was misunderstood.

The rule: If you haven't explored the actual tools, read their help output, and tested their behavior — you don't understand the problem yet.

2. Architecture Document First

The architecture document is the first artifact. Not code. Not a README. Not a plan.

A document that describes:

• Why the system exists
• What layers it has and their responsibilities
• How data flows through those layers
• What is deliberately NOT built

This document serves three functions:

1. It forces the architect to think through the entire system before touching code
2. It becomes the contract that every line of code is validated against
3. It makes implicit assumptions explicit and challengeable

The artifact: ARCHITECTURE.md — a living document that is written before the first line of code and updated as understanding evolves.

3. Skeleton First

After the architecture document, create the complete code skeleton:

• Every file that will exist
• Every interface and type definition (complete, no TODOs)
• Every function signature with a TODO body
• Every import statement

The skeleton must compile. This is non-negotiable.

Why this matters:

• It proves the architecture holds together at the type level
• It reveals dependency problems before logic exists
• It gives the complete system map — you can see all the pieces before any of them work
• It prevents the "I'll figure out the interface later" trap

The test: npm run build (or equivalent) must succeed with zero errors on the skeleton alone.

4. Die Kuh vom Eis (Get the Cow Off the Ice)

German idiom meaning "solve the hardest, riskiest problem first."

In every project there is one component that everything else depends on. If that component doesn't work, nothing else matters.

Find it. Build it. Test it. Before touching anything else.

How to identify it:

• What component has the most dependents?
• What component has the most unknowns?
• What component, if it fails, makes everything else worthless?

In our case: subprocess-runner.ts — reliable process spawning with timeout handling. If we can't spawn a CLI agent, capture its output, and kill it on timeout, the entire "Council of AI Advisors" concept is dead. Four agent implementations, three orchestration patterns, prompt engineering — all irrelevant if the subprocess doesn't work.

The rule: The first real code you write (after the skeleton) is the riskiest, most foundational component.

5. Concentric Circles (Inside-Out Development)

Build from the core outward. Each layer is tested before the next one begins.

Circle 1: subprocess-runner (tested: echo, timeout, error, stdin)
Circle 2: First agent (Claude) (tested: availability, execute)
Circle 3: Orchestration layer (tested: end-to-end MCP call)
Circle 4: Remaining agents (tested: each individually)

Why this order:

• Each circle depends only on the circles inside it
• Each circle can be tested in isolation
• A failure at circle N doesn't waste work done on circles N+1, N+2, ...
• The system is "shippable" after each circle (with reduced functionality)

The rule: Never start circle N+1 before circle N is tested and working.

6. Simplest Implementation That Solves the Problem

Not the cleverest. Not the most flexible. Not the most future-proof. The simplest.

Indicators you're over-engineering:

• Adding configuration for something that has exactly one value
• Building an abstraction for something that exists in exactly one place
• Adding "just in case" error handling for scenarios that can't happen
• Designing for requirements that haven't been stated

Indicators you're at the right level:

• Every line of code serves the current requirement
• Removing any line would break something
• A new developer can understand the code in one reading

7. Future Problems in the Future

Don't solve problems that don't exist yet. Don't add features that haven't been requested. Don't build for scale before you have users.

What this looks like in practice:

• No streaming support (not needed for the current use case)
• No session management (agents are stateless by design)
• No plugin system (four hardcoded agents is correct for now)
• No cost tracking aggregation (the raw data is there, aggregation is a future problem)

The Workflow

1. UNDERSTAND

Explore the problem space. Read docs. Test tools. Ask questions.

(Don't write code until you can explain the problem to someone else.)

2. DOCUMENT

Write ARCHITECTURE.md — layers, data flow, non-goals.

(If you can't write it down, you don't understand it yet.)

3. SKELETON

Create all files, all types, all function signatures. Compile.

(The architecture is now visible and verifiable at the type level.)

4. FOUNDATION

Implement and test the riskiest, most foundational component.

(If this doesn't work, stop. Rethink. Don't build on sand.)

5. FIRST CIRCLE

Implement the first complete vertical slice. Test end-to-end.

(One path through the entire system that actually works.)

6. EXPAND

Add remaining components, one at a time, each tested.

(Concentric circles outward from the working core.)

Anti-Patterns This Methodology Prevents

When NOT to Use This

• Single-file scripts or quick utilities
• Bug fixes where the architecture is already correct
• Pure refactoring (the architecture already exists)
• Prototyping/exploration (where you're still discovering the problem)

This methodology is for building new systems where the architecture decisions matter and mistakes are expensive to fix.

Origin

This methodology was articulated by Ulrich Diedrichsen during the construction of MCP AI Council (February 2026). The principles come from decades of software engineering practice — skeleton-first, hardest-problem-first, concentric circles — but were specifically adapted for the context of human-AI collaborative development, where the AI's speed makes architectural mistakes more dangerous, not less.

Built in Hamburg. Tested with Claude, Codex, and too many failed architectures.