Aufbau von CONTEXT.md — Die Spezifikation, die Ihr Coding-Agent zuerst liest

Jeder figmascope-Export beginnt mit einem .zip, das sieben Artefakte enthält. CONTEXT.md ist das Artefakt, das bewusst als Erstes gelesen wird — von Design. Es ist keine README-Datei. Es ist keine generierte Dokumentation. Es ist ein compilerstiler Vertrag zwischen dem Design und dem Agenten, der daraus Code erzeugen soll.

Dieser Beitrag erläutert, was darin enthalten ist, warum es so strukturiert ist und was schiefläuft, wenn Sie es überspringen.

Was ein Vertrag ist — und was Dokumentation ist

Dokumentation beschreibt, was existiert. Ein Vertrag legt fest, was wahr sein muss. Diese Unterscheidung ist entscheidend, wenn Ihr Leser ein LLM ist, das bereitwillig Abstands­werte erfindet, Layout-Hierarchien verflacht oder Hex-Farben hardcodiert, sobald es keine bessere Option hat.

CONTEXT.md beginnt mit einer Zieldeklaration:

# CONTEXT.md — Jetpack Compose target

This file is the authoritative spec for generating UI code from this bundle.
Read it before reading any other file.

Der Eintrag „Jetpack Compose target" ist kein Schmuck. Der Agent nutzt ihn, um Composable-Primitiven auszuwählen, dp- und sp-Einheiten zu unterscheiden, zu wissen, dass Modifier.padding() die richtige Abstraktion für Abstände ist, und zu verstehen, dass Box mit Alignment der richtige Ansatz für Overlay-Layouts ist. Ein React/Tailwind-Ziel erzeugt eine andere CONTEXT.md mit anderen Primitiven in den Einschränkungen.

Die Anweisung „zuerst lesen" ist ebenfalls bewusst. Agenten verarbeiten Kontext sequenziell. Erscheint eine Token-Regel erst nachdem der Agent bereits über eine Komponente nachgedacht hat, kommt die Einschränkung zu spät. Das Voranstellen des Vertrags bedeutet, dass die Regeln ab dem ersten Token der Generierung aktiv sind.

Der Abschnitt mit strikten Einschränkungen

Der wichtigste Teil von CONTEXT.md ist der Einschränkungs-Block:

## Strict constraints (must follow)

- Never hardcode dp values if a token exists within ±2dp
- Never flatten layout hierarchy — preserve every stack/overlay/absolute node
- Use stringRef values from strings.json, never inline literal text
- Treat missing fields as absent, not zero
- Do not invent component names not present in components/inventory.json

Jede Einschränkung existiert, weil Agenten sie verletzt haben. Die ±2dp-Token-Regel ist das deutlichste Beispiel. Ohne sie schreibt ein Agent, der auf einem Stack-Knoten mit gap: 14 stößt, Arrangement.spacedBy(14.dp). Mit der Regel prüft er, ob spacing.16 oder spacing.12 innerhalb von 2dp liegt, und verwendet stattdessen den Token. Das ist ein anderes Ergebnis — eines, das kohärent bleibt, wenn sich der Token-Wert ändert.

Die Hierarchie-Regel existiert, weil Compose ein Layout-Baum ist. Wenn ein Agent einen verschachtelten Stack in eine flache Liste positionierter Elemente umwandelt, zerstört er das responsive Verhalten, das die ursprüngliche Struktur impliziert. Das IR bewahrt jede Verschachtelungsebene aus gutem Grund — siehe Per-Screen IR — Stack, Overlay, Absolute, Leaf dazu, wie diese Verschachtelung die Layout-Absicht kodiert.

Die Einschränkung lautet nicht „verwende die Tokens, wenn du möchtest." Sie lautet „hardcode niemals, wenn ein Token existiert." Das ist ein Verbot, kein Vorschlag. LLMs reagieren auf Verbote anders als auf Vorschläge.

Die stringRef-Regel ist für i18n wichtig. Wenn ein Agent "Speed Test" direkt einbettet anstatt auf den Ressourcen-Schlüssel zu verweisen, entsteht ein Lokalisierungsloch. Die Einschränkung verweist den Agenten explizit auf strings.json.

Wie der Agent CONTEXT.md sequenziell liest

LLM-Kontextfenster verarbeiten Tokens von links nach rechts. Die Struktur von CONTEXT.md nutzt dies aus. Die Reihenfolge ist:

1. Zieldeklaration (legt den gesamten Generierungs-Rahmen fest)
2. Strikte Einschränkungen (Verbote, die für jede Entscheidung gelten)
3. Bundle-Übersicht (welche Dateien existieren und was jede enthält)
4. Token-Nutzungsregeln (wie Abstände, Farben, Radius und Typografie aufgelöst werden)
5. Scope-Hinweise (ehrliche Lücken — was dieses Bundle abdeckt und was nicht)

Der Bundle-Übersichts-Abschnitt teilt dem Agenten mit, welche Dateien er in welcher Reihenfolge lesen soll:

## Bundle contents

- tokens.json — design tokens (spacing, radius, color, typography)
- screens/*.json — per-screen IR in stack/overlay/absolute/leaf format
- components/inventory.json — component identity list
- strings.json — i18n resource keys
- _meta.json — generation metadata and warnings

Ohne diese Übersicht weiß ein Agent möglicherweise nicht, dass components/inventory.json existiert, oder behandelt _meta.json als Hauptspezifikation. Die explizite Aufzählung leitet die Lesereihenfolge.

Scope-Hinweise — was v0.4 ehrlich nicht abdeckt

Der Scope-Hinweis-Abschnitt ist der Ort, an dem figmascope seine eigenen Einschränkungen dokumentiert. Dies ist bewusst und nicht verhandelbar. Ein Agent, der nicht weiß, dass eine Spezifikation unvollständig ist, füllt die Lücken selbstbewusst mit Erfindungen. Das ist schlimmer als das Wissen um die Lücke.

## Scope notes (v0.4)

- Gradient fills are not supported. Nodes with gradient fills emit a warning
  in _meta.json under warnings. Treat as a solid fill approximation or TODO.
- Typography tokens require Figma Variables to be populated. If tokensSource
  is "inferred-from-frequency" or "none", typography coverage may be partial.
- This bundle covers UI structure only. Navigation, state management,
  and network calls are outside scope.
- Component instances are identified by componentId. Full component
  source props are not included — the inventory gives identity, not implementation.

Die Verlaufsfarben-Warnung ist besonders wichtig. Figma unterstützt komplexe Verlaufsfüllungen ohne direktes Compose-Äquivalent ohne benutzerdefiniertes Zeichnen. Anstatt Verläufe stillschweigend zu verwerfen oder fehlerhaften Code zu generieren, gibt figmascope eine background-gradient-not-supported:<name>-Warnung in _meta.json aus und vermerkt dies hier, damit der Agent betroffene Knoten als bekannte Lücke und nicht als Fehler in seiner eigenen Ausgabe behandelt.

Der Typografie-Hinweis hängt mit dem Feld tokensSource in _meta.json zusammen. Wenn eine Figma-Datei keine Variablen hat, leitet figmascope Tokens aus der Häufigkeit ab — häufige Werte werden zu Tokens, seltene nicht. Der Scope-Hinweis teilt dem Agenten mit, dass diese Ableitung unvollkommen ist, und er keine vollständige Typografie-Abdeckung annehmen soll. Siehe tokens.json erklärt für die Funktionsweise des Ableitungs-Fallbacks.

FALSCH / RICHTIG-Beispiele

Machen wir das konkret. Gegeben ein Stack-Knoten mit gap: 16 und einer Token-Datei mit spacing.16: 16:

Ohne CONTEXT.md-Einschränkungen (FALSCH):

Column(
    modifier = Modifier.padding(horizontal = 24.dp),
    verticalArrangement = Arrangement.spacedBy(16.dp)
) {

Mit CONTEXT.md-Einschränkungen (RICHTIG):

Column(
    modifier = Modifier.padding(horizontal = Spacing.spacing24),
    verticalArrangement = Arrangement.spacedBy(Spacing.spacing16)
) {

Die RICHTIGE Ausgabe referenziert Tokens. Wenn das Design-System spacing.16 von 16dp auf 14dp ändert, bleibt der Code korrekt — ohne eine codebase-weite Suche-und-Ersetze-Aktion.

Ein weiteres Beispiel — String-Behandlung. Gegeben ein Leaf-Knoten mit text: "Speed Test" und stringRef: "speed.test":

FALSCH:

Text(text = "Speed Test")

RICHTIG:

Text(text = stringResource(R.string.speed_test))

Die Einschränkung verweist auf strings.json, der Schlüssel ist speed.test, und der Agent weiß, wie er Punkt-Notation auf Android-Ressourcen-IDs abbildet. Das ist nur möglich, wenn der Agent die Einschränkung gelesen hat, bevor er die Komponente generiert.

Warum nicht einfach den Agenten selbst anweisen?

Sie könnten diese Anweisungen manuell in Ihren Prompt schreiben. figmascope lagert sie in eine Datei aus, weil:

• Die Einschränkungen aus dem tatsächlichen Bundle abgeleitet werden. Die ±2dp-Regel ergibt nur Sinn, wenn tokens.json existiert. CONTEXT.md wird in Kenntnis der vorhandenen Tokens generiert.
• Projektspezifische Scope-Hinweise variieren je nach Datei. Eine Figma-Datei mit vollständiger Variablen-Abdeckung erhält einen anderen Typografie-Hinweis als eine mit abgeleiteten Tokens.
• Die Datei ist im ZIP. Sie können sie als Kontext referenzieren, ohne kopieren und einfügen zu müssen. Cursor, Claude Code und ähnliche Tools unterstützen @-Datei-Referenzen.
• Sie ist reproduzierbar. Jeder Export derselben Figma-Datei erzeugt dieselbe CONTEXT.md. Der Agent Ihres Teams liest jedes Mal denselben Vertrag.

Das Ziel ist nicht, die Standardeinstellungen des Agenten durch Prompt-Engineering zu umgehen. Es ist, eine Spezifikation zu liefern, die die Standardeinstellungen irrelevant macht.

Vergleich mit Alternativen

Figmas Dev Mode gibt Maße, Variablen und Code-Schnipsel aus. Es erzeugt keine Spezifikation. Der Agent, der Dev-Mode-Ausgaben verwendet, muss Regeln aus Beispielen ableiten — was bedeutet, dass er für Randfälle falsche Regeln ableiten wird.

Locofy und ähnliche Tools generieren Code direkt. Sie haben kein CONTEXT.md-Äquivalent, weil sie nicht erwarten, dass ein Agent eine Spezifikation liest — sie erwarten, der Agent zu sein. Das funktioniert, wenn die Code-Generierung des Tools genau mit Ihrem Stack übereinstimmt. Es funktioniert nicht, wenn Sie projektspezifische Namens­konventionen, eine benutzerdefinierte Komponentenbibliothek oder ein Design-System mit Tokens haben, die das Tool nicht kennt.

CONTEXT.md ist ein maschinenlesbares Design-Briefing. Es ist das Artefakt, das in jedem Design-Handoff vor dem LLM-Zeitalter als Confluence-Seite oder Notion-Dokument existierte — nur strukturiert für ein Publikum, das Regeln tatsächlich befolgt.

Wie Sie damit arbeiten

Wenn Sie einen figmascope-Export in Cursor oder Claude Code öffnen:

1. Fügen Sie @CONTEXT.md Ihrem Kontext hinzu, bevor Sie irgendeinen Prompt über das Design stellen.
2. Referenzieren Sie den Screen-JSON, an dem Sie arbeiten: @screens/home.json.
3. Wenn Sie Tokens verwenden, fügen Sie @tokens.json hinzu.
4. Wenn Sie mit Strings arbeiten, fügen Sie @strings.json hinzu.

Die CONTEXT.md-Einschränkungen gelten für die gesamte Sitzung, sobald sie geladen sind. Sie fügen die Datei nicht pro Prompt erneut hinzu — Sie fügen sie einmal zu Beginn hinzu und lassen sie jede nachfolgende Generierung rahmen.

Die anderen Artefakte im Bundle werden im Rest dieser Serie behandelt. Beginnen Sie mit tokens.json erklärt für die Funktionsweise des Token-Systems bei Dateien mit und ohne Figma-Variablen, oder mit Per-Screen IR für die Abbildung von Figma-Layouts auf Stack/Overlay/Absolute/Leaf-Knoten. Bereit, es auszuprobieren? Fügen Sie Ihre Figma-URL auf figmascope.dev ein und exportieren Sie Ihr erstes Bundle.