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.