# Load it, point at it, or cut it

> Take a long instruction file and make it short: keep what nearly every task needs, move what only some tasks need behind a one-line pointer, and delete the lines the agent would not miss.

Page: https://schubergphilis.github.io/ai-training/customizing-agents/load-point-prune/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

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

Claude Code reads its instruction files at the start of every session
(How Claude remembers your project, Claude Code documentation). 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](https://schubergphilis.github.io/ai-training/concepts/what-tokens-cost/#the-rule-that-got-buried) 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 (How Claude remembers your project, Claude Code documentation).

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 (Effective context engineering for AI agents, Anthropic Engineering).

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 (How Claude remembers your project, Claude Code documentation).

## 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
(How Claude remembers your project, Claude Code documentation). 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
(How Claude remembers your project, Claude Code documentation). 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.

```sh
cd <course-repo>/site/examples/customizing-agents/load-point-prune
python3 startup.py
```

#### Checkpoint: How many lines load?

`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?

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

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
(How Claude remembers your project, Claude Code documentation). 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.

#### Checkpoint: Which line should stay?

The procedure should be read when the task is a release, and at no other
time. Which line should the instruction file keep?

- Always read `docs/release.md` before you start work.
- See also the files in `docs/` for more detail.
- @docs/release.md
- To cut a release, read `docs/release.md` and follow it.

## 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 (Best practices for Claude Code, Claude Code documentation). 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 (How Claude remembers your project, Claude Code documentation).
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 (How Claude remembers your project, Claude Code documentation). The audit finds candidates, and you still
make the call on each line.

#### Checkpoint: Keep it, point at it, or cut it?

Buckets:

- Keep in the file
- Move behind a pointer
- Cut

Items:

- Never commit to `main`. Branch as `feat/...` or `fix/...`.
- Test: `uv run pytest`
- The nine steps for cutting a release
- Regenerate the golden files for templates with `uv run pytest --update-golden`
- Use double quotes for strings.
- Keep the PDF library below version 52, which crashes on right-to-left text.
- Write clean, readable, well-documented code.

## 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 (Best practices for Claude Code, Claude Code documentation). When a session goes wrong after the cut,
the cut line that would have stopped it comes back, and only that line.

#### Checkpoint: Two sessions skipped the tests

Two of five sessions after the cut ended without a test run. What do you
change?

- Put the whole 57-line file back, because the cut broke something.
- Add "IMPORTANT" to every rule in the file, so the agent skips none of them.
- Add back when to run the tests, next to the right test command.
- Leave the file as it is. Two sessions out of five are noise.

#### Pitfall: Pointing at the rule every task needs

A team prunes its file and moves the branch rules into `docs/git.md`,
behind the line "for branch naming, read `docs/git.md`". A week later the
agent commits a fix straight to `main`. The task was a small fix, nothing
about it mentioned branch naming, and the agent didn't open the file. Keep
a rule that applies to nearly every task in the instruction file itself.
Pointing is for detail that only some tasks need.

## 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:

```sh
mkdir -p ~/prune-me/docs
cp <course-repo>/site/examples/customizing-agents/load-point-prune/AGENTS.long.md ~/prune-me/AGENTS.md
```

Go 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:

```sh
wc -l ~/prune-me/AGENTS.md ~/prune-me/docs/*.md
```

A 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

1. Every line in an instruction file is in context for every task, and a
   long file gets followed less well than a short one (How Claude remembers your project, Claude Code documentation).
2. 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.
3. An `@path` import expands the file into the context at start-up, so it
   makes the file tidier without making it cheaper (How Claude remembers your project, Claude Code documentation).
4. 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 (Best practices for Claude Code, Claude Code documentation).
5. After a cut, run the usual tasks and add back only the line whose
   absence caused a mistake.

#### Habit

Each time you add a line to an instruction file, look through the rest of
it for a line that no longer prevents a mistake. If you find one, delete
it.

## References

- How Claude remembers your project, Claude Code documentation, https://code.claude.com/docs/en/memory
- Effective context engineering for AI agents, Anthropic Engineering, https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- Best practices for Claude Code, Claude Code documentation, https://code.claude.com/docs/en/best-practices