AI coding agent context: your agent does not need your whole repo
Guide/ 11 min read
Three rules for giving an AI coding agent the right context: name the files, keep CLAUDE.md under 200 lines and know when to compact or clear.
- AI
- Claude Code
In this article (8)
AI coding agent context is everything the agent has in view during a session: your instructions, the files it has read and the conversation so far. More of it does not make the agent better; the relevant part does: the files for the task, a short CLAUDE.md and a clean session when you switch tasks.
Below that becomes three rules for Claude Code, checked against its documentation: point at the files that matter, keep CLAUDE.md short, and know when to run /compact or /clear. At the end, how to spot a saturated context. If you came from how to report a bug to AI, this is the other half: what you hand the agent besides the report.
What AI coding agent context is, and why relevance beats volume
Per Claude Code's context window page, the context holds everything Claude knows about your session: your instructions, the files it reads, its own responses and content that never shows in your terminal. Before you type anything, CLAUDE.md, auto memory, MCP tool names and skill descriptions are already loaded. After that, every file read adds to it.
Two points from the best practices guide explain why volume does not help. First, every request sends the whole conversation, so a session that has collected three unrelated tasks re-reads all three on every turn of the fourth. Second, Claude starts every task by reading your code, and current models are very good at it: they find your layout, conventions and test framework on their own. What they cannot find is what was never in the repo: a decision made in a meeting, a deploy process that lives in one person's head, the environment variable your integration tests need.
That changes the question. It is not "how do I give it the whole repo?" but "what does it need that it cannot see?".
Scroll the figure sideways to see all of it
| What enters the context | When | How you control it |
|---|---|---|
Project, user and parent-directory CLAUDE.md files | At session start | What you write in them; /memory to open them |
Subdirectory CLAUDE.md files | When Claude reads or edits a file in that directory | Where you put them |
.claude/rules/ files with paths | When it works on a matching file | The paths patterns |
| Files it reads | On every read | Naming files with @ and setting boundaries |
| The conversation | On every message | /compact, /clear, /rewind |
Rule 1: point the agent at the files that matter
The best practices guide puts it this way: if you name the file, describe the symptom and say what "fixed" looks like up front, you usually save yourself a round of corrections. And if you already have the file, hand it over instead of describing it: type @ and the path to include its contents in your message. Here is a prompt for a Next.js store (the file names are examples):
After tapping "Add to cart", the header counter does not change until
the page is reloaded. The button is in @components/product/AddButton.tsx
and the cart state in @components/cart/CartProvider.tsx.
Fix it in those two files and do not touch app/checkout/.
It is done when the number changes without a reload and npm run lint
passes.
- The first sentence is the symptom, told the way a customer would see it: what you do and what does not happen.
- The two
@paths put those files' contents into the message. Claude does not have to search for them or read their neighbors to guess where the state lives. - "do not touch app/checkout/" is a boundary. Without it, a cart fix can end up "improving" checkout.
- The last line says what counts as done and which command proves it.
What if you do not know which files they are? Do not guess, and do not ask it to read everything: ask it to find them and tell you before changing anything, or use plan mode, which explores and proposes without editing. For big searches the docs suggest a subagent: it works in its own context window and only the summary comes back to yours.
Rule 2: a short CLAUDE.md (what goes in, what stays out)
CLAUDE.md loads into every session, and the guide warns that this is why every line takes a little of Claude's attention on every task, relevant or not. The memory documentation gives the number: target under 200 lines per file, because longer files consume more context and reduce adherence. Splitting it with @path imports helps organize it but does not cut its cost, since imported files load together with the file that imports them.
| Goes in CLAUDE.md | Stays out |
|---|---|
| The exact lint, typecheck and test commands | The folder layout: Claude reads it itself |
| Places where the code misleads, like an old pattern new code must not copy | The dependency list |
| Decisions that are not in the repo | Generic rules like "write clean code" |
| Anything you have had to correct twice | Multi-step procedures: those go in a skill |
| Clear boundaries on what not to touch | Rules that cannot bend: those go in a hook |
Here is a template for a Next.js project. It is 15 lines long:
@AGENTS.md
# Commands
- Dev server: npm run dev
- Lint: npm run lint
- Types: npx tsc --noEmit
- Production build: npm run build, only when I ask for it.
# Conventions
- Prices arrive in cents; format them with lib/price.ts.
- components/legacy/ is still live, but do not copy its patterns.
# Careful
- app/checkout/ and app/api/payments/: plan first, never a direct change.
- Do not read or print .env.local.
@AGENTS.mdimports that file if your project has one;create-next-app's default setup includes it. Per the docs, when aCLAUDE.mdexists, Claude Code reads theCLAUDE.mdand not theAGENTS.md, unless you import it like this. If you have noAGENTS.md, delete the line.# Commandsare the scripts the Next.js installation docs put inpackage.json(dev,build,lint) plus the TypeScript type check. That is what Claude needs to check its own work; the build line says when to run it.# Conventionsare two examples of what the code does not tell you: which unit prices arrive in, and which folder is still live but must not be imitated. Replace them with yours.# Carefulholds boundaries. The.env.localone is an instruction, not a protection: the docs are clear that Claude treatsCLAUDE.mdas context, not enforced configuration. To make the file unreadable for Claude no matter what, use a hook that protects your .env.
Scroll the figure sideways to see all of it
Where it lives and how it loads, per the docs:
- Project:
./CLAUDE.mdor./.claude/CLAUDE.md, shared with the team through git. User:~/.claude/CLAUDE.md, for all your projects. Local:CLAUDE.local.md, your own preferences for this project, added to.gitignore. - Files in the directory you launch from and the ones above it load at startup; files in subdirectories load when Claude works there. They do not override each other: they are concatenated.
/initgenerates a firstCLAUDE.mdfrom your codebase and, if one exists, suggests improvements instead. The guide says that from there the work is mostly removing lines./memorylists and opens your memory files;/contextlets you confirm they loaded, under Memory files.- If a rule only matters in one part of the codebase, it goes in
.claude/rules/with apathsfield, so it loads only when Claude touches matching files.
One thing the guide stresses: if Claude keeps ignoring a line that is in your CLAUDE.md, adding IMPORTANT probably will not fix it. Either the file has grown long enough that the line gets lost, or it is a rule with no exceptions, and that belongs in a hook.
Rule 3: compact or start clean
Claude Code compacts automatically as you approach the limit, so a full context window does not end your session. What you can do is decide in advance what stays. Per the commands reference, there are two commands for that, and they do different things:
/compact [instructions]summarizes the conversation to free up context and takes optional focus instructions for the summary. After compaction, the project-rootCLAUDE.mdis re-read from disk./clearstarts a new conversation with empty context (aliases/resetand/new). You can go back to the previous one with/resume.
A focused /compact, for a long session on the same cart fix:
/compact keep the changes in components/cart/ and the test commands; drop the exploration of app/checkout/
- "keep…" names what must survive the summary: the cart changes and the test commands. The docs explain that this way the summary keeps what you choose instead of what the automatic pass guesses is important.
- "drop…" names the noise: the checkout exploration you no longer need.
Scroll the figure sideways to see all of it
The guide's rule for /clear is specific: if you have corrected the same thing twice and it is still wrong, a third correction mostly adds to a conversation that already holds two failed attempts for Claude to keep re-reading. /clear plus one new prompt that folds in what you learned works better. And between unrelated tasks, /clear as well: old conversation crowds out the files you need next and costs tokens on every message.
There is a middle ground: /rewind lets you pick a message and summarize from it or up to it, when only part of the conversation has gone stale. And one warning from the docs: an instruction you gave only in conversation can disappear after compaction. If it matters, it goes in CLAUDE.md.
Signs of a saturated context
None of these is an exact metric; they are situations the docs describe and worth watching for:
- You are correcting the same thing a second time. That is where the guide says to
/clearand write a better prompt. - It forgot an instruction you gave in chat, especially after compaction. Move it to
CLAUDE.md. - It mixes details from the previous task into the current one: unrelated tasks piled up in one session.
- It ignores a line in your
CLAUDE.md. Check the file's length and look for contradictions: the docs warn that when two instructions conflict, Claude may pick one arbitrarily. /contextshows warnings. The command draws context usage as a colored grid and gives suggestions for context-heavy tools, memory bloat and capacity warnings.
Common mistakes
- Asking it to "read the whole project" first. That fills the context with files the task does not use. Name the ones that matter or ask it to find them.
- Describing the architecture and folders in
CLAUDE.md. The guide lists that as advice you can stop following: Claude reads the repo itself. - Using capitals and IMPORTANT to get its attention. If a line gets lost, the file needs to be shorter.
- Relying on
CLAUDE.mdfor something that cannot fail. It is context; to block something, use a hook. - Chaining tasks without
/clear. Every new task drags and pays for the history of the previous ones. - Giving important instructions only in chat. They can be lost when the session compacts.
Frequently asked questions
Do /compact or /clear delete my CLAUDE.md?
No. CLAUDE.md lives on disk. After /compact, the project-root one is re-injected; after /clear, the new conversation loads it at the start, like any other.
How many lines should my CLAUDE.md have?
The docs recommend under 200 per file. The templates in this article and the guide have 15 and 14. The number matters less than every line being something Claude could not work out by reading the code.
Does this apply to other agents, like Cursor or Codex?
The commands here are Claude Code's. Naming files, setting boundaries and keeping a short instructions file do not depend on the tool, and several agents read AGENTS.md; with the @AGENTS.md import you share that same file with Claude Code.
How do I see what is loaded right now?
Run /context: it shows usage by category and the memory files that loaded. /memory opens and edits those files.
Checklist
- The prompt names the task's files with
@and says what not to touch. - The prompt says what "done" looks like and which command proves it.
- Your
CLAUDE.mdis under 200 lines and only holds what Claude cannot work out. - The commands in
CLAUDE.mdexist in yourpackage.jsonor your CLI. - Anything that cannot fail lives in a hook, not in a line of
CLAUDE.md. - You run
/clearbetween unrelated tasks and after two failed corrections. - You run
/compactwith a focus when you stay on the same task. /contextlists yourCLAUDE.mdunder memory files.
An agent with the right context makes fewer mistakes and costs you less. For the whole method, follow my 4-step Claude Code workflow; to review before any edit, Claude Code plan mode; to report a failure with everything it needs, how to report a bug to AI; and to be able to undo whatever the agent does, a git workflow for AI agents.
Saw this on Instagram? Comment CONTEXTO on the Reel and I'll send you the guide.
Written by

Published October 30, 2026 · updated November 1, 2026