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

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

[^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]]

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

- **mechanism:** [[ENVIRONMENT.md]]
- **contrasts:** [[Personalization Plane]]
- **mechanism:** [[wikitool]]
- **operates-on:** [[Chemenu]]
<!-- /wikitool:links -->