Load it, point at it, or cut it
The last lesson wrote a short AGENTS.md for invoice-mailer, the
fictional Python service that renders invoices to PDF and sends them over
SMTP. A year later the same file has 57 lines. Each line was added for a
reason, and the agent now follows the file less well than it followed the
short version. In this lesson we make it short again. We point at what
only some tasks need, and we cut what no task needs.
The files for this lesson are in
site/examples/customizing-agents/load-point-prune/ in the course
repository. AGENTS.long.md is the long file, AGENTS.pruned.md is one
pruned version of it, and docs/ holds the files the pruned version points
at. In the commands below, replace <course-repo> with the path to your
copy of the course repository. The loading rules here are Claude Code’s, checked against its
documentation on the date at the end of the lesson. Other agents load
their files in other ways, and the method transfers.
Every loaded line is in every session
Section titled “Every loaded line is in every session”Claude Code reads its instruction files at the start of every session [1]. Every line in them is in the context of every task, the one-line typo fix as well as the release. The lesson on what tokens cost showed what that does to a rule: it competes with all the other text in the window, and a rule among many weighs less than a rule among few. The vendor gives the same advice for instruction files. Its documentation says that each extra line uses up context and makes the agent stick to the rules less well [1].
The choice for each piece of guidance is loading versus pointing. Loading puts the text in the instruction file, so it is in context whether the task needs it or not. Pointing puts one line in the file that says where the text is and when to read it, and the agent opens the file only when a task calls for it. Anthropic’s engineering team describes the same split for agents in general. An agent can keep a short reference such as a file path and load what it points at with a tool at the moment it needs it. Claude Code works this way: its instruction files go into context at the start, and it finds the other files of the project with search tools as it works [2].
Load what nearly every task needs: the test command, the branch rule, the
mistake the agent keeps making. Point at the rest. The vendor’s examples
of guidance to move out of the file are a procedure with many steps and a
rule that matters for only one part of the code. Claude Code also has two
places for those that load less often than the instruction file. A skill
loads when you call it or when the agent decides it fits the task, and a
rule file with a paths field loads only when the agent works with files
that match it [1].
An import still loads
Section titled “An import still loads”Claude Code lets an instruction file import another file with a line such
as @docs/release.md. The import isn’t a pointer. When the session
starts, Claude Code reads the imported file and puts its whole text in
the context with the file that contains the import. The vendor says plainly
that an import keeps a long file tidy without making it cheaper
[1]. A path without the @, such as docs/release.md
in a sentence, is plain text and doesn’t import anything, and Claude Code
also skips an @path written inside a code span or a code block
[1]. The agent reads a file named in plain text only if
it decides to open it.
startup.py in the lesson folder counts the lines each version of the
file puts in context at the start of a session. It follows the import rule
above, simplified. AGENTS.pruned.md points at two files with lines such
as “To cut a release, read docs/release.md and follow it step by step”.
AGENTS.imports.md is the same file with each of those two lines replaced
by an import.
cd <course-repo>/site/examples/customizing-agents/load-point-prunepython3 startup.pyHow many lines load?
Section titled “How many lines load?”A script counts the lines an instruction file puts in context when a session starts, adding the lines of every file it imports with @path. AGENTS.long.md has 57 lines and imports nothing. AGENTS.pruned.md has 20 lines and names docs/templates.md (7 lines) and docs/release.md (11 lines) in plain text. AGENTS.imports.md has 20 lines and imports those two files with @docs/templates.md and @docs/release.md.
AGENTS.long.md has 57 lines and imports nothing. AGENTS.pruned.md and
AGENTS.imports.md have 20 lines each. docs/templates.md has 7 lines and
docs/release.md has 11. The script prints one line per file, in the
order long, imports, pruned, in the form AGENTS.long.md: 57 lines at start.
What does it print?
AGENTS.long.md: 57 lines at start AGENTS.imports.md: 38 lines at start AGENTS.pruned.md: 20 lines at start
Output verified in CI from site/examples/customizing-agents/load-point-prune/startup.py.
Which of the two short files makes the agent read the two docs files before the first task?
The imports version is 20 lines when you read it and 38 lines in the
context, and the 18 lines it imports are there for the typo fix as well.
The pointer version is 20 lines in both places. The files in docs/ cost
nothing until a task touches a template or cuts a release.
A pointer says when
Section titled “A pointer says when”A pointer works only when the agent opens the file it names, and the agent
decides that from the pointer line and the task in front of it. The vendor
gives an example of this case. When there is a CLAUDE.md,
.claude/CLAUDE.md or CLAUDE.local.md in the directory you start Claude
Code in or in any directory above it, Claude Code doesn’t load AGENTS.md
by itself. A CLAUDE.md that asks in a sentence for AGENTS.md to be
read then gets it read only when Claude decides to open it
[1]. So write the pointer as a condition and a place: “Before you change a file in templates/, read
docs/templates.md.” The condition is what the agent matches against the
task. A bare “see docs/” gives it no task to match, and “always read
docs/release.md first” makes it read the file in every session, which
costs as much as loading it.
Which line should stay?
Section titled “Which line should stay?”A team moves a nine-step release procedure out of its instruction file into docs/release.md and keeps one line in the instruction file in its place. The agent is Claude Code, where a line that starts with @ imports the file at start-up.
The procedure should be read when the task is a release, and at no other time. Which line should the instruction file keep?
For each line, when does the agent read the procedure: in every session, only on a release, or never?
When is it in context?
Section titled “When is it in context?”In Claude Code, the project instruction file is read at the start of every session. A line that starts with @ followed by a path imports that file. A rule file with a paths field loads when the agent works with files that match it.
Match each way of giving guidance to when its text is in the agent’s context.
Does Claude Code read the text when the session starts, or does something in the task have to bring it in?
What is in context before the first task?
Section titled “What is in context before the first task?”In Claude Code, the project and user instruction files are read at the start of every session. A file in .claude/rules/ loads at start-up unless a paths field scopes it. A skill's instructions load when you call the skill or when the agent decides the task fits it. A CLAUDE.md in a subdirectory is read when the agent first reads, writes or edits a file in that subdirectory.
Which two of these are in the agent’s context at the start of every session, whatever the task is? Select two.
For each one, does the agent read the text whatever the task is?
Cut what does nothing
Section titled “Cut what does nothing”Pointing makes the file shorter. Pruning instructions makes it shorter again, by deleting lines that no task needs. The vendor’s test asks of each line whether the agent would get something wrong without it, and a line the agent wouldn’t miss goes [3]. The lines that fail the test are usually one of these.
A rule the agent follows anyway. “Write clean, readable, well-documented code” describes what the agent does without it, and so does a line about a convention the agent already applies, such as type hints in a code base that has them everywhere.
A fact the code already states. The formatter’s configuration sets the
quote style and the line length, so “use double quotes” and “keep lines
under 100 characters” repeat it. The dependency list and the Python
version are in pyproject.toml. The paragraph about the modules says only
what the folder names already say. It doesn’t name a generated directory and
doesn’t say where new code goes, which are the parts of a structure
section that the code doesn’t show. A copy of a fact can also go stale
while the code changes, and then the agent has two sources that disagree.
A rule for a problem that has gone away. “Keep the PDF library below version 52” was right when the crash happened. The project has used version 62 for a year, and the line now asks the agent to downgrade.
A line that contradicts another. The long file says uv run pytest
under Commands and python -m pytest under Rules. Given two lines that
disagree, Claude may pick either one [1].
Resolve a conflict by keeping one version, and keep what the cut line meant
as well. The second line also said when to run the tests. The pruned
file says that next to the right command.
Claude Code can look for some of these lines for you. /doctor prompt-audit reports instructions that contradict each other or name
files and commands that don’t exist, and it changes nothing until you ask
it to [1]. The audit finds candidates, and you still
make the call on each line.
Keep it, point at it, or cut it?
Section titled “Keep it, point at it, or cut it?”The lines come from a long instruction file for a Python service that renders invoices and sends them by email. Without a test command in the file, the agent has guessed wrong ones. The formatter's configuration sets double quotes. The project has used version 62 of its PDF library for a year. The agent has committed straight to the main branch before, and nearly every task ends in a commit. Releases happen once a month, and templates change a few times a year.
For each line: would the agent get something wrong if the line were gone, and if so, does nearly every task need it?
Watch the sessions after the cut
Section titled “Watch the sessions after the cut”A pruning pass is a change to a prompt, and you test it the way you test any prompt change: run the usual tasks and watch what the agent does. The vendor asks you to look after the file the way you look after code. Cut lines from it on a schedule, and check in later sessions whether the agent acts differently [3]. When a session goes wrong after the cut, the cut line that would have stopped it comes back, and only that line.
Two sessions skipped the tests
Section titled “Two sessions skipped the tests”A developer pruned a 57-line instruction file to 20 lines. One cut line said to run the tests with the wrong command before finishing, and it was cut because it contradicted the right test command elsewhere in the file. In the next five sessions the agent twice said a task was done without running the tests. Nothing else went wrong.
Two of five sessions after the cut ended without a test run. What do you change?
Which cut line was doing a job, and which part of it?
Which question decides?
Section titled “Which question decides?”A developer goes through a coding agent's instruction file line by line to make it shorter, and needs one question to decide for each line whether it stays.
Which question decides whether a line stays in the file?
What is the instruction file for, from the agent's side?
Which lines go?
Section titled “Which lines go?”A Python service has an instruction file for its coding agent. Its formatter's configuration sets the line length to 100. The service has used version 62 of its PDF library for a year. The agent has committed to the main branch before, and it has added retries around mail calls that the mail queue already retries.
Which two of these can you cut from the file? Select two.
For each line, what does the agent do if the line is gone?
Exercise
Practicing the line test on a file whose facts are given makes it easier to use on a file you care about, where the facts are yours to find. Copy the long file to a scratch folder outside the course repository. You edit the copy and leave the original alone:
mkdir -p ~/prune-me/docscp <course-repo>/site/examples/customizing-agents/load-point-prune/AGENTS.long.md ~/prune-me/AGENTS.mdGo through ~/prune-me/AGENTS.md line by line and mark each line keep,
point or cut. Use these facts about the project. The formatter’s
configuration sets double quotes and a line length of 100. Every public
function already has type hints. The project has used version 62 of its
PDF library for a year. The agent has committed to main before, has
edited uv.lock by hand, and has added retries around SMTP calls. Move
each point group into its own file under ~/prune-me/docs/, and replace
it in AGENTS.md with one line that says when to read it and where it is.
Delete every cut line. Then count what you have left:
wc -l ~/prune-me/AGENTS.md ~/prune-me/docs/*.mdA good result is about 20 lines in AGENTS.md, with every rule the agent has broken
still in it, the test command written once and correctly, and no @
imports. Compare it with AGENTS.pruned.md, docs/templates.md and
docs/release.md in the lesson folder, which are one answer, not the only
one. Where your choice and the model answer differ on a line, say what
mistake the agent would make without that line, or why it would make
none. Which of your
cuts would you check first in a real session, and why that one?
Stretch: Do the same pass on a copy of an instruction file from a project you work in, on a branch of its own. Then run three of your usual tasks with the pruned file and add back only the lines whose absence caused a mistake.
Recap
- Every line in an instruction file is in context for every task, and a long file gets followed less well than a short one [1].
- Load what nearly every task needs, and point at the rest with one line that says when to read the file and where it is.
- An
@pathimport expands the file into the context at start-up, so it makes the file tidier without making it cheaper [1]. - Prune by asking of each line whether the agent would get something wrong without it. Cut rules the agent follows anyway, facts the code states, problems that have gone away, and one of every pair of lines that contradict each other [3].
- After a cut, run the usual tasks and add back only the line whose absence caused a mistake.
You can now
- Decides for each piece of guidance whether to load it or point at it
- Prunes instruction files line by line
References
Section titled “References”- Anthropic. How Claude remembers your project. Claude Code documentation. Reference.
Claude Code memory - Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, Jeremy Hadfield. Effective context engineering for AI agents. Anthropic Engineering. Reference.
Anthropic context engineering - Anthropic. Best practices for Claude Code. Claude Code documentation. Reference.
Claude Code best practices