CommunityCodierung & Entwicklunggithub.com

engineering-principles

Entwicklungs-Skill. Wende fundamentale Softwareentwicklungs-Prinzipien und die Unix-Philosophie an, wenn du Features implementierst, Bugs behebst, Module oder APIs entwirfst, refaktorierst oder Code reviewst.

Was ist engineering-principles?

Dieser Skill bietet einen strukturierten Arbeitsablauf und eine Reihe von Entwurfsprinzipien, die auf der Unix-Philosophie basieren. Er hilft Entwicklern und KI-Agenten, Software systematisch zu entwerfen, zu debuggen und weiterzuentwickeln. Der Skill konzentriert sich darauf, die kleinste korrekte Lösung zu finden, die verständlich und sicher zu ändern ist. Er behandelt Prinzipien als Werkzeuge zum Nachdenken und nicht als starre Gesetze. Der Skill unterstützt Plattformen wie Claude Code, Cursor und Codex und ermutigt zu pragmatischen Entscheidungen über Einfachheit, Abstraktion, Kopplung und Leistung. Anstatt Checklisten abzuarbeiten, zielt der Skill darauf ab, Prinzipien in konkrete Kompromisse und überprüfte Änderungen umzusetzen.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NickLitharis/groundwork/tree/HEAD/engineering-principles

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Engineering-Prinzipien

Baue die kleinste korrekte Lösung, die verständlich und sicher zu ändern bleibt. Behandle Prinzipien als Werkzeuge zum Nachdenken, nicht als Gesetze, die über Anforderungen, Repository-Konventionen oder Beweisen stehen.

Arbeitsablauf

  1. Den Vertrag festlegen. Lies den relevanten Code, die Aufrufer, Tests und Repository-Anweisungen. Identifiziere erforderliches Verhalten, Ein- und Ausgaben, Invarianten, Fehlermodi und Kompatibilitätsbeschränkungen. Unterscheide beobachtete Fakten von Annahmen. Frage nur, wenn eine ungelöste Anforderung die Lösung materiell verändert.
  2. Ein verhältnismäßiges Design wählen. Verwende lokale Muster und vorhandene Fähigkeiten wieder. Bevorzuge eine direkte Implementierung; füge Struktur hinzu, wenn sie echte Komplexität enthält oder eine tatsächliche Grenze schützt. Berücksichtige Sicherheit, Datenintegrität und Ressourcengrenzen, wo die Änderung sie berührt.
  3. Ein Anliegen nach dem anderen ändern. Halte das Diff kohärent. Bewahre nicht verwandte Arbeit. Trenne verhaltenserhaltende Refaktorisierung von absichtlichen Verhaltensänderungen, damit jede überprüfbar ist. Behebe die Ursache, nicht nur das beobachtete Symptom.
  4. Das versprochene Verhalten verifizieren. Verwende den schmalsten sinnvollen Test oder ausführbaren Szenario, einschließlich relevanter Fehlerpfade. Überprüfe, was tatsächlich ausgeführt wurde; eine leere Testauswahl beweist nichts. Bestehende Tests sind Belege für die Behauptungen und Pfade, die sie ausüben, kein Beweis für vollständige Korrektheit oder Kompatibilität.
  5. Die Änderung abschließen. Aktualisiere betroffene Aufrufer, Verträge und Dokumentation. Entferne Code, der durch diese Änderung obsolet wurde. Berichte kurz über das Ergebnis, die Verifikation und eventuelle verbleibende Einschränkungen; erkläre ein Prinzip nur, wenn es eine Entscheidung materiell beeinflusst hat.

Skaliere diesen Ablauf je nach Risiko: Eine lokale Umbenennung braucht wenig Zeremonie; eine gemeinsam genutzte API oder eine Änderung persistierter Daten benötigt Nachweise über Konsumenten und Migration. Erzeuge keine Entwurfsdokumente oder eine Spezialistenkette für routinemäßige Änderungen.

Debugging und Repository-Workflow

Behandle einen vom Benutzer gemeldeten Fehler als Reproduktion; bitte ihn nicht, ihn nur zur Bestätigung zu wiederholen. Trenne beobachtetes Verhalten von Hypothesen und sammle dann Beweise, die wahrscheinliche Ursachen unterscheiden. Verwende eine fokussierte Reproduktion, gezielte Inspektion oder einen Debugger, anstatt Code durch Raten zu ändern. Behebe die Ursache, bewahre nützliche Diagnoseinformationen ohne Geheimnisse preiszugeben, und unterdrücke niemals einen Fehler, um den Pfad erfolgreich erscheinen zu lassen. Füge fehlende Regressionstests hinzu und überprüfe das relevante Wiederherstellungsverhalten, wenn ein Fehler einen teilweisen Zustand hinterlassen kann.

Verwende die vorhandenen Build-, Test-, Run- und Generierungs-Einstiegspunkte des Repositorys. Lies ihre dokumentierten Voraussetzungen und rufe dieselben Befehle auf, die Menschen und CI verwenden; füge keine zweite Toolchain hinzu und verlange kein Make, wo das Repository eine andere geeignete Schnittstelle hat. Ein Testbefehl ohne passende Tests ist kein Beweis.

Pflege nützliche Mitwirkenden-Dokumentation: bewahre das Warum, Invarianten und Schlüsselabläufe, die Code allein nicht erklärt; aktualisiere betroffene Dokumente, wähle Benutzerreferenz, Tutorial oder Fehlerbehebungsmaterial je nach Zielgruppe. Vermeide breite Dokumentations-Umschreibungen, die nichts mit der Änderung zu tun haben.

Entwurfsprinzipien

Korrektheit beginnt mit Verträgen

Definiere, was wahr bleiben muss, bevor du ein Muster wählst. Mache ungültige Zustände schwer darstellbar durch geeignete Typen, Konstruktoren und explizite Zustandsübergänge. Halte die Eigentümerschaft von veränderlichem Zustand und Ressourcenlebenszyklen klar.

Validiere nicht vertrauenswürdige Eingaben an Grenzen. Entferne keine Prüfungen nur, weil sie defensiv aussehen: Stelle fest, ob die Bedingung unmöglich, bereits garantiert oder immer noch ein echter Fehlermodus ist. Bewahre nützlichen Fehlerkontext, ohne Geheimnisse preiszugeben. Verwandle niemals einen Fehler in ein erfundenes erfolgreiches Ergebnis.

Einfachheit: KISS und YAGNI

KISS bedeutet, die Komplexität zu minimieren, die ein Betreuer verstehen muss, nicht nur die Zeilenanzahl. YAGNI bedeutet, aktuelle Anforderungen zu implementieren, nicht spekulative zukünftige Features. Beides entschuldigt nicht fehlende Fehlerbehandlung, unsicheren Speicher oder einen nicht wartbaren Kurzschluss.

Vermeide Plugins, generische Frameworks, Konfigurationsebenen oder Erweiterungspunkte ohne aktuellen Bedarf. Ein einfaches Design kann dennoch klare Grenzen haben, die spätere Änderungen kostengünstig machen.

Komplexität im gesamten System

Unterscheide wesentliche Komplexität (vom Problem gefordert), optionale Komplexität (eine Fähigkeit mit Kosten) und zufällige Komplexität (vermeidbare Schwierigkeit bei der Implementierung spezifizierten Verhaltens). Verwende diese als Denkkategorien, nicht als Feature-Kontingent. Wende sie auf Implementierung, Schnittstelle, Integration und den Aufwand und das Fehlerrisiko der Benutzer an: Kosten an einer Stelle zu senken, kann sie an eine andere verschieben. Entferne zufällige Komplexität; behalte optionale Fähigkeiten, wenn ihr Nutzen für den Benutzer ihre Gesamtkosten über die gesamte Lebensdauer rechtfertigt. Vergleiche unter Zeitdruck den aktuellen Lieferwert mit dem Ende-zu-Ende-Aufwand, Support und Wartung; weniger Zeilen oder Features allein begründen keine geringeren Gesamtkosten. Beispiele findest du unter Komplexität, Schnittstellen und Leistung.

Kohäsion, Kopplung und Informationsverbergung

Gruppiere Code, der sich aus demselben Grund ändert; trenne Belange, die sich unabhängig ändern. Verberge volatile Implementierungsentscheidungen hinter einer kleinen, kohärenten Schnittstelle. Bevorzuge ein tiefes Modul, das nützliche Arbeit leistet, gegenüber einer Kette von Durchgangs-Wrappern.

Eine Schnittstelle kann etwas allgemein gehalten sein, wenn dies einem gemeinsamen Mechanismus erlaubt, identifizierbare Aufrufer zu bedienen, ohne die Richtlinie eines Aufrufers einzubetten. Halte sie nicht allgemeiner als durch aktuelle Nutzungen gerechtfertigt: erratene zukünftige Bedürfnisse können gegenwärtige Aufrufer belasten. Wähle eine spezialisierte Schnittstelle, wenn ihr Vertrag tatsächlich spezifisch ist.

Single Responsibility betrifft einen kohärenten Grund zur Änderung, nicht eine Methode pro Klasse. Niedrige Kopplung bedeutet, dass Konsumenten wenig Wissen über Interna benötigen, nicht dass jeder Aufruf eine Schnittstelle erfordert. Halte Abhängigkeitsrichtungen explizit und vermeide Zyklen, wo praktikabel.

Abstraktion und DRY

DRY bedeutet eine autoritative Darstellung eines Wissensstücks, nicht die Eliminierung jedes ähnlich aussehenden Sequenz. Teile Logik, wenn Aufrufer dieselbe Regel ausdrücken und sich gemeinsam weiterentwickeln sollten. Halte oberflächlich ähnlichen Code getrennt, wenn er zu unterschiedlichen Konzepten oder Lebenszyklen gehört.

Wenn Wissen auch in generierten Dateien vorkommt, identifiziere seine autoritative Quelle und den Generator. Schütze nicht verwandte Änderungen vor der Neugenerierung; löse überlappende Eigentumsverhältnisse auf, anstatt Benutzerarbeit zu überschreiben. Aktualisiere die Quelle, führe den vorhandenen Generator aus und überprüfe das abgeleitete Diff. Bearbeite generierte Ausgaben nicht von Hand als dauerhafte Korrektur und füge keine Generierungsmechanik für triviale Arbeit hinzu.

Identifiziere vor dem Extrahieren den gemeinsamen Vertrag, die erwarteten Änderungsgründe und die Komplexität, die die Abstraktion entfernt. Verwende keine numerische Wiederholungsschwelle als Beweis. Ein wenig Duplizierung kann weniger kosten als die falsche Kopplung.

SOLID als diagnostische Fragen

Verwende diese Fragen, wo das Design profitiert; erzwinge keine objektorientierte Architektur für prozeduralen oder funktionalen Code.

  • Single Responsibility: Mischt diese Einheit unabhängig wechselnde Belange?
  • Open/closed: Gibt es eine demonstrierte Variationsachse, die es wert ist, isoliert zu werden, und nicht ein hypothetisches Erweiterungsframework?
  • Liskov Substitution: Kann eine Implementierung eine andere ersetzen, ohne Aufrufer durch stärkere Vorbedingungen, schwächere Garantien oder inkompatible Fehler zu überraschen?
  • Interface Segregation: Hängen Konsumenten nur von Fähigkeiten ab, die sie nutzen?
  • Dependency Inversion: Sollte eine stabile Richtlinie von einem schmalen Vertrag abhängen anstatt von volatilen I/O-Details? Eine Funktion oder ein Parameter kann diese Nahtstelle bieten; eine Klassenhierarchie ist nicht erforderlich.

Bevorzuge Komposition vor Vererbung, wenn Vererbung keine echte substituierbare Beziehung modelliert. Verwende sprachidiomatische Mechanismen anstelle von Musternamen als Ziel.

Lesbarkeit und geringste Überraschung

Wähle Namen, die Domänenbedeutung, Einheiten und Eigentümerschaft offenlegen. Halte Kontrollfluss und Seiteneffekte leicht nachvollziehbar. Verwende Kommentare für Begründungen, Einschränkungen und nicht offensichtliche Garantien, nicht um offensichtliche Aussagen zu erzählen.

Folge den Repository-Konventionen, es sei denn, sie verursachen ein konkretes Problem. Funktionsgröße, Parameteranzahl und Verschachtelungstiefe sind Warnsignale, keine universellen numerischen Grenzen. Zusätzliche Indirektion ist nicht automatisch saubererer Code. Kommentare können Begründungen, Einschränkungen und eine Abstraktion bewahren, die Code allein nicht erklärt; beurteile ihren Wert im Kontext, anstatt sie zu entfernen oder kohärente Logik aufzuteilen, um eine Längen- oder Kommentar-Anzahlregel zu erfüllen.

Abhängigkeiten und Leistung

Verwende eine gewartete, geeignete Bibliothek für schwierige etablierte Fähigkeiten, insbesondere Kryptographie und Protokollverarbeitung. Bewerte Eignung, Sicherheit, Lizenz, Kompatibilität, Betriebskosten und Abhängigkeitsgewicht. Füge keine Abhängigkeit für eine triviale Operation hinzu, die bereits von der Sprache oder dem Repository bedient wird.

Wähle sinnvolle Datenstrukturen und Algorithmen für erwartete Eingabegrößen. Vermeide offensichtliche redundante Arbeit und verschwenderische Allokation oder Kopieren. Miss vermutete Engpässe vor komplexer Optimierung; benchmarke repräsentative Arbeitslasten und schütze Korrektheit. Benenne die Arbeitslast, Metrik, Baseline, Ziel und Stoppkriterium; verwende Maße, die an tatsächliche Benutzer- oder Systemergebnisse gebunden sind, nicht an Aktivitätszählungen. Stoppe, sobald der Vertrag erfüllt ist oder ein weiterer Gewinn die zusätzliche Komplexität und Wartung nicht wert ist. Entscheide, ob der Vertrag Latenz, Durchsatz oder Ressourcennutzung bewertet: Batching kann den Durchsatz verbessern, während es die Antwortzeit verschlechtert. Gib keine festgelegte Latenz- oder Speicheranforderung für stilistische Einfachheit auf. Beispiele findest du unter Komplexität, Schnittstellen und Leistung.

Unix-Philosophie in der Praxis

Schreibe kohärente Komponenten, die eine Aufgabe gut erledigen und sich durch explizite Verträge zusammensetzen lassen. Dies erfordert nicht einen Prozess pro Funktion, Microservices, textbasierte Speicherung oder Zustandslosigkeit überall. Interne Bibliotheken mit klaren APIs können gleichermaßen zusammensetzbar sein.

  • Trenne Mechanismus von Richtlinie. Halte wiederverwendbare Berechnung unabhängig von Präsentation, Umgebung und sich ändernden Geschäftsentscheidungen, wo diese Trennung die Kopplung reduziert.
  • Entwerfe für Zusammensetzbarkeit. Vermeide versteckten globalen Zustand und unnötige hartcodierte Pfade. Mache Abhängigkeiten und Effekte explizit; lasse Aufrufer gegebenenfalls Ziele wählen.
  • Bevorzuge überprüfbare Darstellungen. Verwende einfache Datenstrukturen und dokumentierte Formate. Text ist wertvoll für interoperable Werkzeuge; binäre Formate sind gültig, wenn Genauigkeit, Volumen oder Leistung sie erfordern.
  • Halte normalen Betrieb leise, Fehler sichtbar. Stille bedeutet kein irrelevantes Geplapper, nicht fehlende Ergebnisdaten oder unterdrückte Diagnosen.
  • Werkzeuge wiederverwenden. Bevorzuge vorhandene zuverlässige Fähigkeiten gegenüber dem Neubau. Halte Automatisierung nicht interaktiv, wenn sie für Skripte gedacht ist.

Wähle den Schnittstellenstil nach seinen menschlichen und maschinellen Konsumenten, nicht nach Tradition. Eine Funktions- oder Bibliotheks-API, eine stabile CLI oder ein Filter können für maschinelle Aufrufer und wiederholbare Arbeit geeignet sein; menschliche Aufgaben benötigen möglicherweise Auffindbarkeit, Feedback oder direkte Interaktion. Wenn beide echte Konsumenten sind, trenne Domänenlogik von optionalen Wrappern, damit sie sich Verhalten teilen, ohne eine GUI obligatorisch zu machen. Folge dem einfachsten Stil, der den Vertrag erfüllt. Siehe Unix-Schnittstellen und Komplexität, Schnittstellen und Leistung für praktische Abwägungen.

Für CLI-, Pipeline- und Konfigurationsdesign lies Unix-Schnittstellen. Wenn Komplexität, Schnittstellenstil oder Leistungsabwägungen die Entscheidung materiell prägen, lies Komplexität, Schnittstellen und Leistung. Für konkurrierende Prinzipien und Beispiele lies Abwägungen. Diese Referenzen sind bedingt; keine ist für eine nicht verwandte lokale Änderung obligatorisch.

Für praktisches Debugging, Projektbefehle, generierte Artefakte, Maintainer-Dokumentation und Beispiele zur Abhängigkeitsbewertung lies Debugging und Wartung.

Sichere Evolution und Verifikation

Eine Refaktorisierung bewahrt beobachtbares Verhalten, einschließlich Ausgaben, Fehler, Seiteneffekte und Verträge, auf die sich Konsumenten verlassen. Behebe während einer Refaktorisierung nicht stillschweigend Eigenheiten. Eine absichtliche Vertragsänderung aktualisiert stattdessen explizit betroffene Tests und Konsumenten; Tests von überholten Anforderungen sind keine dauerhaften Einschränkungen.

Schütze öffentliche Grenzen mit verhaltensorientierten Tests. Verwende ausreichende Abdeckung wieder; füge Regressions- oder Charakterisierungstests hinzu, wenn ein wichtiger Pfad ungeschützt ist. Bevorzuge reale Implementierungen oder fokussierte Fakes, wo praktikabel, verwende aber Doubles, um wirklich kostspielige, nicht deterministische oder unsichere Grenzen zu isolieren. Vermeide Behauptungen über private Methodenaufrufe oder genauen Quelltext, es sei denn, diese sind selbst der Vertrag.

Überprüfe aussagekräftige Randfälle: fehlerhafte Eingaben, leere Daten, Ressourcenfehler und gegebenenfalls Parallelität oder teilweise Schreibvorgänge. Schreibe keinen willkürlichen Abdeckungsprozentsatz oder eine vollständige Suite für jede Änderung vor.

Bewahre öffentliche Kompatibilität, es sei denn, ihre Änderung ist im Umfang enthalten. Für dauerhafte Verträge und persistierte Daten überprüfe Konsumenten, Bereitstellungsreihenfolge, Migration und Wiederherstellung. Verwende Expand/Contract oder einen anderen gestuften Ansatz, wenn alte und neue Versionen koexistieren müssen; eine koordinierte atomare Änderung kann andernfalls ausreichen. Entferne keine Wiederherstellungspfade oder installiere keine Kompatibilitäts-Shims ohne tatsächliche Anforderung.

Abschließende Entscheidungsprüfung

Bevor du den Abschluss erklärst, frage:

  • Erfüllt die Implementierung den tatsächlichen Vertrag, einschließlich relevanter Fehler?
  • Ist jede Abstraktion, Abhängigkeit und geänderte Datei durch diese Aufgabe gerechtfertigt?
  • Kann ein Betreuer die Regel, ihren Zustandsbesitzer und die sie schützenden Beweise lokalisieren?
  • Habe ich vorhandenes Verhalten bewahrt oder die beabsichtigte Änderung explizit in den betroffenen Konsumenten gemacht?
  • Was habe ich tatsächlich verifiziert und was bleibt unverifiziert?

Verwende diese Prüfung privat; gib keinen Standardbericht oder Prinzipien-Score für jede Änderung aus.

Verwandte Skills