The Problem
Every new chat is a new contractor who has never seen your project.
You open a new session. Before you can ask for the thing you actually want, you type the same three paragraphs you typed yesterday: what this project is, what it's built with, and please stop making everything purple.
You ask for a new page. It comes back purple.
The agent is not being stupid. It is being new. Every session starts with one that has never seen your project and is very willing to guess — and a confident guess does not feel like a guess. It arrives as a decision, fully formed, in your files.
So you correct it. And the correction lands in a conversation, and the conversation ends.
The universal truth
Nothing you say to an agent survives the session unless it goes into a file. An agent with no written rules invents its own, confidently, and invents different ones next time. Your conventions live in your project as a pattern; the agent needs them as a sentence.
Every coding agent reads a project instructions file at the start of every session. In Claude Code that file is CLAUDE.md, sitting in the top level of your project folder; other agents read one under a different name, and if you're not sure which, ask yours. Writing the file is not the hard part. Knowing what belongs in it is — and every line that belongs in it, you have already typed, in a temper, into a chat window you have since closed.
The skill that does this
There's a skill that reviews this whole correction loop for you — vc-claude-md-harvester. Install it and it separates your real words from tool noise, groups repeated corrections, recovers the failure each rule prevents, and proposes the right home without overwriting anything. Do it by hand once first. The machine cannot safely decide whether two complaints mean the same rule, or whether that rule should govern every future session.
Do it by hand, once
Use one recent project session where you corrected the agent. Each step is one thing you say and one thing you then look at. Do not paste the whole transcript into a chat; keep the history on your own machine.
- Find the right history folder. Say: "Tell me the current project's path, then locate the Claude Code session-history folder that corresponds to it. Show me the candidate path and the newest session filenames. Do not read another project's history." Check the path yourself. Escaped folder names are easy to guess wrong, and a confident guess can mine somebody else's work.
- Separate your words from tool echoes. Say: "Write and run a small
nodescript that extracts only turns where a human actually typed words. Exclude tool results echoed back as user turns. Report the total labelled-user turns and the total human turns, then save the human text with timestamps." Spot-check three rows against the source. In one real session, 317 of 360 apparent user turns were tool output; a naive search is mostly the machine quoting itself. - Find what you paid for twice. Say: "Search the human turns for corrections — no, stop, don't, we use, never, always, why did you — and show the exact quote, date and nearby action that triggered each one. Do not turn them into rules yet." Read the context. "Don't do that" without the failed action beside it teaches nothing.
- Group by the rule, not the wording. Put corrections together only when they prevent the same failure. "We use pnpm", "stop using npm", and "why did you run npm install" are one rule with three receipts. Make this grouping yourself. Similar words can hide different boundaries, and the agent benefits from inflating the count.
- Choose the right home. For each group ask: is it a fact that should hold across the whole project, a folder-specific rule, a multi-step procedure, or something that must be mechanically blocked? Put those respectively in
CLAUDE.md,.claude/rules/, a skill, or a hook. Read the proposed home. A five-step procedure stuffed intoCLAUDE.mdwill be skimmed; a safety boundary written as advice will be ignored. - Check for drift before adding anything. Say: "Compare each candidate with the current
CLAUDE.md,.claude/rules/and project memory. Mark it new, already-said, or contradictory, and quote the existing line." A contradiction is more valuable than a new rule: it explains why the agent kept choosing both answers. - Propose; never overwrite. Say: "Write a separate candidates file with the proposed rule, the failure it prevents, the exact quotes, dates, count, destination and drift status. Leave every instruction file untouched." Read the ranked list and accept only rules you want governing a session you are not watching.
That is the loop. You found the right history, removed tool noise, recovered corrections with their failures, grouped repeated payments, chose the right home, checked for drift, and kept the proposal separate. At the fourth and seventh steps you made the calls the machine cannot safely make about the rules that constrain it.
Now let the skill run it
You are not going to parse session files and cluster corrections by hand every week. Install the skill and collapse the same loop to one instruction:
A normal request
"I keep explaining the same project rules in every new session. Find the corrections I repeat and show me which ones should become permanent."
It locates the project history, filters real human turns with a local node script, ranks repeated corrections, recovers the triggering failures, sorts each candidate into instructions, path rules, skills or hooks, checks the existing files for drift, and writes a separate proposal with quotes, dates and counts. It does exactly what you just did by hand. Your job is the last five minutes: deciding which corrections are truly one rule, then saying yes or no to the rules that will govern future sessions. The rest is why it works, and the four ways this file goes bad.
Why It Works
The instructions file people write on day one is always mediocre — mostly right, a bit generic, missing everything that makes the project theirs. It gets good by correction, and the corrections are the one thing you already have thousands of. You just have them in the worst possible form: scattered across sessions you closed, in the sentences you typed when you were annoyed. Those sentences are the most honest description of how you want to work that exists anywhere, and they are sitting on your hard drive in a format a machine can read.
Which is why the count matters more than the wording. One correction is a preference; you might never care again. The same correction twice is a rule you have now paid for twice, and the vendor's own guidance draws the line in exactly that place: put it in the file when the agent "makes the same mistake a second time", or when you type the same correction you typed last session (Anthropic's memory docs). Recurrence is the ranking because recurrence is the evidence.
And the second thing to understand about this file is what it can and cannot do to the agent. It is loaded as context. It persuades; it does not block. The same docs are blunt about it: the agent treats these instructions "as context, not enforced configuration", with no guarantee of strict compliance. So a rule that must hold every time — the tests run before every commit, that folder never gets written to — will be followed most of the time and fail exactly when it matters. Those belong in a hook: a small command the agent runs at a fixed moment, which can actually refuse. The skill flags them and hands them over with the detail everyone gets wrong the first time — Claude Code treats a hook exiting with code 1 as a non-blocking error and carries on anyway, so a hook meant to enforce a policy has to exit with code 2 (hooks docs).
Last: the file is read into every session, so it costs you something on every session. The docs target under 200 lines, because longer files consume more context and get followed less closely. A harvest that only ever adds lines degrades the file it is trying to improve, so the skill counts what you already have, adds its proposals, and if the total goes over, it tells you what to cut.
Where It Bites
1. The Groundhog Briefing
Symptom: every session opens with you typing the same intro. "This is a recipe site. It's a plain page with a bit of JavaScript. Don't add a framework."
Root Cause: you are storing your project's ground rules in your own head and re-uploading them by hand, every time. And the version you type when you're tired is shorter and worse than the fresh one.
Recovery:
- Run the skill first — it gets you the rules you have already earned.
- Then fill the gaps by hand: "Read my project and add what this is, what it's built with, and the conventions you can see me already following."
- Read what it wrote and cut every line that merely describes your folders. The agent can read your code. Keep only what it could never have guessed.
Prevention: anything you have typed at the top of a conversation twice belongs in the file, not in the conversation.
2. The Invented Convention
Symptom: a new colour every time. A new file layout every time. A third different library doing a job the first one already did. "Why does it keep picking a different one?"
Root Cause: your project has conventions, but they exist only as a pattern in your files — never as a stated rule. The agent finds nothing to follow and reaches for its own default. Its defaults are perfectly reasonable. They are just not yours, and they are not stable between sessions.
Recovery:
- Say: "List every place in my project where the same kind of thing is done two different ways — colours, file names, folder layout, how I handle dates."
- For each, pick the version you want. Not the "best" one — the one you'll remember.
- Say: "Write those into the instructions file as rules, one line each, plain language." Then, separately: "Now change the odd ones out to match."
Prevention: write the choice down the day you make it. An unwritten convention holds for exactly as long as you remember to retype it, and the agent has no memory of you ever having made a choice at all.
3. The Rule It Follows Most of the Time
Symptom: the file plainly says "always run the tests before you commit". It usually does. Then one afternoon it doesn't, and that is the afternoon something breaks.
Root Cause: you wrote an enforcement rule in a place that has no power to enforce. The instructions file is read as context and followed by judgment, and judgment has an off day. The failure rate is low enough that you trusted it and high enough to hurt you.
Recovery:
- Say: "Go through my instructions file and tell me which lines are facts you should know, and which are things that must happen every single time without exception."
- For the second list: "Set those up as hooks instead, and make them exit with code 2 so they actually block."
- Test one by deliberately doing the forbidden thing and watching it get refused.
Prevention: "always" and "never" in your instructions file are a smell. If the consequence of a miss is real, it needs a hook, and a hook that exits with code 1 does nothing at all.
4. The File It Never Loaded
Symptom: you wrote the file. It is a good file. The agent behaves exactly as though it does not exist — and you cannot tell whether it ignored the rule or never saw it.
Root Cause: the file is in a folder the agent doesn't read from, or you started the agent somewhere else in your project, or two files in the tree contradict each other and it picked one arbitrarily. You have been debugging your prose when the problem was your plumbing.
Recovery:
- Start a fresh session and run
/memory. It lists every instruction file loaded into the session you are actually in. - If yours is not in that list, the agent has never seen it, and every rule in it is decoration. Move it to where the list says instructions get loaded from.
- If it is in the list, say: "Find anything in here that contradicts itself, or isn't true any more." Resolve every one — faced with two conflicting rules, it will simply pick one.
Prevention: check the file is loaded before you spend an evening arguing with its wording. Do it once per project, on the day you create the file.
What to Say to Your Agent
- Harvest before you write. "Show me what I've corrected more than once, with the quotes and the counts." Read the counts. A three is a rule; a one can wait.
- Demand the failure, not just the rule. "For each one, tell me what actually went wrong that made me say it." A rule without its reason attached is a rule your future self deletes.
- Make it concrete enough to check. "Keep the styling tidy" is worthless. "All buttons use the green from the header, never blue" is a rule you can look at the code and verify. If you can't tell by looking whether it was followed, it isn't yet a rule.
- Route the "always" rules out of the file. "Which of these must hold every time? Set those up as hooks that exit with code 2."
- Keep it short on purpose. "We're over the line budget. What should come out, and what should move to a path-scoped rule?"
- Prove it loaded. "Run /memory and show me the list." Your file is on it, or none of this happened.
Keep these out of the file
- A tour of your folders. The agent can read your code. Anything it could have worked out by looking is costing you context and buying nothing.
- Anything that changes weekly. Today's plans are a conversation. A stale instruction is worse than no instruction, because the agent will loyally follow it.
- Secrets. No passwords, no keys. This file is read into every session and it is the first thing you'd hand to anyone you showed your work to.
Quick Reference
The starting move: "Mine my past sessions and show me what I've already corrected more than once." Then accept or reject each line.
The trigger, forever after: you correct the agent about the same thing a second time → it goes in the file. Now, not later.
- Goes in the file: what the project is · what it's built with · your conventions · your repeated corrections · the short never-do list.
- Goes in a hook instead: anything that must hold every time. Exit code 2 blocks; exit code 1 does not.
- Goes in a path-scoped rule: anything that only matters in one folder.
- Goes in a skill: anything that is a procedure rather than a fact.
- Stays out: a tour of your folders · this week's plans · secrets.
- The budget: under 200 lines. Longer files get followed less closely, not more.
The one check nobody runs: open a fresh session, run /memory, and confirm your file is in the list. If it is not there, the agent has never read a word of it.