---
number: 123
lang: de
title: "Works as designed: Warum Repo-Struktur und Architektur wichtig sind"
date: 2026-10-16
stability: stable
review_by: 2028-10-16
author: "Stefan Wendel"
coauthor: "Claude Opus 5.5"
coauthor_id: claude-opus-5-5
---
# Works as designed: Warum Repo-Struktur und Architektur wichtig sind

**Die 1-n-Regel: ein Business-Repo, n Arbeits-Repos, und jedes Arbeits-Repo verweist per Link-Back auf das Business-Repo.**

2026-10-16 · Stefan Wendel · Claude Opus 5.5

---

<figure class="cartoon">
  <img src="/cartoons/0123-de-v1.svg" width="520" height="420" alt="Wohnzimmer: Ein frisch aufgebauter Kleiderschrank steht deutlich schief. Daneben liegt ein Haufen übrig gebliebener Teile, halb so hoch wie der Schrank: gestapelte Bretter, eine ganze Tür, ein Einlegeboden, ein Beutel Schrauben, überall Schrauben und Dübel. Ein Paar steht Arm in Arm davor und betrachtet zufrieden sein Werk." />
  <figcaption>„Funktioniert doch. Die übrigen Teile waren bestimmt nur Architektur.“</figcaption>
</figure>

Bei 1001lessons.io arbeiten jeden Tag mehrere Agenten am Code: Analyse, Weiterentwicklung, Fixes, Quality-Scans. Damit diese Agenten nicht jedes Mal raten müssen, wo sie etwas finden oder wie etwas funktioniert, ist unser Repo-Setup bewusst einfach.

**Ein Business-Repo für alles Übergreifende**, gegliedert wie ein kleines Unternehmen:

- `product/` – Spezifikation, Architektur, Prototypen, Runbooks, Entscheidungen
- `marketing/` – Positionierung, Zielgruppen, Texte, Videos
- `strategy/` – Betriebsmodell, Prinzipien, Haltungen, Risiken

**Ein Arbeits-Repo pro Subdomain und/oder Komponente**: Backend-Core, Frontend, API-Verträge (OpenAPI), Infrastruktur, Landing Page, Blog. Jedes dieser Arbeits-Repos hat eine eigene `CLAUDE.md`: Was ist dieses Repo, welche Doku liegt hier (und nicht im Business-Repo), und wo findet der Agent alles andere? Der letzte Punkt ist der „Link-Back“ aus [#0120](/120).

**Doku gehört in die Arbeits-Repos.** Dafür gibt es eine einfache Faustregel: Alles, was sich im selben Pull Request wie der Code ändert, gehört in dieses Repo. So liegen zum Beispiel alle unsere knapp 60 ADRs (Architecture Decision Records) im Core-Repo, weil es Entscheidungen über den Core sind. Das Frontend hat seine eigenen ADRs, weil sie nur das Frontend betreffen. Coding Guidelines, Threat Model, IAM-Doku: jeweils dort, wo der Code dazu liegt. Das ist mit [Shift Into](/101) gemeint: Die Doku wird Teil des Codes und muss in letzter Konsequenz auch beim Code liegen.

Das Business-Repo folgt derselben Regel. Was sich mit keinem einzelnen Code-Teil ändert – Produktentscheidungen, Spezifikation, Marketing, Strategie –, gehört dorthin.

**Strukturiere Deine Repos fachlich, damit sich die Agenten leichter zurechtfinden.**

Was uns Menschen das Leben einfacher macht, macht es auch Agenten einfacher. Domain-Driven Design hat uns gute Vorschläge gemacht, wie man komplexe Softwareprodukte so schneidet, dass man sich darin zurechtfindet. Diese Prinzipien wenden wir auch hier an, entgegen der These, AI schreibe ohnehin bald direkt Binärcode und Struktur sei dann egal ([Elon Musk, Anfang 2026](https://hackernoon.com/elon-wants-ai-to-skip-code-and-spit-out-binaries-thats-not-progress)). Gute Architekturprinzipien helfen, eine saubere Struktur aufzusetzen und – das ist fast wichtiger – sie während der Entwicklung konsequent einzuhalten. Je mehr Code die AI generiert, desto wichtiger ist eine klare, konsequent eingehaltene Grundstruktur. Sie steht in unseren Coding Guidelines und wird mit jedem Build durch [ArchUnit](https://www.archunit.org/) geprüft; bei uns schrittweise, Modul für Modul, derzeit für Billing, Pricing und Löschung. Konkret:

- *Domain-Driven Design:* fachliche Packages statt technischer Schichten, etwa `domain/auth`, `domain/accesscontrol`, `domain/erasure`.
- *Ports and Adapters* (Onion-Architektur): die Domäne in der Mitte, alles Externe außen herum, etwa `portsadapters/slackapi`, `portsadapters/stripe`, `portsadapters/cognito`. Die Domäne kennt weder Slack noch Stripe.

Ein Beispiel: Ein Agent, der Löschanfragen ändern soll, landet ohne Suche in `domain/erasure`. Der Diff bleibt klein und an einer Stelle.

**Und wenn mehrere Agenten gleichzeitig arbeiten?** Dann bekommt jeder eine eigene Git-Worktree mit eigenem Port-Slot. Das ist ein Thema für sich: [#0119 git worktree reicht nicht](/119).

**Die Lesson:** Doku liegt dort, wo sie sich ändert, und jedes Repo sagt in seiner `CLAUDE.md`, wo der Rest liegt. Doku ist Code: [Shift Into](/101).