chemenu/kb/concepts/decisions/Structural Enforcement over Documented Rule.md

type, concept_type, tags, created, modified, related, sources, provenance, summary

type	concept_type	tags	created	modified	related	sources	provenance	summary
types/concept.md	decision	quality tooling tests governance	2026-08-31	2026-08-31	see-also Ambient Environment Dependency mechanism wikitool see-also Iteration and Cost Limits see-also Mass-Update Gate	Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31	sourced	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¹ . 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¹ . 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¹ . 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

• Green Suite Blind Spot

Beziehungen

Siehe auch

• Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31

Fußnoten

Beziehungen

• see-also: Ambient Environment Dependency
• mechanism: wikitool
• see-also: Iteration and Cost Limits
• see-also: Mass-Update Gate

---

1. Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31 ↩︎