The context system that stops Claude from drifting

Work with an agent for more than a few days and you hit the same wall: it forgets every decision you made, and one new feature breaks three others. I kept fixing that same pain over and over, until I noticed the fix was already sitting in my repo, half-built by accident. Here's the real version, from my own projects, and the two files I was missing.

Why it drifts

An agent has no memory between sessions. Every new chat starts from zero. You explain the project, it makes reasonable calls, it moves. Tomorrow you open another chat and it remembers none of it: not the stack, not why you picked that library, not what shouldn't be touched. So you explain again, it guesses again, and bit by bit the code starts contradicting itself. The AI isn't dumb. You're asking it to remember something you never saved anywhere.

The idea: files that travel with the repo

The fix isn't a longer prompt. It's a set of files the agent reads before doing anything, and that live in the repo forever. Another day, another agent, another teammate: everyone starts from the same context. Here's roughly mine:

my-project/
├── CLAUDE.md                  # what the project is and what it is NOT
├── .claude/
│   ├── agent-trust-policy.md  # rules: what the agent must never do
│   └── settings.json          # hooks that block dangerous commands
├── design.md                  # design tokens (colors, type)
├── code-standards.md          # code conventions (the one I was missing)
└── docs/
    ├── architecture.md        # stack, boundaries, invariants
    └── specs/
        └── 01-login.md        # one unit at a time

• CLAUDE.md — what the product is, who it's for, and what's deliberately out of scope. The first thing the agent reads.
• agent-trust-policy.md — the behavior rules: what the agent must never do (delete outside its lane, touch secrets, push to main without a PR).
• design.md — the design tokens, so it doesn't invent colors or fonts.
• architecture.md — the stack, the boundaries between layers, and the invariants the code never breaks.
• docs/specs/ — one spec per unit of work. The piece that actually changes things.

The loop: one unit at a time

Here's the mindset shift. You don't tell the agent "build the dashboard." You write a small spec, with a goal, the decisions, what not to touch, and a checklist of what has to be true to call it done:

# Spec: email login

## Goal
A user can sign up and log in with email. Nothing else.

## Decisions
- Auth with Clerk (already installed).
- Don't touch the navbar or the sidebar.

## Implementation
- Create /login and /signup with Clerk components.
- Protect every route except /login and /signup.

## Checklist (verify before closing)
- [ ] Routes protected by default
- [ ] No hardcoded colors (use design.md tokens)
- [ ] npm run build passes

Then you hand it the spec in one prompt. The agent reads the context, reads the spec, and builds against a system instead of guessing:

Read CLAUDE.md, code-standards.md, design.md and docs/specs/01-login.md.
Mark spec 01 as "in progress" in the progress tracker.
Implement it exactly as written, nothing beyond scope.

You review the result against the checklist. If it passes, close the unit and push. If something's off, you write one concrete corrective prompt, fix that one thing, and move on. One clean unit at a time, instead of an agent running loose for an hour and leaving you a pile to untangle.

The file most people skip: the state

This is the one that does the most work and the one people forget. A state file that updates every step, and rebuilds the whole context in a single prompt when you come back tomorrow, next week, or in six months:

# Project state

**Current phase:** auth
**In progress:** email login (spec 01)
**Done:** base layout, dark theme
**Decisions:** Clerk for auth; Postgres for metadata only
**Next:** user dashboard

This is exactly what fixes the no-memory problem. The agent reads it, understands where the project is, and picks up right where you left off. You don't have to re-explain yourself.

The two files I was missing

I already had half of this before the video: the agent rules, the project context, the state. What the video showed me were two gaps.

The first, code-standards.md. Without it, the pattern the agent uses in function 16 doesn't match function 5. Four lines save weeks of drift:

# Code standards

- TypeScript strict. No `any`.
- `use client` only when the component needs interactivity.
- No raw Tailwind color classes: use the tokens.
- One component per file. Names in English.

The second, splitting the invariants out into architecture.md: the rules the system never violates. Things like "request handlers don't run long AI work, that goes in background tasks" or "authorization is checked at every mutation." The agent treats them as boundaries, not suggestions.

When it matters (and when it's overkill)

For a one-file fix, this is overkill: open the chat and do it. But for something you'll maintain for weeks, with an agent coming and going, it's the difference between making progress and fighting your own code in week three. Writing these files is real work, and that's why people skip it to feel productive now. The time you save skipping it is the same time you lose later, debugging output that stopped making sense.

What's really happening

The system isn't a product or a magic prompt. It's that the thinking stays with you, and the agent gets a written contract instead of guessing. The files are cheap. The clarity is the expensive part, and it's the part AI still doesn't do for you.

Now try this

On your next project, before you ask the agent for anything:

• Write a CLAUDE.md. Three sentences of what it is, and a list of what it's NOT.
• Write a spec for the first feature, with its checklist.
• Create a state file and have the agent update it every step.
• Add code-standards.md the moment the agent invents its second different pattern.