Was eine Kontextdatei für einen Agenten ist
Eine Kontextdatei ist eine kurze Datei im Repository, die ein Coding-Agent vor jedem Auftrag liest. Sie sagt, wie man die Tests startet, welche Regeln das Team einhält und was niemand anfassen darf.
Ohne sie lernt der Agent Ihr Projekt bei jedem Auftrag neu und rät den Rest. Eine frühere Lektion zählt, was das Kontextfenster füllt; diese Lektion schreibt die Datei, die ein Team behält.
Am Ende dieser Lektion
Notiz
Ich kann eine kurze Kontextdatei schreiben, die einem Coding-Agenten sagt, wie er in einem Repository arbeitet.
Schlüsselwörter
| Begriff | Was er bedeutet | Beispiel |
|---|---|---|
| Kontextdatei | feste Notizen, die ein Agent vor jedem Auftrag liest | AGENTS.md |
| Konvention | eine Regel, die das Team immer einhält | |
| Befehl | eine Zeile, die Sie tippen, um etwas zu starten | npm run test |
| Geschützter Pfad | eine Datei oder ein Ordner, den der Agent nicht ändern darf | |
| Zeilengrenze | die meisten Zeilen, die die Datei haben darf |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
Eine Kontextdatei sagt, was der Code verschweigt
Der Code zeigt, was das Programm tut. Er zeigt nicht, wie das Team arbeitet. Eine Kontextdatei hat vier Arten von Zeilen: die Befehle zum Testen und Starten, die Konventionen, die geschützten Pfade und wo was liegt.
opencode, der Agent in diesem Labor, liest eine Datei namens AGENTS.md ganz oben im Projekt. Andere Agenten lesen Dateien mit anderen Namen.
Durchgerechnetes Beispiel: Zeilen behalten oder streichen
| Zeile | Behalten oder streichen | Warum |
|---|---|---|
| Tests starten mit npm run test | Behalten | Ein Befehl, den der Agent jedes Mal braucht |
| Preise sind ganze Cent, nie Dezimalzahlen | Behalten | Eine Konvention, die der Code nicht sagt |
| Nicht ändern: data/preise.json | Behalten | Ein geschützter Pfad |
| Der Kiosk wurde 2019 eröffnet | Streichen | Geschichte, die der Agent nicht braucht |
| gesamt addiert den Warenkorb | Streichen | Das sagt der Code schon |
| API_KEY=abc123 | Streichen | Ein Geheimnis gehört nie ins Repository |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
Kurz, wahr und sicher
Der Agent liest jede Zeile bei jedem Auftrag, jede Zeile kostet also Zeit und Platz. Legen Sie eine Zeilengrenze fest, etwa 40 Zeilen, und halten Sie sie ein.
Eine Zeile, die nicht mehr stimmt, ist schlimmer als keine Zeile. Ein Befehl, den es nicht gibt, schickt den Agenten in die falsche Richtung. Ein Pfad, der umgezogen ist, schützt nichts.
Ein häufiger Fehler
Warnung
Viele denken, eine längere Kontextdatei bringe bessere Arbeit. Eine Regel in Zeile 300 übersieht man leicht, als Agent wie als Mensch. Halten Sie die Datei kurz und prüfen Sie, ob jeder Befehl und jeder Pfad darin noch existiert.
Die Modellhilfe schreiben, Teil 1
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const basis = process.env.AI_URL || \"http://ai:4000\";' '// Die Token einer Antwort oder null, wenn sie keine nennt.' 'function zaehlen(daten, name) {' ' return daten.usage && typeof daten.usage[name] === \"number\" ? daten.usage[name] : null;' '}' > model.js"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Die Modellhilfe schreiben, Teil 2
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'async function fragen(nachrichten, probe, max) {' ' try {' ' const res = await fetch(basis + \"/v1/chat/completions\", {' ' method: \"POST\",' ' headers: { \"content-type\": \"application/json\", authorization: \"Bearer lab\" },' ' body: JSON.stringify({ model: \"lab\", messages: nachrichten, max_tokens: max || 100 }),' ' signal: AbortSignal.timeout(30000),' ' });' ' if (res.ok === false) throw new Error(\"Status \" + res.status);' ' const d = await res.json();' ' return { text: d.choices[0].message.content, eingabe: zaehlen(d, \"prompt_tokens\"), ausgabe: zaehlen(d, \"completion_tokens\"), aufgezeichnet: false };' ' } catch (fehler) {' ' console.log(\"Aufgezeichnete Probe: Kein Modell hat geantwortet (\" + fehler.message + \").\");' ' return { text: probe, eingabe: null, ausgabe: null, aufgezeichnet: true };' ' }' '}' 'module.exports = { fragen };' >> model.js"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Beispiel-Repository und Prüfung schreiben, Teil 1
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const fs = require(\"fs\");' 'const { fragen } = require(\"./model\");' 'const NL = String.fromCharCode(10);' 'fs.mkdirSync(\"ctx-demo/data\", { recursive: true });' 'fs.mkdirSync(\"ctx-demo/src\", { recursive: true });' 'const pkg = { name: \"kiosk\", scripts: { test: \"node --test\", lint: \"node lint.js\" } };' 'fs.writeFileSync(\"ctx-demo/package.json\", JSON.stringify(pkg, null, 2));' 'fs.writeFileSync(\"ctx-demo/data/preise.json\", JSON.stringify({ apfel: 35, saft: 85 }));' 'fs.writeFileSync(\"ctx-demo/src/kiosk.js\", \"module.exports = {};\" + NL);' > kontext.js"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Beispiel-Repository und Prüfung schreiben, Teil 2
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const entwurf = [\"# Notizen für Coding-Agenten\", \"Tests starten mit npm run test\",' ' \"Stil prüfen mit npm run lint\", \"Seite bauen mit npm run build\",' ' \"Preise sind ganze Cent, nie Dezimalzahlen.\", \"Nicht ändern: data/preise.json\",' ' \"Nicht ändern: geheim/schluessel.txt\", \"API_KEY=abc123 für den Testserver\"];' 'fs.writeFileSync(\"ctx-demo/AGENTS.md\", entwurf.join(NL) + NL);' >> kontext.js"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Beispiel-Repository und Prüfung schreiben, Teil 3
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const GRENZE = 40;' 'const SPERRE = \"Nicht ändern: \";' 'const zeilen = fs.readFileSync(\"ctx-demo/AGENTS.md\", \"utf8\").trim().split(NL);' 'const skripte = JSON.parse(fs.readFileSync(\"ctx-demo/package.json\", \"utf8\")).scripts;' 'const gefunden = [];' 'if (zeilen.length > GRENZE) gefunden.push(\"zu lang: \" + zeilen.length + \" Zeilen\");' >> kontext.js"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Beispiel-Repository und Prüfung schreiben, Teil 4
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'zeilen.forEach(function (zeile, nr) {' ' const woerter = zeile.split(\" \");' ' const i = woerter.indexOf(\"run\");' ' const wo = \"Zeile \" + (nr + 1) + \": \";' ' if (i > 0 && woerter[i - 1] === \"npm\" && skripte[woerter[i + 1]] === undefined) gefunden.push(wo + \"unbekanntes Skript \" + woerter[i + 1]);' ' const pfad = zeile.slice(SPERRE.length);' ' if (zeile.indexOf(SPERRE) === 0 && fs.existsSync(\"ctx-demo/\" + pfad) === false) gefunden.push(wo + \"unbekannter Pfad \" + pfad);' ' if (zeile.indexOf(\"KEY=\") >= 0 || zeile.toLowerCase().indexOf(\"passwort\") >= 0) gefunden.push(wo + \"sieht wie ein Geheimnis aus\");' '});' >> kontext.js"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Beispiel-Repository und Prüfung schreiben, Teil 5
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'async function main() {' ' console.log(\"AGENTS.md: \" + zeilen.length + \" Zeilen, Grenze \" + GRENZE);' ' gefunden.forEach(function (eins) { console.log(eins); });' ' const f = \"Schreiben Sie in einem kurzen Satz, warum die Kontextdatei eines Coding-Agenten kurz bleiben soll.\";' ' const probe = \"Der Agent liest jede Zeile bei jedem Auftrag, eine lange Datei begräbt also die wichtigen Regeln.\";' ' const antwort = await fragen([{ role: \"user\", content: f }], probe, 60);' ' console.log(\"Das Modell sagte: \" + antwort.text);' '}' 'main();' >> kontext.js"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Die Kontextprüfung ausführen
docker exec -w /home/node/project agent node kontext.jsHier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Was der Run ausgibt
| Zeile | Was sie zeigt |
|---|---|
| AGENTS.md: 8 Zeilen, Grenze 40 | Der Entwurf ist kurz genug |
| Zeile 4: unbekanntes Skript build | package.json hat kein Skript build |
| Zeile 7: unbekannter Pfad geheim/schluessel.txt | Den geschützten Pfad gibt es nicht |
| Zeile 8: sieht wie ein Geheimnis aus | Ein erfundener Schlüssel, der raus muss |
| Das Modell sagte: ... | Ein Satz aus dem Labor. Eine Aufgezeichnete Probe, wenn kein Modell antwortet |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.