Rules & memory

The last chapter was about thinking inside a session — researching, proposing, agreeing on an approach before any code moved. But every move you’ve made so far evaporates the moment you close the terminal. Plan mode makes the agent smart for one conversation; this chapter makes it smart across all of them. It’s the difference between an engineer who’s sharp today and one who actually knows your codebase.

Here’s the friction this fixes, and you’ve almost certainly felt it. Every session on the payments service opens the same way: you tell the agent the test command is npm test, you remind it that charges are stored in cents not dollars so it stops generating off-by-100 bugs, you re-explain that your team writes commit messages in Conventional Commits format. It listens, it complies — and tomorrow it’s forgotten all of it, because tomorrow is a fresh context window. You are paying the same tax, in tokens and in typing, every single day.

The fix is the whole point of this site: write the context down once so the agent always has it. A fact you establish in a CLAUDE.md file is a fact you never re-establish. That’s context engineering at its most concrete — you stop renting the agent its knowledge of your project by the session and start owning it.

The two ways context persists

Claude Code carries knowledge across sessions through two complementary mechanisms, and the distinction runs through this whole chapter:

• CLAUDE.md files — instructions you write. Rules, conventions, architecture, “always do X.” Loaded into every session, in full, at launch.
• Auto memory — notes Claude writes for itself, based on your corrections and what it learns as it works. You don’t author it; you audit it.

You guide the agent’s behavior with the first and let it accumulate learnings with the second. Most of this chapter is about the first, because that’s the lever you control directly. (the canonical reference for both.)

The project we’ll equip

Same payments service you’ve been living in. Over the next few lessons you’ll stop re-explaining it and start writing it down:

• Generate the first CLAUDE.md from the repo with /init, so the agent’s baseline knowledge of the project is captured automatically
• Learn what actually belongs in a rule — the durable, project-specific facts worth their place in context, versus the vague filler that just burns tokens
• Layer rules across scopes — personal preferences, team-shared project rules, and per-subsystem files, and how they stack
• Let the agent keep its own notes with auto memory and /memory, and learn when that fits better than a rule you write by hand

By the end, the payments service will explain itself to the agent. You’ll start each session not by re-teaching it the basics, but already past them.

Start with generating the first CLAUDE.md.