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

---

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.

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 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). 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 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.

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.