--- type: types/concept.md concept_type: architecture tags: [] created: 2026-08-31 modified: 2026-08-31 related: - mechanism: ENVIRONMENT.md - contrasts: Personalization Plane - mechanism: wikitool - operates-on: Chemenu sources: [Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31] confidence: 0.50 confidence_base: 0.50 provenance: sourced summary: 'Muster fuer eine Datei, die eine Instanz ueber ihre Umgebung informiert, ohne Betriebsvoraussetzung zu sein: Health-Check meldet ohne zu scheitern, pro Checkout statt pro Repo' --- # Optional Instance Context File **Typ:** Architecture ## Definition Eine **Optional Instance Context File** ist eine Datei, die eine Instanz über ihre eigene Umgebung informiert, ohne Betriebsvoraussetzung zu sein: sie erspart einer Sitzung Fragen, deren Antworten sich selten ändern, und ihr Fehlen kostet Zeit, aber keine Korrektheit. Das Muster ist die schwächere Schwester der [[Personalization Plane]]. Beide liefern ein Template aus, beide füllen es in einem Setup-Schritt, beide prüfen das Ergebnis mit einem Health-Check. Der Unterschied liegt darin, was der Check tut, wenn die Datei fehlt — und dieser eine Unterschied entscheidet, ob „optional" hält oder nur behauptet ist. Erste Umsetzung: [[ENVIRONMENT.md]] in [[Chemenu]], Stack-Version `1.8.0`[^s-conversation-environment-md-as-an-optional-third-session-level-file-session-2026-08-31]. ## Kernpunkte - **Der Health-Check meldet, aber scheitert nie.** Eine fehlende Datei ergibt `OK` mit dem Vermerk „absent (optional)", kein `FAIL`. Ein `FAIL` würde die Datei durch die Hintertür verpflichtend machen und damit die Eigenschaft aufheben, um derentwillen sie entworfen wurde. Der Preis ihres Fehlens sind ein paar Fragen, keine falsche Ausgabe — und ein Check, der darauf rot wird, sortiert die beiden Kosten falsch ein. - **Genau ein Zustand ist meldenswert, und zwar als `WARN`:** ein umbenanntes, nie ausgefülltes Template. Diese Datei ist vorhanden, wird in jeder Sitzung mitgeladen und beantwortet nichts — schlechter als Abwesenheit, weil Abwesenheit ehrlich ist. Eine reine Existenzprüfung würde sie durchwinken; erkennbar wird sie über einen Sentinel im Template. - **Pro Checkout, nicht pro Repo.** Was hier steht, gilt einer Arbeitskopie: zwei Clones desselben Repos sind zwei Umgebungen. Deshalb ist die Datei gitignored, und deshalb ist eine committete Fassung schädlicher als gar keine — sie gibt dem zweiten Clone Antworten, die falsch sind statt zu fehlen, und eine falsche Angabe wird geglaubt. - **Das Ignore-Muster muss die Datei von ihrem Template trennen.** Das naheliegende `.md*` schluckt beides und nimmt der Distribution die Vorlage. Der Ausschluss gehört verankert und in beide Richtungen geprüft: die Datei muss ignoriert sein, das Template darf es nicht. - **Kontext, keine Autorität.** Die Datei beschreibt, was vorhanden ist, nicht, was erlaubt ist. Ein aufgeführter Remote autorisiert keinen Push an den Gates vorbei, ein aufgeführter Dienst öffnet kein Gate, und nichts darin ist eine Quelle für einen Wiki-Eintrag. Zugangsdaten gehören nicht hinein: die Datei liegt im Klartext und geht in jeden Agenten-Kontext. - **Raten ist schlimmer als Lücken lassen.** Der Setup-Schritt trägt ein, was aus dem Checkout ablesbar ist, fragt einmal nach dem Rest und akzeptiert „weiß ich nicht" — ein leerer Abschnitt wird gelöscht, nicht mit Plausiblem gefüllt. Eine geratene Zeile kostet mehr als die fehlende, aus demselben Grund, aus dem die Datei nicht committet wird. ## Beispiele - [[ENVIRONMENT.md]] — erste und bislang einzige Umsetzung: Harness, Skills, MCP-Server, Connectoren, Remotes, CI-Ort - [[wikitool]] — trägt den `environment`-Check in `doctor` und liefert das Template über `dist export` aus - [[CLAUDE.md]] — bindet die Datei als Import ein und trägt damit den Fall „Import, der legitim nie auflöst" ## Wann zu verwenden Wenn eine Angabe drei Eigenschaften zugleich hat: sie ändert sich selten, sie wird trotzdem immer wieder erfragt, und ihr Fehlen macht die Arbeit langsamer statt falsch. Dann lohnt eine Datei, und dann darf sie optional sein. Das Muster verlangt vier Dinge, die zusammengehören: ein ausgeliefertes Template, einen Setup-Schritt, der es anbietet statt es zu verlangen, einen Health-Check, der meldet ohne zu scheitern, und einen mechanisch geprüften Ausschluss aus der Versionskontrolle. Fehlt der Check, verrottet die Datei unbemerkt; fehlt der geprüfte Ausschluss, wandert eine Arbeitskopie in das Repo aller anderen. ## Wann NICHT zu verwenden - **Für Betriebsvoraussetzungen.** Was eine Instanz zum Funktionieren braucht, gehört in die [[Personalization Plane]] oder in einen echten `FAIL`. „Optional" ist eine Aussage über die Folgen des Fehlens, keine Höflichkeitsform. - **Für Angaben, die eine Maschine ermitteln kann.** `git remote -v` beantwortet sich selbst; aufgeschrieben wird, was sonst erfragt würde, nicht was ohnehin abrufbar ist. Ein aufgeschriebener Wert, den ein Kommando widerlegen kann, ist eine Kopie, die driftet. - **Für Regeln.** Wer Normatives hineinschreibt, erzeugt die zweite Kopie, die Invariante 8 von [[AGENTS.md]] verbietet. - **Für Geheimnisse.** Tokens und Passwörter gehören in die Shell-Konfiguration, nicht in eine Datei, die jede Sitzung mitliest. ## Verwandte Concepts - [[KB Stack Versioning]] — das Muster kam mit `1.8.0`, ohne Kompatibilitätsbruch ## Beziehungen ## Siehe auch - [[Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31]] ## Fußnoten [^s-conversation-environment-md-as-an-optional-third-session-level-file-session-2026-08-31]: [[Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31]] ## Beziehungen - **mechanism:** [[ENVIRONMENT.md]] - **contrasts:** [[Personalization Plane]] - **mechanism:** [[wikitool]] - **operates-on:** [[Chemenu]]