Context as code: how we run every project from four files

Coding agents are fast and forgetful. Each session opens with no idea what was decided yesterday, which facts were verified, or what is still open. Most teams compensate by re-explaining – in chat, every time – and the explanation drifts a little on every retelling.

We took the opposite route. The context lives in the repository as plain text, next to the code, and the session reads it before it does anything. Chats die; files stay. The practice costs a few minutes per session and removes the most expensive failure in agent-driven work: confident output built on a stale picture.

The four files

Every project we run – client systems and our own – carries the same four files at its root.

• –A map file (in our tooling it is CLAUDE.md). Verified facts about the stack, the commands that actually work, the rules that must not be broken, and a table of where things live. Facts only – if it cannot be verified, it does not go in.
• –STATE.md. Where the project is right now and the open threads, updated at the end of every working session without being asked. The first thing any session reads.
• –DECISIONS.md. A dated, append-only log: what was decided, why, what it replaced. Never rewritten – if a decision is reversed, a new dated entry says so.
• –IDEAS.md. Dated ideas, never deleted. An idea that is dropped moves to a done or rejected line with the reason, so nobody proposes it again from scratch next quarter.

What a skeleton looks like

The files are short and boring on purpose. A sanitised skeleton of the map file, the one we hand to a new project, reads roughly like this:

• –Tech facts – framework and version, the dev command that works on this machine, the test and type-check commands that must exit clean before anything is called done.
• –Architecture map – a table of routes or modules and the file that owns each one, so nobody spends tokens rediscovering it.
• –Working rules – language and tone, what must never be claimed, what must never appear in the repository (secrets, client data, personal names).
• –Definition of done – a checklist the session ticks before reporting back: type-check clean, lint clean, the remnant greps empty, the state file updated.

How a session runs

Start: read STATE.md, then the map. Work: change only what was asked, match the surrounding style, remove what the edit orphaned. Finish: run the checks the map names, write the new state and any decision, then report. No session ends with a plan in chat and nothing on disk.

Small checks fail loudly. A typo in one of twelve translation files or a missing key is caught by a script, not by a reader. Evals gate releases the same way – we wrote about that separately in the build log on evals before launch.

We work inside a client’s tools and data, remotely, rather than from a slide deck – some teams call this forward-deployed engineering. The four files are what make it possible to step in and out of a system without losing the thread, and what let the client’s own people pick it up later.

Why the client gets the same pack

At handover a client receives the runbook, the decisions log, the checks the system was tested against, and a context file written for whoever – or whatever – works on it next. An engineer they hire in a year can read it in ten minutes. So can their own agents.

That is the point. The code says what the system does; the files say why, what was tried, and what must not change. Of the two, the second is the harder thing to rebuild – and it is the part most vendors leave in their heads when they walk away.