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

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

- [[Green Suite Blind Spot]]

## Beziehungen

## Siehe auch

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

## 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]]

<!-- wikitool:links -->
## Beziehungen

- **see-also:** [[Ambient Environment Dependency]]
- **mechanism:** [[wikitool]]
- **see-also:** [[Iteration and Cost Limits]]
- **see-also:** [[Mass-Update Gate]]
<!-- /wikitool:links -->