Skip to content

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)
  1. What AI coding agent context is, and why relevance beats volume
  2. Rule 1: point the agent at the files that matter
  3. Rule 2: a short CLAUDE.md (what goes in, what stays out)
  4. Rule 3: compact or start clean
  5. Signs of a saturated context
  6. Common mistakes
  7. Frequently asked questions
  8. Checklist

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?".

what the agent needs to fix the cartapp/checkout/boundary: "do not touch app/checkout/"products/layout.tsxcomponents/cart/CartProvider.tsx@ in the prompt: read in fullproduct/AddButton.tsx@ in the promptlegacy/lib/package.jsonCLAUDE.mdloaded at the start of every sessionthe rest: it searches when it needs to2 files with @, 1 boundary, nothing elseClaude reads the repo on its own: give it what it cannot see

Scroll the figure sideways to see all of it

What enters the contextWhenHow you control it
Project, user and parent-directory CLAUDE.md filesAt session startWhat you write in them; /memory to open them
Subdirectory CLAUDE.md filesWhen Claude reads or edits a file in that directoryWhere you put them
.claude/rules/ files with pathsWhen it works on a matching fileThe paths patterns
Files it readsOn every readNaming files with @ and setting boundaries
The conversationOn 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.
  1. The first sentence is the symptom, told the way a customer would see it: what you do and what does not happen.
  2. 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.
  3. "do not touch app/checkout/" is a boundary. Without it, a cart fix can end up "improving" checkout.
  4. 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.mdStays out
The exact lint, typecheck and test commandsThe folder layout: Claude reads it itself
Places where the code misleads, like an old pattern new code must not copyThe dependency list
Decisions that are not in the repoGeneric rules like "write clean code"
Anything you have had to correct twiceMulti-step procedures: those go in a skill
Clear boundaries on what not to touchRules 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.
  1. @AGENTS.md imports that file if your project has one; create-next-app's default setup includes it. Per the docs, when a CLAUDE.md exists, Claude Code reads the CLAUDE.md and not the AGENTS.md, unless you import it like this. If you have no AGENTS.md, delete the line.
  2. # Commands are the scripts the Next.js installation docs put in package.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.
  3. # Conventions are 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.
  4. # Careful holds boundaries. The .env.local one is an instruction, not a protection: the docs are clear that Claude treats CLAUDE.md as context, not enforced configuration. To make the file unreadable for Claude no matter what, use a hook that protects your .env.
anatomy of a short CLAUDE.mdCLAUDE.md15 lines@AGENTS.md# Commands- npm run dev- npm run lint- npx tsc --noEmit# Conventions- prices in cents: lib/price.ts- components/legacy/: do not copy# Careful- app/checkout/: plan first- never read .env.localthe import loads in fullhow it checks its work:the exact commandswhat reading the codewill not tell itboundaries; if it cannot bend,it is a hook, not a lineunder 200 lines: what Claude cannot work outout: folder layout, dependency lists, generic rules

Scroll the figure sideways to see all of it

Where it lives and how it loads, per the docs:

  • Project: ./CLAUDE.md or ./.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.
  • /init generates a first CLAUDE.md from your codebase and, if one exists, suggests improvements instead. The guide says that from there the work is mostly removing lines.
  • /memory lists and opens your memory files; /context lets you confirm they loaded, under Memory files.
  • If a rule only matters in one part of the codebase, it goes in .claude/rules/ with a paths field, 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-root CLAUDE.md is re-read from disk.
  • /clear starts a new conversation with empty context (aliases /reset and /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.
which command fits the situationsituationcommandwhat is leftsame task, long session/compact <focus>a summary plus theproject CLAUDE.mdnew, unrelated task/clearempty conversation;CLAUDE.md loads againsame fix failedtwice/cleara new prompt withwhat you learnedpart of it is noise/rewindsummary from or up tothe message you pickunsure what fills it/contextnothing: it only measureswhat is on disk survives; the chat does notan instruction given only in chat can be lost when it compacts

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 /clear and 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.
  • /context shows 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.md for 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.md is under 200 lines and only holds what Claude cannot work out.
  • The commands in CLAUDE.md exist in your package.json or your CLI.
  • Anything that cannot fail lives in a hook, not in a line of CLAUDE.md.
  • You run /clear between unrelated tasks and after two failed corrections.
  • You run /compact with a focus when you stay on the same task.
  • /context lists your CLAUDE.md under 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

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published October 30, 2026 · updated November 1, 2026

← Blog