The File That Makes It Competent
You write the standing brief that turns a capable generalist into someone who already works here. Not a prompt for one task, but a file that loads on every run, states the ground truth of your project, and gets one line longer every time the agent gets something wrong. By the end you have a file that answers the questions your agent kept guessing at, and you can point at each line and name the failure that put it there.
loaded before every single run
┌────────────────────────────────────────────────┐
│ stack/AGENTS.md │
│ ────────────── │
│ what this project is │
│ how work is done here │
│ what is true that it cannot see │
│ what it must never do │
└───────────────────┬────────────────────────────┘
│
┌──────────┐ ▼ ┌───────────┐
│ your │──▶ [ the run ]──▶│ result │
│ request │ └─────┬─────┘
└──────────┘ │
▼
┌──────────────────────┐
│ you ✋ │
│ spot what it got │
│ wrong, write the │
│ line that stops it │
└──────────┬───────────┘
│
└──▶ back into the fileA prompt fixes this run. A line in this file fixes every run after it, and the only thing that writes those lines is a person who noticed.
- Say in one sentence what belongs in a standing brief and what belongs in a single request.
- Name the four things a project brain must contain and give a real example of each from your own work.
- Write a rule that is checkable — a path, a command, a name — instead of a rule that is an attitude.
- Turn a specific failed run into exactly one line of file, and say what that line prevents.
- Cut your own file by a third and defend every line that survived.
- Name where your brief lives, what loads it, and how you would prove it was loaded.
stack/AGENTS.md — the standing brief your agent reads before every run, in four sections: what this project is, how work is done here, what is true that the agent cannot see, and what it must never do. Every line in it traces to something that went wrong or obviously would have.
By now your harness runs, and you have watched it do one real thing. If you have used it more than twice you have already noticed the tax: every session starts from zero. The agent does not know that the sheet with the real numbers is the second tab, that the client is called Northgate in the contract and NG in the folder names, that nothing gets written to the archive directory, that the build command is not the one in the README because the README is out of date. So you type it again. And again, slightly differently, which is worse than typing it the same way, because now two runs behaved differently for a reason you will not remember.
A prompt is scoped to one request. It arrives, it does its job, it leaves with the session. A project brain is scoped to the project. It is a file on disk or a document in a workspace, and the harness puts it in front of the model automatically, before your request, on every run without being asked. That automatic part is the whole difference. A file you have to remember to attach is a prompt with extra steps.
The shift in your head is from instructing to describing. A prompt says do this thing now. A brief says this is what is true here. The agent is not short of capability. It is short of local facts, and local facts are exactly the things nobody writes down because everyone in the room already knows them. Your brief is where the room's shared knowledge stops being tribal.
Key insight: if you find yourself typing the same sentence into a third session, that sentence is not a prompt. It is a line of your project brain that has not been written down yet.
Briefs sprawl when nobody has told you what shape they are. Four sections, in this order, and if a line does not belong in one of them it probably does not belong.
What this project is. Two or three sentences of orientation. What the thing does, who it is for, what the moving parts are called. This exists so the agent stops inferring your domain from filenames.
How work is done here. The conventions and the commands. Where new files go. What the test command actually is. Which sheet is authoritative. What the naming pattern for a client folder is. Which format a date takes in this system, because in every real system some part of it disagrees with the rest. This section is the largest and it is almost entirely concrete nouns.
What is true that the agent cannot see. The most valuable section and the one people skip, because it is the only one that requires you to think rather than transcribe. The agent sees the current state of your files. It does not see that the legacy/ folder is frozen and only kept for an audit, that two columns are named the same thing for historical reasons and only one is read, that the numbers in the January tab were entered by hand and are the ones the client argues about. Every one of those is invisible to inspection and expensive to guess wrong.
What it must never do. Lifted straight from your charter and narrowed by your blast radius table. Not attitudes. Actions. Never write to archive/. Never message a client directly. Never change a historical row; append a correction row instead.
The single most common way a project brain fails is that it fills up with things that sound like guidance and cannot be checked.
"Write clean, maintainable code." "Be thorough." "Prioritise the user experience." "Follow best practices." Every one of these is true, none of them changes a decision, and all of them cost you budget on every run for the rest of the project. The model already aims at good work. Telling it to aim at good work is the instruction equivalent of nodding.
Test each line with one question: could a stranger tell whether this line was followed? "Be careful with the database" fails. "Run migrations only against the local copy; never against the file in data/prod/" passes, because someone can look and see. "Match the existing style" fails, unless you name the file to match. "New endpoints go in src/api/, one file per resource, named after the resource in the plural" passes.
The temptation is to sit down and write the whole thing at once, from first principles, in one satisfying afternoon. Files written that way are long, plausible, and mostly about problems you do not have.
The better method is unglamorous. Start with a short file: the four sections, maybe fifteen lines, only what you already know for certain. Then run real tasks. When a run goes wrong, do not just correct it in the chat and move on — that fix dies with the session. Ask the narrower question: what one sentence, present at the start, would have prevented this? Write that sentence into the file. Then run the next task.
This gives you a file where every line has a story, and that turns out to matter more than it sounds. Lines without stories accumulate, get contradicted by other lines, and eventually someone deletes the whole section because nobody remembers which parts are load-bearing. A brief grown one correction at a time is self-justifying by construction.
Keep the correction small and behavioural. If the agent wrote to the wrong folder, the line is about the folder, not about carefulness. One failure, one line, stated as a fact or a prohibition. If a failure needs a paragraph to prevent, it is probably not a brief problem at all — it is a structural one, and Part 2 and Part 3 of this course are where structure lives.
Here is the discipline that separates a brief from a wiki. The file is loaded before every single run. A line you add today is read on the next four hundred runs, whether or not it is relevant to any of them.
That cost is real in three ways. It occupies budget that could have held the actual material of the task. It dilutes: an important prohibition surrounded by forty lines of mild preference is harder to follow than the same prohibition in a short file. And it decays quietly, because the longer the file, the less often anyone reads the whole thing, and stale lines in a brief are worse than no lines. An instruction that names a command you renamed six weeks ago is not neutral. It actively sends the agent to the wrong place, with confidence.
So treat length as a budget rather than a side effect. A useful working target is one screen, and if that sounds aggressive, notice what falls off the bottom when you enforce it: the general advice goes first, then the duplicated statements, then the rules that were true once in March. What survives is paths, commands, names, and prohibitions.
Warning: the most expensive line in a project brain is not the useless one. It is the one that was true, then quietly stopped being true, and is now confidently pointing the agent at a path that moved.
The mechanism differs by track and it will keep drifting as tools change, so learn the property rather than the filename. The property is: the brief is present without anyone choosing to bring it.
In a repo-based harness, that means a plain markdown file at the root of the working directory, picked up automatically when the harness starts there. Common names are AGENTS.md and CLAUDE.md, and several harnesses read one or both. Keeping the canonical copy in stack/AGENTS.md and linking or copying it to the root gives you one file to edit, versioned with everything else, and a root file that whichever harness you use will find.
In a workspace-based setup, it means a document attached to the project or space itself, or standing instructions configured on it, so that every conversation started inside that workspace already has it. The test is the same: start a fresh session, ask a question that only the brief could answer, and see whether it answers. If you had to attach anything, it did not load.
That test is worth running deliberately rather than assuming. Put one specific, checkable fact in the file — a naming convention, a directory that is off limits, the real name of the second tab — then open a clean session and ask about it. This takes thirty seconds and it is the only proof you will get.
Remember: filenames and loading mechanisms are the part of this module most likely to change under you. The durable rule is that the brief loads automatically and you have verified it in a clean session. Where a tool looks for it is a detail you re-check when you switch tools.
A brief is a living file, and the failure mode of living files is that they only ever grow. Corrections go in, nothing comes out, and after a few months you have a document that is half archaeology.
Give it a standing review, attached to something you already do. Once a month, or whenever you finish a batch of runs, read the whole file top to bottom and ask three questions of each line. Is it still true? Has it ever been violated? Would I notice if it were? A line that is still true and gets violated is doing work. A line that is still true and has never been at risk is a candidate for deletion, because it is describing something the agent was going to do anyway. A line that is no longer true is an emergency, and it is why the review exists.
The most useful signal in the review is repetition of correction. If you find yourself telling the agent the same thing in chat for the third time, that is not the agent failing to learn. That is the file missing a line, or having a line that is buried, contradicted, or too vague to act on. Repetition in your chat history is the highest-quality input this file will ever get, and it is free.
A freelancer sets an agent to reconcile a monthly invoice sheet. Three months in, the accountant asks for the sheet to be reorganised, and the tab holding last year's figures is renamed from 2024 to Archive 2024. The brief still says the historical tab is called 2024. On the next run the agent finds no tab by that name, decides the historical data must be missing, and rebuilds the year's totals from the current tab, which only holds the last ninety days. The output looks complete: same layout, same formatting, plausible numbers. It is discovered five weeks later by a client who remembers a figure from spring that is no longer there.
Nothing in that run was a reasoning failure. The agent did exactly what a confident, competent person would do given a file that told them something false. A brief is a set of claims about your project, and a claim that has gone stale does more damage than a claim that was never made — which is the entire reason the review habit is part of this module and not a footnote.
Twenty minutes, in two halves. First you draft, then you run something real and let the run tell you what the draft missed.
- Every line in the file names something checkable: a path, a command, a tab, a label, a spelling, or a specific forbidden action.
- You can point at any line and say which run, or which near miss, put it there.
- The file fits on one screen, and the four sections are still distinguishable.
- A fresh session answered a file-only question correctly, so you have proof of loading rather than an assumption.
- At least one thing you were tempted to include is deliberately absent, and you can say why.
Do not write a project brain for a one-off job. If a task runs once, everything it needs belongs in the request, and a standing file is overhead you pay forever for a benefit you collect once. The same applies to a project whose conventions you are still inventing: a brief written on Monday and contradicted on Wednesday teaches the agent to be wrong with confidence. Wait until the shape has held for a handful of real runs, then write down what actually held.
Use this when the blank file is the obstacle. It interviews you for the local facts you have stopped noticing, then produces a first draft short enough to be worth editing. Run it in a session that already has access to your project if your harness allows it, so it can ask about things it can see; if not, answer from memory and let the first real run correct you.
<task>
Interview me about one project, then draft a short standing brief that an AI agent
will load before every run in that project.
</task>
<context>
A standing brief is not a prompt. It loads automatically on every run, so every
line costs budget on every run forever. It has exactly four sections: what this
project is, how work is done here, what is true that an agent cannot see by
looking at the files, and what it must never do.
My project: [one or two sentences — what it is and what the agent will be doing
in it]
Already decided, do not re-litigate: [paste the "## Never" lines from
stack/charter.md, and any rows you marked irreversible in stack/blast-radius.md]
</context>
<instructions>
1. Ask me ONE question at a time, at most eight, waiting for each answer.
2. Prioritise questions that surface things an agent could not learn by reading
the files: names that differ between systems, areas that are frozen, data
that was entered by hand, tools that are configured differently than they
look, and the exact commands or locations for routine work.
3. If an answer is a generality, ask once for the specific name, path or command,
then move on.
4. After the last answer, output the brief.
</instructions>
<output_format>
A markdown document with exactly these four headings and nothing else:
## What this is (2-3 sentences)
## How work is done here (bulleted; each line names a real command, path,
file, tab, label or naming pattern)
## What you cannot see (bulleted; each line a fact that inspection would
not reveal)
## Never (bulleted; each line one specific forbidden action)
Fifteen lines total or fewer across all four sections.
</output_format>
<rules>
- Every line must be checkable by a stranger. Reject anything that is an attitude,
a value, or a quality bar.
- Do not include lines about writing clean code, being thorough, or following
best practices.
- Do not invent a detail about my project. If you need one, ask.
- No statistics and no claims about how often anything fails.
- If you cannot fill a section from my answers, leave it with a single line
saying what you still need.
</rules>Run this after a real run has gone sideways. It takes the transcript of what happened and produces the smallest set of lines that would have prevented it, which is almost always fewer lines than you would have written by hand. Its main job is to stop you from turning one bad run into a policy document.
<task> Read the run below and tell me the minimum lines to add to my standing brief so this specific failure cannot repeat. </task> <context> My current standing brief: [paste the full contents of stack/AGENTS.md] What I asked for in the run: [paste your request] What actually happened: [paste the relevant part of the transcript, or describe in specifics what it touched, what it named wrongly, and where it guessed] </context> <instructions> 1. Name what the agent did not know, as a fact about my project rather than as a behaviour. 2. Propose the smallest number of lines that would have prevented it. Prefer one. Never propose more than three. 3. For each proposed line, say which of the four sections it belongs in and which observation in the run it is answering. 4. Check the proposed lines against my current brief and flag any that duplicate, contradict, or make an existing line redundant. 5. Name anything in my current brief that this run showed to be stale or unused. </instructions> <output_format> ## What it did not know [one or two sentences] ## Lines to add [for each: the exact line to paste, its section, and the observation it answers] ## Conflicts with what is already there [bulleted, or "none"] ## Candidates for deletion [bulleted, or "none"] </output_format> <rules> - Propose lines, not paragraphs. Each line stands alone and names something concrete. - Do not propose a rule for a failure that did not occur in this run. - Do not propose anything that starts with "always be" or "make sure to". - If the failure was structural rather than informational — the agent could reach something it should not reach — say so and propose no lines. </rules>
Open a blank file, write the four headings, and fill only the third one: what is true here that someone looking at the files would not know. That section is where nearly all the value is, and you can write it in ten minutes because it is just the things you would tell a competent new contractor on their first morning. Add the other three sections from your next three real runs, one line per surprise.
Save the brief where the rest of the course can read it, and keep the copy at your harness's expected location linked rather than duplicated so there is one file to correct. Module 05 turns your good runs into named moves and each of those moves assumes this file is loaded. Module 07 describes new tools in the same voice you used here. Module 12 hands this file across an agent boundary as part of a written handoff.
Save as: stack/AGENTS.md — read again in Module 05, Module 07, and Module 12.
Say these out loud. If you cannot, reread the section named after each.
- I can point at every line in my file and name the failure, or near miss, that put it there. (Write it from failures, not from imagination)
- I can name something I deliberately left out, and say what it would have cost on every run. (Every line costs, on every run)
- I proved my file loads by asking a fresh session a question only that file could answer. (Where it lives and how it gets loaded)
Module 04 opens the run itself and shows you everything that was in front of the model at the moment it decided — this file included, along with three other sources you have not counted yet. You will measure them, then cut a third.