--- type: types/concept.md concept_type: decision tags: [quality, tooling, tests, governance] created: 2026-08-31 modified: 2026-08-31 related: [Ambient Environment Dependency, wikitool, Iteration and Cost Limits, Mass-Update Gate] sources: [Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31] confidence: 0.50 confidence_base: 0.50 provenance: sourced summary: Entscheidung, eine wiederkehrende Fehlerregel in die Ausfuehrung einzubauen statt sie aufzuschreiben - Rangfolge erzwingen vor melden vor erinnern, belegt an einer Regel, die gelesen wurde und nicht wirkte --- # Structural Enforcement over Documented Rule **Typ:** Decision ## Definition Wo ein Fehler sich wiederholt, wird die Regel dagegen **in die Ausführung eingebaut**, statt sie aufzuschreiben. Eine aufgeschriebene Regel wirkt nur, solange jemand sie liest, sie im richtigen Moment erinnert und sie befolgt; eine strukturell durchgesetzte Regel macht den Fehler unschreibbar oder bricht sichtbar ab. Die Entscheidung ist nicht "Dokumentation ist wertlos". Sie ist eine Rangordnung für den Fall, dass beides möglich wäre: **erst erzwingen, dann dokumentieren, warum erzwungen wird.** Die Dokumentation erklärt die Regel und ihre Ausnahmen; sie trägt aber nicht die Durchsetzung. ## Kernpunkte - **Der harte Beleg: eine gelesene Regel hat den Fehler nicht verhindert.** Bei Gitea-Issue #8 führten zwei neue Tests dieselbe Umgebungsabhängigkeit erneut ein - geschrieben von jemandem, der das Issue vorher gelesen hatte[^s-conversation-hardening-the-test-suite-against-silent-environment-dependencies-session-2026-08-31]. Das ist kein Sorgfaltsmangel, sondern die Aussage über die Wirksamkeit von Prosa in diesem Fall: sie wurde gelesen und wirkte nicht. - **Der Stack wendet dasselbe Prinzip schon an anderer Stelle an.** Die Gates sind bewusst im Code durchgesetzt und nicht als Anweisung formuliert - ein Prompt-Limit ist eines, an dem ein Agent sich vorbeireden kann. Siehe [[Iteration and Cost Limits]] und [[Mass-Update Gate]]. Die Fixture-Entscheidung ist derselbe Grundsatz, angewandt auf die Testsuite. - **Erzwingen schlägt Melden, und beides schlägt Erinnern.** Rangfolge: (1) den Fehler unmöglich machen, (2) ihn beim Auftreten sichtbar abbrechen lassen, (3) ihn dokumentieren. Bei #8 war Option 1 die Fixture (die Abhängigkeit kann nicht mehr entstehen), Option 2 der zweite CI-Schritt (meldet nach dem Push), Option 3 der Satz im Issue - der bereits gescheitert war. - **Ein Guard, der erst nach dem Push meldet, schützt nicht dort, wo die Fehler entstehen.** Der verworfene zweite CI-Job hätte den Lauf des Entwicklers nie berührt. Geschrieben werden die Fälle aber genau dort. - **Ein Guard darf nicht auf einer zufälligen Eigenschaft seiner Umgebung beruhen.** Der CI-Container galt als "Maschine ohne globale git-Konfiguration"; seit `actions/checkout@v7` legt der Checkout selbst eine an[^s-conversation-hardening-the-test-suite-against-silent-environment-dependencies-session-2026-08-31]. Ein Guard mit dieser Voraussetzung hätte still aufgehört zu greifen, ohne roten Lauf. Die strukturelle Variante hängt an nichts dergleichen. - **Die Entscheidung wird begründet dort hinterlegt, wo jemand sie rückgängig machen würde.** Der Kommentar am CI-Tests-Schritt hält fest, warum es beim einen Lauf bleibt - sonst rüstet irgendwann jemand den zweiten aus dem alten Grund nach. Das ist die Rolle, die der Dokumentation bleibt: nicht die Regel tragen, sondern ihre Aufhebung teuer machen. - **Das Prinzip gilt rekursiv, und dort liegt seine offene Flanke.** Die Fixture aus `1.7.1` pflegt ihre Variablenliste von Hand, und die Pflicht zum Nachtragen steht - in Prosa. Das ist exakt dasselbe Muster eine Ebene höher und als Gitea-Issue #23 offen[^s-conversation-hardening-the-test-suite-against-silent-environment-dependencies-session-2026-08-31]. Wer dieses Concept anwendet, sollte prüfen, ob sein Guard selbst nur durch eine Regel zusammengehalten wird. - **Der Preis ist Aufwand vor dem Nutzen.** Erzwingen kostet Code, Tests für den Guard und einen Nachweis, dass er greift. Aufschreiben kostet einen Absatz. Der Tausch lohnt sich, wenn der Fehler wiederkehrt oder sein Schaden still ist - nicht bei jedem Einzelfall. ## Beispiele - [[wikitool]] - die autouse-Fixture aus `1.7.1`, die die Umgebungsabhängigkeit unschreibbar macht, statt in `instructions/dev/testing-conventions.md` davor zu warnen - [[Iteration and Cost Limits]] - 60 Aufrufe je Session und der Loop-Breaker, im Code durchgesetzt statt als Anweisung formuliert - [[Mass-Update Gate]] - Exit 42 mit Freigabe-Token statt der Bitte, vorsichtig zu sein - [[AGENTS.md]] - Invariante 8 ("eine Regel, ein Ort") ist die dokumentarische Hälfte desselben Anliegens: eine Regel kann nur erzwungen werden, wenn sie genau eine Fassung hat ## Wann zu verwenden - Ein Fehler ist zum zweiten Mal aufgetreten, besonders wenn der Verursacher die Regel dagegen kannte. - Der Fehler ist beim Entstehen unsichtbar und wird erst später und woanders sichtbar. - Die Regel wäre in einem Dokument abgelegt, das im entscheidenden Moment niemand offen hat. - Es gibt eine mechanische Prüfung, die den Fehler eindeutig erkennt - ohne die bleibt nur die Dokumentation. ## Wann NICHT zu verwenden - Für Urteilsfragen. Was auf eine Seite gehört, welcher Ton angemessen ist, ob ein Befund eine eigene Seite verdient - dafür gibt es keine mechanische Prüfung, und eine erzwungene Näherung wäre schlechter als eine gute Anleitung. - Für Einzelfälle ohne Wiederholungsrisiko. Ein Guard, der nie greift, ist Code, der gewartet werden muss und nichts trägt. - Wenn die Durchsetzung mehr Fehlalarme produziert als Funde. Ein Guard, dessen Meldungen man gewohnheitsmäßig überliest, hat den Schutz bereits verloren und kostet weiter. - Als Ersatz für die Begründung. Ein erzwungener Check ohne erklärenden Kommentar wird beim ersten Widerstand entfernt. ## Verwandte Concepts - [[Ambient Environment Dependency]] - [[Iteration and Cost Limits]] - [[Mass-Update Gate]] - [[Green Suite Blind Spot]] ## Beziehungen - **Gegenmittel zu:** [[Ambient Environment Dependency]] - **angewandt in:** [[Iteration and Cost Limits]] - **angewandt in:** [[Mass-Update Gate]] - **umgesetzt in:** [[wikitool]] ## Siehe auch - [[Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31]] - [[Ambient Environment Dependency]] - [[wikitool]] - [[Iteration and Cost Limits]] - [[Mass-Update Gate]] ## Fußnoten [^s-conversation-hardening-the-test-suite-against-silent-environment-dependencies-session-2026-08-31]: [[Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31]]