The chat that forgets
Most people use Claude the same way they use a search box. Open a tab, explain the situation, get an answer, close the tab. Tomorrow, open a new tab and explain the situation again.
That works until the work has a history. Then the cost shows up in three places. You spend the first ten minutes of every session rebuilding context. You get answers that contradict decisions you made last week, because nothing recorded them. And mistakes repeat, because the correction you typed on Tuesday lived only in Tuesday's tab.
A project is the fix, and it is not a clever prompt. It is a folder of plain text files that get read before every conversation, so the context stops being something you carry and becomes something the workspace holds.
Everything below is that idea, worked out in detail.
What a project actually is
Two different things are called "project mode" in practice, and mixing them up is the first source of confusion. Both are worth using. They work the same way underneath.
In the Claude app: a Project
Projects are self-contained workspaces with their own chat histories and knowledge bases. Inside each one you can upload documents, provide context, and hold focused chats. Two parts do the work:
- Project knowledge — documents, text, code or other files you upload, which Claude uses to understand the context and background of every individual chat inside that project.
- Project instructions — a set of instructions you define once for the project, to tailor how Claude responds in it.
Projects are available on every plan, including free accounts, which can create up to five. On paid plans, when the knowledge base approaches the context limit, retrieval kicks in automatically to expand capacity while keeping response quality. On Team and Enterprise plans a project can be shared with colleagues at view or edit level.
One thing to understand early: separate chats inside a project do not read each other. What they share is the instructions and the uploaded files. That is exactly why the files matter — they are the only memory that survives between conversations.
In Claude Code: the repository is the project
If you work in a repo, the same job is done by a file called CLAUDE.md sitting in the folder. Each session starts with a fresh context window, and CLAUDE.md files are instructions you write to give Claude persistent context across those sessions. You don't upload it. It is read from disk at the start of every session, along with any CLAUDE.md in the directories above it.
The practical translation: write the files once, use them in both places. Commit them to your repo so they are versioned, and upload the same files into the app project so a phone conversation and a terminal session are working from one manual.
The eight elements
A useful way to hold the whole thing in your head: eight parts, in the order you encounter them during a day of work. The first four set the work up. The last four close it out.
WORKSPACEThe repoOne folder that holds everything the product is.
MEMORYContext filesWhat you would otherwise re-explain, written down once.
BRIEFPlan modeAgree what will happen before anything is written.
TICKETA clear outcomeOne finished artifact, not an activity.
EYESPreviewLook at the result, don't take its word for it.
REVIEWThe checklistThe same list every time, built from real mistakes.
SCHEDULERoutinesWork that repeats, written so it can be handed over.
PERMISSIONSDelegation rulesWhat may happen without asking, and what may not.
Most people who try a project and abandon it have set up the first two and none of the rest. Workspace and memory alone give you a better-informed assistant. It is the brief, the ticket and the review that change how much finished work you actually get.
The files, decoded
This is the part that looks intimidating from the outside: a folder full of capitalised .md files that everyone seems to understand except you. There is no magic in them. They are markdown — plain text with headings and bullets. The capitalisation is convention, nothing more. Only one filename is special.
CLAUDE.md how to work, who the customer is, the quality bar ROADMAP.md what matters this week, what is out of scope REVIEW.md what to check before shipping app/ the thing that ships context/ what the product is and why customers/ who buys, what they said specs/ decided behaviour, written before it is built demos/ proof you can show a stranger routines/ work that repeats
CLAUDE.md — the only filename with special status
In Claude Code, this one is read automatically. Treat it as the place you write down what you would otherwise re-explain: add to it when the same mistake happens a second time, when a review catches something Claude should have known about this codebase, or when you type the same correction you typed last session.
Three rules from the official guidance are worth following exactly:
- Keep it short. Target under 200 lines. Longer files consume more context and reduce how consistently the instructions are followed.
- Be concrete enough to verify. "Use 2-space indentation" beats "format code properly"; "run npm test before committing" beats "test your changes".
- Remove contradictions. If two rules conflict, one may get picked arbitrarily.
One honest limitation, stated in the docs and worth repeating: CLAUDE.md is context, not enforced configuration. It shapes behaviour reliably; it does not physically prevent anything. If something must never happen, that belongs in a permission rule or a hook, not in a sentence.
If you're starting from an existing repo, running /init generates a first CLAUDE.md by analysing the codebase, and suggests improvements rather than overwriting when one already exists.
ROADMAP.md — and why "out of scope" is the valuable half
Four lines for this week. Each one a finished artifact, not an activity: "index.html v1 live" rather than "work on the homepage". Under it, two sections that matter more than the roadmap itself — decisions already made, with dates, and things explicitly out of scope.
The out-of-scope list is what stops you rebuilding the same argument every third week. It is also what stops Claude helpfully expanding the job while you weren't looking.
REVIEW.md — the checklist, built from your own mistakes
Write it the second time something goes wrong, not the first. Every blocker in it should be traceable to a real incident: a stale number that survived into a live page, a price hardcoded into HTML instead of read from its source file, vocabulary that arrived from somewhere else and stuck. The list turns those from accidents into things that cannot pass.
The folders
Six folders, one job each. /app is what ships. /context answers "why does this exist" for anyone arriving cold. /customers holds real people in their own words. /specs is behaviour decided before it is built — without a spec, "is this correct?" has no answer. /demos is proof you can show a stranger in two minutes. /routines is work that repeats.
Other filenames you'll see
| File | What it is |
|---|---|
CLAUDE.local.md | Personal project preferences that shouldn't be committed — add it to .gitignore. |
.claude/rules/*.md | Instructions split by topic, optionally scoped to file paths so they load only when Claude works with matching files. |
AGENTS.md | The neutral equivalent used by other tools. Claude Code reads CLAUDE.md, not AGENTS.md — if your repo already has one, create a CLAUDE.md that imports it with @AGENTS.md. |
MEMORY.md | Not yours to write. It is the index of auto memory — notes Claude writes for itself from your corrections and preferences, stored per repository. |
Everything else — ROADMAP.md, REVIEW.md, FOLDERS.md — is an ordinary file with a name you chose. It has weight because CLAUDE.md points at it, or because you uploaded it into the project knowledge.
Plan mode
Plan mode is the single highest-leverage thing on this page, and the least used.
It tells Claude to research and propose changes without making them: read files, run commands to explore, write a plan — but not edit your source. Edits stay blocked until you approve the plan.
The value is not politeness. It is arithmetic. A task with twenty decision points, each right most of the time, is wrong overall more often than you'd guess. Plan mode moves every one of those decisions to a moment where reversing costs a sentence instead of a rollback.
How to use it
Enter it by pressing Shift+Tab, or by prefixing a single prompt with /plan. You can also start a session in it with claude --permission-mode plan. In VS Code and the desktop app there is a mode selector next to the prompt box.
When the plan is ready, you get three choices: approve and let it run, approve and review each edit individually, or keep planning and say what to change. Ctrl+G opens the proposed plan in your text editor so you can rewrite it directly before anything proceeds. That last one is underrated — editing the plan is faster than describing the edit.
To make it the default for a project's terminal sessions, set defaultMode to plan in the project's .claude/settings.json.
The same discipline in a normal chat
Plan mode is a Claude Code feature. In the app there is no read-only switch — but the behaviour is one sentence in your CLAUDE.md, and it works:
plan-mode rule for a chat project
When a change is more than a small edit, propose the plan first: which files change, what changes in each, in what order, and why. Wait for my approval. Do not write the file until I approve.
The point of both versions is the same. Separate deciding from doing, and put yourself in between.
When to skip it
A typo fix does not need a plan. Plan mode earns its keep when the cost of a wrong first step is high: anything touching several files, anything structural, anything you would have to undo by hand.
The daily loop
Six moves. Once it is habit, a working session looks like this and nothing else.
-
Open the ticket, not the topic
One outcome, phrased as a finished artifact. "The pricing page reads its numbers from pricing.json and passes REVIEW" — not "let's improve pricing".
-
Ask for the plan
Plan mode, or the sentence from chapter 05. Read what comes back for the thing you didn't ask for. That's where scope creep lives.
-
Approve, correct, or narrow
Correcting a plan costs a sentence. Correcting a build costs a session. Narrowing is usually the right move — half the plan, done properly.
-
Build one file
One file, finished, before the next one starts. Two half-finished files are worth less than one finished file, and much harder to review.
-
Review before you look
Ask for the header first: file name, where it goes, what URL it becomes, one line on what changed, and which blockers from REVIEW.md were cleared. Then open it.
-
Write down what went wrong
The second time a mistake appears, it goes into REVIEW.md or CLAUDE.md as a rule. This step is the entire compounding mechanism. Skip it and you are back to the chat that forgets.
A real project
Abstract templates teach badly. Here is the actual shape of a project set up this week for aireadyinjector.com — a product site with its own worker, pricing file and public registry, run by one person.
Nine files went into the project knowledge: the three top-level markdown files, and one README for each of the six folders. The project instructions field got only the first and last sections of CLAUDE.md — how to work, and what is out of scope — because instructions are best spent on behaviour, with the detail left in the knowledge base.
What went into CLAUDE.md, and why
| Section | Why it exists |
|---|---|
| Canonical hierarchy | Company → flagship site → product → product site → audit engine. Every session used to start by re-explaining this. |
| Words we never use | Vocabulary that had drifted in from other tools and kept reappearing in copy. Listing it killed it. |
| One number, one file | The signal count had two different values in circulation. Naming the owning file ended the argument. |
| Prices come from pricing.json | A price hardcoded into HTML is a price that will be wrong on one page forever. |
| Readiness language only | Never "compliant", "certified" or "guaranteed" — claims the product cannot evidence. |
| The file header ritual | Before opening any file: number, upload path, resulting live URL, one-line description. |
Every line in that table came from something that had already gone wrong at least once. That is the whole method: a project file is a mistake that has been promoted to a rule.
What the roadmap looked like
Four lines for the week, each one a file. Under them, the decisions with dates — including the ones that killed earlier decisions, which is the part people forget to write down. Under that, a short out-of-scope list, mostly good ideas belonging to other properties.
The one that catches everyone
Six folders each want a README.md. Uploaded into project knowledge, six files called README.md collide — the last one wins and you quietly lose five. Rename them context-README.md, customers-README.md and so on before uploading, or put all six into one FOLDERS.md as in the templates below.
Set it up
Eight steps, written the way I want instructions written: where you are, what you click, what you see, what you do next. Fifteen minutes for the first project.
-
Create the project
Where: claude.ai, left sidebar
Click: Projects → Create project
See: a name and description field
Do: name it after the thing, not the category. "AI-READY INJECTOR", not "Work". -
Write CLAUDE.md first
Where: any text editor
Do: start from the template below and fill in sections 1, 2 and 5 only
See: roughly one page
Next: resist writing more. The file grows from real corrections, not from imagination. -
Write ROADMAP.md and REVIEW.md
Do: four roadmap lines for this week; three blockers in REVIEW you have already been burned by
See: two short files
Next: if you cannot name three past mistakes, ship one thing first and come back. -
Upload the knowledge
Where: inside the project, right-hand panel
Click: Project knowledge → Add content
See: your files listed with the percentage of context they occupy
Watch for: duplicate filenames overwriting each other. -
Set the project instructions
Click: Set project instructions
Do: paste only the "how to work with me" and "out of scope" sections
Why: instructions define behaviour; the knowledge base carries information. Mixing them wastes both. -
Commit the same files to your repo
Where: repository root
Do: commit CLAUDE.md, ROADMAP.md and REVIEW.md
Result: Claude Code reads CLAUDE.md automatically in every terminal session, and the files are versioned — you can see when a rule was added and why. -
Turn on plan mode where you code
Where: a Claude Code session
Do: press Shift+Tab until the status bar shows plan mode, or prefix a prompt with/plan
See: a written plan and three approval options instead of immediate edits. -
Run one real task through the loop
Do: take the first roadmap line and run chapter 06 end to end
Then: whatever annoyed you during that session becomes the first new line in CLAUDE.md or REVIEW.md. The project is now alive.
What breaks it
Writing the files as a wish list
The instinct is to write everything you hope will be true. What works is the opposite: write only what has already caused a problem. A file of twelve earned rules outperforms a file of sixty imagined ones, and it stays short enough to be followed.
Letting CLAUDE.md sprawl
Past a couple of hundred lines, the file eats context and adherence drops. When it grows, move the detail into the knowledge base or into path-scoped rules and keep the main file as the index.
Contradicting yourself across files
Two files claiming ownership of the same fact is the most common cause of "why did it use the old number?" Section 4 of the template exists for this: one fact, one owner, written down.
Treating instructions as enforcement
A line in CLAUDE.md is strong guidance, not a lock. Anything that must be structurally impossible belongs in permission rules or a hook.
Forgetting to re-upload after editing
A file edited in your repo does not update itself in the app's project knowledge. When a rule changes, change it in both places, or the two surfaces will start giving you different answers.
Never opening the files again
A project that is set up once and never revised is just a longer prompt. The compounding comes from step six of the loop.
Who it pays off for
The solo founder
Biggest gain, by a distance. You are the only person holding the context, and you hold it badly across three weeks and five properties. The project holds it instead, and your decisions stop evaporating.
The consultant or agency
One project per client. The client's vocabulary, constraints and approved claims live in their project and cannot leak into someone else's deliverable. Onboarding a second person becomes a file transfer instead of a briefing.
The small team
Shared projects on Team and Enterprise plans mean everyone gets the same standards without a meeting about standards. The review checklist becomes team property rather than one person's habit.
The non-developer
Nothing on this page requires code. A markdown file is a text file with headings. If you run a practice, a shop or an editorial calendar, the same three files — how we work, what matters now, what to check before publishing — do the same job.
Where it is overkill
One-off questions, throwaway drafting, anything with no history and no next session. Setting up a project for a single task costs more than it returns. The threshold is roughly: will I come back to this next week?
Templates
Copy from the page or download the files. No attribution required, no signup, nothing to buy.
CLAUDE.md
# CLAUDE.md
<!-- The operating manual for this project. Claude reads this first, every session.
Keep it under ~200 lines. Facts and rules only — no history, no narrative. -->
## 1. What this project is
- Product: <name> — <one sentence a stranger would understand>
- Live at: <domain>
- Repository: <owner/repo>
- Deployed by: <how a file gets from the repo to the live site>
- Primary language: <EN>. Secondary: <none>
## 2. Who the customer is
- Buyer: <role, company size, country>
- What they are trying to avoid: <the fear or cost>
- What they are buying: <the outcome, not the feature>
- What they already tried: <so we don't sell it again>
## 3. Words we use, words we never use
Use: <term>, <term>, <term>
Never use: <term>, <term>, <term>
## 4. Sources of truth
One fact, one file. If two files disagree, the one named here wins.
| Fact | Owner |
| --- | --- |
| Prices | `pricing.json` |
| <count / metric> | `<file>` |
| Legal identity | `<file>` |
Never hardcode a fact that a file already owns.
## 5. How to work with me
- One file at a time. Finish it, then ask before starting the next.
- Before opening any file, show: file number, exact upload path, resulting live
URL, one-line description of what changed.
- When a change is more than a small edit, propose the plan first. I approve,
then you write.
- If a request conflicts with this file, say so instead of guessing.
- Ask when a decision is mine to make. Don't invent a number, a price, a date,
a partner name, or a legal detail.
## 6. Definition of done
- [ ] Passes every line in `REVIEW.md`
- [ ] Every fact comes from a source of truth in section 4
- [ ] Works on mobile at 380px
- [ ] Claims nothing we cannot evidence
## 7. Out of scope
- <thing that keeps pulling attention>
- <the redesign that is not this week>
- <the feature that needs a decision I have not made>
ROADMAP.md
# ROADMAP.md Updated: <YYYY-MM-DD> ## This week Four lines. Each one a finished artifact, not an activity. 1. <file or page> — <what "done" looks like> 2. <file or page> — <what "done" looks like> 3. <file or page> — <what "done" looks like> 4. <file or page> — <what "done" looks like> ## Next, not now - <the good idea that would eat the week> - <the second product> ## Out of scope for this project - <thing that belongs to another site> - <thing that needs a partner decision> ## Decisions already made - <YYYY-MM-DD> — <decision>. Reason: <one line>. Replaces: <what it killed>. - <YYYY-MM-DD> — <decision>. Reason: <one line>. ## Open questions - <question> — needed before <which roadmap line>
REVIEW.md
# REVIEW.md
## Blockers — a file with any of these does not ship
- [ ] A number that contradicts the source of truth in `CLAUDE.md` section 4
- [ ] A price written into the page instead of read from `pricing.json`
- [ ] Vocabulary from the "never use" list
- [ ] A claim we cannot evidence ("certified", "guaranteed", "compliant")
- [ ] A link, file, or endpoint that returns 404
- [ ] A name, logo, or partner reference I did not approve
## Check before shipping
- [ ] Renders at 380px wide without horizontal scroll
- [ ] Every internal link resolves
- [ ] Metadata matches the visible page
- [ ] Nothing changed outside the file we agreed to touch
## How to report
1. File number and name
2. Exact upload path in the repo
3. Resulting live URL
4. One line: what changed
5. Which blockers were relevant and how each was cleared
## Mistakes log
- <YYYY-MM-DD> — <what broke> → new rule: <the line added above>
Sources
Product behaviour on this page comes from Anthropic's own documentation, checked on 2 September 2026. Where the docs and this page disagree, the docs are right.
- What are projects? — project knowledge, project instructions, plan availability, sharing
- How Claude remembers your project — CLAUDE.md, file locations, size guidance, rules, auto memory
- Choose a permission mode — plan mode, approval options, defaults
- Best practices for Claude Code