Ich habe den improve-codebase-architecture-Skill für ein Projekt ausgeführt, an das ich seit November arbeite. Sonnet 4.6 verbrachte elf Minuten damit, meinen Code zu lesen, öffnete einen Markdown-Bericht in meinem Editor und listete sechs Dinge auf, von denen es glaubte, dass sie leise unter mir verrotteten.
Den ersten habe ich verworfen. Mit dem zweiten habe ich gestritten. Der dritte ließ mich zusammenzucken, in die Küche gehen, Kaffee einschenken, den ich nicht wollte, und zurückkommen, um ihn noch einmal zu lesen.
Es wurden zwei parallele Implementierungen desselben Konzepts gefunden – eine in meinem Frontend, eine in meinem Backend –, die in völlig unterschiedlichen Ordnern lagen, völlig unterschiedlichen mentalen Modellen gehörten und keine einheitliche Verbindung zwischen ihnen hatten. Sie trieben. Ich hatte drei Wochen zuvor einen Fehler gemeldet, dessen Ursache genau diese Abweichung war. Ich hatte die beiden Ereignisse nicht miteinander verbunden. Die Fähigkeit verband sie in einem Absatz.
Das ist der Moment, in dem ich aufhörte, diesen Skill als ein weiteres GitHub-Repo zu betrachten, und begann, ihn als das Einzige zu betrachten, was zwischen mir und der Codebasis steht, auf die ich zusteuere, wenn ich ohne architektonischen Druck weiterhin mit AI-Geschwindigkeit ausliefere.
Wenn Sie bis zum ersten Quartal 2026 in Claude Code Vibe-Coding betrieben haben und sich Ihre Codebasis langsam schwerer anfühlt, als sie sollte – schwerfällig in der Navigation, beängstigend beim Refactoring, voller kleiner Module, die scheinbar alle auf eine Weise voneinander abhängig sind, die Sie nicht auf einem Whiteboard zeichnen können – ist dieser Beitrag genau das Richtige für Sie. In den nächsten 4.000 Wörtern geht es darum, warum das passiert, was John Ousterhout vor zwanzig Jahren herausgefunden hat, was es reparierbar macht, und wie Matt Pococks improve-codebase-architecture-Fähigkeit das Problem in Claude Code umsetzt.
Die echten Kosten von schnellem Shipping mit AI
Hier ist das, was niemand auf die AI-Coding-Marketingseiten stellt.
Der Grund dafür, dass sich Claude Code in der zweiten Woche magisch und im vierten Monat schwer anfühlt, ist nicht, dass das Modell schlechter wird. Es liegt daran, dass Ihre Codebasis schneller schlechter wird, als Ihr Gehirn sie modellieren kann. Software hatte schon immer diese Eigenschaft – Ousterhout hat ein ganzes Buch darüber geschrieben, „A Philosophy of Software Design“, auf das ich gleich zurückkommen werde. Aber die Rate hat sich geändert. AI schreibt im Durchschnitt keinen besseren oder schlechteren Code als ich. Es schreibt Code fünf- bis zehnmal schneller als ich. Für jede architektonische Abkürzung benötige ich fünfzehn Minuten statt zwei Tage, was bedeutet, dass sich die Entropie auf einem Kalender zusammensetzt, an dem mein Urteilsvermögen nie geübt war.
Der technische Name für das, was passiert, ist Software-Entropie. Der codeförmige Name ist „Schlammball“. Das Gefühl, wenn Sie es erlebt haben, ist der Moment, in dem Sie eine Datei öffnen und feststellen, dass Sie nicht mehr wissen, wer diese Funktion aufruft, was sie zurückgibt, wenn die Eingabe fehlerhaft ist, oder ob eine Änderung die Testsuite oder die Produktion oder beides kaputt macht.
Dieses Gefühl habe ich bei dem oben erwähnten Projekt erreicht. Nicht, weil der Code schlecht war – das meiste davon wurde überprüft, das meiste hatte Tests, das meiste wurde in der Produktion für zahlende Benutzer ausgeführt. Das Problem war feinkörniger als „schlechter Code“. Das Problem war, dass ich dreißig Module hatte, wo ich zwölf brauchte. Zusammengehörige Konzepte waren auf mehrere Dateien aufgeteilt worden, da sich die Aufteilung in dem Moment, in dem ich jedes Stück schrieb, sauberer anfühlte. Die gesamten kognitiven Kosten dieser Aufteilungen waren nun höher als die kognitiven Kosten der Duplizierung, die sie vermieden hatten.
Das ist es, was AI beschleunigt. Die Entscheidung zum Aufteilen, Extrahieren und Abstrahieren ist günstig, wenn ein Agent dies in zwanzig Sekunden erledigen kann. Die Entscheidung ist so billig, dass ich sie ohne nachzudenken treffe. Das Ergebnis ist eine Codebasis in Form eines Fraktals aus kleinen, höflichen, individuell korrekten Modulen ohne Zentrum.
Ousterhout hat ein Wort für diese Form. Er nennt es flach. Der Fix hat auch einen Namen: deep modules. Die Fertigkeit, durch die ich Sie jetzt führen werde, ist das erste Tool, das ich verwendet habe und das den Fix umsetzt, ohne dass ich jeden Freitagnachmittag dreihundert Seiten eines Software-Designbuchs erneut lesen muss.
Deep Modules vs. flache Module – im Klartext
Bevor ich durch die Fertigkeit gehe, benötigen Sie den Wortschatz. Sobald Sie es haben, liest sich die Ausgabe des Skills wie Englisch. Ohne sie sieht der Bericht wie eine Refactoring-Einkaufsliste aus.
Ein Modul ist eine Einheit Ihrer Anwendung mit einer klaren Grenze. In einer React-App kann ein Modul eine Komponente sein. In einem Knotendienst kann es sich um eine Funktion, eine Klasse oder einen Ordner handeln. Was es zu einem Modul macht, ist nicht seine Größe – es ist die Tatsache, dass es ein Außen und ein Innen gibt und das Innere verborgen ist.
Die Schnittstelle ist das, was jemand lernen muss, um das Modul von außen nutzen zu können. Funktionssignaturen. Komponenten-Requisiten. Öffentliche Methoden. Dokumentation. Typdefinitionen. Alles, was ein Anrufer in seinen Kopf laden muss, damit das Modul seine Arbeit erledigt.
Die Implementierung umfasst alles innerhalb der Grenze, von dem der Aufrufer nichts wissen muss. Schleifen, Helfer, Zustandsautomaten, Datenbankabfragen, Wiederholungsversuche – die eigentliche Arbeit.
Jetzt kommt der Teil, der zählt.
Ein tiefes Modul hat eine kleine Schnittstelle und eine komplexe Implementierung. Sie lernen zehn Dinge darüber und es erledigt tausend Dinge für Sie. Die Leverage Ratio – das pro gelernter Schnittstelleneinheit zugängliche Verhalten – ist hoch. Ousterhouts klassisches Beispiel ist der Unix-Dateisystemaufruf read(fd, buf, n). Drei Argumente. Dahinter verbergen sich jahrzehntelange Betriebssystemkomplexität. Sie denken nicht an Festplattengeometrie, Seitencaches oder Blockzuordnung. Sie fragen nach n Bytes. Sie erhalten n Bytes.
Ein flaches Modul verfügt über eine Schnittstelle, die ungefähr so komplex ist wie die Implementierung, die es verbirgt. Sie lernen zehn Dinge darüber und es erledigt elf Dinge für Sie. Oder im schlimmsten Fall lernen Sie zehn Dinge darüber und es erledigt acht Dinge für Sie, weil die Schnittstelle mehr Lecks enthält, als die Implementierung enthält. Die Leverage Ratio liegt nahe eins. Das Modul zahlt kaum seine Miete.
Hier ist ein konkretes Paar. Bleiben Sie bei mir – das ist der Moment, in dem das Vokabular landet.
// SHALLOW: this module's interface is bigger than what it hides
export class UserAuthHelper {
hashPassword(password: string, salt: string): Promise<string>;
generateSalt(): string;
verifyPasswordAgainstHash(password: string, hash: string, salt: string): Promise<boolean>;
isPasswordStrongEnough(password: string): boolean;
getMinimumPasswordLength(): number;
getMaximumPasswordLength(): number;
generateSessionToken(userId: string): string;
validateSessionToken(token: string): { userId: string } | null;
revokeSessionToken(token: string): Promise<void>;
}
Das liest man und spürt es schon. Um dieses Ding nutzen zu können, muss ich über Salts, Hashes, Sitzungstoken, Passwortregeln und Widerruf Bescheid wissen, allesamt Implementierungsdetails der Authentifizierung. Die Schnittstelle lässt das Innere des Moduls in das Gehirn jedes Anrufers dringen.
Jetzt die tiefe Version desselben.
// DEEP: small interface, the complexity is locked inside
export class Auth {
signIn(email: string, password: string): Promise<Session>;
signOut(session: Session): Promise<void>;
currentUser(session: Session): Promise<User | null>;
}
Drei Methoden. Salts, Hashes, Sitzungsgenerierung, Passwortregeln, Widerruf, Ablauf, Aktualisierungstoken – all das befindet sich in signIn, signOut und currentUser. Der Anrufer muss davon nichts wissen. Wenn ich nächsten Monat von bcrypt auf argon2 migrieren möchte, ändert sich kein Anrufer. Wenn ich Multi-Faktor-Authentifizierung hinzufügen möchte, bleibt die Schnittstelle gleich – signIn wird hinter der Naht nur noch umfangreicher.
Das ist die Bewegung, nach der die Fertigkeit sucht. Jede Gelegenheit zur Vertiefung ist im Kern eine Gelegenheit, die zweite Form anzunehmen und die erste zu vertuschen.
Bevor wir fortfahren, benötigen Sie noch einen weiteren Wortschatz.
Lokalität gibt an, wie verwandte Funktionen in der Codebasis gruppiert werden. Hohe Lokalität bedeutet, dass die Dinge, die sich gemeinsam verändern, nebeneinander leben. Geringe Lokalität bedeutet, dass zum Ändern einer Funktion Dateien in drei Ordnern bearbeitet werden müssen, die nicht einmal voneinander wissen. Der flache UserAuthHelper oben hat eine mittlere Lokalität – zumindest ist es eine Klasse. Der Fehler, den ich in meinem Projekt gefunden habe, hatte eine niedrige Lokalität – die authentifizierte Logik wurde in apps/web/src/lib/session.ts und services/api/src/auth/session.go dupliziert, ohne gemeinsame Typen und ohne erzwungenen Vertrag zwischen ihnen.
Eine Vertiefung verbessert in der Regel automatisch die Lokalität. Wenn Sie drei shallow modules in einem tiefen Modul zusammenfassen, wird der zugehörige Code in dieselbe Datei verschoben, was bedeutet, dass die nächste Person, die ihn bearbeitet (wahrscheinlich der zukünftige ich, um 23 Uhr, in zwei Monaten), alles auf einmal sehen kann.
Was der Skill tatsächlich bewirkt
Der improve-codebase-architecture-Skill, der von Matt Pocock geschrieben und als Teil seines Open-Source-Skills-Repositorys (https://github.com/mattpocock/skills) ausgeliefert wird, ist ein kleines Markdown-Paket, das die Art und Weise, wie Claude Code Ihr Repository liest, neu gestaltet. Sie installieren es wie jeden anderen Skill – legen Sie es in ~/.claude/skills/ ab oder verwenden Sie den Installationsbefehl von README – und wenn Sie Claude Code von da an bitten, nach Refactoring-Möglichkeiten zu suchen, geschieht dies durch Ousterhouts Linse statt durch generische „Code-Geruch“-Heuristiken.
Mechanisch bewirkt die Fertigkeit drei Dinge.
Zunächst wird das Repo mit einer bestimmten Frage gescannt: Wo sind die shallow modules geclustert? Es wird nicht nach einzelnen fehlerhaften Dateien gesucht. Es wird nach Clustern kleiner Module gesucht, die eng miteinander verbunden sind, wobei jedes einzelne über eine Schnittstelle verfügt, die fast so komplex ist wie seine Implementierung, und bei denen Sie beim Lesen des Codes die Reibung beim Bewegen zwischen ihnen spüren können.
Zweitens wird eine Liste von Vertiefungsmöglichkeiten erstellt – meiner Erfahrung nach normalerweise zwischen drei und zehn –, die jeweils als kurzer Vorschlag verfasst sind: Welche Module zusammengeführt werden sollen, wie die neue Schnittstelle aussehen sollte, wo die Testnaht angesiedelt wäre und welche Risiken der Refactor mit sich bringt. Der Vorschlag soll von einem Menschen gelesen, mit ihm diskutiert und entweder angenommen, geändert oder abgelehnt werden.
Drittens: Wenn Sie einen Vorschlag annehmen, tritt der Skill in einen interaktiven Designdurchgang ein. Claude schlägt die neue Schnittstelle vor, Sie ändern Namen und Formen, das Modell wird überarbeitet und sobald die Schnittstelle festgelegt ist, schlägt es eine Implementierungsstrategie vor. Die Strategie umfasst, wie Anrufer migriert werden und wo die Testgrenze gesetzt wird. Wenn Sie grünes Licht geben, reicht der Skill ein GitHub-Problem ein (oder einen anderen Issue-Tracker, den Sie angeschlossen haben), sodass die Arbeit auch dann nachverfolgt wird, wenn Sie sie an diesem Tag nicht erledigen.
Die beiden Dinge möchte ich hervorheben. Der Skill führt kein eigenständiges Refactoring Ihres Codes durch. Es zeigt Chancen auf und hilft Ihnen beim Nachdenken. Der Mensch macht jede architektonische Entscheidung. Und die Fähigkeit ist eigensinnig – sie bevorzugt insbesondere weniger, tiefere Module gegenüber mehr, kleineren Modulen. Wenn Ihr Team eine starke kulturelle Präferenz in die andere Richtung hat, werden Sie dagegen ankämpfen.
Der Tag, an dem ich es auf meinem eigenen Repo ausgeführt habe
Das Repo, das ich getestet habe, war ein SaaS-Dashboard, an das ich seit November wöchentlich versende. Etwa 1.500 Commits, die meisten von mir, gelegentlich paarprogrammiert mit Claude Code. TypeScript über den gesamten Stack, React Router im Frontend, ein Node-Dienst im Hintergrund, eine Postgres-Datenbank darunter. Echte Benutzer. Echte Käfer. Echte kognitive Kosten, jedes Mal, wenn ich es öffne.
Ich habe einen Sonntagmorgen abgeräumt, Kaffee gekocht und eine Eingabeaufforderung ausgeführt:
Nutzen Sie den Skill improve-codebase-architecture. Scannen Sie dieses Repo und erstellen Sie eine Liste der Vertiefungsmöglichkeiten, geordnet nach Auswirkung.
Elf Minuten. Sechs Möglichkeiten.
Ich werde drei davon durchgehen, da die anderen drei Variationen derselben Muster waren und Sie daraus die Form erhalten.
Gelegenheit 1: Das Konzept der duplizierten Sitzung. Das war es, was mich dazu brachte, den Kaffee wegzustellen. Der Skill zeigte an, dass apps/web/src/lib/session.ts und Es gab verschiedene Typen. Andere Benennung. Unterschiedliche Fehlersemantik. Das Frontend behandelte abgelaufene Sitzungen stillschweigend als „Benutzer abmelden“. Das Backend gab einen 401-Fehler zurück. Es gab keinen gemeinsamen Vertrag zwischen ihnen, was bedeutete, dass sich jede Abweichung zwischen den beiden als UX-Fehler manifestieren würde. Der Vorschlag des Skills: Definieren Sie ein einzelnes Session-Modul mit einer Schnittstelle (in einem gemeinsamen Schema eingegeben), einer kanonischen Zustandsmaschine (ausgedrückt in OpenAPI plus einem generierten Client) und einem Adapter auf jeder Seite, der die Schnittstelle in der lokalen Umgebung implementiert.
Zwei Adapter, eine Schnittstelle. Eine echte Naht. Ich hatte drei Wochen zuvor einen sitzungsbezogenen Fehler gemeldet. Die Fähigkeit wusste das nicht. Die Fähigkeit sah die Architektur und sagte allein anhand der Architektur die Form des Käfers voraus.
Gelegenheit 2: Der fragmentierte Logger. Ich hatte vier Protokollierungsdienstprogramme. Ein console.log-Wrapper im Frontend. Eine pino-Konfiguration im Backend. Ein „strukturierter Ereignis“-Helfer für Analysen. Ein „Telemetriespannen“-Helfer für die Ablaufverfolgung. Jedes einzelne wurde separat hinzugefügt, um einem echten Bedarf gerecht zu werden. Jeder einzelne sah für sich genommen sauber aus. Zusammen bedeuteten sie, dass ich, wenn ich den Fluss eines bestimmten Benutzers über den Stack debuggen wollte, vier Protokollsätze in vier verschiedenen Formaten lesen musste. Der Vorschlag des Skills: ein einzelnes Observability-Modul mit einer Schnittstelle – event(name, payload), error(err, context), span(name, fn) – und vier Adaptern, die sich auf die vorhandenen Transporte verteilen. Gleiche Anrufseiten. Gleiche Ausgänge. Eine Schnittstelle, die ich lernen kann, vier Implementierungen dahinter. Dies war eine reine Vertiefung – keine Funktionalität verloren, das Leben der Anrufer deutlich vereinfacht.
Gelegenheit 3: Die, mit der ich gestritten habe. Der Skill hat meine Formularvalidierungshelfer als vertiefende Gelegenheit gekennzeichnet. Ich hatte validateEmail, validatePhone, validateRequired und ein halbes Dutzend andere, jede davon eine kleine reine Funktion. Der Vorschlag: Reduzieren Sie sie in ein einziges Validator-Modul mit einem fließenden API. Ich drängte zurück. Reine Funktionen sind normalerweise tiefer, als sie aussehen – validateEmail(email) hat eine winzige Schnittstelle und eine nicht triviale Implementierung (RFC 5322 ist nicht freundlich), und die Hebelwirkung ist in Ordnung. Das Gegenargument des Skills betraf die Lokalität: Die Validatoren wurden zusammen, in Clustern, in jedem Formular verwendet, und der umgebende Code musste sechs verschiedene Funktionen statt einer importieren.
Nach zehn Minuten Hin und Her im Chat räumte ich ein, dass das Lokalitätsargument real war, schlug jedoch einen Kompromiss vor: Behalten Sie die reinen Funktionen bei und fügen Sie ein Form-Modul mit einem flüssigen API hinzu, das sie zusammensetzt. Der Fachmann stimmte zu, entwarf die neue Form und reichte die Beschwerde ein. Das war der Moment, in dem ich diesem Ding vertraute.
Die anderen drei Möglichkeiten betrafen ein Router-Statusmodul, in dem eine Zustandsmaschine entstanden war, eine Zahlungsintegration, die Webhook-Details in den UI-Code durchsickerte, und ein Feature-Flag-System, das sich still und leise in drei unabhängige Feature-Flag-Systeme verwandelt hatte. Alle drei bekamen Vorschläge. Zwei habe ich angenommen; eine, die ich auf das nächste Quartal verschoben habe.
Nähte und Adapter – Warum die Vertiefung Tests möglich macht
Hier ist der Teil der Fertigkeit, der direkt damit zusammenhängt, ob Ihre Codebasis testbar ist, und der Grund, warum das alles wichtiger ist als nur „Code sieht besser aus.“
Eine Naht ist eine Grenze in Ihrem Code, an der Sie eine Fälschung durch eine echte ersetzen können, ohne den umgebenden Code zu ändern. Michael Feathers hat es in „Working Effectively With Legacy Code“ so genannt – vor zwanzig Jahren, aber noch nie war es relevanter als im Jahr 2026. Die Schnittstelle eines Moduls ist seine natürliche Nahtstelle. Wenn das Modul über eine kleine, saubere Schnittstelle verfügt, können Sie zu Testzwecken eine Fälschung auf der anderen Seite dieser Schnittstelle anbringen. Wenn das Modul über eine weitläufige, undichte Schnittstelle verfügt, muss jeder Test auf zwölf verschiedene Arten vorgeben, real zu sein, und Sie hören auf, Tests zu schreiben, weil sie weh tun.
Ein Adapter ist die konkrete Implementierung, die auf der anderen Seite der Naht lebt. Das Echte spricht mit dem Echten – Postgres, dem Netzwerk, der Systemuhr. Die Fälschung gibt für den Test alles zurück, was Sie wollen.
Das sauberste Beispiel und das, mit dem ich dies jetzt meinem Team beibringe, ist die Systemuhr.
// The interface — a one-method module
interface Clock {
now(): Date;
}
// The real adapter
class SystemClock implements Clock {
now() { return new Date(); }
}
// The fake adapter, for tests
class FakeClock implements Clock {
constructor(private current: Date) {}
now() { return this.current; }
advance(ms: number) {
this.current = new Date(this.current.getTime() + ms);
}
}
Nun hängt jeder Code, der von der Zeit abhängt, von Clock ab, nicht von Date.now(). In der Produktion erhält es die echte Uhr. In Tests bekommt es eine gefälschte Uhr, die ich um eine Stunde, einen Tag, ein Jahr vorstellen kann. Jeder zeitabhängige Test, den ich geschrieben habe, war flockig. Jeder Test, den ich geschrieben habe, seit ich die Uhr mit zwei Adaptern in ein tiefes Modul extrahiert habe, ist deterministisch.
Der Skill liebt diese Art von Refactoring. Wenn es ein Repo scannt, stellt es bei jedem Modul die Frage: Wo würde die Testnaht hingehen? Wenn die Antwort „nirgendwo offensichtlich ist – das Modul kommuniziert direkt mit der Datenbank und dem Netzwerk und der Uhr und dem Dateisystem gleichzeitig“, ist das eine vertiefende Chance. Die Lösung besteht darin, die Abhängigkeiten in Module mit eigenen Schnittstellen zu extrahieren und dann auf beiden Seiten Adapter einzufügen. Plötzlich wird jede Prüfung, die schmerzhaft war, einfach.
Das ist der Teil, der sich am schnellsten amortisiert. Die erste Vertiefung, die ich aus dem Bericht des Skills machte – das Sitzungsmodul – ersparte mir in der nächsten Woche einen ganzen Nachmittag, als ich einen Randfall mit Sitzungsablauf testen musste. Vor dem Refactor hätte ich eine Testdatenbank aufgebaut, einen HTTP-Aufruf simuliert und gebetet. Nach der Umgestaltung habe ich einen gefälschten Sitzungsadapter instanziiert, seinen Ablauf auf 30 Sekunden festgelegt und eine Assertion ausgeführt.
Die Legacy-Codebase-Falle (und wie man sie vermeidet)
Nun die Warnung, denn diesen Fehler hätte ich fast gemacht.
Wenn Sie diesen Skill auf einer älteren Codebasis ausführen – einer mit lückenhafter Testabdeckung, geringer Lokalität und überall shallow modules – besteht der erste Instinkt darin, den Bericht von oben nach unten zu bearbeiten. Nutzen Sie die größte Gelegenheit zur Vertiefung, führen Sie eine aggressive Umgestaltung durch und versenden Sie.
Nicht.
Der Grund, warum jeder leitende Ingenieur mit Narben an den Händen den gleichen Rat hat – nicht getesteten Code nicht umgestalten – liegt darin, dass shallow modules ohne Tests genau die Module sind, bei denen eine Vertiefung Dinge zerstören wird, von denen Sie nicht wussten, dass sie existieren. Anrufer sind auf undokumentiertes Verhalten angewiesen. Randgehäuse verstecken sich in den Ritzen zwischen den Modulen. Die Form der Käfer ist genau der Grund, warum die Module überhaupt flach waren.
Der richtige Schritt ist der unscheinbare. Schreiben Sie vor der Vertiefung Charakterisierungstests rund um das vorhandene flache Modul. Keine Unit-Tests. Keine perfekten Tests. Es handelt sich lediglich um Tests, die das aktuelle Verhalten – einschließlich des fehlerhaften Verhaltens – genau bestimmen, sodass Sie bei tiefergehender Betrachtung erkennen können, was sich geändert hat. Das Buch von Feathers ist hier die kanonische Referenz. Der Skill selbst empfiehlt in seinem README ungefähr den gleichen Workflow für Legacy-Code: Schreiben Sie Tests, die das aktuelle Verhalten des Clusters dokumentieren, den Sie vertiefen möchten, führen Sie den Vertiefungsvorschlag des Skills mit diesen Tests durch und verwenden Sie die Testdeltas als erzwingende Funktion für Designentscheidungen.
Ich befolge diese Regel jetzt auch bei Greenfield-Code. Wenn ein Vertiefungsvorschlag ein Modul betrifft, das keine Tests hat, ist der erste Commit im Refactor der Test-Commit. Das vertiefende Commit kommt an zweiter Stelle. Es verlangsamt mich um vielleicht zwanzig Minuten pro Refactoring und erspart mir eine Stunde später die Debugging-Sitzungen „Warte, warum ist das Dashboard jetzt leer?“. Den Handel werde ich jedes Mal in Anspruch nehmen.
Wie oft führe ich es jetzt aus (und wo es stolpert)
Ich führe den Skill jeden Montagmorgen für mein Hauptprojekt und ungefähr alle fünf Arbeitstage für Nebenprojekte mit hoher Commit-Geschwindigkeit aus. Dieser Rhythmus ergab sich aus einer einfachen Beobachtung: Bei einem Projekt, bei dem ich täglich mit Claude Code versende, sammelt sich die Entropie schnell genug an, dass eine wöchentliche Architekturüberprüfung sie tatsächlich erfasst, bevor sie erstarrt. Bei einem weitgehend stabilen Projekt ist eine monatliche Angabe in Ordnung.
Der Rhythmushinweis aus der Dokumentation des Skills lautet „alle paar Tage in schnelllebigen Codebasen“ und das deckt sich mit meiner Erfahrung. Wenn ich es zwei oder drei Wochen lang ruhen lasse, steigt der Bericht von sechs auf fünfzehn Gelegenheiten, und mit fünfzehn bekomme ich Entscheidungsmüdigkeit und fange an, den Bericht völlig zu ignorieren. Sechs ist die richtige Zahl, um tatsächlich zu handeln.
Nun der ehrliche Teil – wo die Fähigkeit ins Stolpern gerät.
Es ist schlecht in sprachspezifischen Redewendungen. Als ich es auf einem Go-Dienst ausführte, schlug es ständig klassenförmige Designs vor, die nicht zum Kern von Go passten. Das Vokabular von Modulen, Schnittstellen und Adaptern lässt sich übersetzen, aber die Form der Vorschläge ist auf TypeScript und Python ausgerichtet. Wenn Sie in einer Sprache sprechen, die eine starke eigene Meinung hat – Go, Rust, Elixir –, werden Sie die ersten fünf Minuten jedes Vorschlags damit verbringen, die Redewendung zu übersetzen.
Es ist auch blind für die Laufzeitkosten. Bei jedem Vorschlag, den ich erhalten habe, ging es um kognitive Kosten – wie einfach ist der Code zu verstehen, wie testbar ist die Naht – und keiner von ihnen berücksichtigte Dinge wie Speicherlayout, Zuordnungsmuster oder Hot-Path-Leistung. Für die meisten App-Codes ist das in Ordnung. Bei allem, was leistungsabhängig ist, müssen Sie Ihr eigenes Urteil darüber legen.
Und der dritte Stolperstein: Manchmal werden Vertiefungen vorgeschlagen, für deren Validierung ich die Testsuite neu schreiben müsste. Der Vorschlag sieht für sich genommen schön aus, aber die Kosten der Migration – einschließlich der Tests, die von der aktuellen Form abhängen – sind höher als der Wert der neuen Form. Die Fähigkeit modelliert Migrationskosten nicht sehr gut. Ich lese jetzt jeden Vorschlag mit einer Frage oben: Wie sieht die Migration aus und sind die Migrationskosten geringer als die Hebelwirkung, die ich gewinnen würde? In der Hälfte der Fälle lautet die Antwort „Ja“. Mit der anderen Hälfte schließe ich das Thema ab.
Wenn Sie die älteren Fertigkeiten wie die Karpathy CLAUDE.md-Installation oder einen der 32 täglichen Claude Code-Hacks ausgeführt haben, über die ich letzten Monat geschrieben habe, reiht sich diese Fertigkeit klar darüber ein. Die Hacks machen den Versand von Claude Code schneller. Die Architekturfähigkeit ist der architektonische Druck, der verhindert, dass die Geschwindigkeit Ihre Codebasis verrottet.
Die Frage, die ich jetzt mit mir herumtrage
Sechs Wochen, nachdem ich begonnen habe, diesen Skill wöchentlich auszuführen, unterscheidet sich meine Codebasis deutlich von der, die sie vorher hatte. Nicht wesentlich kleiner – ich habe nicht so viel Code gelöscht –, aber deutlich navigierbarer. Das Sitzungsmodul ist ein Ort. Das Observability-Modul ist ein Ort. Die Formkomposition hat eine einzige Vordertür. Wenn ich um 23 Uhr eine Datei öffne, um etwas zu debuggen, kann ich normalerweise das gesamte Konzept aus der Datei, in der ich mich befinde, erkennen, anstatt zwischen vier Dateien hin und her zu springen und die Architektur aus dem Speicher zu rekonstruieren.
Die wichtigere Änderung ist die Änderung vor der Codebasis. Wenn ich Claude Code auffordere, jetzt eine neue Funktion auszuliefern, denke ich zuerst in Modulen. Wo wird die Naht sein? Was ist die Schnittstelle? Wie sieht die tiefe Version davon aus? Der Skill hat mir beigebracht, diese Fragen zu stellen, bevor ich die Eingabeaufforderung schreibe, was bedeutet, dass die Eingabeaufforderungen selbst Code erzeugen, der bereits näher an dem liegt, was der nächste Scan des Skills vorschlagen würde.
Software-Entropie ist ein einseitiger Pfeil ohne architektonischen Druck. AI hat den Pfeil gerade schneller bewegt. Der Fix ist nicht langsamer AI. Die Lösung besteht in einem größeren Druck, der früher durch etwas ausgeübt wird, das mit der Versandrate skaliert. Der Skill
Wenn Sie etwas aus diesem Beitrag mitnehmen, nehmen Sie die Frage auf, die ich jetzt in jede Claude Code-Sitzung einbeziehe: Ist dieses Modul tiefer oder flacher als das, was es ersetzt? Stellen Sie es, bevor Sie die Eingabeaufforderung schreiben. Fragen Sie es noch einmal, wenn Sie den Unterschied lesen. Fragen Sie es am Montagmorgen beim Kaffee, während eine kleine Markdown-Datei Ihr Repo scannt und Ihnen die Dinge erzählt, die Sie bereits halb wussten, für die Sie aber zu müde waren.
Diese Frage bringt mehr für meinen Code als alle Fähigkeiten, Frameworks oder Refactoring-Tools, die ich in den letzten zwei Jahren installiert habe. Die Codebasis, an die Sie im Jahr 2027 liefern, wird die Codebasis sein, die diese Frage erstellt hat – oder die, die sie nicht erstellt hat.
Öffnen Sie den Bericht. Lesen Sie die sechs Dinge. Wählen Sie eine aus.
Häufig gestellte Fragen
Was ist der improve-codebase-architecture-Skill in Claude Code?
Es handelt sich um eine Open-Source-Fähigkeit von Matt Pocock, die ein Repository nach shallow modules durchsucht und vertiefende Refaktoren vorschlägt. Es läuft in Claude Code, erstellt eine Liste von Architekturmöglichkeiten und hilft Ihnen beim interaktiven Entwerfen der neuen Schnittstellen. Die vollständige Anleitung zu dem, was in meinem Repo gefunden wurde, finden Sie oben unter „Der Tag, an dem ich es in meinem eigenen Repo ausgeführt habe“.
Was ist ein Deep-Modul im Software-Design?
Ein tiefes Modul ist ein Modul mit einer einfachen Schnittstelle und einer komplexen Implementierung, sodass ein Aufrufer sehr wenig über das Modul erfährt, aber im Gegenzug viel Verhalten erhält. Der Begriff stammt aus John Ousterhouts „A Philosophy of Software Design“. Im Gegensatz dazu verfügen flache Module über Schnittstellen, die fast so komplex sind wie ihre Implementierungen, und bieten eine geringe Hebelwirkung.
Wie oft sollte ich den Codebase-Architektur-Skill ausführen?
Alle paar Tage bei schnelllebigen Codebasen mit täglichen AI-unterstützten Commits und wöchentlich bis monatlich bei stabileren Repos. Nach drei Wochen des Schweigens wächst der Bericht auf mehr als zehn Gelegenheiten an, und Entscheidungsmüdigkeit setzt ein. Sechs Gelegenheiten pro Woche sind der optimale Zeitpunkt, um die Vorschläge tatsächlich umzusetzen.
Führt der Skill-Refactor-Code automatisch durch?
Nein, und das ist Absicht. Es zeigt vertiefende Möglichkeiten auf und hilft Ihnen beim Entwerfen der neuen Schnittstelle und Naht, aber der Mensch trifft jede architektonische Entscheidung und genehmigt jede Änderung. Sobald Sie einen Vorschlag annehmen, kann ein GitHub-Problem eingereicht werden, um den Refaktor zu verfolgen.
Sollte ich Module in einer Legacy-Codebasis ohne Tests vertiefen?
Nicht direkt. Schreiben Sie zunächst Charakterisierungstests rund um den flachen Cluster, um das vorhandene Verhalten festzulegen, und vertiefen Sie sie dann mit den Tests als Sicherheitsnetz. Die Vertiefung des ungetesteten shallow modules ist eine der schnellsten Möglichkeiten, eine Regression zu versenden.
Lassen Sie uns zusammenarbeiten
Möchten Sie AI-Systeme aufbauen, Arbeitsabläufe automatisieren oder Ihre technische Infrastruktur skalieren? Ich würde gerne helfen.
- Fiverr (benutzerdefinierte Builds und Integrationen): fiverr.com/s/EgxYmWD
- Portfolio: mejba.me
- Ramlit Limited (Unternehmenslösungen): ramlit.com
- ColorPark (Design & Branding): colorpark.io
- xCyberSecurity (Sicherheitsdienste): xcybersecurity.io
