Step four of the backfill procedure says to pause the downstream job before touching the partition. It sits about 1,400 tokens into the instructions file, below the naming conventions and above a note on test fixtures. The agent reads it on every task, whether or not anyone is backfilling anything.
That’s the data team at Vinehall Foods, a company that doesn’t exist, and I picked every token count in this post. The backfill section runs 1,900 tokens. About one task in forty needs it.
Three places to put knowledge, and a procedure fits none of them
A typical agent setup gives you three homes for what the agent should know.
A tool gives it a capability: run this query, read that file. A Model Context Protocol server packages a set of tools behind a connection, so the warehouse or the scheduler is reachable from any agent that speaks the protocol. Neither says in what order to do things, or what to check in between.
The instructions file, CLAUDE.md or AGENTS.md depending on your tool, holds standing rules, and I’ve written about what earns a place in it. It’s loaded every session, which is right for “never write to prod schemas” and wrong for a twelve-step runbook. I’ve argued that the context window is a budget, and a procedure you run three times a month is a line item paid on every task.
Tokens aren’t the only cost. A step buried among unrelated rules gets treated like them, as general guidance. That’s how “pause the downstream job first” gets skipped.
A fourth place: a procedure folder
Each procedure gets a folder with a PROCEDURE.md and, optionally, scripts and reference files. The instructions file keeps a short index: each procedure’s path and description, plus a rule to read the matching file first. The body is read only when a task matches. Scripts are run, not read, so only their output enters the context.
Here’s the Vinehall folder, shortened to fit a page:
procedures/backfill-partition/
├── PROCEDURE.md
├── reference/
│ └── table-owners.md
└── scripts/
├── check_downstream.py
├── run_backfill.py
└── compare_counts.py
And the entry in the instructions file:
## Procedures
For a matching task, read the file first. Run its scripts; don't read them.
- `procedures/backfill-partition/PROCEDURE.md`: backfill or reload one
date partition of a warehouse table. Use when a task mentions backfill,
reload, reprocess, or a missing or wrong partition for a date.
And PROCEDURE.md itself:
# Backfill a partition
Use this for one table and one partition date at a time.
## Before you start
1. Confirm the table name and partition date with the requester.
2. Look up the table's owner and downstream jobs in
`reference/table-owners.md`.
## Steps
1. Run `python scripts/check_downstream.py <table>`. It lists the jobs
that read this table and whether each one is paused.
2. Pause every job it lists as running. Do not continue until a second
run of the script prints `all paused`.
3. Run `python scripts/run_backfill.py <table> <date> --dry-run` and
show the row estimate to the requester.
4. Run the same command without `--dry-run`.
5. Run `python scripts/compare_counts.py <table> <date>`. It compares
the source row count with the partition's.
## Checks
- Counts must match within 0.1 percent. If they don't, leave the
downstream jobs paused and report both numbers.
- Resume the downstream jobs only after the counts pass.
- Post the table, date, row counts and resumed jobs in the task thread.
## Scripts
- `check_downstream.py`: read-only, queries the scheduler.
- `run_backfill.py`: writes to the warehouse; refuses to run if any
downstream job is still active.
- `compare_counts.py`: read-only.
The description is written as a trigger, in the words a person would type, because it’s all the agent sees when deciding whether to read the rest. And the pause is enforced twice: as a numbered step read at the moment of the work, and inside run_backfill.py, which won’t run while a downstream job is active.
The arithmetic for Vinehall
Say the team runs 120 agent tasks in a month and three are backfills. In the instructions file, the procedure costs 1,900 tokens on all 120, or 228,000 tokens.
As a procedure file, the index line is about 40 tokens on every task and the body loads three times: 4,800 plus 5,700, or 10,500 tokens. That’s a cut of roughly 95 percent.
I care more about the skipped step than the tokens. When the body loads, the agent is reading a runbook for the thing it’s about to do, with no unrelated rules around it.
Where each piece goes
| Piece of knowledge | Home | Why there |
|---|---|---|
| “Never write to prod schemas without a ticket” | Instructions file | Applies to every task, short enough to always load |
| Backfill a partition, ordered steps with checks | Procedure folder | Needed rarely, ordered, has scripts to bundle |
| Run a SQL query against the warehouse | Tool | A single capability with typed inputs |
| Pause, resume and inspect scheduler jobs for any team’s agent | Tool server | Shared system with its own auth, used by many agents |
| Which jobs read which tables | Reference file inside the procedure folder | Only useful mid-procedure, read on demand |
My test is frequency and ordering. Something that always applies is a rule. An ordered sequence that applies sometimes is a procedure. Something the agent calls is a tool, and it moves behind a server once more than one agent needs it.
Write it like a runbook, review it like code
A procedure folder is instructions plus executable files, and the scripts run with whatever permissions the agent has. So it goes through pull request review like any other code. Ask what each script writes to and which credentials it touches. A procedure copied from somewhere on the internet deserves more suspicion than a library, since it can carry both code and text that steers the agent.
The match is the model’s judgment, so a vague description will misfire or never fire, and nothing forces the agent to open the file. That’s why the pause also lives in a script that refuses to run. A procedure doesn’t replace the tool server it calls; Vinehall still needs the scheduler connection. But since it’s only Markdown and scripts, the folder works with any agent that can read files and run commands.
I’d start by opening the instructions file and looking for numbered lists. Each one is a candidate to move out.