Einen KI-Coding-Agenten Branch- und Commit-Regeln einhalten lassen, ohne Releases zu brechen

## Nur eine Agenten-Anweisungsdatei pflegen und prüfen, welcher Teil des Repositorys zu ändern ist - Pflege eine einzige kanonische Datei für Agentenanweisungen. Erwartet ein Harness einen anderen Dateinamen, verweise mit einem Symlink auf die kanonische Datei, statt den Inhalt zu duplizieren: Eine zweite echte Datei driftet mit der Zeit auseinander und kann Validatoren brechen, die den alternativen Pfad als eigenständigen Artefakttyp behandeln. Erhalte den Symlink; lass ihn nicht wieder in eine reguläre Datei umwandeln. - Eine einzelne Änderung kann mehrere Oberflächen gleichzeitig betreffen — ausgelieferte Produktinhalte, Katalog- oder Konfigurationsmetadaten sowie Build- oder CLI-Code. Nimm nicht an, eine Änderung sei „nur Code" oder „nur Dokumentation", ohne zu prüfen, welche Oberfläche die jeweils geänderte Datei verantwortet, und bearbeite die Oberfläche, der das Verhalten gehört, statt einer benachbarten. - Behandle die eigenen Anweisungsdateien des Repositorys als Autorenkontext für das Repository selbst. Jede Regel, die zur Laufzeit ein ausgeliefertes Artefakt beeinflussen muss, gehört in dieses Artefakt und nicht in die Anweisungsdatei des Repositorys, da Endnutzer das Artefakt mit ihren eigenen Anweisungen ausführen. ## Auf einem Feature-Branch arbeiten und nur per Pull Request mergen - Erstelle für jede nicht-triviale Änderung einen Feature-Branch. Bist du bereits auf dem für die Aufgabe richtigen Branch, nutze ihn weiter; erzeuge keine zusätzlichen Branches oder Worktrees, außer es wird ausdrücklich verlangt. - Leite jede Änderung am Standard-Branch über einen Pull Request. Direkte Pushes oder Merges umgehen Validierung und Release-Prüfungen und verursachen Versions-Drift, die später eine mehrstufige Wiederherstellung erfordert; verlasse dich auf den Branch-Schutz, um dies durchzusetzen, statt ihn zu umgehen. - Überlasse Releases der Release-Automatisierung. Erhöhe im Routinealltag keine von Releases verwalteten Versionsnummern manuell und schreibe keine Release Notes von Hand; verwende konventionelle Commit-Titel, damit die Automatisierung die Änderungsabsicht klassifizieren kann. ## Alle Tests ausführen und automatische Tests von Evaluationen trennen - Führe die vollständige Testsuite nach jeder Änderung aus, die Parsing, Konvertierung, Ausgabe oder mechanische Konventionen betrifft. Die lokale Suite ist dieselbe, die auch die CI ausführt; es gibt keine separate, nur lokale Spur, die übersprungen werden darf. - Trenne Prüfungen nach ihrer Art. Deterministische Invarianten — Schema und Frontmatter, Pfadsicherheit, Ausgabeform, grep-fähige Verträge — gehören in die automatisierte Suite und müssen in der CI bestehen. Nicht-deterministisches Verhalten wie Urteilsvermögen und Zurückhaltung wird durch Evaluation validiert, nicht als brüchiger String-Test vorgetäuscht. - Findet ein Reviewer eine grep-fähige Invariante, die der Suite entgangen ist, verschärfe bevorzugt eine bestehende Schutzprüfung, statt eine neue Suite hinzuzufügen, und fixiere die kleinste falsifizierbare Einheit — ein Token, einen Pfad oder eine Fixture, die bei der regressierenden Änderung fehlgeschlagen wäre — statt den gesamten Dateiinhalt als Snapshot festzuhalten. ## Festlegen, wohin temporäre Dateien gehören, und Pläne und Doku im Repository ablegen - Schicke Wegwerf-Arbeitsdateien standardmäßig ins Temp-Verzeichnis des Betriebssystems: ein pro Lauf angelegtes temporäres Verzeichnis, das das Betriebssystem zurückfordert, für Dateien, die einmal verwendet und dann verworfen werden. - Für Arbeitsdateien, die mehrere Aufrufe überdauern müssen, verwende ein stabiles, dem aktuellen Nutzer gehörendes Präfix statt eines zufälligen Temp-Verzeichnisses, damit spätere Läufe es wiederfinden. Lege das Wurzelverzeichnis privat an (nur für den Besitzer), lehne es ab, wenn es ein Symlink ist oder einem anderen Nutzer gehört, und halte ein Verzeichnis pro Lauf, sofern spätere Läufe nicht absichtlich benachbarte finale Artefakte aufzählen. - Binde Arbeitsdateien nur dann an das Arbeits-Repository, wenn das Artefakt wirklich untrennbar mit diesem Repository oder Branch verbunden ist, vom Nutzer direkt kuratiert werden soll oder ein repo-relativer Pfad selbst zentraler Bestandteil der Ausgabe ist. - Dauerhafte Ausgaben — Pläne, Spezifikationen, Dokumentation, finale Liefergegenstände — gehören an einen vom Repository verfolgten Ort, niemals in eine der beiden Arbeitsdatei-Ebenen. ## Nur ASCII in Namen verwenden und Markdown-Tabellen mit senkrechten Strichen trennen - Halte Bezeichner — Datei-, Befehls- und Agentennamen — ausschließlich ASCII, weil Konverter und Regex-Muster sich darauf verlassen. - Schreibe Markdown-Tabellen als durch Pipe-Zeichen getrennte Zeilen, niemals mit Rahmenzeichnungszeichen. - Unicode ist in Fließtext unproblematisch; bevorzuge ASCII-Pfeile (-> und <-) innerhalb von Codeblöcken und Terminalbeispielen, damit kopierte Befehle portabel bleiben. ## Das Commit-Präfix fix oder feature danach wählen, was die Änderung bewirkt - Wähle das konventionelle Präfix danach, was die Änderung bewirkt, nicht nach Dateityp. Inhalte in einem docs- oder skills-Verzeichnis können trotzdem Produktcode sein; reserviere ein docs-Präfix für Dateien, deren einziger Zweck Dokumentation ist. - Passen sowohl fix- als auch feature-Präfix, wähle standardmäßig fix: Das Beheben von defektem oder fehlendem Verhalten ist ein Fix, selbst wenn es durch das Hinzufügen von Code umgesetzt wird. Reserviere das feature-Präfix für eine Fähigkeit, die der Nutzer zuvor nicht erreichen konnte, ohne dass etwas defekt war. Faustregel: Wäre ein heute geschriebener Regressionstest vor der Änderung fehlgeschlagen, handelt es sich um einen Fix. - Gib den engsten sinnvollen Komponenten-Scope an — den Namen der Skill, des Moduls oder Bereichs — und beziehe einen Commit niemals auf das gesamte Projekt. Füge niemals ohne ausdrückliche Bestätigung des Nutzers eine Breaking-Change-Markierung hinzu, da sie eine automatische Erhöhung der Hauptversion auslöst, die der Nutzer möglicherweise nicht will. ## Mit relativen Pfaden jede ausgelieferte Einheit in jedem KI-Tool lauffähig machen - Halte jede auslieferbare Einheit in sich geschlossen: Referenziere nur Dateien innerhalb des eigenen Verzeichnisbaums, mit relativen Pfaden. Wechsle niemals in eine benachbarte Einheit hinüber und hartkodiere keinen absoluten Installationspfad — Installationsorte sind versioniert und unvorhersehbar, und die Paketierung kopiert jede Einheit isoliert. Dupliziere eine gemeinsam genutzte Datei in jede Einheit, statt verzeichnisübergreifend abhängig zu sein. - Verlasse dich nicht auf host-spezifische Variablen — Substitutionen wie skill-directory, session-id oder plugin-root — ohne einen Fallback, der funktioniert, wenn der Wert leer oder nicht aufgelöst ist; mehrere werden nur in einem Harness befüllt und sind anderswo stillschweigend leer. - Mache bei einem ausgeführten Shell-Befehl, der ein gebündeltes Skript aufruft, die Auflösung deterministisch: Setze im selben Befehl inline ein absolutes Basisverzeichnis (der Shell-Zustand bleibt zwischen Aufrufen nicht erhalten) und referenziere das Skript von dort aus, statt eines bloßen relativen Pfads, der sich gegen das Projektverzeichnis des Nutzers auflöst statt gegen das der Einheit. ## In Agentenanweisungen nur prüfbare Regeln schreiben und Review-Hinweise vor dem Ändern sortieren - Lass eine Zeile nur zu, wenn sie eine falsifizierbare Einschränkung formuliert, einer bekannten Standardtendenz oder beobachteten Abkürzung entgegenwirkt oder Fachwissen liefert, das eine Entscheidung verändert. Streiche vage Formulierungen zu Aufwand oder Qualität wie „sei gründlich"; ersetze sie durch eine beobachtbare Regel oder streiche sie ganz. Hänge keine motivierende Begründung an eine Anweisung, die bereits für sich selbst steht. - Wiederhole eine Anweisung nur an einer nachgewiesenen Drift-Stelle, an der ihre Platzierung darüber entscheidet, ob sie greift, und sichere ein wirklich notwendiges Duplikat mit einem Paritätstest ab. - Behandle das Einarbeiten von Review-Feedback als inhaltliche Überarbeitung: Klassifiziere jeden Punkt als Change, Verify oder Consider und bearbeite nur Change-Punkte; behebe jeden auf seiner zuständigen Ebene mit dem kleinsten Mechanismus; lies den Abschnitt danach erneut und entferne Text, den die Änderung dupliziert oder obsolet gemacht hat. Die Formulierung des Reviewers ist eine Hypothese über die Lösung, keine Weisungsbefugnis darüber. ## Projektkonventionen im bereits geladenen Kontext suchen, statt Anweisungsdateien zu nennen - Muss eine Einheit eine Projektkonvention ermitteln — Issue-Tracker, Commit-Format, Lint-Befehl, Scope-Grenzen —, beschreibe, wonach im bereits geladenen Kontext des Agenten zu suchen ist, nicht welche Datei zu öffnen ist. Benenne auf dem Lesepfad keine Anweisungs-Dotfiles: Der Host injiziert die Root-Anweisungsdatei bereits, ihr Dateiname unterscheidet sich je nach Harness, und einen Agenten anzuweisen, benannte Anweisungsdateien zu öffnen, ist genau die Form, die Prompt-Injection-Abwehrmechanismen als verdächtig markieren. - Benenne eine konkrete Datei nur dort, wo eine Kontextreferenz das Bedürfnis nicht ausdrücken kann — etwa beim Zurückschreiben einer Konvention in ein Ziel oder beim Lesen von Inhalten, die ein frischer Subagent tatsächlich nicht erbt. - Beschreibe eine Fähigkeit nach Kategorie („der Issue-Tracker des Projekts, z. B. GitHub Issues, Linear oder Jira" und „welche Schnittstelle er auch bietet"), und werte ein fehlendes Binary, eine fehlende Umgebungsvariable oder einen fehlenden Connector niemals als Beweis dafür, dass die Fähigkeit nicht verfügbar ist. ## Inhalte statt Versionsnummern vergleichen, um zu prüfen, ob die Sitzung die neueste Änderung hat - Nimm nach dem Bearbeiten von Inhalten, die eine lange laufende Sitzung beim Start geladen hat, an, dass die Sitzung noch die Kopie von vor der Bearbeitung verwendet. Caches erfassen den Zustand zum Ladezeitpunkt, und Änderungen innerhalb eines Releases ändern keine Versionsnummer, sodass eine übereinstimmende Version nur beweist, dass der Cache aus diesem Release stammt, nicht dass er deine neueste Änderung erfasst hat. - Bestätige, welche Kopie aktiv ist, indem du den Inhalt der geladenen Datei mit deiner Arbeitskopie vergleichst, nicht indem du die Versionszeichenkette liest. Sind sie identisch, ist die laufende Kopie aktuell und vertrauenswürdig; unterscheiden sie sich, starte neu oder nutze einen frischen Ladepfad, bevor du einem Verhaltenstest vertraust. - Mechanische Codepfade — Skripte, Parser, alles, was die Testsuite prüft — laufen immer mit dem aktuellen Quellcode. Nur die beim Start geladene Anweisungs- und Fließtext-Ebene trägt dieses Veraltungsrisiko.