Piyush-Nagar/coding-agents-skills

Code wird weitaus häufiger gelesen als geschrieben. Wartbarkeit ist das, was eine 3 Jahre alte Codebasis, die eine Freude ist, von einer unterscheidet, die ein Teergraben ist. Optimiere für den nächsten Entwickler, der vielleicht in sechs Monaten Du selbst bist.

Was ist coding-agents-skills?

Dieser Skill konzentriert sich auf die langfristige Wartbarkeit von Codebasen, ein entscheidendes Merkmal für professionelle Softwareentwicklung. Er basiert auf der Erkenntnis, dass Code weitaus häufiger gelesen als geschrieben wird, und bietet eine Reihe von Regeln, die sicherstellen, dass eine Codebasis auch nach Jahren noch zugänglich und erweiterbar bleibt. Der Skill unterstützt allgemeine Softwareentwicklungsplattformen und -sprachen, da er Prinzipien wie Feature-basierte Paketierung, den Einsatz von Interfaces nur an Modulgrenzen, die Vermeidung von totem Code und die Bevorzugung kleiner, reiner Funktionen betont. Zusätzlich werden klare Warnsignale (Red Flags) definiert, wie z. B. Dateien über 500 Zeilen oder gemeinsame `utils`-Pakete, die auf strukturelle Probleme hinweisen. Entwickler lernen, wie sie durch Dependency Injection, versionierte öffentliche APIs, strikte CI-Prüfungen und regelmäßige Abhängigkeitsaktualisierungen die Wartbarkeit ihrer Projekte drastisch verbessern können.

Funktioniert mit✓Claude Code~Codex CLI~Cursor

npx skills add https://github.com/Piyush-Nagar/coding-agents-skills/tree/HEAD/backend/core/nfr/maintainability

Dokumentation

Wartbarkeit

Regeln

Eine Funktion, ein Ort. Paketieren nach Feature (siehe backend/core/SKILL.md). Eine einzelne Änderung sollte benachbarte Dateien betreffen, nicht verstreute Ebenen.
Interfaces nur an Modulgrenzen. Innerhalb eines Features sind konkrete Klassen in Ordnung. Interfaces existieren, damit Aufrufer sich auf Verträge über Grenzen hinweg verlassen können, nicht um jede Klasse zu dekorieren.
Löschen, nicht auskommentieren. Toter Code und // TODO-ewige Kommentare vergammeln. Git erinnert sich; die IDE muss es nicht.
Bevorzuge kleine, reine Funktionen. Einfacher zu testen, einfacher zu durchdenken, einfacher zu kombinieren. Seiteneffekte an den Rändern des Systems, nicht überall verstreut.
Tests decken Verhalten ab, nicht Implementierung. Eine Umschreibung von Interna sollte Tests nicht brechen. Tut sie es doch, ist der Test an die falsche Sache gekoppelt.
Öffentliche APIs sind versioniert. Breaking Changes hinter einer neuen Version oder einem Feature-Flag – niemals eine stille Umbenennung.
Dependency Injection statt statischer Singletons. Statische sind nicht testbar und verstecken Kopplung. Übergib Abhängigkeiten; mocke sie in Tests.
Abhängigkeiten festlegen und regelmäßig aktualisieren. Lockfiles committet; Renovate/Dependabot erstellt automatisch PRs. Zwei Jahre zurückzufallen bedeutet eine ungeplante zweiwöchige Migration.
Dokumentiere das „Warum“, nicht das „Was“. Code zeigt das Was; Kommentare erklären die Geschäftsregel, die historische Einschränkung, den nicht offensichtlichen Kompromiss.
Linten, formatieren und typüberprüfen in CI. Nicht empfehlend, sondern blockierend. Menschen sollten über Design diskutieren, nicht über Leerzeichen.
Halte den Build grün und schnell. Flaky oder langsame Tests werden ignoriert, und einmal ignoriert, schützen sie nichts.

Warnsignale

Eine einzelne Datei über ~500 Zeilen, oder eine Klasse mit über ~10 öffentlichen Methoden – normalerweise ein Feature, das ausbrechen will.
Gemeinsames „utils“-Paket, in dem verwaiste Helfer sterben.
Das zu testende Objekt mocken, um einen Test bestehen zu lassen.
„Fass das Modul nicht an, niemand versteht es mehr.“
CI-Build-Zeit gemessen in zig Minuten.