1. Share the map with Sam
After his personal triumph, Tommy returns to the portal — and for the first time not from scratch. In his hands is a rough PROJECT_NOTE, which he sketched out during the day. He rewrites it cleanly — no longer “scribbles for himself,” but a clear note: what the project is, which zones there are, what is load-bearing, and where it is scary to poke around blindly.
He reads it again — and catches a thought:
“Listen, this note turned out good. It’s a pity it’s only for me. I think it would be useful for Sam — then I wouldn’t have to explain every time what’s where.”
“That can be done.” Alex perks up. “You already hand it to Sam through @ whenever you remember, of course. But there’s a better way: make the agent read this note by itself at the start of every session, without your reminders. Put it in the project root under a special name — CLAUDE.md — and that’s it.”
“Hold on. How is that then different from my PROJECT_NOTE? Both are about the project.”
“Only in how they get into the stream. PROJECT_NOTE you keep for yourself and hand over manually, through @, whenever you remember. But CLAUDE.md lives in the project root under a special name, and the AI agent reads it itself and appends it to the start of the stream in every new session. Remember the three things in the story file? The last item there is Project rules — that’s exactly it. Write it once — the agent reads it forever, on its own.”
Tommy nods — the picture falls into place, and one more piece clicks in. Not new magic, just the same message stream: one file just gets dropped into it by itself, every time.
How a note gets into the stream. On the left, the same project note in two files: PROJECT_NOTE you put into the stream yourself through @, when you remember; CLAUDE.md lies in the project root, and the agent puts it into the stream by itself. On the right, three streams in a row. In the morning: agent instructions on top, project rules from CLAUDE.md below them, and in the history the PROJECT_NOTE you added. After /clear: CLAUDE.md is still there, but the note is gone from the history. Tomorrow, in a new session: CLAUDE.md is there again on its own, but the note has to be added by hand through @ again. CLAUDE.md is put at the start of every stream automatically — after /clear, after compression, the next day. The cost: it is read in every session and takes up space, so keep it short and to the point. The limit: it is advice to the agent, not a lock — it will read the rule but can still make a mistake. Bottom line: the same text — the difference is who puts it into the stream: you, when you remember; the agent, every time. How a note gets into the stream The same text the only difference is delivery PROJECT_NOTE you add it yourself, via @ — when you remember CLAUDE.md lies in the project root the agent adds it to the stream by itself — every time Morning session agent instructions CLAUDE.md project rules history @PROJECT_NOTE added by you you added the note, CLAUDE.md — by itself After /clear agent instructions CLAUDE.md project rules history PROJECT_NOTE gone with the history the note is gone, CLAUDE.md — still there Tomorrow agent instructions CLAUDE.md project rules history @PROJECT_NOTE by hand again the note — via @ again, CLAUDE.md — by itself again CLAUDE.md is put at the start of every stream automatically — after /clear, after compression, the next day Cost It is read in every session and takes up space each time. So keep it short and to the point, not a novel. Limit It is advice to the agent, not a lock: it will read the rule but can still make a mistake. Same text — the difference is who puts it into the stream: you, when you remember; the agent, every time“And what should go in there, besides the zone description?”
“Here’s the interesting part. Not just ‘what project it is.’ In CLAUDE.md, they put three kinds of things.” Alex counts on his fingers. “First — about the project: what it’s built with, which build and test commands there are, where which zones are. Second — how to work with you: all the way down to what tone to answer in, whether to use ‘you’ informally or formally, what to call you. Third — boundaries: what is load-bearing, where it’s dangerous to go. In other words, not just ‘here’s the project,’ but ‘here’s the project, here’s how to talk to me, and here’s where not to poke around.’”
2. How to start an empty CLAUDE.md
“Fine, I’ll set one up.” Tommy creates an empty CLAUDE.md in the portal root, and immediately loses steam. The cursor blinks in the void. “And… what do you even write? Where do you start? Sit down and draft rules for the entire project from scratch — that’s downright soul-crushing.” And there is more responsibility now — this is not just a document for him, but also an important instruction for the AI.
“Oh, that’s a familiar fear.” Alex smirks. “An empty file paralyzes everyone. Here are two hacks so you don’t have to write from scratch.”
Hack one — speak it aloud. “Remember the voice input utility, Handy? Don’t type — speak. Create a README.md file in the project and just say out loud, like you’re telling me now: what you’re building, what’s important here, what you’re afraid to touch, how you like to work. It will type it up on its own.”
Tommy perks up — typing long text isn’t his thing, and speaking it is much easier. He holds down the key and says everything he figured out about the portal during the day: the zones, what is load-bearing, where not to go. The text spills into README.md by itself.
“I have a draft,” he says. “Rough, but alive. Only this is README, not CLAUDE.md.”
Hack two — let the agent assemble the scaffold. “And now don’t move it by hand. There’s a command that will scan the project itself and fill in your empty CLAUDE.md for you:”
/init“It will go through the portal — see what it’s built with, what build and test commands there are, what the zone structure is — and it will even read your spoken README and take it into account. And it will lay all of that out as a neat draft in your CLAUDE.md. All you’ll have to do is skim it and add your own notes.”
Tommy runs /init. The agent scans the repository and assembles the first draft: it pulled the stack and commands out of the code itself, and the zone description and “where not to poke around” from the spoken README. The very same empty CLAUDE.md that Tommy was just moping over is now filled with a draft, and it already has almost everything needed. Tommy opens it, skims through it, and adds a couple of clarifications about fragile zones by hand.
“Where does it go now?”
“Nowhere,” Alex shrugs. “It’s already in place. The project root is its rightful place — the agent will find it there on its own.”
The file itself came out more detailed — with a table of zones and even a list of what the agent found broken along the way. Boiled down to the essentials, here’s what Tommy got:
# CLAUDE.md
Project: client's launch portal (retro arcade promo campaign).
Stack and commands: npm run build (build), npm test (tests).
Zones: showcase (pages/ + assets/), reward-flow, leaderboard, bonus-game, partner zones.
Load-bearing: showcase and reward-flow. Fragile: partner zones — do not touch blindly.“See?” Alex smirks. “No blank sheet. You spoke your thoughts into README aloud, /init read both the code and your README and assembled the scaffold, and you only skimmed and clarified. An empty file doesn’t scare you anymore.”
3. How to set the agent’s way of speaking
Tommy looks over the ready file — and notices something is missing. The agent now knows the project from it, but still speaks just as dryly, in a bureaucratic way — even in its /init report it addresses him formally: “your requests,” “won’t touch it without you.” And then Alex throws in:
“Want a trick? Add one line at the very bottom — how to address you.”
Tommy adds:
Address me informally, use “you,” and call me Tommy.Saves it, opens a new session — and the agent from the very first reply became one of their own: by name, in that exact tone, without bureaucracy. One line in a text file — and the character changed.
“Oh, that’s seriously awesome.” Tommy laughs.
The agent’s character is just text that can be rewritten. Tone, language, address, work rules — all lines in a file, not some setting baked in somewhere permanently. Don’t like it — change the line. Want it stricter — add it. No deep internals, no configs.
Alex suggests checking how the AI responds given the presence of CLAUDE.md
Tommy does exactly that right away — he asks the agent point-blank, deliberately without context:
What is the project built with, and what zones are there?And the agent answers right away, without asking again — because it read CLAUDE.md. It did open a couple of files — to double-check the details — but it already knew where to look: nobody had to explain to it what was where. Explain the project once — and you don’t repeat yourself anymore. And not just once: that will be the case for the entire life of the project.
“By the way,” Alex says in passing, “besides this file that you write yourself, the agent also has its own memory between sessions — it accumulates some facts and fixes on its own. You can peek into it like this:”
/memory“But that’s for later. For now just know it exists and can be viewed. We’ll go over it later, separately — it has its own subtleties.”