Was macht Codebase-Architektur verbessern?
Erkunde eine Codebasis, wie es eine KI tun würde, decke architektonische Reibung auf, entdecke Möglichkeiten zur Verbesserung der Testbarkeit und schlage Modulvertiefungs-Refactorings als GitHub-Issue-RFCs vor.
Ein tiefes Modul (John Ousterhout, „A Philosophy of Software Design“) hat eine kleine Schnittstelle, die eine große Implementierung verbirgt. Tiefe Module sind testbarer, KI-navigierbarer und ermöglichen Tests an der Grenzfläche statt im Inneren.
Prozess
1. Erkunde die Codebase
Verwende das Agent-Tool mit subagent_type=Explore, um die Codebase natürlich zu durchsuchen. Folge KEINEN starren Heuristiken – erkunde organisch und notiere, wo du auf Reibung stößt:
- Wo erfordert das Verständnis eines Konzepts das Springen zwischen vielen kleinen Dateien?
- Wo sind Module so flach, dass die Schnittstelle fast so komplex ist wie die Implementierung?
- Wo wurden reine Funktionen nur aus Gründen der Testbarkeit extrahiert, aber die eigentlichen Fehler verstecken sich darin, wie sie aufgerufen werden?
- Wo erzeugen eng gekoppelte Module Integrationsrisiken in den Nähten zwischen ihnen?
- Welche Teile der Codebasis sind ungetestet oder schwer zu testen?
Die Reibung, die du erfährst, IST das Signal.
2. Präsentiere Kandidaten
Präsentiere eine nummerierte Liste von Vertiefungsmöglichkeiten. Zeige für jeden Kandidaten:
- Cluster: Welche Module/Konzepte sind beteiligt
- Warum sie gekoppelt sind: Gemeinsame Typen, Aufrufmuster, Mitbesitz eines Konzepts
- Abhängigkeitskategorie: Siehe REFERENCE.md für die vier Kategorien
- Testauswirkung: Welche vorhandenen Tests würden durch Boundary-Tests ersetzt
Schlage noch keine Schnittstellen vor. Frage den Nutzer: „Welche davon möchtest du erkunden?“
3. Nutzer wählt einen Kandidaten
4. Rahme das Problemfeld ein
Bevor du Sub-Agenten startest, schreibe eine nutzerorientierte Erklärung des Problemfelds für den gewählten Kandidaten:
- Die Einschränkungen, die jede neue Schnittstelle erfüllen müsste
- Die Abhängigkeiten, auf die sie angewiesen wäre
- Eine grobe, illustrative Codeskizze, um die Einschränkungen konkret zu machen – dies ist kein Vorschlag, sondern nur eine Möglichkeit, die Einschränkungen zu verankern
Zeige dies dem Nutzer und fahre dann sofort mit Schritt 5 fort. Der Nutzer liest und denkt über das Problem nach, während die Sub-Agenten parallel arbeiten.
5. Entwerfe mehrere Schnittstellen
Starte 3+ Sub-Agenten parallel mit dem Agent-Tool. Jeder muss eine radikal andere Schnittstelle für das vertiefte Modul erstellen.
Gib jedem Sub-Agenten ein separates technisches Briefing (Dateipfade, Kopplungsdetails, Abhängigkeitskategorie, was verborgen wird). Dieses Briefing ist unabhängig von der nutzerorientierten Erklärung in Schritt 4. Gib jedem Agenten eine andere Design-Einschränkung:
- Agent 1: „Minimiere die Schnittstelle – strebe maximal 1-3 Einstiegspunkte an“
- Agent 2: „Maximiere Flexibilität – unterstütze viele Anwendungsfälle und Erweiterungen“
- Agent 3: „Optimiere für den häufigsten Aufrufer – mach den Standardfall trivial“
- Agent 4 (falls zutreffend): „Entwirf nach dem Ports & Adapters-Muster für grenzüberschreitende Abhängigkeiten“
Jeder Sub-Agent gibt aus:
- Schnittstellensignatur (Typen, Methoden, Parameter)
- Nutzungsbeispiel, das zeigt, wie Aufrufer es verwenden
- Welche Komplexität es intern verbirgt
- Abhängigkeitsstrategie (wie Abhängigkeiten behandelt werden – siehe REFERENCE.md)
- Kompromisse
Präsentiere die Entwürfe nacheinander und vergleiche sie dann in Prosa.
Nach dem Vergleich gib deine eigene Empfehlung: welcher Entwurf deiner Meinung nach am stärksten ist und warum. Wenn Elemente verschiedener Entwürfe gut zusammenpassen, schlage einen Hybriden vor. Sei meinungsstark – der Nutzer möchte eine klare Einschätzung, nicht nur ein Menü.
6. Nutzer wählt eine Schnittstelle (oder akzeptiert die Empfehlung)
7. Erstelle GitHub-Issue
Erstelle ein Refactoring-RFC als GitHub-Issue mit gh issue create. Verwende die Vorlage in REFERENCE.md. Bitte den Nutzer NICHT um Überprüfung vor der Erstellung – erstelle es einfach und teile die URL.