Repo understanding & context for coding agents

The first three turns are great — the agent read your repo, used your helpers, matched your conventions. Then it decays on a predictable schedule. Turns 5-10: it stops reaching for your utils/format.ts and substitutes stdlib alternatives. Turns 10-20: it re-suggests config you already overrode ("try verbose: true" after you disabled verbose three turns ago). Turns 20-30: naming, error shape, and import order drift toward generic LLM defaults. Turn 30+: the replies are StackOverflow-grade advice that could apply to any project. This is context drift, and it has structure, so you can fight it.

Three mechanisms compound. Window pressure: long conversations push early messages to the back of the window where they get summarized aggressively or dropped — and project specifics ("we use the logger from lib/log.ts, not console") are exactly the load-bearing-but-unremarkable facts a summary discards. Retrieval staleness: an agent that can read files on demand tends to fetch for the first few turns, then stop re-reading even as the conversation drifts into code it never loaded. Distribution gravity: the model's training wants "normal" code, so without active reinforcement your project's weirdnesses erode back toward the mean.

The leading indicators are cheap to watch: a suggestion that reaches for console.log when you have a logger, re-introduction of an overridden setting, the agent asking "what's your file structure?" after it already read the repo, or the phrase "a common pattern is" with no project specifics. The fixes, in order of effort: re-pin the load-bearing facts in three sentences; force a re-read of the specific file before the next suggestion; branch a fresh, tightly-scoped session for a new subtask instead of continuing a saturated one; and run separate narrow sessions for separate concerns (API, frontend, tests) so none of them saturates. The tools that win aren't the ones with the biggest window — they're the ones that automate re-pinning so you don't have to remember to do it.

The instinct when an agent struggles is to paste in more context or reach for a bigger model. It usually backfires, and there are two separate reasons why.

First, more context is more stale, conflicting context. A large window makes it tempting to carry everything forward, but the session then holds dead branches, abandoned plans, old errors, and superseded assumptions mixed in with the current state. The agent has more to read and less signal about what still matters — one real report had MCP tool schemas alone consuming roughly a third of the window before any task even began. Another user found that dumping more context is precisely what caused the agent to start editing the wrong files. Scoped handoffs beat bigger dumps: the fix is to give the next step only what it needs, keep sources attached so you can verify them, and treat context as working material that expires, not a pile that only grows.

Second, when you do have to reduce context across a long session, how you compress it matters enormously. A normal model summary is fine for prose and dangerous for infrastructure: it turns a concrete file path into "the config file," a cache key into "the build cache," a failing command into "tests failed." Those shortcuts are fine in a human status update and catastrophic as input to the next agent run. What you want is closer to deterministic context folding — reduce the surrounding material but keep the exact anchors stable: paths, ids, hashes, command names, file lists, and the verification commands that count as proof. The agent doesn't need every word from the last session; it needs the facts it must not improvise, in a form a human can still audit. If a compression step can't distinguish current facts from discarded ideas, it's just another unreviewed prompt blob — and the next run inherits its mistakes.

Here's the failure shape. You ask "where do we handle 401s?" The agent runs Grep "401|unauthorized" against the repo root, gets 38 hits across legacy/, archived/, tests/, node_modules, three vendored SDK copies and a .next/ cache, reads the top 12 by filename heuristic, and answers from the most recent file it loaded — often the deprecated middleware under legacy/auth/, because dead code tends to be verbose and matches more search terms. It read 47 files and burned ~80,000 input tokens to get the wrong answer. The model didn't hallucinate; it faithfully read irrelevant evidence. Search-scope is the first knob, upstream of every context-window technique — chunking and handoff summaries are just backstops for the case where the search was too wide.

Four tactics, in order of leverage. 1. A real .cursorignore / .claudeignore / .aiignore with .gitignore syntax: exclude node_modules, dist, .next, **/__generated__/**, **/*.generated.*, vendor/, and — the biggest wins — legacy/, archived/, deprecated/, plus lockfiles. The legacy and archived blocks alone tend to halve token spend; generated code matches every search term and never holds the answer; lockfiles have the worst token-per-irrelevance ratio in the repo. Commit it as load-bearing infrastructure. 2. Hand the agent a file list when you already know the files: "Read src/middleware/auth.ts and src/routes/api.ts... If you need a file outside this list, stop and ask. Do not search." That last sentence turns searching into a permission boundary. 3. Scope the tool grants — Claude Code, Cursor, and Codex all support per-tool allow/deny; the deny rules are the load-bearing half (Bash(grep:.) blocks unscoped repo-wide greps, Read(node_modules/**) stops the agent chasing imports into transitive deps). A tool grant survives a forgetful agent in a way a prompt doesn't. 4. Search-only sub-agents: when a search is genuinely needed, spin a child agent whose only job is to return matching paths (no contents); the parent reads the short list and never sees the 38 noisy hits.

Diagnostic you can run today: the read-to-cite ratio — how many files the agent read during a query versus how many appear by name in its answer. At or below 2:1 is healthy; above 5:1 the search was too wide; above 10:1, treat the answer as untrustworthy no matter how confident it sounds. And no, RAG doesn't fix this — it just moves the over-fetch into the embedding step where it's harder to see. If you wouldn't let the agent grep node_modules, don't let it embed node_modules either.

Real teams don't standardize on one AI surface. One developer explains the folder layout to Claude Code, another pastes the same files into Cursor, a third asks Codex to inspect the same failing path. Everyone is using an agent, but the team is still moving context by hand — and copy-paste is the worst version of it, because the moment a file excerpt lands in a chat it's stripped from its source. The agent can't tell whether it's current, which repo it came from, or why you selected it.

What's missing is a context bridge: a small, inspectable path between the project and the agent that carries files, commands, decisions, and constraints without turning the whole repo into one oversized prompt. A useful bridge keeps five things attached to the task instead of trapped in a transcript: project facts (root, package manager, framework, scripts, constraints) that shouldn't be rediscovered every run; paths with intent (is this the bug source, an example, a test, a config, or a boundary to avoid?); recent commands (the last failing test, build command, or server log usually matters most); decisions (if the team rejected a design or chose a library, the next agent should inherit that, not reopen it); and open questions, so the model asks for judgment instead of inventing certainty.

The deeper requirement is that context has to be searchable, not just present. Giving an agent file access isn't the same as giving it useful workspace context — a large repo is full of old experiments, generated files, fixtures, migrations, and stale docs that look related but aren't. Without a way to scope and expose context deliberately, the agent spends budget rediscovering what you already know, and every tool switch pays the cost again. The stable asset across model changes, quota changes, and tool switches isn't a perfect prompt; it's the control surface around the run — what the agent saw, what it did, what it changed, and what a human approved — carried with the task instead of reconstructed after the fact.

The pattern shows up constantly on the forums: one developer loses context and active working state across Claude Code projects; another builds local project memory by hand because the agent keeps forgetting prior investigations; a third is trying to make components retrievable by agents and asking what metadata or schema would let that happen. The common thread is that a chat transcript is not project memory. When the session ends, the next one sees files, not the path that produced them — so it re-derives decisions, re-runs investigations, and sometimes redoes work another agent already finished.

The fix is to move project-specific facts out of session memory and into something durable the agent re-reads: shared memory the whole workspace can see, plus explicit records of what was decided and verified. This matters most the moment agent work becomes parallel. When several agents touch the same repo, context fragmentation becomes a real risk — one agent solves a problem another already handled, another edits a file without knowing it's been claimed, a third follows the plan superficially and skips the helper tests that would have proven the change. Coordination needs four things that a transcript can't provide: shared memory, file ownership, explicit task boundaries, and a record of verification. These aren't luxuries for big teams; they become necessary as soon as work runs in parallel.

The most useful systems aren't the ones that generate the most code — they're the ones that leave the best trail: task intent, repo context, edits, tests, failures, retries, and final verification. That trail is what lets a developer resume work, review another agent, or explain a change three weeks later without reverse-engineering the last twenty prompts. Checkpoint the important decisions separately from the raw transcript, so the next run inherits the conclusion instead of re-reading the noise that led to it.

A well-tended CLAUDE.md (or AGENTS.md) is the closest thing we have to an immune system against context drift. Fifteen lines re-read every session — conventions, the helpers to use instead of reimplementing, and the gotchas — cost an hour to set up and pay back continuously. A decent skeleton is concrete, not aspirational:

# Project conventions
- Logger: `lib/log.ts`, never `console`
- Errors: throw `AppError` from `lib/errors.ts`
- Style: no semicolons, single quotes, 2-space indent

# Helpers (use these, don't reimplement)
- `formatDate(d)` in `lib/format.ts`
- `parseId(s)` in `lib/parse.ts`

# Gotchas
- The `db` client is a singleton; never construct a new one
- Session middleware runs before auth; don't read user before turn N

The problem is the second half of the lifecycle. Instruction files and execution policies start as helpful memory and quietly become stale infrastructure the agent obeys long after the codebase moved on. Libraries change, incident decisions get superseded, patterns evolve — and the agent still trusts the old rule. Auto-memory makes it worse by piling on duplicate files and vague indexes. A stale execution policy is especially dangerous because it grants or denies action: a rule that no longer applies can be as harmful as a missing permission prompt.

The answer isn't to delete instructions — it's to make them age visibly. Freshness needs provenance: for each rule, when was it created, which files or incidents justify it, has the related code changed since, and when did a human last confirm it? If the tool can't show whether a rule is still true, the agent shouldn't treat it as law. Keep the instruction files reviewable and dated rather than accumulating unaudited memory that the agent follows on faith.

Vibe coding is good at producing a first version: a feature appears, the demo works, momentum feels great. The hard part starts after it works, because maintainability needs a different artifact than generation. A generated first draft hides its own debt — tool choices, skipped edge cases, copied patterns, assumptions about the data model — none of it fatal in a prototype, all of it expensive the moment the next change depends on understanding why the first version looks that way. If that context dies with the chat, the project becomes hardest to change exactly when it starts to matter.

The real test isn't whether the agent made the demo work. It's whether another person can review the change, reproduce the setup, and continue the work without rebuilding the story from scratch. That requires preserving five things while they're still fresh: the original intent and constraints (what was the agent optimizing for?); the key decisions (which library, which schema change, which path it avoided, and why); the commands and their output (builds, tests, migrations, failures — part of the record, not terminal noise that scrolls away); a deliberately reviewed diff (accepting all changes because the demo works is how prototypes become unstable products); and an exported handoff — a compact Markdown or HTML record that beats a raw transcript as a starting point for the next developer.

This is also where developers keep asking for version and prior-change awareness: agents that know what changed in the last release, so a fix doesn't silently undo recent work or reopen a settled decision. Production work can't tolerate the loose context a prototype gets away with — when an agent touches architecture, security, billing, data models, or deployment paths, the handoff has to carry the boundaries, the migration state, and the verification commands that count as proof, not just the instructions. The mature move is to treat the working prototype as the start of the workflow, not the end: the point where output becomes reviewable evidence.

Visual browser editing gets described as a convenience — click an element, ask for a spacing change, watch the code update. The bigger idea is that the browser is a source of context. Source code tells you what should happen; the browser tells you what did. A React component can look correct in isolation while the rendered page fails because a parent container constrains width, a global style overrides it, loaded content is longer than the placeholder, an image arrives with a different aspect ratio, a sticky header changes the visible area, or mobile text wraps into a control sized for desktop. Those failures are hard to explain from code and obvious in the browser — which is why screenshots, DOM snapshots, console logs, and network requests have become normal parts of AI-assisted frontend work. If the tool can't see that runtime state, the developer has to translate it into prose, and that translation is lossy, slow, and repetitive.

A serious visual-editing loop needs four connected pieces: element selection (clicking a button or table row tells the tool the DOM node, computed styles, source component, route, and data state); code mapping (does the visible issue come from a component file, a design token, a utility class, a layout wrapper, or generated content?); live verification (after a patch, reload and compare the result against the requested state, with screenshots and console checks); and a reviewable code diff (visual editing should still produce normal, inspectable, testable code). A visual editor without code mapping is a paintbrush; code generation without browser verification is a hopeful guess.

This isn't only design polish. A checkout button that does nothing may need the DOM event handler, console error, failed network request, route params, and session state bundled together; a dashboard table that overflows on mobile needs the CSS grid, column defs, sample data, viewport width, and a screenshot. "Fix the table on mobile" isn't enough — the browser state is the missing context. And it changes the handoff: instead of "the left rail looked strange on my machine," a developer can hand over the viewport, selected element, computed styles, screenshot, console state, and the patch, so a teammate or second agent can reopen the exact situation. Guardrails still matter (prefer design tokens over hard-coded values, verify multiple viewports, keep generated code aligned with existing patterns) — the browser should provide evidence, not bypass the codebase.

The failure that makes this dangerous is that nothing crashes. A Godot developer upgraded to 4.7 and every agent they tried — Claude Code, Cursor, Copilot, Gemini CLI, Codex, OpenCode — kept quietly emitting older-version API calls: renamed nodes, moved signals, deprecated function signatures. The editor didn't error; the game just behaved wrong, and the bug looked like their logic instead of a stale assumption. They ended up building a separate tool (GodotPrompter) whose entire job was to feed the agent the current version's API so it would stop reaching for the old one. That's a workaround for a context gap every framework has.

The root cause: an agent's baseline knowledge of a library is frozen at whatever version dominated its training data, and it defaults to that version unless the session explicitly overrides it. Your package.json / requirements.txt / project.godot says React 19 or Godot 4.7; the model's instinct says React 17 or Godot 4.4. Reading your source doesn't reliably fix it, because your source is exactly where it copies the old patterns from if any of them are still lying around. And it fails silently — wrong-version code often compiles, so you discover it at runtime or in review, never at the moment of generation.

Make the installed version a load-bearing fact the agent re-reads, not something it infers. Concretely: (1) pin the exact versions and their breaking-change notes at the top of your instruction file — "Godot 4.7; get_node signature changed in 4.5; use await, not yield." (2) Point the agent at the installed docs, not the internet's median version — a link or local copy of the version you actually run. (3) Add a version assertion to the proof loop: before a change is accepted, have the agent state which version's API it used and why, so a wrong assumption surfaces in review instead of production (the broader verify-before-commit pattern lives in Guardrails & proof loops). Version is context; if you don't supply it explicitly, the model supplies a stale default.

The trend is a real signal about a real gap: developers are hand-building structured context — llms.txt manifests, .ai/ folders, context skills — because the raw chat and IDE experience loses the thread mid-session and starts guessing. Giving an agent a curated map of the repo genuinely beats letting it grep blindly and confidently invent an answer. So yes, it helps.

The problem is that a hand-maintained context file has two failure modes, and both are quiet. The first is drift: the file describes the code as it was three refactors ago, nobody updated it, and now the agent obeys stale rules with full confidence — which is worse than no file, because wrong-but-authoritative beats absent. The second is compaction: a long session summarizes your carefully written context down to a sentence, and the agent forgets the very thing you wrote the file to preserve.

So the win was never the file itself; it's keeping the context accurate and making sure it's actually loaded when it matters. Two implications follow. Prefer context derived from the real current state of the repo over a snapshot you have to remember to hand-edit — a description that reads the code can't drift the way a static file does. And keep what you told the agent recoverable across sessions, so a compaction event doesn't silently erase the project's ground rules. A context file is a good start; a context file nobody maintains is a trap with good intentions.

An agent with no design context defaults to the most average UI in its training: centered cards, default shadows, a palette nobody chose. The reason usually isn't the model — it's missing context. Your design system already encodes the right answers in tokens, a component library, a spacing scale, and the real rendered app, but the agent never sees any of it unless you make them first-class context it reads every time.

Two different kinds of context matter here, and people usually supply neither. The first is the source of truth: your theme, tokens, and component files in the repo, so generated code reaches for your Button and your spacing scale instead of hand-rolling new ones. The second is a visual reference: what the current app actually looks like, so the agent matches your interface rather than guessing at it. Pasting a single screenshot into a chat doesn't stick — it's gone next session.

The goal is to make the design system behave like constraints, not suggestions. When the agent can read your primitives as part of the project and see the rendered result, "build a settings page" produces something that looks like your product. When it can't, you get a demo that has to be re-skinned by hand — which is most of the time people spend cleaning up agent UI.

Most CLAUDE.md files are written on faith. You add a rule, the next session feels a bit better, and you conclude the rule worked — but you're reading tea leaves, because you changed one thing and the model's output varies run to run anyway. That's how instruction files bloat into hundreds of lines of cargo-culted advice, half of which the agent ignores and some of which actively costs you tokens by getting re-read every session for no benefit.

The only honest way to know is to run the same task twice: once with the rule, once without, on a repo state you can reset between runs. Then compare what actually happened, not how it felt. Did the agent follow the rule, or quietly skip it? Did the diff get smaller and more on-target, or just different? Did it burn more or fewer tokens getting there? You need a record of both runs side by side, because memory of "the good run" is exactly the thing that fools you.

Two disciplines make this work. Change one rule at a time — a batch of edits tells you nothing about which line mattered. And pick tasks representative of your real work, not toy prompts, since a rule that helps on a greenfield script may do nothing on a large existing codebase. Done this way, your instruction file stops being a wishlist and becomes a short set of rules you've actually seen change the output — which is also the version the agent is most likely to keep obeying.

A null result here usually means the experiment was pointed at the wrong thing. Deleting the rules file and then asking whether the model still reasons well measures the model, and the model didn't change. An instruction file was never a reasoning upgrade — it does not make an agent smarter about an algorithm or better at reading a stack trace. What it buys is constraint compliance: which logger to use, which helper already exists so it isn't reimplemented, which singleton not to construct, which directory is off limits. Those rules only show up in the output when the task actually touches them.

So the honest question is not "did the answers feel worse." It is: on work where a rule could bind, how often did the agent violate it, and what did that cost in rework? A self-contained bug fix gives your conventions nothing to constrain, so of course deleting them looks free. Run the same comparison on a change that spans four files and reaches for two of your internal helpers, and the difference stops being a vibe — it shows up as wrong-file edits, a larger diff, and the same review comment you already wrote last week.

The null result is still informative, just not as permission to delete. It usually means the file has drifted into material the agent has no occasion to apply: aspirational tone guidance, restated framework documentation, rules describing code that no longer exists. That content is not neutral. It is re-read every session, it competes for attention with the actual task, and stale rules keep getting obeyed long after they stopped being true — which is worse than no rule at all.

The useful response to "nothing changed" is to cut the file down to the handful of rules you have actually watched change an outcome, not to keep the whole thing on faith or bin it on one weak signal. A rules file should be short enough that every line has earned its place and specific enough that a violation is visible when it happens.

More than it looks, and for a reason that isn't convenience. Pasting is lossy in both directions: you lose the reference — which file, which lines, which revision — and you add tokens that duplicate what the agent could already read for itself. A selection reference is the opposite: small, exact, and resolvable. src/api/handler.ts#L30-L48 tells the agent where to look and lets it read the current content rather than your snapshot of it.

The three you're missing, in order of how much they matter:

• Terminal output selection. The most under-rated of the set. Error output, a failing test's tail, the actual result of a command — these are the concrete facts of the situation, and paraphrasing them in prose is where a surprising amount of debugging goes wrong. Sending the exact bytes is strictly better than characterising them.
• Editor selection as a reference, not a copy. Beyond token savings, this removes an entire class of error where you paste a version of the code that has already been edited since.
• Conversation export. Getting a reasoned exchange out as Markdown is how it becomes a durable artifact instead of dying with the session — which matters most for the exchanges that produced a decision.

The principle worth carrying regardless of which tool you land on: prefer references over content. Anything the agent can fetch itself, hand it a pointer; reserve pasted content for things it genuinely cannot reach. That reduces tokens and raises accuracy at the same time, which is unusual — most context decisions trade one against the other.

Be most sceptical of the metric they lead with. A tool can cut token use by retrieving less and still be worse, because the agent then edits the wrong files or misses a call site — and that cost lands in review, not on the invoice. Measure the outcome, not the input.

A comparison that produces a real answer:

• Build ground truth by hand, first. For each task, the complete set of files and lines that must change — and, critically, the trap sites: places that look like they need the change and don't. Without traps you can only measure recall, and a tool that returns everything scores perfectly on recall while being useless.
• Hold everything else constant. Same model, same spec, same repo state, isolated worktrees so runs can't contaminate each other. One variable: how the agent discovers code.
• Score recall, precision, and correctness separately. Finding the right files, avoiding the wrong ones, and producing a change that works are three different capabilities. Tools tend to be good at one and marketed on all three.
• Use several task shapes. A mechanical rename, tracing behaviour across layers, and finding a call site from a vague description stress completely different retrieval mechanics — a tool can win decisively on one and lose on another.
• Count index freshness as a cost. Indexing time is usually trivial. Staleness isn't: an index built before your last refactor confidently returns a structure that no longer exists, which is a failure mode plain search simply doesn't have.

Set up this way the honest result is usually "better on some task shapes, worse on others" — which is far more useful than a headline percentage, because it tells you when to reach for it.

Start by accepting that the code is not the problem. It runs. What is missing is a description of the system at a level a human can hold: what the pieces are, which way data flows, where the boundaries sit, and which parts will hurt when touched. Agents are good at producing that description and bad at being trusted with it, which shapes the whole exercise.

The map that actually helps is short and specific:

• Surfaces and entry points. Every route, job, webhook, and CLI that can start work. Anything not on this list is either unreachable code or a hole in the map, and both are worth knowing.
• Data flow for the two or three journeys that matter. Signup, checkout, whatever the product's spine is — traced from request to storage and back, naming the actual functions and tables.
• The data model as it exists, not as intended: the tables, the concepts they represent, and where one concept lives in more than one place.
• The trust boundary. Where authentication is decided, where authorisation is enforced, and every place that decision is trusted rather than made.
• Environment and secret inventory. Which variables exist, which are required, and which are silently defaulted. Inherited systems break here first.
• Blast radius. For each module: what breaks if it changes, and what test would notice.

Then the step that separates a map from a plausible story — verify it. Every claim gets a file path and a line, or a command that demonstrates it. An unverified architecture summary is precisely the artifact an agent is best at generating and worst at getting right, and a wrong map is more dangerous than no map, because you will act on it.

Do this once, keep it in the repo, and make the first job of any change updating the section that change invalidates.