chemenu/kb/entities/systems/ENVIRONMENT.md.md

---
type: types/entity.md
entity_type: system
tags: []
created: 2026-08-31
modified: 2026-08-31
related:
  - implements: Optional Instance Context File
  - rests-on: Personalization Plane
sources: [Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31]
provenance: sourced
summary: 'Optionale, gitignorete Root-Datei: Harness, Skills, MCP-Server, Connectoren, Remotes und CI-Ort eines Checkouts; doctor meldet sie, scheitert aber nie an ihr'
---
# ENVIRONMENT.md

**Typ:** System

## Beschreibung

`ENVIRONMENT.md` hält fest, womit *ein bestimmter Checkout* arbeitet: welches Harness läuft,
welche Skills publiziert sind, welche MCP-Server erreichbar sind, welche Connectoren dranhängen,
wohin `publish` veröffentlicht und wo CI läuft. Es ist das dritte Root-Dokument der
Sitzungsebene neben `USER.md` und `SOUL.md`, und es beantwortet die Frage, die die beiden offen
lassen: `USER.md` sagt, *wer* die Instanz bedient, `SOUL.md`, *wie* sie klingt — womit sie
arbeitet, sagte bis dahin niemand.

Das Problem war nicht Unkenntnis, sondern Wiederholung. Es sind über Wochen konstante Werte, die
trotzdem jede Sitzung neu erfragte, weil nichts sie festhielt.

Die Datei ist **optional** und **gitignored**. Beides unterscheidet sie von der
[[Personalization Plane]], deren Muster sie sonst übernimmt; die Verallgemeinerung steht unter
[[Optional Instance Context File]].

## Kerndaten

- **Zweck:** Harness, Skills, MCP-Server, Connectoren, Remotes und CI-Ort eines Checkouts festhalten
- **Status:** Aktiv, eingeführt mit Stack-Version `1.8.0`[^s-conversation-environment-md-as-an-optional-third-session-level-file-session-2026-08-31]
- **Version:** eingeführt 2026-08-31, Commit `a243a4a`[^s-conversation-environment-md-as-an-optional-third-session-level-file-session-2026-08-31]
- **Sprache/Technik:** Markdown, Abschnittsvorgabe über `ENVIRONMENT.md.template`
- **Standort:** Repo-Wurzel: `/ENVIRONMENT.md` — gitignored, nie committet
- **Ausgeliefert:** nur als `ENVIRONMENT.md.template`, über die Root-Allowlist von `dist export`
- **Health-Check:** `wikitool doctor`, Prüfung `environment` — meldet, scheitert nie[^s-conversation-environment-md-as-an-optional-third-session-level-file-session-2026-08-31]

## Beziehungen
- **implementiert:** [[Optional Instance Context File]]

## Details

### Warum gitignored und nicht committet

Zwei Clones desselben Repos sind zwei verschiedene Umgebungen. Eine committete Fassung würde dem
zweiten Clone Antworten geben, die falsch sind statt zu fehlen — und falsch wiegt hier schwerer,
weil die Datei geglaubt wird. Das ist der Unterschied zu `USER.md`/`SOUL.md`, die committet sind
und lediglich vom Export ausgenommen werden.

Der Preis ist, dass ein frischer Clone die Datei nie mitbringt; `instructions/bootstrap.md`
Schritt 5 bietet das Anlegen deshalb ausdrücklich an.

### Das Ignore-Muster trennt Datei und Template

`.gitignore` trägt den verankerten Eintrag `/ENVIRONMENT.md`, der das `.template` bewusst nicht
trifft. Das naheliegende `ENVIRONMENT.md*` würde beide schlucken, und `dist export` verlöre
damit die Vorlage. `wikitool docs verify` prüft deshalb beide Richtungen: `ENVIRONMENT.md` steht
in `REQUIRED_IGNORE_CANARIES`, `ENVIRONMENT.md.template` in `REQUIRED_TRACKED_PATHS`[^s-conversation-environment-md-as-an-optional-third-session-level-file-session-2026-08-31].

### Kontext, keine Autorität

Die Datei beschreibt, was vorhanden ist, nicht, was erlaubt ist. Ein dort gelisteter Remote
autorisiert kein `git push` — Invariante 5 von [[AGENTS.md]] führt weiter über
`wikitool publish` —, ein gelisteter MCP-Server öffnet kein Gate, und nichts darin ist eine
Quelle im Sinne von Invariante 3. Zugangsdaten gehören nicht hinein: die Datei liegt im Klartext
im Arbeitsverzeichnis und in jedem Agenten-Kontext.

### Import statt Link

[[CLAUDE.md]] bindet sie als `@ENVIRONMENT.md` ein, nicht als Markdown-Link. Der Maßstab aus
`instructions/CONTRACT.md` ist, *wann* die Entscheidung fällt: importieren, was nebenbei
gebraucht wird, verlinken, was gezielt nachgeschlagen wird. Welcher MCP-Server welche Frage
beantwortet, wird mitten in einer Aufgabe gebraucht — und eine Sitzung, die erst nachschlagen
müsste, fragt stattdessen wieder den Nutzer, also genau die Kosten, die die Datei beseitigen
soll.

Ob Claude Code einen unaufgelösten `@import` still überspringt oder meldet, ist weiterhin
**unbestätigt** — dieselbe offene Frage, die [[CLAUDE.md]] seit `1.1.1` trägt. Sie wiegt hier
schwerer, weil Abwesenheit bei dieser Datei der Dauerzustand sein darf und nicht nur ein
Übergang während des Setups.

### Warum nicht unter `instructions/dev/`

Der Auftrag sprach von einer Erweiterung „im dev skillset". `instructions/CONTRACT.md` verbietet
jedoch Referenzen von außerhalb auf `instructions/dev/`, weil sie beim `dist export` ins Leere
zeigen würden; ein Link aus `CLAUDE.md` bräuchte die `dist:strip`-Marker-Konstruktion. Mehr
Mechanik für weniger Reichweite — und der Inhalt betrifft auch reine Content-Sitzungen, die
denselben Remote und denselben MCP-Server benutzen.

### Kein eigenes Kommando

Es gibt bewusst kein `wikitool environment`. Die Datei wird oft gelesen und selten geschrieben;
ein Kommando dafür wäre Maschinerie ohne Abnehmer. Die Oberfläche besteht aus dem Template und
zwei Instruktionsschritten (`bootstrap.md` Schritt 5, `setup-instance.md` Schritt 9).

## Historie

- 2026-08-31 — Angelegt mit Stack-Version `1.8.0` (Commit `a243a4a`), aus Gitea-Issue #24[^s-conversation-environment-md-as-an-optional-third-session-level-file-session-2026-08-31]

## Siehe auch
- [[Personalization Plane]]
- [[Optional Instance Context File]]
- [[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

- **implements:** [[Optional Instance Context File]]
- **rests-on:** [[Personalization Plane]]
<!-- /wikitool:links -->