chemenu/kb/concepts/architectures/Optional Instance Context File.md

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

type	concept_type	tags	created	modified	related	sources	confidence	confidence_base	provenance	summary
types/concept.md	architecture		2026-08-31	2026-08-31	mechanism ENVIRONMENT.md contrasts Personalization Plane mechanism wikitool operates-on Chemenu	Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31	0.50	0.50	sourced	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¹ .

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 <Name>.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

Beziehungen

• mechanism: ENVIRONMENT.md
• contrasts: Personalization Plane
• mechanism: wikitool
• operates-on: Chemenu

---

1. Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31 ↩︎