What you end this module with
Core 1 of Context Engineering for Claude Code got you a brief. Then a session made three real decisions and never wrote them down anywhere but the chat. That is where this module starts.
You end with a CLAUDE.md, a first dev-doc, and a lessons.md : files a fresh session can read cold and still get the project right, without you in the room.
The lessons
In order. Each one answers a specific way work gets lost between sessions.
- git init and /init
A project with no git history has nothing to hand off. /init writes the first CLAUDE.md once there is something real to describe: code, or at minimum a scoped brief. - Install and run the updating-claude-md skill
A working CLAUDE.md today, without learning to build the skill yourself yet. Using a skill is not the same as building one. That comes later, in Specialist 4. - CLAUDE.md as the hub, not the archive
CLAUDE.md carries the gist and points at the file with the detail. Progress numbers and status-as-of blocks belong in the dev-doc they describe, not here. - docs/ shapes the idea, dev-docs/ records the build
docs/ holds the brief and the scope as they stand today. dev-docs/ is the dated trail of what actually happened, including the parts that went wrong. - Naming sessions and one session, one job
Brainstorming, researching and building are three different intents. Mixing them in one session is where decisions start getting lost. - The context gauge, compacting, restarting
Watch the window fill. Hand off by updating the files before compacting forces the choice for you. - lessons.md
The one file that turns a mistake into a rule instead of a repeat. Every entry here is something that actually happened.
Tip
No CLAUDE.md to write yet: there's no code here.
That's the real reply /init gave on a brief-only project: it needs actual code to analyze, and writing one anyway would mean making things up. On a project that's still just a brief, run the updating-claude-md skill instead. It reads what exists, even just docs/brief.md, and creates the first CLAUDE.md from that.
We cover Skills (what they are, and where they live) in more depth on the Claude Skills page.
The assignment
Starts from
The Core 1 brief, plus a session in which three decisions were made in conversation only. Same as where Stop Claude guessing left off.
Required output
CLAUDE.md, docs/, a first dev-doc, lessons.md.
Passes when
A fresh session, given only the files, states the goal, the approved decisions, the current state and the next action, without being told them.
Close the Claude Code chat. Does the work survive?
Open a fresh session against your own project and run this. Don't explain anything first. That's the point.
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'.A session with no memory of your conversation can only answer from the files. What it cannot answer is what a teammate would also miss.
Then check what the fresh session got wrong.
What the fresh session lost
- GoalIt couldn't state the goal, or got it wrong.
- Approved decisionsIt couldn't name a decision you'd already approved.
- Current stateIt couldn't say where the project stands today.
- Next actionIt couldn't say what happens next.
- 0 lost: Your files carried the whole handover on their own. That's the passing bar for Core 2: closing the chat didn't cost you anything.
- 1–2 lost: Some of the work still only lives in your head. Write the missing piece into CLAUDE.md or a dev-doc, then run the prompt again.
- 3–4 lost: Most of this project only exists in the conversation. Start with CLAUDE.md: it's the file a fresh session reads first.
Our own result
We ran this prompt twice on the reference project. The first time, only the brief existed. The second time, after CLAUDE.md, the first dev-doc and a commit, with the session's own memory moved aside so it read like a teammate opening the repo cold.
| Test 1: files only | Test 2: after CLAUDE.md + dev-doc + commit | |
|---|---|---|
| Goal | Recovered. | Recovered, same answer, now sourced. |
| Decisions | Brief-level only. Lost: the stale-fact threshold, the broken-file error rule, the consistency rule, the chosen build path, and the build order. | All of it, each with the file it came from. |
| State | Scoped, nothing built. | Scoped, nothing built. Same answer, now sourced from the dev-doc. |
| Next action | Not in the files. | Get the go-ahead to build, then start step one of the build order, sourced. |
The method correcting itself
During the reference project's Core 2 run, Claude answered “Saved” nine times after nine of the owner's decisions. It took three attempts to state what actually happened: the first two were wrong in different ways.
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.The tool log settled it: every “Saved” had gone to Claude Code's own auto-memory on that one laptop, outside the repo, invisible to anyone else who opened it. The fix went into the lessons file, in one line that says exactly what happened instead of the word “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.The work has to live in the repo, not in the person.
The project at this point
Three files from the reference project after Core 2, simplified samples. Same project every module, further along.
---
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.Where the knowledge repo lives
In enterprise teams the production repos sit under change control, so “just git init it” doesn't have an obvious home. Three real options, same as the org-wide version of this argument.
- A separate repo in the same org
Same admin boundary, same billing, but not under deployment change control. Usually the fastest to get approved, because nothing about production changes. - A repo outside the org entirely
Clean separation if the org's access rules make even a second internal repo hard to get. Costs you a second place to remember to look. - docs/ and dev-docs/ inside the existing repo
No new repo, no new approval. Works if the team can add plain-text folders without touching deploy paths or triggering the same review as code.
Let your project keep its own notes
Three free files: a Claude skill that rewrites your project notes when a session ends, a filled-in example of the record it keeps, and a sample plan you can copy.
