My 6 file context system
Every AI coding session starts from zero. Six markdown files in the repo fix that: what the project is, how it's built, how it looks, how I work. Here's the system, and how it bends per project type.
This post's shape: Lead 162 words, 01 319 words, 02 111 words, 03 319 words, 04 168 words, 05 50 words.
Every session with a coding agent starts cold. It doesn't know the folder convention, the state management decision you made three weeks ago, the component you already built that does most of this, or the pattern you explicitly rejected. So it guesses. Reasonably, fluently, and wrong in ways that take longer to unpick than to have written yourself.
The instinct is to fix this in the prompt. That works once. By the fourth session you're re-typing the same six paragraphs of preamble, and the parts you forget to type are the parts that come back as re-work.
The fix is boring: put the context in the repo, version it with the code, and point the agent at it. Six files, each answering a different question, each changing at a different rate.
A side effect I didn't expect at first: the files are at least as useful to me as they are to the agent. Me in two months - also starting cold.
The six files
project-overview.md - what this is, who it's for, what it deliberately does not do. Scope boundaries and non-goals. This is the file that answers "should this feature exist at all," and it's the one that stops an agent from helpfully building you an admin panel nobody asked for. Changes almost never. If it changes, the project changed.
architecture.md - folder structure, data flow, module boundaries, and the decisions behind them. Not just what the structure is, but why, because "why" is what prevents a second, parallel way of doing the same thing appearing in week three. This is the highest-leverage file in the set. Most agent output that technically works but is architecturally wrong traces back to this file being thin.
ui-context.md - design tokens, type scale, spacing, the component inventory, layout and motion conventions. The interface truth. Without it you get a new button component per feature and six slightly different shades of the same grey.
code-standards.md - naming, typing, file structure, error handling, imports, what's banned outright. This is the file that keeps diffs reviewable. It's less about correctness and more about making generated code look like it came from the same hand as the rest of the repo.
ai-workflow-rules.md - how the agent is expected to behave. Plan before editing. No unrequested refactors. Stop and ask when a contract is ambiguous rather than inventing one. Update the tracker when a unit of work lands. I write these as outcomes rather than instructions, because instructions get followed literally and outcomes get followed sensibly.
progress-tracker.md - what's done, what's in flight, what's next, known issues, decisions deferred. The fastest-changing file in the set and the entire point of the system for multi-session work. It's the handoff note between sessions.
An entry point file (AGENTS.md, or CLAUDE.md depending on the tool) ties them together and tells the agent which to read for which kind of task.
Don't build on one vendor's syntax
The entry point originally used Claude Code's native @import syntax to pull the six files in. Clean, and it worked well. It also stopped working the moment the system had to run on free-tier agents that don't honour @import at all — they'd read the entry point, ignore the imports, and proceed confidently on nothing.
Now the entry point uses direct markdown references. Slightly less elegant, works everywhere. The general rule I took from it:
A context system that only runs on one tool isn't a system, it's a configuration.
Test it against the least capable agent you expect to use, not the best one.
Adapting it per project
The six files are a starting shape, not a template to fill in dutifully. Three questions decide how it bends:
Does it have a real interface? Does it have real architecture? Am I inheriting it or starting it?
Marketing and brand sites. ui-context.md becomes the heaviest file in the repo: section inventory, motion specs, easing and duration conventions, the type scale. architecture.md shrinks to routing and where content comes from. code-standards.md is mostly rules for extracting sections into components and typing repeated content as data arrays rather than copy-pasted JSX.
Headless CMS builds and replatforms. architecture.md absorbs the content model: collections, fields, relationships, and the mapping from the old system to the new one. Add an explicit source-of-truth rule, because in a migration the single most expensive mistake is two systems both believing they own a field. progress-tracker.md tracks by collection rather than by feature.
Backend and infrastructure work with no UI. ui-context.md either disappears or gets replaced by an interface contract file: request and response shapes, error codes, timeouts, retry behaviour. architecture.md grows to cover deployment topology and failure modes, which matter more here than folder structure does.
Internal tools and dashboards. project-overview.md carries user roles and permissions, because that's the thing agents guess at most confidently and most wrongly. code-standards.md carries data-fetching and state rules, since that's where dashboards rot.
Long-lived personal repos. progress-tracker.md quietly becomes a decision log. Its job shifts from "where was I" to "why did I do it that way."
Team projects. The six files stay at repo level as shared truth, and each component gets a thin overlay that references them rather than restating them. Components that touch several others get the full treatment; near-isolated ones that just deliver something get a lightweight version with interface alignment only. Restating shared context per component is how you end up with six versions of the standards, five of them stale.
What it costs, and where it fails
Files rot. The tracker rots first and lies most convincingly, because a stale tracker reads exactly like a current one. Updating it has to be part of the definition of done or it decays into fiction within a week.
More context isn't strictly better. Agents pattern-match hard on whatever you wrote at length, so a bloated code-standards.md full of rules you don't actually enforce will pull output toward the rules you cared least about. Cut anything you wouldn't reject a PR over.
And the system doesn't rescue a vague spec. It makes a well-understood project faster to build; it does nothing for a project you haven't thought through. Context is not a substitute for knowing what you're building.
There's also a floor. For a one-off script or a two-day landing page, six files is ceremony. A single AGENTS.md is enough. The system starts paying for itself somewhere around "this will take more than three sessions" or "someone else will touch this."
The part I didn't expect
Writing the six files forces decisions you'd otherwise defer. You can't write architecture.md without deciding on boundaries. You can't write project-overview.md without naming what you're not building. The agent is the reason I started doing it. The clarity is the reason I kept doing it.