Repository Instructions und Guardrails

Repository Instructions und Guardrails

0:00 Im letzten Modul haben wir gelernt, wie ein guter Auftrag aussieht. Jetzt geht es um alles, was nicht in jeden einzelnen Auftrag gehört, weil es immer gilt: die Befehle des Projekts, seine Konventionen, seine Grenzen. Das schreibt man einmal auf und legt es ins Repository. Und dabei begegnet uns eine Unterscheidung, die im Raum regelmäßig vermischt wird und die den Kern dieses Moduls bildet: Eine Anweisungsdatei ist eine Bitte.

0:25 Verbindlich wird eine Regel erst eine Ebene tiefer. Wer das verwechselt, hält sich für abgesichert und ist es nicht.

Repository Instructions und Guardrails

0:32 Wir gehen zunächst die Mechanik durch — und die überrascht fast alle, weil die Dateien anders zusammengesetzt werden, als man denkt. Dann die Frage, was überhaupt hineingehört; dabei bekommen Sie eine Prüffrage, mit der Sie jede Zeile beurteilen können. Danach Konventionen und die Definition von „fertig", das Kernkapitel über beratend gegen verbindlich, und schließlich die Grenzen: Was darf ein Agent ändern, was darf er sehen, welche Rechte bekommt er?

0:58 Und am Ende schreiben Sie die Datei für ein echtes Projekt.

Dauerhafte Anweisungen im Repository

1:02 Beginnen wir mit dem Grundsatz und der Mechanik. Der Grundsatz: Was jeder Lauf wissen muss, gehört nicht in den Prompt. Die Mechanik überrascht fast immer — die Dateien werden von der Wurzel abwärts zusammengesetzt, und die näher gelegene gewinnt. Was ein Agent in jedem Lauf wissen muss, gehört in eine Datei im Repository.

1:22 Und die drei Eigenschaften am Ende sind der eigentliche Gewinn: versioniert, im Team änderbar, im Review sichtbar. Damit wird aus Wissen, das bisher in Köpfen und Chatverläufen steckte, ein Artefakt, über das man sprechen kann. Je nach Werkzeug heißt die Datei anders — die Aufgabe ist dieselbe. Und sie wird gelesen, bevor überhaupt gearbeitet wird. Das Bild dazu: die Hausordnung, die im Flur hängt, statt der Ermahnung, die jeder Neue einzeln bekommt.

1:50 Fünf Regeln, und die letzte hat es in sich. Gelesen wird von global über die Repository-Wurzel abwärts, aneinandergehängt und durch Leerzeilen getrennt. Die näher am Arbeitsverzeichnis liegende Datei gewinnt bei Widersprüchen — das ist sinnvoll, muss man aber wissen, wenn man mehrere anlegt. Je Verzeichnis höchstens eine.

2:12 Und dann die Obergrenze: zusammengeführt 32 Kibibyte als Voreinstellung. Die Fußzeile zieht die Konsequenz, und die ist unangenehm: Was darüber liegt, geht verloren — unsichtbar und ungemeldet. Aus „halte es kurz" wird damit eine harte Zahl. Der zweite Punkt ist der gefährlichste, weil er lautlos ist: über die Obergrenze schreiben und den Verlust nicht bemerken. Sie sehen keine Warnung.

2:36 Sie sehen nur, dass Regeln irgendwie nicht mehr greifen — und suchen dann an der falschen Stelle. Der erste Punkt betrifft größere Projekte: eine Datei je Unterverzeichnis anlegen, ohne den Vorrang zu bedenken; dann überschreibt eine lokale Datei eine globale Regel, ohne dass es jemand wollte. Und der dritte ist der Grund für dieses ganze Modul: Anweisungen mündlich weitergeben, statt sie zu versionieren.

Was hineingehört und was nicht

3:00 Jetzt zur wichtigsten praktischen Frage: Was schreibt man eigentlich hinein? Und dafür gibt es eine Prüffrage, die ich Ihnen wörtlich mitgeben möchte: Würde das Streichen dieser Zeile dazu führen, dass der Agent Fehler macht? Wenn nein — streichen. Sieben Zeilen links, sieben rechts, und das Ordnungsprinzip ist immer dasselbe: Links steht, was der Agent nicht erraten kann. Rechts, was er ohnehin weiß oder ableiten kann.

3:27 Befehle, die man nicht erraten kann — hinein. Sprachkonventionen, die ohnehin gelten — heraus. Bekannte Fallstricke — hinein. Eine Datei-für-Datei-Beschreibung der Codebasis — heraus, die steht im Code. Und die letzte Zeile rechts ist mein Favorit: Selbstverständliches wie „schreibe sauberen Code" gehört nicht hinein. Solche Sätze kosten Platz und wirken nichts.

3:51 Vier Punkte, und sie sind zugleich eine Diagnoseanleitung. Erstens: Eine überladene Datei führt dazu, dass Regeln überhaupt nicht mehr greifen — nicht einzelne, sondern der Ansatz als Ganzes. Zweitens, und das ist die nützlichste Diagnose: Wird eine Regel trotz Nennung missachtet, ist die Datei meist zu lang. Drittens: Fragt der Agent nach etwas, das drinsteht, ist Ihre Formulierung mehrdeutig.

4:16 Und viertens, mit einem Augenzwinkern, aber ernst gemeint: Eine Hervorhebung wirkt nur, solange sie die einzige ist. Wer alles wichtig schreibt, schreibt nichts wichtig.

Struktur und Befehle dokumentieren

4:27 Jetzt der Teil, der am meisten bringt und am langweiligsten aussieht. Wo liegt was, und mit welchem Befehl wird geprüft? Die wirkungsvollsten Zeilen einer solchen Datei sind genau diese — nicht die klugen Architekturgedanken, sondern die schlichten Befehlszeilen. Wo liegt was, und mit welchem Befehl wird geprüft, getestet, gelintet und gebaut.

4:48 Ohne diese Angaben sucht ein Agent bei jedem Lauf neu — und rät im Zweifel falsch, etwa einen Testbefehl, den es in Ihrem Projekt gar nicht gibt. Mit ihnen führt er die Prüfungen aus Modul 8 selbst aus. Und damit schließt sich der Kreis: Das ist der wirksamste Hebel aus Modul 11 — der selbst ausführbare Check —, hier endlich nutzbar gemacht.

5:08 Vier Zeilen Dokumentation verwandeln einen Agenten, den Sie kontrollieren müssen, in einen, der sich selbst kontrolliert. Drei Abschnitte, zehn Zeilen, und jede einzelne besteht die Prüffrage. Die Befehle kann niemand erraten. Die Konvention, an Systemgrenzen den unbestimmten Typ zu verwenden, ist eine Projektentscheidung aus Modul 6 — kein Agent bringt sie mit.

5:31 Beträge in Cent als ganze Zahl ist eine fachliche Festlegung, deren Verletzung teuer wird. Und der gesperrte Bereich ist eine Grenze, die im Code nirgends steht. Die Fußzeile nennt das Auswahlkriterium noch einmal: Jede Zeile hier ist eine, die der Agent nicht erraten kann. Der zweite Punkt ist der, der schleichend passiert: Die Datei schreiben und die Skripte danach umbenennen.

5:54 Dann verweist Ihre Anweisungsdatei auf Befehle, die es nicht mehr gibt — und der Agent scheitert an etwas, das Sie ihm selbst gesagt haben. Der erste ist verwandt: Befehle nennen, die nur mit lokaler Sondereinrichtung laufen. Und der dritte ist eine Frage der Arbeitsteilung: Formatierung und Lint gehören in die Pipeline, nicht in die Anweisungsdatei.

6:14 Was ein Werkzeug automatisch erledigt, muss niemand lesen.

Konventionen und Definition of Done

6:18 Jetzt zu den Konventionen und zu einer Frage, die auch ohne Agenten in vielen Teams unbeantwortet ist: Was heißt eigentlich „fertig"? Und die Antwort dieses Kapitels lautet: Fertig heißt nicht, dass die Änderung existiert. Konventionen, die im Team ohnehin gelten, sollten aufgeschrieben sein: Strenge, Umgang mit dem abschaltenden Typ, Modulgrenzen, Benennung.

6:40 Und dann kommt ein Satz, der wie eine Nebenbemerkung klingt und eine ziemlich grundsätzliche Beobachtung ist: Ein Agent hält sich an geschriebene Regeln zuverlässiger als an ungeschriebene — an ungeschriebene gar nicht. Er kann sie ja nicht kennen. Das ist übrigens bei neuen Kolleginnen und Kollegen nicht viel anders, nur höflicher formuliert. Dasselbe gilt für die Definition von fertig.

7:02 Vier Punkte, und der zweite ist der, der in der Praxis den Unterschied macht: Ob Tests für die Fehlerfälle verlangt sind, nicht nur für den Erfolgspfad. Ohne diese Angabe bekommen Sie zuverlässig Tests für den glücklichen Fall — und genau die brauchen Sie am wenigsten. Dazu kommen: welche Prüfungen gelaufen sein müssen und mit welchem Ergebnis, ob und wo fachliche Änderungen dokumentiert werden.

7:24 Und der vierte Punkt ist der unterschätzte: Was ausdrücklich nicht dazugehört. Eine Abgrenzung nach unten verhindert wuchernden Umfang. Der erste Punkt ist die Kernaussage dieses Kapitels: „fertig" als Zustand des Codes definieren statt als Zustand der Prüfung. Der Code existiert immer — das ist kein Kriterium. Der zweite ist eine Ehrlichkeitsfrage: Konventionen aufschreiben, die im Team gar nicht gelebt werden.

7:49 Dann bekommen Sie Code, der sich vom übrigen Projekt unterscheidet, und der Agent hat alles richtig gemacht. Und der dritte: die Definition von fertig je Aufgabe neu erfinden lassen. Sie gehört genau deshalb in die Datei — sie ändert sich nicht mit der Aufgabe.

Beratend oder verbindlich

8:06 Und jetzt der Kern des ganzen Moduls. Es ist eine einzige Unterscheidung, aber sie entscheidet darüber, ob Ihre Absicherung real ist oder gefühlt. Die Dokumentation formuliert es klar: Anders als Anweisungen, die beratend sind, sind Hooks deterministisch und garantieren, dass die Aktion stattfindet. Eine Anweisungsdatei ist eine Bitte. Sie wirkt, weil das Modell sie liest und meist befolgt — und „meist" ist bei manchen Regeln völlig ausreichend. Bei anderen nicht.

8:34 Verbindlich wird eine Regel erst durch einen Mechanismus, der sie erzwingt: eine Berechtigung, eine Sandbox, einen Hook, ein Tor in der Pipeline. Das Bild: Ein Schild „Bitte nicht betreten" ist eine Bitte. Ein abgeschlossenes Tor ist eine Regel. Beides hat seinen Platz — aber verwechseln sollte man sie nicht, besonders nicht bei Sicherheitsfragen.

8:56 Vier Ebenen mit steigender Verbindlichkeit. Die Anweisungsdatei ist beratend. Berechtigungen und Sandbox wirken verbindlich und vorher — sie verhindern, dass etwas überhaupt versucht wird. Ein Hook wirkt verbindlich und deterministisch, etwa indem er das Schreiben in ein bestimmtes Verzeichnis blockiert. Und ein Tor in der Pipeline wirkt verbindlich, aber nachher.

9:18 Die Fußzeile ist mir wichtig, damit kein falscher Eindruck entsteht: Die Anweisungsdatei bleibt trotzdem nötig — sie erklärt das Warum, das eine Sperre nicht mitliefert. Eine Sperre ohne Begründung erzeugt Umgehungsversuche. Vier Entscheidungsregeln, und sie sind erfreulich handlich. Soll eine Regel verstanden werden? Anweisungsdatei, mit Begründung. Darf sie nie verletzt werden?

9:42 Berechtigung oder Hook — nicht Bitte. Soll eine Verletzung auffallen, aber nicht blockieren? Eine Meldung in der Pipeline. Und betrifft die Regel das Ergebnis, nicht den Weg? Dann ein Tor am Ende. Gehen Sie mit diesen vier Fragen einmal durch Ihre bestehende Anweisungsdatei — Sie werden vermutlich zwei bis drei Zeilen finden, die eine Ebene tiefer gehören.

Änderungen, Abhängigkeiten, Grenzen

10:06 Jetzt zu den Grenzen im Projekt: Was darf ein Agent ändern, und was nicht? Und dazu eine Frage, die auch ohne Agenten viel zu leichtfertig behandelt wird: Eine neue Abhängigkeit ist eine Entscheidung, keine Kleinigkeit. Manche Bereiche eines Projekts sind für automatische Änderungen tabu — generierter Code, Migrationen, veröffentlichte Schnittstellen.

10:27 Und eine neue Abhängigkeit bringt drei Dinge mit, an die man im Moment des Hinzufügens selten denkt: Wartung, Sicherheitsfläche und Lizenzfragen. Beides gehört ausdrücklich geregelt und nicht dem Einzelfall überlassen. Denn im Einzelfall wirkt jede einzelne Abhängigkeit harmlos — die Summe ist das Problem, und die Summe entscheidet niemand.

10:47 Vier Kategorien, jeweils mit eigener Begründung. Generierte Dateien, weil sie beim nächsten Lauf ohnehin überschrieben werden — jede Handarbeit dort ist verlorene Zeit. Datenbankmigrationen, deren Reihenfolge Bestand hat und rückwirkend nicht mehr änderbar ist. Veröffentlichte Signaturen, deren Änderung Konsumenten bricht — der Punkt aus Modul 7.

11:08 Und alles, was das Kassenterminal betrifft, weil dort eigene Zwänge gelten, etwa eine alte Laufzeit. Schauen Sie in Ihrem Projekt nach solchen Bereichen; es gibt sie fast immer, und meist weiß es nur einer. Der erste Punkt ist die Anwendung des Kernkapitels: Sperren nur aufschreiben, ohne sie technisch zu verankern. Bei generiertem Code mag das reichen. Bei einer Migration nicht.

11:31 Der zweite ist eine Warnung vor Übervorsicht: Abhängigkeiten pauschal verbieten und damit Rückfragen erzwingen, die am Ende niemand liest — eine Regel, die dauernd anschlägt, wird abgeschaltet. Und der dritte ist ein Klassiker aus Modul 6: generierten Code von Hand nachbessern lassen, statt den Generator zu ändern. Die Verbesserung überlebt den nächsten Lauf nicht.

Sicherheit, Datenschutz, Geheimhaltung

11:53 Jetzt ein Kapitel, bei dem die Anweisungsdatei die schwächste Ebene ist — und das muss man klar sagen. Der Agent kennt den Unterschied zwischen harmlosen und sensiblen Daten nicht von allein. Und was wirklich nicht abfließen darf, wird über Berechtigungen geregelt, nicht über Bitten. Welche Daten dürfen ein Werkzeug erreichen und welche nie? Geheimnisse, Kundendaten, personenbezogene Daten und interne Schnittstellen brauchen eine klare Grenze.

12:20 Und jetzt die Zweiteilung, die dieses Modul durchzieht: Aufgeschrieben gehört die Grenze, damit sie verstanden wird. Durchgesetzt gehört sie über die Ebene darunter. Beides. Wer nur aufschreibt, hat eine Bitte. Wer nur sperrt, bekommt Umgehungsversuche von Menschen, die nicht verstehen, warum. Vier Fragen, die Sie beantworten sollten, bevor der erste Agent in Ihrem Repository arbeitet. Welche Verzeichnisse und Dateien dürfen nie gelesen werden?

12:48 Ob und wohin Netzzugriff erlaubt ist — das ist die folgenreichste Einstellung überhaupt, denn ohne Netz kann nichts abfließen. Wie mit echten Daten in Testfällen umzugehen ist. Und der vierte Punkt, den man gern vergisst: Wer gibt frei, wenn eine Grenze im Einzelfall überschritten werden soll? Eine Grenze ohne benannten Ausnahmeweg wird irgendwann still umgangen.

13:10 Der erste Punkt ist der klassische Denkfehler: Geheimnisse in der Anweisungsdatei erwähnen — also hinschreiben, wo sie liegen und dass man sie nicht lesen soll — statt sie schlicht unerreichbar zu machen. Sie haben damit einen Wegweiser geschrieben. Der zweite ist bequem und rechtlich heikel: echte Kundendaten als Testdaten verwenden.

13:28 Und der dritte fasst das Kapitel zusammen und ist der wichtigste Satz des Moduls: Eine Bitte in der Anweisungsdatei ist keine Zugriffskontrolle. Nie.

Rechte, Checkpoints und Review

13:37 Zum Abschluss die Frage der Rechte — und ein sehr praktischer Rat, der so schlicht klingt, dass man ihn leicht überhört: Kleine Commits sind der Rückweg. Sie sind kein Stil, sie sind Ihre Möglichkeit zur Umkehr. Lesen, schreiben, Befehle ausführen, ins Netz gehen — jede Berechtigung ist einzeln zu vergeben. Und jetzt der Zusammenhang, den man kennen sollte: Der sinnvolle Zuschnitt hängt daran, wie gut die Änderungen anschließend geprüft werden.

14:04 Weitreichende Rechte und gründliche Prüfung passen zusammen. Weitreichende Rechte und flüchtige Prüfung nicht. Beide Schrauben gehören gemeinsam gedreht. Und kleine Commits sind dabei kein Stil, sondern die Möglichkeit zur Umkehr — was Sie in Stücken bekommen haben, können Sie in Stücken zurücknehmen. Vier Punkte, und der letzte ist der grundsätzliche.

14:25 Ein Review ist die Stelle, an der jemand die Verantwortung übernimmt — das ist seine eigentliche Funktion, nicht das Finden von Fehlern. Kleine Commits machen ein Zurücknehmen billig statt schmerzhaft. Ein nachvollziehbarer Verlauf erklärt später, warum etwas so ist — und „später" heißt oft: in einem Jahr, wenn niemand mehr da ist, der dabei war.

14:46 Und dann der Satz, den ich Ihnen mitgeben möchte: Ein Werkzeug kann Rechenschaft nicht übernehmen, nur Arbeit. Der erste Punkt ist die gefährliche Kombination, über die wir gerade gesprochen haben: weitreichende Rechte vergeben und die Prüfung gleichzeitig verkürzen. Beides passiert leicht zusammen, weil beides bequem ist. Der zweite: einen ganzen Lauf in einem Commit ablegen und damit die Umkehr verlieren — dann bleibt nur alles oder nichts.

15:12 Und der dritte ist psychologisch und deshalb hartnäckig: den Review als Formalie behandeln, wenn der Agent gründlich wirkte. Gründlichkeit im Auftreten ist kein Qualitätsmerkmal — bei Menschen übrigens auch nicht.

Übung — die Anweisungsdatei schreiben

15:24 Jetzt schreiben Sie eine solche Datei — und weisen ihre Wirkung nach. Die Tagline sagt, worauf es ankommt: Der Vergleich beweist es, nicht die Meinung. Sie werden dieselbe Aufgabe zweimal bearbeiten lassen, mit und ohne. Das Lernziel: dauerhafte Projektanweisungen so formulieren, dass sie das Verhalten eines Agenten nachweisbar verändern.

15:46 Erfolgreich sind Sie, wenn dieselbe Aufgabe mit und ohne die Datei bearbeitet wurde und Sie die Unterschiede Zeile für Zeile benennen und begründen können. Und ich verrate Ihnen den häufigsten Aha-Moment vorweg: Die Hälfte der zuerst geschriebenen Zeilen fällt der Prüffrage zum Opfer, weil der Agent sie ohnehin befolgt.

16:03 Wer früh fertig ist, überführt eine der Regeln in eine verbindliche Ebene und schaut, was sich dadurch zusätzlich ändert. Fünf Schritte. Zuerst sammeln Sie ungefiltert — Befehle, Konventionen, Sperren, alles, was Ihnen einfällt. Dann unterwerfen Sie jede Zeile der Prüffrage und streichen, was durchfällt; das ist der schmerzhafte und der lehrreiche Schritt.

16:24 Danach lassen Sie die Aufgabe ohne die Datei bearbeiten und sichern das Ergebnis. Dann mit der Datei, und Sie vergleichen. Und im letzten Schritt bestimmen Sie, welche Regeln eine verbindliche Ebene brauchen. Die Fußzeile sagt, warum dieser Schritt dazugehört: Nicht jede Regel gehört auf die beratende Ebene — sonst wäre das hier eine Dokumentationsübung.

16:46 Vier Sätze zum Mitnehmen. Anweisungen werden von der Wurzel abwärts zusammengesetzt, mit 32 Kibibyte als Grenze — und was darüber liegt, geht lautlos verloren. Die Prüffrage je Zeile: Würde ihr Fehlen zu Fehlern führen? Sonst streichen. Eine überladene Datei führt dazu, dass Regeln überhaupt nicht mehr greifen. Und der Kernsatz: Beratend ist die Anweisung, verbindlich erst Berechtigung, Hook oder Pipeline.

17:12 Im letzten Fachmodul geht es darum, wie man den Code prüft, der auf diesem Weg entsteht.