One of the easiest mistakes to make with Claude Code is assuming that “memory” is just one thing. It is not.

There is CLAUDE.md. There are rules. There is auto memory. There is subagent memory. There are settings that influence how all of this behaves. And if you mix up what each layer is for, Claude can end up feeling forgetful, inconsistent, or weirdly aware of the wrong things.

The good news is that the system is more coherent than it first looks.

The short version is this: CLAUDE.md is where you teach Claude how your project works. Rules are where you split that guidance into smaller and more targeted pieces. Auto memory is where Claude accumulates lessons over time. Subagent memory is where specialised agents build up their own knowledge base. Anthropic’s docs describe CLAUDE.md and auto memory as complementary systems that both load at the start of every conversation, while rules help scope instructions more precisely, especially in larger projects.

That distinction matters a lot.

Because if you put everything into one giant CLAUDE.md, you bloat the context. If you rely on auto memory for permanent architecture guidance, you make the system fuzzy. And if you never structure rules by path or topic, Claude ends up carrying too much irrelevant instruction at once. Anthropic explicitly warns that these instructions consume tokens in the context window and recommends keeping each CLAUDE.md under about 200 lines.

So let’s do a proper deep dive 🤿.

First principle. Teach the project, not just the code

A good CLAUDE.md is not a random pile of reminders. It should answer three questions clearly:

1. What is this project?

What technologies does it use? How is the repo structured? Where are the apps, packages, services, modules, or major domains?

1. Why does it exist?

What is the business purpose of the system? What are the important parts of the repo actually for?

1. How should Claude work in it?

How do you run the project? How do you test changes? How does Claude verify its own work? What tools and commands should it prefer?

Project CLAUDE.md files should cover things like build and test commands, coding standards, architectural decisions, naming conventions, and common workflows, and /init can generate a starting file automatically by analysing the codebase.

This is why I think the best CLAUDE.md files feel more like an index than a manifesto.

You are not trying to describe everything. You are trying to give Claude the shortest possible path to the right mental model.

A weak version says something like:

This project uses React, TypeScript, and a component-based architecture. We value clean code and testing.

A useful version says something like:

• App shell lives in apps/web

• Shared UI lives in packages/ui

• API clients live in packages/api

• Use bun, not node

• Run bun test for unit tests

• Run bun typecheck before finishing

• For auth flows, inspect packages/auth first

• For billing changes, read docs/billing-rules.md

That second version gives Claude somewhere to go.

CLAUDE.md works best when it stays small

This is one of the most important best practices, and also one of the easiest to ignore.

Anthropic says CLAUDE.md content is loaded into the context window at the start of every session, so longer files consume more context and reduce adherence. Their recommendation is to target under 200 lines per file, keep instructions specific and concise, and split large files using imports or .claude/rules/.

CLAUDE.md, rules, and auto memory all compete for attention, so high-quality project awareness comes from using the right layer for the right type of knowledge, not from stuffing everything into one always-loaded file.

Your root CLAUDE.md should be the stable core. It should contain the information Claude needs almost every time. It should not become the place where every team note, file path, edge case, workflow, and exception goes to die.

Once that file starts growing aggressively, the usual solution is not “add more structure inside the same file.” The better solution is “move the detail into rules or imported files.”

Write instructions like commands, not like documentation

Anthropic’s docs say Claude follows specific, concrete, and verifiable instructions more reliably than vague guidance. Their examples are all imperative. “Use 2-space indentation.” “Run npm test before committing.” “API handlers live in src/api/handlers/.”

You should say:

• Use bun, not node

• Check existing patterns before creating a new abstraction

• Run bun test and bun typecheck before finishing

• Prefer functional React components

• Put API handlers in src/api/handlers

You shouldn’t say:

• The project uses bun

• The team tends to prefer functional components

• Testing is generally recommended before finalising

One is operational, the other is descriptive. Claude does better with operational language because it translates more directly into action.

Tables often beat prose

This is one of my favourite tips from my experience working with Claude Code because it captures how these systems actually behave in practice.

If Claude needs to decide where to look first, a lookup table is often better than a long paragraph. A table turns your project knowledge into a little routing system.

For example:

| Need              | Where to look first                                   |
| ----------------- | ----------------------------------------------------- |
| Billing logic     | `packages/billing/`, `apps/web/src/features/billing/` |
| Auth flow         | `packages/auth/`, `apps/web/src/routes/login/`        |
| Shared UI pattern | `packages/ui/`                                        |
| API client code   | `packages/api/`                                       |
| Test examples     | `tests/`, `packages/*/src/**/*.test.ts`               |

That is easier for Claude to act on than three paragraphs explaining the repo philosophy. It is also easier for you to maintain!

If your goal is project awareness, the more you can convert fuzzy prose into decision-friendly structure, the better.

Use imports to keep the main file lean

Anthropic supports @path imports inside CLAUDE.md, including relative and absolute paths, recursive imports up to five levels deep, and even home directory imports for personal files. They also explicitly suggest using imports when instructions get too large.

This is useful because it lets your main file stay short without losing richness.

A clean pattern looks like this:

# Project overview
See @README.md for the high level product overview.

# Commands
See @package.json for scripts and @docs/dev-workflow.md for build steps.

# Domain notes
- Billing details: @docs/billing-rules.md
- Auth details: @docs/auth-flows.md

That gives Claude access to the deeper material without forcing your root file to carry every detail inline.

It also means your CLAUDE.md can act like a project map, which is usually a better job for it anyway.

Use multiple CLAUDE.md files, but do it intentionally

Anthropic documents a hierarchy for CLAUDE.md files. You can have managed, user, project, and more specific directory-level files. Claude walks up the directory tree from the current working directory, loading broader files first and more specific ones later. It can also discover subdirectory CLAUDE.md files and load them when Claude reads files in those directories.

From analysing Claude Code source code, it’s evident that this hierarchy is one of the main reasons monorepo setups can work well. A repo-level file can provide broad standards, while a nested package-level file can override or refine guidance for that area. It also notes that files closer to the current working directory have more practical priority because they load later.

That is powerful, but it can also get messy fast. The mistake is thinking, “great, I can put instructions everywhere.”

The better approach is:

• Put broad, stable project guidance at the root

• Put domain specific guidance near the domain

• Avoid repeating the same rule in multiple places

• Periodically remove contradictions and update the content of files as your project evolves

If two files disagree, Claude may follow either one inconsistently. Anthropic calls that out directly.

Rules are where the system really starts to scale

For larger projects, Anthropic recommends .claude/rules/ so instructions stay modular and easier to maintain. Rules can load every session or only when matching files are opened, and path-specific rules use YAML frontmatter with a paths field.

This is one of the biggest upgrades you can make to project awareness.

Instead of having one huge file that tries to teach Claude everything about frontend, backend, infra, testing, data migrations, and docs, you create smaller files with one concern each.

Something like:

.claude/rules/
  testing.md
  code-style.md
  security.md
  frontend/react-patterns.md
  backend/api-rules.md

And if a rule only matters for API files, scope it:

---
paths:
  - "src/api/**/*.ts"
---
# API Development Rules

- Validate all request inputs
- Use the standard error response format
- Add OpenAPI comments for public endpoints

According to the docs, rules without paths are loaded unconditionally, while path-scoped rules activate when Claude reads matching files. That makes them much more context-efficient than always-loaded instructions.

This is why I would frame the architecture like this:

• CLAUDE.md is your project’s operating manual.

• Rules are your project’s specialised playbooks.

Auto memory

CLAUDE.md is what you write. Auto memory is what Claude writes based on corrections and preferences. They are complementary systems. CLAUDE.md is for persistent instructions and architecture-level guidance. Auto memory is for learnings and patterns Claude accumulates over time. Both load at the start of every conversation, but they serve different purposes.

People sometimes want Claude to “remember the project better,” and they start asking it to save architecture notes as memory. But if that guidance is stable and important, it usually belongs in CLAUDE.md or in rules, not in memory.

Auto memory is better for things like:

• user preferences Claude keeps forgetting (I find this is the most common use case)

• lessons learned from repeated corrections

• non obvious working agreements

• project context that is real but not easily derivable from the code

• references to outside systems

From the Claude Code source code analysis, we can see it defines memory categories such as user, feedback, project, and reference, and makes it clear that memory is intended for information that cannot be easily inferred from the codebase, Git history, or repository structure.

That is the right filter. If Claude can discover it by reading the repo, it probably should not live in memory.

What MEMORY.md is really doing

MEMORY.md is the entry point to Claude Code’s auto memory system for a project. Each project gets its own memory directory at ~/.claude/projects/<project>/memory/, and that directory is shared across the same Git repository, including worktrees and subdirectories. Inside it, Claude keeps a small MEMORY.md file as an index, plus any number of topic-specific memory files:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Concise index, loaded into every session
├── debugging.md       # Detailed notes on debugging patterns
├── api-conventions.md # API design decisions
└── ...                # Any other topic files Claude creates

Rather than storing everything in one large file, Claude uses MEMORY.md as a map of what is already known and where that knowledge lives. That makes the system easier to scale and keeps memory more organised. If needed, you can also move the auto memory directory somewhere else through your user or local settings:

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

In practice, MEMORY.md gives Claude a lightweight overview of project knowledge, while the supporting files hold the deeper details.

According to the source code analysis, MEMORY.md is not just a normal notes file. Indeed it acts as an index for individual memory files. The index is always loaded, while individual memories are surfaced by relevance, rather than all being injected every time. The analysis also indicates that the index is capped at 200 lines or 25KB, and that descriptions matter because they influence which memories are selected later.

That leads to a very practical insight. A good memory system is not just about saving facts. It is about making those facts retrievable.

So if you are manually curating memory, write entries in a way that future Claude can find them.

Bad memory description:

Some notes about a previous issue

Better memory description:

Billing integration tests must use real Stripe sandbox because mocks hid webhook ordering bugs

The second one is much more likely to be recalled when relevant. It is also more likely to be useful.

The # shortcut is useful, but you still need judgment

You can type # in the Claude Code interface to create memories, which makes memory feel a bit like quick rule capture.

That is useful, but the same principle still applies. Just because something is worth remembering for a week does not mean it belongs in the permanent project guidance layer.

A decent rule of thumb is:

• Put stable project truth in CLAUDE.md

• Put scoped, domain specific truth in rules

• Put learned preferences, corrections, or temporal context in memory

This simple separation solves a lot of mess before it happens.

Settings matter more than people think

Settings are not the same thing as memory files, but they influence the environment around them.

Anthropic’s settings docs describe multiple scopes for configuration: managed, user, project, and local. They also explain the precedence order, where managed settings override everything, followed by command line arguments, then local, project, and user settings. The docs also list settings related to memory and project behaviour, including autoMemoryDirectory, and recommend project settings for team shared configuration and local settings for personal overrides in one repository.

This matters because a strong memory strategy is not just about writing good instructions. It is also about placing the right behaviour at the right scope.

For example:

• personal preferences across all repos belong in user scope

• team shared hooks and tooling belong in project scope

• machine specific or experimental overrides belong in local scope

And if you are using auto memory heavily, the autoMemoryDirectory setting can change where that data lives, though the docs note that it is not accepted in shared project settings for safety reasons.

That last detail is a good reminder that not all “memory-related” behaviour belongs in the repo itself.

Subagents can have their own persistent memory too

Anthropic documents a memory field for subagents that gives them a persistent directory across conversations. Supported scopes are user, project, and local. When enabled, the subagent gets instructions for reading and writing to its memory directory, and it also receives the first 200 lines or 25KB of that directory’s MEMORY.md. Anthropic recommends project as the default scope when the subagent’s knowledge should be project-specific and shareable via version control.

That means you can create agents that do not just help with a task. They can slowly become better at that task in the context of your project.

• A code reviewer subagent can remember recurring review issues.

• A debugging subagent can remember recurring failure patterns.

• A docs subagent can remember how your team prefers technical writing to be structured.

This is powerful because it separates “main project awareness” from “specialized role awareness.”

And in practice, that usually makes the overall system cleaner.

A practical strategy that actually works

If I were setting up Claude Code from scratch for a serious repo, I would do something like this:

1. Start with /init

Anthropic says /init can generate a starting CLAUDE.md based on the codebase and suggest improvements if one already exists. That gives you a draft. Not a finished system, but a draft.

2. Rewrite the root CLAUDE.md as an index

Keep only the high value, always relevant material:

• project purpose

• repo map

• important commands

• verification steps

• links or imports to deeper docs

3. Convert broad prose into imperative instructions

Turn soft descriptions into concrete actions.

4. Move specialised content into .claude/rules/

Especially if it is:

• file type specific

• domain specific

• noisy

• not always relevant

5. Use path-scoped rules aggressively

Only load React rules for React files. Only load API rules for API files.

6. Use imports for deeper docs

Do not paste long reference docs into the root file if an import will do the job.

7. Let memory capture learnings, not architecture

Use memory for corrections, preferences, deadlines, external references, and other non-obvious context.

8. Give subagents their own memory when specialisation matters

This is especially useful for repeat reviewer, debugger, or research workflows.

Common mistakes that make Claude feel forgetful

The first is one giant CLAUDE.md. This usually starts as “let’s help Claude more” and ends as “Claude ignores half of this.”

The second is using memory for things Claude should derive from the repo. If the answer is in the codebase, teach Claude where to look. Do not turn the memory layer into a shadow documentation system.

The third is contradictory guidance across files. Anthropic explicitly warns that contradictory rules can reduce consistency.

The fourth is putting personal preferences into shared project files. Those belong in user or local scope instead. Anthropic’s settings and CLAUDE.md scope model both support that separation.

The fifth is writing fuzzy instructions. “Keep things clean” is not project awareness, but wishful thinking.

Takeaway

Claude Code does not become project-aware because you gave it more words. Instead, it becomes project aware when you make the project legible and accessible.

That means:

• stable context goes in CLAUDE.md

• scoped context goes in rules

• learned context goes in memory

• specialized context goes in subagent memory

• configuration lives in the right settings scope

Once you separate those layers, the system starts to feel much less magical and much more reliable.

And honestly, that is the real goal. Not “make Claude remember everything”, but make it remember the right things, in the right place, for the right reason.

If you want one compact checklist to apply after reading this, use this:

• Keep the root CLAUDE.md under about 200 lines when possible. Anthropic recommends that target for reliability and context efficiency.

• Treat the root file as a project index, not a dumping ground.

• Answer what, why, and how clearly.

• Write instructions as commands.

• Use lookup tables for routing Claude to the right code.

• Move specialised guidance into .claude/rules/.

• Use paths frontmatter for file specific rules.

• Use imports instead of bloating the main file.

• Save stable architecture in instructions, not in memory.

• Use memory for learnings, corrections, and non obvious project context.

• Give important subagents persistent memory when their specialisation benefits from it.

Now, I would be interested in knowing what’s the biggest thing Claude Code still forgets about your project today, and which layer do you think should fix it: CLAUDE.md, rules, memory, or subagents?

See you in the next one!

Subscribe now

The first time you look at Claude Code closely, it can feel like a box full of parts that all seem important, but not obviously related.

You see CLAUDE.md. Then rules. Then skills. Then hooks. Then subagents. Then MCP servers. Then… the list goes on. Then context management, planning before coding, verifying outputs, and avoiding letting the session turn into a mess. At first glance, it is easy to think: why are there so many pieces just to get an AI coding workflow working well?

But after spending some time with these concepts, I think the answer is actually pretty simple.

Claude Code is not one thing. It is a small operating system for AI-assisted development.

And like any good system, different parts exist for different jobs.

Start here. Claude Code needs memory, structure, and reach

A good mental model is this:

1. CLAUDE.md and rules shape behaviour.

2. Skills package reusable know-how.

3. Hooks enforce automatic actions.

4. Subagents isolate work.

5. MCP servers connect Claude to the outside world.

That is the big picture (mainly, because there is more to it, but this is enough to get us started).

Once you see it that way, the moving parts stop feeling random. They start feeling like layers. The interesting part is not learning each feature in isolation, but understanding what problem each one solves, and what happens when you try to use the wrong one for that problem. Anthropic’s docs make that distinction pretty clear. CLAUDE.md gives persistent instructions, rules can scope those instructions more precisely, skills extend Claude with reusable playbooks, hooks provide deterministic automation, subagents work in separate contexts with their own tools and prompts, and MCP is the bridge to external tools, data sources, and APIs.

CLAUDE.md and rules. The behavioral layer

If I had to pick the first thing to set up in Claude Code, it would be this.

CLAUDE.md is where you put persistent instructions that Claude should carry into every session for a project, for your personal workflow, or even across an organization. The docs describe it as plain markdown that Claude reads at the start of every session. They also make an important point that is easy to miss: these instructions are context, not hard enforcement. So if the file is vague, bloated, or contradictory, performance drops. Anthropic recommends keeping it specific, concise, and well-structured, with a rough target of under 200 lines per file.

That last bit matters more than it seems.

A lot of people treat instruction files like a dumping ground. They keep adding preferences, workflows, architecture notes, testing conventions, edge cases, and random reminders until the thing becomes unreadable. Then they wonder why the agent follows it inconsistently. The problem is not that the model is “bad at instructions.” The problem is that the instruction layer is carrying too much weight.

That is where rules come in.

For larger projects, Anthropic recommends organising instructions inside .claude/rules/, and those rules can even be path-specific so they only load when Claude is working in matching areas of the codebase. That means you do not need every frontend rule, testing rule, security note, and data migration convention loaded all the time. You can scope them. In other words, CLAUDE.md should define the broad operating principles of the project, while rules help keep that guidance modular and targeted.

So, if you want one simple distinction:

Use CLAUDE.md for shared default behaviour. Use rules when the project is getting too big for one instruction file to stay sharp.

Skills. The reusable playbook layer

This is where Claude Code starts getting interesting.

A skill is not just “more instructions.” A skill is a packaged capability. Anthropic defines skills around a SKILL.md file. Claude can load a skill automatically when it is relevant, or you can invoke it directly with a slash command (/) based on the skill name (/my_skill). Skills can also include frontmatter, supporting files, argument handling, restricted tool access, and even subagent execution.

That changes the way you should think about them.

A rule says, “here is how we do things around here.”

A skill says, “when this kind of task appears, here is the exact playbook to follow.”

That is a huge difference.

For example, suppose your team has a repeatable workflow for debugging flaky tests, preparing release notes, reviewing API design, or migrating components from one pattern to another. You could try to cram that into CLAUDE.md, but then every session pays the context cost whether that workflow is relevant or not. Skills solve that by staying optional and task-focused. Anthropic explicitly positions them that way in the docs and even notes that for task-specific instructions that do not need to live in context all the time, skills are the better fit.

This is one of those places where the abstraction really clicks.

A good Claude Code setup is not just about telling the model how your codebase works, but about identifying which workflows deserve to become first-class tools.

That is what skills are.

Hooks. The enforcement layer

If CLAUDE.md and skills are about guidance, hooks are about guarantees.

Anthropic describes hooks as user-defined shell commands that run at specific points in Claude Code’s lifecycle. Their wording is important here: hooks provide deterministic control. In other words, they are for the things that must happen, every time, without relying on the model to remember or choose correctly. The best practices guide reinforces the same distinction: unlike CLAUDE.md, which is advisory, hooks are deterministic and guarantee the action happens.

That makes hooks the right tool for a very specific category of problems:

• Run formatting after edits.

• Block writes to protected files.

• Send a notification when Claude needs input.

• Reinject context after compaction.

• Audit configuration changes.

Hooks are workflow mechanics. If you try to solve these mechanics with prompts alone, you are basically hoping the model behaves. Hooks exist so you do not need hope.

This is also where a lot of AI workflows quietly become trustworthy. Not because the model got smarter, but because some parts of the workflow stopped depending on the model entirely.

That is a pattern worth paying attention to.

The more a task sounds like “always do X when Y happens,” the more likely it belongs in a hook, not in a prompt.

Subagents. The isolation layer

Subagents are one of the clearest signs that Claude Code is built for agentic work, not just chat.

Anthropic describes subagents as specialised AI assistants that run in their own context window, with their own system prompt, tool access, and permissions. Claude can delegate work to them when a task matches the subagent’s description, and the subagent works independently before returning the result. The docs also point out why this matters: subagents preserve context, enforce constraints, specialise behaviour, and can route work to different models.

In long coding sessions, context gets polluted fast. Research, false starts, logs, file reads, debugging dead ends, and exploratory thoughts all pile into the same conversation. Anthropic’s best practices page repeatedly emphasises that context is the most important resource to manage, because performance degrades as the context window fills.

Subagents are how you stop every task from becoming everyone’s problem:

• Need a security pass across many files? Use a security reviewer subagent.

• Need research on a subsystem before implementation? Delegate it.

• Need a focused investigation that should not clutter the main thread? Subagent.

I think this is one of the most underrated shifts in AI coding workflows. The question is no longer just “what should the model do?” It is also “which context should do it?”

That is a different level of workflow design.

MCP servers. The reach layer

Without MCP, Claude Code is mostly limited to the local environment and whatever tools it already has access to. With MCP, it can reach out.

Anthropic describes MCP, the Model Context Protocol, as an open standard that lets Claude Code connect to external tools and data sources through MCP servers. Their examples include issue trackers, monitoring platforms, databases, design tools, and workflow automation systems. They also note an important security warning: third-party MCP servers are not universally verified, and untrusted servers can introduce prompt injection or other risks.

This is where Claude Code stops being “an assistant in my repo” and starts becoming “an agent in my workflow.” That sounds exciting, and it is. But it also changes the stakes.

Once Claude can read tickets, inspect production signals, query a database, read Figma, or draft emails, the design problem becomes larger than coding. You are now designing an operational system. Permissions matter. Trust boundaries matter. Server choice matters. Tool access matters.

So while MCP is easily the most expansive capability in the stack, it is also the one that benefits most from restraint.

Just because Claude can connect to everything does not mean it should.

How these parts fit together in practice

Here is the cleanest way I can describe the whole stack:

• CLAUDE.md tells Claude how to behave by default.

• Rules narrow that guidance by topic or path.

• Skills package repeatable expertise or workflows.

• Hooks automate mandatory actions.

• Subagents keep big or noisy tasks isolated.

• MCP servers connect Claude to outside systems.

A practical workflow might look like this:

Your CLAUDE.md defines coding standards, project conventions, and preferred commands. A rule file adds stricter guidance for the /api directory. A skill gives Claude your internal release checklist. A hook runs linting after edits and blocks writes to a protected migration folder. A subagent handles security review in its own context. MCP connects Claude to GitHub, Jira, Sentry, and your database.

At that point, Claude Code is no longer just reacting to prompts, but operating inside a designed environment. And I think that is the real lesson here.

The quality of the workflow does not come from one magical feature. It comes from putting the right responsibility in the right layer.

Best practices that actually matter

Anthropic’s best practices page covers a lot, but a few ideas stand out because they connect directly to all the moving parts above.

First, give Claude a way to verify its work. Tests, screenshots, and expected outputs dramatically improve results because Claude can check itself instead of making you the only feedback loop.

Second, explore first, then plan, then code. Anthropic recommends separating research and planning from implementation, especially for tasks that touch multiple files or unfamiliar areas. That maps nicely to plan mode, but also to skills and subagents when you want a more structured workflow.

Third, provide specific context. Reference files, constraints, patterns, and symptoms. Claude can infer a lot, but it cannot read your mind (yet 😅).

And finally, manage context aggressively. Use /clear between unrelated tasks and avoid stuffing persistent instructions with everything under the sun.

Most of Claude Code’s “moving parts” are really context management tools in disguise.

Closing thoughts

When people first look at Claude Code, they often ask which feature matters most. I think that is the wrong question.

The better question is: what kind of problem am I trying to solve?

• If the problem is persistent guidance, reach for CLAUDE.md and rules.

• If the problem is reusable know how, reach for skills.

• If the problem is guaranteed automation, reach for hooks.

• If the problem is isolation and focus, reach for subagents.

• If the problem is external connectivity, reach for MCP.

That is when the system starts making sense.

Claude Code does not become powerful because it has many parts. It becomes powerful when each part has a clear job. And honestly, that is probably the deeper pattern behind good AI workflows in general. Not more prompts. Not more cleverness. Better boundaries.

Practical takeaway:

• Start with a small, sharp CLAUDE.md

• Add rules only when the project needs more structure

• Turn repeated workflows into skills

• Use hooks for anything that must happen every time

• Use subagents to protect context

• Add MCP carefully, with trust and permissions in mind

Which part of Claude Code feels most useful to you right now: rules, skills, hooks, subagents, or MCP servers, and why?