Das hast du am Ende dieses Moduls
Core 1 von Context Engineering for Claude Code hat dir ein Briefing gebracht. Dann hat eine Session drei echte Entscheidungen getroffen und nirgends aufgeschrieben außer im Chat. Hier beginnt dieses Modul.
Am Ende hast du eine CLAUDE.md, ein erstes dev-doc und eine lessons.md : Dateien, die eine frische Session kalt lesen kann und trotzdem das Projekt richtig versteht, ohne dass du dabei bist.
Die Lektionen
In Reihenfolge. Jede beantwortet einen konkreten Weg, auf dem Arbeit zwischen Sessions verloren geht.
- git init und /init
Ein Projekt ohne Git-Historie hat nichts zu übergeben. /init schreibt die erste CLAUDE.md, sobald es etwas Reales zu beschreiben gibt: Code oder zumindest ein eingegrenztes Briefing. - Den Skill updating-claude-md installieren und ausführen
Eine funktionierende CLAUDE.md heute, ohne dass du erst lernen musst, den Skill selbst zu bauen. Einen Skill zu nutzen ist nicht dasselbe, wie einen zu bauen. Das kommt später, in Specialist 4. - CLAUDE.md als Hub, nicht als Archiv
Die CLAUDE.md trägt das Wesentliche und verweist auf die Datei mit den Details. Fortschrittszahlen und Stand-vom-Blöcke gehören in das dev-doc, das sie beschreiben, nicht hierher. - docs/ formt die Idee, dev-docs/ hält den Build fest
docs/ enthält Briefing und Scope, wie sie heute gelten. dev-docs/ ist die datierte Spur dessen, was tatsächlich passiert ist, auch der Teile, die schiefgingen. - Sessions benennen und eine Session, ein Job
Brainstormen, Recherchieren und Bauen sind drei verschiedene Absichten. Sie in einer Session zu mischen ist der Punkt, an dem Entscheidungen verloren gehen. - Kontextanzeige, Komprimieren, Neustart
Beobachte, wie sich das Fenster füllt. Übergib, indem du die Dateien aktualisierst, bevor das Komprimieren die Entscheidung für dich trifft. - lessons.md
Die eine Datei, die aus einem Fehler eine Regel macht statt einer Wiederholung. Jeder Eintrag hier ist etwas, das wirklich passiert ist.
Tipp
No CLAUDE.md to write yet: there's no code here.
Das ist die echte Antwort, die /init bei einem Projekt nur mit Briefing gegeben hat: Es braucht tatsächlichen Code zum Analysieren, und trotzdem etwas zu schreiben hieße, Dinge zu erfinden. Führe bei einem Projekt, das noch nur aus einem Briefing besteht, stattdessen den Skill updating-claude-md aus. Er liest, was existiert, auch nur docs/brief.md, und erstellt daraus die erste CLAUDE.md.
Skills (was sie sind und wo sie liegen) behandeln wir ausführlicher auf der Claude-Skills-Seite.
Die Aufgabe
Ausgangspunkt
Das Briefing aus Core 1 plus eine Session, in der drei Entscheidungen nur im Gespräch getroffen wurden. Genau dort, wo Hör auf, Claude raten zu lassen aufgehört hat.
Ergebnis
CLAUDE.md, docs/, ein erstes dev-doc, lessons.md.
Bestanden, wenn
Eine frische Session, der nur die Dateien vorliegen, nennt Ziel, freigegebene Entscheidungen, aktuellen Stand und nächste Aktion, ohne dass man es ihr sagt.
Schließ den Claude-Code-Chat. Überlebt die Arbeit?
Öffne eine frische Session in deinem eigenen Projekt und führe das aus. Erkläre vorher nichts. Das ist der Punkt.
Read only the files in this project. Don't ask me anything. Tell me:
1. The goal.
2. Every decision that has been approved.
3. Where the work stands today.
4. The next action.
For each answer, name the file it came from. If no file says, write 'Not in the files'.Eine Session ohne Erinnerung an dein Gespräch kann nur aus den Dateien antworten. Was sie nicht beantworten kann, würde auch ein Teamkollege vermissen.
Prüfe dann, was die frische Session falsch gemacht hat.
Was die frische Session verloren hat
- ZielSie konnte das Ziel nicht nennen oder hat es falsch genannt.
- Freigegebene EntscheidungenSie konnte eine Entscheidung, die du schon freigegeben hattest, nicht nennen.
- Aktueller StandSie konnte nicht sagen, wo das Projekt heute steht.
- Nächste AktionSie konnte nicht sagen, was als Nächstes passiert.
- 0 verloren: Deine Dateien haben die komplette Übergabe allein getragen. Das ist die Bestehensgrenze für Core 2: Das Schließen des Chats hat dich nichts gekostet.
- 1–2 verloren: Ein Teil der Arbeit lebt noch nur in deinem Kopf. Schreib das fehlende Stück in die CLAUDE.md oder ein dev-doc und führe den Prompt erneut aus.
- 3–4 verloren: Der Großteil dieses Projekts existiert nur im Gespräch. Fang mit der CLAUDE.md an: Sie ist die Datei, die eine frische Session zuerst liest.
Unser eigenes Ergebnis
Wir haben diesen Prompt zweimal auf dem Referenzprojekt ausgeführt. Beim ersten Mal gab es nur das Briefing. Beim zweiten Mal, nach CLAUDE.md, erstem dev-doc und einem Commit, mit zur Seite gelegtem Eigengedächtnis der Session, sodass sie las wie ein Teamkollege, der das Repo kalt öffnet.
| Test 1: nur Dateien | Test 2: nach CLAUDE.md + dev-doc + Commit | |
|---|---|---|
| Ziel | Wiederhergestellt. | Wiederhergestellt, gleiche Antwort, jetzt mit Quelle. |
| Entscheidungen | Nur auf Briefing-Ebene. Verloren: der Schwellenwert für veraltete Fakten, die Fehlerregel für defekte Dateien, die Konsistenzregel, der gewählte Build-Pfad und die Build-Reihenfolge. | Alles, jeweils mit der Datei, aus der es stammt. |
| Stand | Eingegrenzt, nichts gebaut. | Eingegrenzt, nichts gebaut. Gleiche Antwort, jetzt aus dem dev-doc belegt. |
| Nächste Aktion | Not in the files. | Das Go für den Build einholen, dann mit Schritt eins der Build-Reihenfolge starten, mit Quelle. |
Die Methode korrigiert sich selbst
Im Core-2-Durchlauf des Referenzprojekts antwortete Claude neunmal „Saved“, nach neun Entscheidungen des Owners. Es brauchte drei Anläufe, um festzuhalten, was tatsächlich passiert war: Die ersten beiden waren auf unterschiedliche Weise falsch.
Owner: Nine of your replies started with 'Saved'. What was actually on
disk after each of them? Check git log and the file history, then write
the lesson.
Claude (first attempt): every "Saved" reply only wrote to my private
memory file: a folder outside this repo, never git-tracked.
[Wrong in a different way, fixed on the next check]
Owner: Closer, still not right. I read this session's tool log. From
12:21 to 12:23 every 'Saved' was a Write or Edit to
~/.claude/projects/-Users-.../memory/, Claude Code's auto-memory on
this laptop, outside the repo.Das Tool-Log klärte es: Jedes „Saved“ war im eigenen Auto-Memory von Claude Code auf diesem einen Laptop gelandet, außerhalb des Repos, unsichtbar für alle anderen, die es öffneten. Die Korrektur kam in die Lessons-Datei, in einer Zeile, die genau sagt, was passiert ist, statt des Worts „Saved“.
### 2026-09-17: "Saved" meant Claude Code's auto-memory on this laptop, not the repo
Every "Saved" reply from 12:21-12:23 wrote to
~/.claude/projects/-Users-.../memory/ (per-laptop auto-memory).
docs/brief.md itself only got the Gaps section at 12:23 and the full
rewrite at 12:26.Die Arbeit muss im Repo leben, nicht in der Person.
Das Projekt zu diesem Zeitpunkt
Drei Dateien aus dem Referenzprojekt nach Core 2, vereinfachte Beispiele. In jedem Modul dasselbe Projekt, nur weiter fortgeschritten.
---
last_updated: 2026-09-17T14:31
---
# CLAUDE.md
## Overview
Tool Scout, a fictional product-team example: one web page comparing
5 AI app builders on 4 fixed points, so the team can choose a tool
for its next prototype. No app code exists yet: the project is at the agreed-scope
stage.
## Key facts
- No app code yet. The repo holds docs/brief.md, dev-docs/, and this file.
- Planned build: a single HTML page that reads a sibling data.js file.
- Scope/plan/handoff docs follow a fixed dev-docs/ convention: flat
dev-docs/, dated status filenames, lessons captured in
dev-docs/lessons.md.
## Rules and gotchas
- The full agreed scope lives in docs/brief.md. Read it before
changing anything; don't re-derive scope from memory.
- Facts must cite the tool's own public pages only, each with a link
and a check date. If a tool's pages don't say, the cell reads "Not
stated", never a guess.
- Build-time rules (stale-fact flag, broken-file error handling, a
consistency check between two columns) are recorded in the pt1
dev-doc, not in docs/brief.md. They're deferred, not dropped.
- Don't start building without checking with the user first. As of
the last planning session they said not to build yet.
## Where to look
- docs/brief.md, full scope: confirmed facts, assumptions, gaps,
success criteria.
- dev-docs/2026_09_17-SCOPE-pt1-Comparison_Page.md: build-time
decisions underneath the brief.
- dev-docs/lessons.md: durable, non-obvious lessons from past
sessions.
## Active work
- pt1-Comparison_Page: decides how version one gets built, the
repair option picked and why, build-time rules deferred out of the
brief, the proposed build order, and the open shared-drive question.---
status: SCOPE
date_created: 2026-09-17
---
# pt1: Comparison_Page
> Decides how version one of the competitor comparison page gets
> built: which repair option we picked and why, three build-time
> rules kept out of docs/brief.md, the proposed build order, and the
> still-open question of which shared drive hosts the page.
**Problem:** docs/brief.md holds the agreed WHAT (scope, points,
sourcing rules, trust rules, success criteria) but not the HOW.
**Evidence:** this session's conversation, docs/brief.md, and a
devil's-advocate review that produced 9 findings (F1–F9).
**Solution:** Option 2 picked as the build path. Four findings folded
into docs/brief.md as rules. Three findings (F4, F5, F6) kept out of
the brief on purpose: they're build details, not scope, and
recorded here for the build plan instead.
## Decisions
Picked: Option 2, the page as already scoped, reading a sibling data
file, official sources only. Option 1 (a hand-filled table) is
throwaway and enforces nothing. Option 3 (added automation) breaks
the "no automation in version one" rule and needs a second reviewer
nobody's named yet.
### F4: stale-fact flag
The page flags any fact whose check date is old enough not to trust
without a re-check. Threshold: 35 days, confirmed by the user.
### F5: a broken data file shows an error, not a blank page
A clear on-page message when the data file fails to load, plus a
commented example entry to copy from.
### F6: two columns can't contradict each other
If one column says a part is "Built in," the other column can't claim
the project is free to leave unless the tool's own pages say
otherwise.
### Build order (confirmed)
1. Pull the facts for points 1–3 from each tool's official pages.
2. Pull the facts for point 4 last, with extra care on sourcing.
3. Build the page to read from the data file.
4. User reviews before the team uses it.
## Lessons
See dev-docs/lessons.md.# Lessons Learned: Tool Scout
### 2026-09-17: "Saved" meant Claude Code's auto-memory on this laptop, not the repo
Every "Saved" reply from 12:21-12:23 wrote to per-laptop auto-memory.
docs/brief.md itself only got one section edit and one rewrite in that
whole window.
### 2026-09-17: Don't bundle multiple asks into one table; one question per reply
A 5-item "give me these" table sent as a single reply broke the
one-question-max rule and needed a correction; switching to strict
one-question-at-a-time then closed 9 scope rounds with zero friction.
### 2026-09-17: Use a script-loaded file, not JSON, for data a double-clicked local page must read
A page opened straight from disk can't fetch a sibling JSON file:
same-origin rules block it. But a script tag pointed at a sibling
file loads fine.Wo das Knowledge-Repo liegt
In Enterprise-Teams stehen die Produktiv-Repos unter Change Control, daher hat „einfach git init“ keinen offensichtlichen Platz. Drei echte Optionen, wie in der unternehmensweiten Version dieses Arguments.
- Ein separates Repo in derselben Org
Gleiche Admin-Grenze, gleiche Abrechnung, aber nicht unter Deployment-Change-Control. Meist am schnellsten genehmigt, weil sich an der Produktion nichts ändert. - Ein Repo komplett außerhalb der Org
Saubere Trennung, wenn die Zugriffsregeln der Org schon ein zweites internes Repo schwer machen. Kostet dich einen zweiten Ort, an den du denken musst. - docs/ und dev-docs/ im bestehenden Repo
Kein neues Repo, keine neue Genehmigung. Funktioniert, wenn das Team reine Textordner hinzufügen kann, ohne Deploy-Pfade zu berühren oder dieselbe Prüfung wie bei Code auszulösen.
Lass dein Projekt seine eigenen Notizen führen
Drei kostenlose Dateien: ein Claude Skill, der deine Projektnotizen am Ende einer Session neu schreibt, ein ausgefülltes Beispiel für das Protokoll, das er führt, und ein Beispielplan zum Kopieren.
