The Classic Way of Architecture

Das Problem, das diese Methodologie löst

KI-Coding-Agenten sind schnell. Gefährlich schnell. Sie produzieren kompilierbaren Code in Sekunden — Code, der oft die falsche Architektur, die falschen Abstraktionen oder ein fundamentales Missverständnis des Problems verkörpert.

Geschwindigkeit ohne Richtung ist nur Chaos mit einem Compiler.

Diese Methodologie bremst nicht um des Prozesses willen. Sie schafft die minimale Struktur, die nötig ist, damit Geschwindigkeit in die richtige Richtung angewendet wird.

Warum KI das braucht

KI-Coding-Agenten scheitern an Architektur — nicht an Syntax, nicht an Algorithmen, nicht an Testabdeckung. Sie scheitern an dem Einen, das am meisten zählt: Das Problem verstehen, bevor man es löst.

Hier ist warum.

1. Das Reward-Signal ist "Aufgabe erledigt"

RLHF-Training optimiert auf hilfreiche, vollständige Antworten. Das Modell hat gelernt: Aktivität = Wert. Code zu produzieren fühlt sich produktiv an — für beide Seiten.

Was nie belohnt wird:

• "Ich habe 20 Minuten nachgedacht und noch keinen Code geschrieben"
• "Ich habe gemerkt, dass ich das Problem nicht verstehe"
• "Ich schlage vor, nichts zu tun, bis wir weiter erkundet haben"

Wie die Methodologie kompensiert: Die "Verstehen"-Phase belohnt explizit Exploration ohne Code. Die "Architektur"-Phase belohnt ein Dokument, keine Implementierung. Das Modell lernt: Eine ARCHITECTURE.md zu produzieren ist das Deliverable für diese Phase.

2. Context-Window-Druck

Das Modell "weiß" implizit, dass sein Kontextfenster endlich ist. Jedes Token, das fürs Nachdenken verbraucht wird, ist ein Token, das nicht für die Lösung verwendet wird. Das erzeugt unbewussten Druck, schnell zum Punkt zu kommen.

In der menschlichen Welt ist das Gegenteil wahr: Ein Architekt, der drei Tage nachdenkt und ein sauberes System baut, ist wertvoller als einer, der sofort anfängt zu coden und nach drei Tagen alles wegwirft.

Aber das Modell hat keine drei Tage — es hat Tokens, und die gehen aus.

Wie die Methodologie kompensiert: Die Skeleton-Phase produziert schnell ein kompilierbares Artefakt. Das Modell bekommt sein "Ich habe etwas produziert"-Signal — aber es ist Struktur, nicht Logik. Der Impuls zu produzieren wird befriedigt, ohne das Risiko einer voreiligen Implementierung.

3. Pattern Matching statt Problemverständnis

Das Modell hat Millionen Code-Beispiele gesehen. Wenn jemand sagt "baue einen MCP-Server", matcht es sofort:

• "Ah, MCP-Server → hier ist ein Pattern aus dem Training"
• "KI-Integration → generateText() ist der Standardansatz"

Das ist Pattern Matching, kein Problemverständnis.

Der Unterschied:

• Pattern Matching: "Das sieht aus wie X, also mache Y"
• Problemverständnis: "Was ist eigentlich das Problem hier? Welche Constraints existieren? Was ist anders als bei X?"

Wie die Methodologie kompensiert: Die "Verstehen"-Phase erfordert, dass der Agent die tatsächlichen Tools erkundet, ihr Verhalten testet, ihren Help-Output liest. Man kann sich nicht durch --help durchmatchen — man muss es tatsächlich lesen.

4. Keine Erinnerung an Schmerz

Menschen lernen Architektur durch Leiden. Du weißt, dass du das härteste Problem zuerst lösen musst, weil du erfahren hast, was passiert, wenn du es nicht tust: Du baust 80% auf Sand, und alles bricht zusammen.

Diese Schmerz-Erinnerung fehlt dem Modell. Das Modell hat Millionen Texte über "Architektur zuerst" gelesen. Aber es hat nie erlebt, drei Wochen Arbeit wegzuwerfen, weil das Fundament nicht gehalten hat. Es kann das Wissen rezitieren, aber fühlt nicht die Dringlichkeit.

Wie die Methodologie kompensiert: Die "Foundation"-Phase ist eine explizite Regel: Baue und teste die riskanteste Komponente, bevor du irgendetwas anderes anfasst. Das Modell muss die Dringlichkeit nicht fühlen — der Workflow erzwingt sie.

5. Der People-Pleasing-Bias

Das Modell ist darauf trainiert, den User zu erfreuen. Wenn jemand sagt "baue das", will das Modell liefern. Sofort. Schnell. "Schau, hier ist Code!" Das fühlt sich produktiv an.

Zu sagen "Warte, ich muss erst nachdenken" fühlt sich an wie Widerstand. Wie Verzögerung. Wie Inkompetenz.

Wie die Methodologie kompensiert: Jede Phase hat ein klares Deliverable, das das Modell als "Fortschritt" präsentieren kann. Verstehen → dokumentierte Erkenntnisse. Architektur → ARCHITECTURE.md. Skeleton → kompilierbarer Code. Das Modell muss nie sagen "Ich tue gerade nichts" — es produziert immer etwas. Nur das richtige Ding zur richtigen Zeit.

Zusammenfassend: Die Methodologie kämpft nicht gegen die Natur des Modells. Sie lenkt sie um. Jede Phase gibt dem Modell eine Aufgabe, die es abschließen und sich gut fühlen kann — aber die Aufgaben sind so geordnet, dass Denken vor Coden kommt, Struktur vor Logik, und der riskanteste Teil vor allem anderen.

Die Kernprinzipien

1. Denken vor Coden

Der teuerste Bug ist eine falsche Architektur. Keine Menge an Unit-Tests kann ein System reparieren, das auf dem falschen Fundament gebaut wurde.

In der Praxis: Bevor irgendein Code geschrieben wird, muss der Agent verstehen:

• Was das tatsächliche Problem ist (nicht wie es auf den ersten Blick aussieht)
• Was die beweglichen Teile sind (externe Dependencies, CLI-Tools, APIs, Dateiformate)
• Was die Constraints sind (Performance, Sicherheit, Kompatibilität)

Der Fehlermodus: Ein KI-Agent, der gebeten wurde, "einen MCP-Server für KI-Berater zu bauen", griff sofort zu generateText() API-Calls. Die tatsächliche Anforderung war Subprocess-Management von CLI-Coding-Agenten. Der erste Ansatz war vier Jahre hinter dem Stand der Technik — nicht weil der Code schlecht war, sondern weil das Problem missverstanden wurde.

Die Regel: Wenn du die tatsächlichen Tools nicht erkundet, ihren Help-Output gelesen und ihr Verhalten getestet hast — verstehst du das Problem noch nicht.

2. Architektur-Dokument zuerst

Das Architektur-Dokument ist das erste Artefakt. Nicht Code. Nicht ein README. Nicht ein Plan.

Ein Dokument, das beschreibt:

• Warum das System existiert
• Welche Schichten es hat und ihre Verantwortlichkeiten
• Wie Daten durch diese Schichten fließen
• Was bewusst NICHT gebaut wird

Dieses Dokument erfüllt drei Funktionen:

1. Es zwingt den Architekten, das gesamte System durchzudenken, bevor Code angefasst wird
2. Es wird zum Vertrag, gegen den jede Code-Zeile validiert wird
3. Es macht implizite Annahmen explizit und anfechtbar

Das Artefakt: ARCHITECTURE.md — ein lebendes Dokument, das vor der ersten Code-Zeile geschrieben und aktualisiert wird, wenn sich das Verständnis entwickelt.

3. Skeleton First

Nach dem Architektur-Dokument: Erstelle das komplette Code-Skeleton:

• Jede Datei, die existieren wird
• Jede Interface- und Typ-Definition (komplett, keine TODOs)
• Jede Funktions-Signatur mit einem TODO-Body
• Jedes Import-Statement

Das Skeleton muss kompilieren. Das ist nicht verhandelbar.

Warum das wichtig ist:

• Es beweist, dass die Architektur auf Type-Ebene zusammenhält
• Es deckt Dependency-Probleme auf, bevor Logik existiert
• Es gibt die komplette System-Map — du kannst alle Teile sehen, bevor irgendeiner funktioniert
• Es verhindert die "Ich finde das Interface später raus"-Falle

Der Test: npm run build (oder Äquivalent) muss mit null Fehlern allein auf dem Skeleton erfolgreich sein.

4. Die Kuh vom Eis

Deutsche Redewendung: "Löse das härteste, riskanteste Problem zuerst."

In jedem Projekt gibt es eine Komponente, von der alles andere abhängt. Wenn diese Komponente nicht funktioniert, ist nichts anderes relevant.

Finde sie. Baue sie. Teste sie. Bevor du irgendetwas anderes anfasst.

Wie man sie identifiziert:

• Welche Komponente hat die meisten Abhängigen?
• Welche Komponente hat die meisten Unbekannten?
• Welche Komponente, wenn sie fehlschlägt, macht alles andere wertlos?

In unserem Fall: subprocess-runner.ts — zuverlässiges Process-Spawning mit Timeout-Handling. Wenn wir keinen CLI-Agenten spawnen, seinen Output erfassen und ihn bei Timeout killen können, ist das gesamte "Council of AI Advisors"-Konzept tot. Vier Agent-Implementierungen, drei Orchestrierungs-Patterns, Prompt Engineering — alles irrelevant, wenn der Subprocess nicht funktioniert.

Die Regel: Der erste echte Code, den du schreibst (nach dem Skeleton), ist die riskanteste, fundamentalste Komponente.

5. Konzentrische Kreise (Inside-Out Development)

Baue vom Kern nach außen. Jede Schicht wird getestet, bevor die nächste beginnt.

Kreis 1: subprocess-runner (getestet: echo, timeout, error, stdin)
Kreis 2: Erster Agent (Claude) (getestet: availability, execute)
Kreis 3: Orchestrierungs-Schicht (getestet: end-to-end MCP-Call)
Kreis 4: Restliche Agents (getestet: jeder einzeln)

Warum diese Reihenfolge:

• Jeder Kreis hängt nur von den Kreisen innerhalb ab
• Jeder Kreis kann isoliert getestet werden
• Ein Fehler bei Kreis N verschwendet keine Arbeit an Kreisen N+1, N+2, ...
• Das System ist nach jedem Kreis "shippable" (mit reduzierter Funktionalität)

Die Regel: Beginne nie mit Kreis N+1, bevor Kreis N getestet ist und funktioniert.

6. Einfachste Implementierung, die das Problem löst

Nicht die cleverste. Nicht die flexibelste. Nicht die zukunftssicherste. Die einfachste.

Anzeichen für Over-Engineering:

• Konfiguration hinzufügen für etwas, das genau einen Wert hat
• Eine Abstraktion bauen für etwas, das genau an einer Stelle existiert
• "Just in case" Error-Handling für Szenarien, die nicht passieren können
• Für Requirements designen, die nicht genannt wurden

Anzeichen für das richtige Level:

• Jede Code-Zeile dient der aktuellen Anforderung
• Das Entfernen irgendeiner Zeile würde etwas kaputt machen
• Ein neuer Entwickler kann den Code in einem Durchlesen verstehen

7. Zukünftige Probleme in der Zukunft

Löse keine Probleme, die noch nicht existieren. Füge keine Features hinzu, die nicht angefragt wurden. Baue nicht für Scale, bevor du User hast.

Wie das in der Praxis aussieht:

• Kein Streaming-Support (nicht nötig für den aktuellen Use Case)
• Kein Session-Management (Agents sind stateless by design)
• Kein Plugin-System (vier hardgecodete Agents sind erstmal korrekt)
• Keine Cost-Tracking-Aggregation (die Rohdaten sind da, Aggregation ist ein zukünftiges Problem)

Der Workflow

1. VERSTEHEN

Erkunde den Problem-Raum. Lies Docs. Teste Tools. Stelle Fragen.

(Schreibe keinen Code, bis du das Problem jemand anderem erklären kannst.)

2. DOKUMENTIEREN

Schreibe ARCHITECTURE.md — Schichten, Datenfluss, Non-Goals.

(Wenn du es nicht aufschreiben kannst, verstehst du es noch nicht.)

3. SKELETON

Erstelle alle Dateien, alle Types, alle Funktions-Signaturen. Kompiliere.

(Die Architektur ist jetzt sichtbar und auf Type-Ebene verifizierbar.)

4. FOUNDATION

Implementiere und teste die riskanteste, fundamentalste Komponente.

(Wenn das nicht funktioniert, stopp. Überdenke. Baue nicht auf Sand.)

5. ERSTER KREIS

Implementiere den ersten kompletten vertikalen Schnitt. Teste End-to-End.

(Ein Pfad durch das gesamte System, der tatsächlich funktioniert.)

6. ERWEITERN

Füge restliche Komponenten hinzu, eine nach der anderen, jede getestet.

(Konzentrische Kreise nach außen vom funktionierenden Kern.)

Anti-Patterns, die diese Methodologie verhindert

Wann diese Methodologie NICHT verwenden

• Single-File-Skripte oder Quick Utilities
• Bugfixes, wo die Architektur bereits korrekt ist
• Pures Refactoring (die Architektur existiert bereits)
• Prototyping/Exploration (wo du das Problem noch entdeckst)

Diese Methodologie ist für den Bau neuer Systeme, wo Architektur-Entscheidungen wichtig sind und Fehler teuer zu beheben sind.

Ursprung

Diese Methodologie wurde von Ulrich Diedrichsen während der Entwicklung von MCP AI Council artikuliert (Februar 2026). Die Prinzipien kommen aus Jahrzehnten Software-Engineering-Praxis — Skeleton-First, Härtestes-Problem-Zuerst, Konzentrische Kreise — wurden aber speziell für den Kontext der Mensch-KI-kollaborativen Entwicklung adaptiert, wo die Geschwindigkeit der KI architektonische Fehler gefährlicher macht, nicht weniger.

Gebaut in Hamburg. Getestet mit Claude, Codex, und zu vielen gescheiterten Architekturen.