The folder method: one AI agent that survives every model update

This is the whole setup from the video: the folder, the map, the three files in every job, and the five prompts that write them. Download the starter folder with the button at the top, or build it by hand with the command further down.

Why your agent keeps breaking

You've seen the localhost demos with 300 agents running an entire business. They burn tokens, and every agent in them runs on a prompt someone tuned for one model. When the next model drops, nothing crashes. It just quietly gets worse. A study of 5,669 bug reports across agent frameworks found 76% of them were silent wrong output, with no error at all. You find out from a customer.

Most of the frameworks those demos were built on got retired or rewritten in the last year:

Meanwhile OpenAI's Codex team shipped about a million lines of code in five months without writing any of it by hand. One giant instruction file didn't work for them, so they cut it to about 100 lines that point the agent at a folder of docs. They called it giving Codex a map instead of a manual.

The rule

One agent. One map at the top. One folder per job with three things inside. Write the proof before the playbook.

• The agent is the one you already use: Claude Code, Codex, Cursor. The labs build that part better than you will, and every release they ship replaces whatever loop you wrote yourself.
• The map is AGENTS.md, a short table that tells the agent where it is and which folder to open for each job.
• Each job folder holds the playbook (what to do), the toolbox (everything it's built before, so it never builds the same thing twice) and the proof (what done looks like, checked before it hands you anything).
• A new model can break your playbook. The proof is how you catch it, so the proof gets written first.

The folder

The four parts you write are the map, the playbook, the toolbox and the proof. Everything else in the tree is plumbing the agent reads from or fills in.

my-agent/
├── AGENTS.md          the map: which folder to open for each job
├── CLAUDE.md          one line: @AGENTS.md
├── CHANGELOG.md       every fix, dated, with the model name
├── toolbox/           scripts and templates more than one job uses
└── jobs/
    └── weekly-report/
        ├── PROOF.md   the proof: pass/fail checks on the output
        ├── SKILL.md   the playbook: trigger, inputs, steps, rules
        ├── tools/     the toolbox for this job
        ├── data/      what the job reads, plus a test fixture
        └── runs/      dated outputs

The starter folder has this layout with one blank job in jobs/first-job/. To build it by hand instead:

mkdir -p my-agent/jobs/weekly-report/{tools,data/fixture,runs} my-agent/toolbox && cd my-agent && touch AGENTS.md CHANGELOG.md jobs/weekly-report/{SKILL.md,PROOF.md} && echo "@AGENTS.md" > CLAUDE.md

The example job all the way through is a weekly metrics report. Rename it to your own first job. Anything you do more than once in the same shape works, like answering a client inquiry or turning notes into a blog post.

Step 1: the map

AGENTS.md answers two questions: where am I, and where do I go. It's a routing table. Keep it under 100 lines, and only put in what the agent can't figure out by reading the folder.

# <your agent's name>

One agent, one folder per job. Find the job below, open its folder, follow SKILL.md.

## Rules that apply to every job
- Read the job's SKILL.md fully before doing anything.
- Reuse what is in tools/ and toolbox/ before building anything new.
- Save anything you build to the job's tools/ and link it from SKILL.md.
- Run the job's PROOF.md before returning. Fix every fail first.
- If a job is not listed here, stop and ask.

## Jobs
| When asked to... | Open |
| --- | --- |
| write the weekly report | jobs/weekly-report/ |
| reply to a client inquiry | jobs/client-reply/ |
| publish a blog post | jobs/publish-post/ |

## Shared
- toolbox/ holds scripts and templates used by more than one job.
- CHANGELOG.md is where fixes get logged. Read the last five entries before starting.

CLAUDE.md is the one line @AGENTS.md. Recent versions of Claude Code read AGENTS.md on their own, and the import covers the sessions where it can't. Codex, Cursor and GitHub Copilot read AGENTS.md as it is. Gemini CLI looks for GEMINI.md by default, so add AGENTS.md to context.fileName in its settings.json. For any other tool, paste the map into your first message.

Step 2: the interview

Don't write the playbook yourself. Get interviewed into it. You know the job, but you won't remember half of what you know until something asks. Open your agent in the my-agent folder, paste this, and answer one question at a time.

You are going to write a playbook for one job I do, so an AI agent can run it without me. Interview me first, one question at a time. Cover: what triggers the job, what inputs it needs and where they live, every step in order, the judgment calls and how I make them, what I reuse (templates, scripts, past examples), what a bad result looks like, what a finished result looks like, and who it goes to. Keep asking until you could run it without me. Then say "ready" and stop.

Step 3: the proof

This is the file almost nobody writes. PROOF.md is a pass/fail checklist for the finished output. The agent runs it before it hands you anything, and you run it every time the model changes. It goes before the playbook because it's the part that doesn't change when the model does, and the playbook gets checked against it.

Three rules. Grade the output, not the steps it took. Every line has to be something two people would agree on without arguing. Include one fixture: a sample input in data/fixture/ and the output you expect from it.

From the interview, write jobs/<job>/PROOF.md. Don't write SKILL.md yet. It is a pass/fail checklist for the finished output, not the steps. Each line must be something two people would agree on without arguing. Under 20 lines. Include one fixture: put a sample input in data/fixture/ and write the output you expect from it in data/fixture/expected.md.

# PROOF: weekly-report

Run on the newest file in runs/ before returning. Every line pass or fail. Fix every fail first.

## Output
- [ ] File exists at runs/YYYY-MM-DD-report.md with today's date
- [ ] Every number in the report appears in data/exports/ (no invented numbers)
- [ ] Comparison section names last week's figure for each metric
- [ ] Anything that moved more than 20% is flagged
- [ ] Under 300 words
- [ ] No section from the template is empty

## Fixture
- [ ] Running the job on data/fixture/input.csv produces a report matching data/fixture/expected.md on every number

## Reuse
- [ ] Nothing was built that already existed in tools/ or toolbox/
- [ ] Anything new was saved to tools/ and linked from SKILL.md

If you can't write a proof line for a step, the step is a vibe. Make it checkable or cut it.

Anthropic's guide to evals says what this buys you. When a new model comes out, teams without evals face weeks of testing. Teams with them can tune their prompts and upgrade in days.

Step 4: the playbook

Now the playbook gets written with the proof already sitting next to it, so its last step can point at a file that exists.

Turn the interview into jobs/<job>/SKILL.md. Start with a name and a one-line description of what the job does and when to use it, then these headings: Trigger, Inputs, Steps, Rules. Under 80 lines. Steps are imperative, one line each. Leave out anything the agent could learn by reading the folder. Do not use ALWAYS, NEVER or MUST unless breaking the rule would be a disaster. Every reusable thing becomes a link to a file in tools/ or data/. The last step is: run PROOF.md and fix every fail before returning.

---
name: weekly-report
description: Writes the Friday metrics report from the exports in data/. Use when asked for the weekly report.
---

## Trigger
Friday, or when asked.

## Inputs
- data/exports/ (latest CSV)
- data/last-report.md (for the comparison)

## Steps
1. Run tools/pull-metrics.py on the newest CSV.
2. Fill tools/report-template.md with the numbers.
3. Write three sentences on what changed vs last week. Numbers first, opinion second.
4. Flag anything that moved more than 20%.
5. Save to runs/YYYY-MM-DD-report.md.
6. Run PROOF.md. Fix every fail before returning.

## Rules
- Do not invent a number. If it is missing, say so.
- Reuse tools/ before building anything. Save what you build there and link it here.

The name and description at the top are the Agent Skills format. The description is how the agent decides it's in the right folder, so write it like a search result. In this setup the map is what sends the agent to the folder. Because the file is in the standard format, you can also copy a job into Claude Code's .claude/skills/ later if you want it to load on its own.

Keep it short. This is the one file you'll edit when the model changes, and less text means less to go stale. New models follow instructions more literally, which is why OpenAI's and Anthropic's own migration guides tell you to strip out the old ALWAYS and NEVER emphasis.

Step 5: the toolbox

The toolbox is every script, template, checklist and example the job reuses. Anything the agent builds while running the job gets saved to tools/ and linked from the playbook, so it never builds the same thing twice.

Scripts matter more than you'd think. A script does the same thing on every model, and a paragraph of instructions doesn't. When a step can be a script, make it a script. The same goes for proof lines: a script that counts the words or matches every number against the input is a stronger check than the model grading its own work.

Read the interview and jobs/<job>/SKILL.md. List every template, script, checklist or example this job reuses. For each one, create the file in jobs/<job>/tools/ (or toolbox/ if more than one job will use it). Where SKILL.md describes the thing in words, replace the description with a link to the file. Any step that can be a script becomes a script. Where a line in PROOF.md can be checked by a script, like a word count, a file name or numbers matching the input, write that script in tools/ and point the proof line at it. Then add this rule to SKILL.md: anything you build while running this job gets saved to tools/ and linked here.

A typical job ends up with one or two scripts, a template, one good example of a finished output and a checklist. If tools/ has twenty files in it, the job is too big. Split it.

Run it

Open your agent in my-agent/ and ask for the job in the same words you used in the map: "write the weekly report." It reads the map, opens jobs/weekly-report/, follows SKILL.md, uses what's in tools/, saves the result to runs/, and runs PROOF.md on it before it answers you.

Watch the first few runs. Something will come back wrong, and that's what the next section is for.

When it gets something wrong

Don't argue with it in the chat. A chat fix dies when the window closes. Open the file the mistake points to.

Then log the fix in CHANGELOG.md with the date, the job and the model that was running:

## 2026-10-07 · weekly-report · claude-fable-5-1
Fail: flagged a 12% move as big. Fix: SKILL.md step 4 now says "more than 20%" instead of "a big change."

The log is why the agent gets better instead of starting from zero every session.

When a new model drops

Budget an hour, not a week.

1. 1.Change the model in your agent's settings. You never wrote the loop, so the API changes are the vendor's problem.
2. 2.Run every job's PROOF.md against its fixture.
3. 3.Where one fails, edit that job's SKILL.md and nothing else. Expect to delete more than you add. The old emphasis is usually what breaks.
4. 4.Log each change in CHANGELOG.md with the date and the model name.
5. 5.Leave tools/, data/ and PROOF.md alone. They don't care which model runs them.

I changed the model. Run every job's PROOF.md against its fixture in data/fixture/. For each fail, edit only that job's SKILL.md. Prefer deleting or softening an instruction over adding one. Do not touch tools/, data/ or PROOF.md. Append each change to CHANGELOG.md with today's date and the model name. Report what passed, what failed, and what you changed.

You'll still have to change something. Every lab says prompts tuned for one model need adjusting for the next. What the folder gets you is small edits, in one file per job, that you find in an hour instead of hearing about from a customer.

Where this comes from

Using folders as the architecture is Jake Van Clief's Interpretable Context Methodology. The playbook, toolbox and proof split comes from Cooper Simson. The file names come from two open standards, AGENTS.md for the map and Agent Skills for the playbook. Writing the proof first is my part.

• Interpretable Context MethodologyJake Van Clief's paper on folder structure as agent architecture.↗
• Harness engineering, from OpenAIThe Codex team's million lines and the map file.↗
• Demystifying evals for AI agentsAnthropic on why a written check makes a model upgrade take days.↗
• Agent Skills, from AnthropicWhere the SKILL.md format came from.↗
• AGENTS.md in Claude CodeHow Claude Code reads AGENTS.md and @ imports.↗