This module installs the habit that turns a repository into context you can trust: interrogating unfamiliar code with a read-only agent under a citation rule, and shaping the repo itself — instruction files, feedback loops, grounded docs — so every future prompt from every teammate starts from a better position.
Sana has owned orders-api for two years. Now she inherits billing-service — forty thousand lines she has never read, and a change due Friday.
Her old move is to open the files and start reading. Instead she points a read-only agent at the repo and asks it to map the request path.
A fluent tour: entry points, the main flow, and the line "proration logic lives in billing/proration.py, in apply_discount, called from the invoice worker." It reads authoritatively.
She opens billing/proration.py. There is no apply_discount. The discount math is inlined in build_invoice, three files away.
The agent had narrated a plausible architecture instead of the real one, and every downstream claim resting on that phantom function was now suspect.
She runs the pass again with a tighter scope and one hard rule: a file path and a symbol per claim, or it does not count.
She opens two cited files at random; both hold up. The agent had, in fact, mapped the real skeleton in a fraction of the time reading would have taken.
The value was only bankable once she spot-checked it.
The Common Core taught context engineering as a prompting discipline: what you put in the window determines what comes out. This module applies it at the scale where backend engineers actually live — a repository.
Two facts set the agenda. First, "explaining unfamiliar code" is a top-rated AI strength in the 2025 Stack Overflow survey, and understanding code before changing it is the daily reality of every services engineer who inherits a new client codebase every 6–18 months. Second, coding agents now read your repo as part of their prompt: a CLAUDE.md, an AGENTS.md, a copilot-instructions.md, your linter config, and your test suite are all context that every agent run consumes — which means they are all surfaces you can engineer.
The engineers getting compounding returns from AI are not writing better one-off prompts; they are shaping repositories so that every prompt, from every teammate, starts from a better position. That is codebase context engineering: exploration (getting accurate context out of a repo), instruction files (putting durable context in), repo ergonomics (making the environment itself a feedback loop), grounded onboarding docs, and the hazards — context rot and training cutoffs — that silently corrupt all of it.
A coding agent's effective prompt is your instruction files + your repo's structure + whatever it can discover with its tools. You control all three. Engineering them once improves every AI interaction anyone has with that repo afterward — it is the highest-leverage AI work a senior engineer does.
The single safest, highest-value agentic workflow is also the least practiced: point an agent at an unfamiliar codebase with no write access and interrogate it. Nothing can break. Hallucinations are cheap to catch because the ground truth is sitting in your editor. And the payoff lands exactly where the job hurts: ramping onto a legacy service before a change, inheriting a client codebase, or answering "what would break if we touched this?"
The tooling is interchangeable — the protocol is not. In Claude Code, plan mode (read-only by design) or a plain session where you simply don't approve edits; in Copilot, Chat with the workspace/agent context in ask mode; in Cursor, chat with codebase context enabled. On a $0 path, Copilot Free's chat allowance handles exploration sessions, and Gemini Code Assist or Continue.dev (open-source, bring-your-own-key) are workable alternates.
Unstructured "explain this codebase" prompts produce plausible tour-guide prose. Structured interrogation produces a mental model. Run these passes in order against a service you need to understand:
Pass 1 — Skeleton (breadth):
"Map this repo: entry points (servers, CLIs, cron/queue consumers),
the request path from entry to persistence for the main flow,
external dependencies (DBs, queues, third-party APIs), and where
configuration comes from. Cite file paths for every claim."
Pass 2 — Load-bearing walls (depth):
"Trace what happens when <core operation, e.g. 'an order is placed'>
end to end. List every side effect: writes, events emitted, caches
touched, emails/webhooks fired. Cite the exact functions."
Pass 3 — Danger list (judgment):
"What in this codebase would you least want to modify without tests?
Look for: shared mutable state, implicit ordering dependencies,
duplicated business logic, catch-and-ignore error handling,
concurrency. Rank by risk and cite evidence."
Two rules make this trustworthy:
Comprehension you haven't tested is comprehension you don't have. Close the loop by inverting the roles: after your passes, have the agent quiz you ("ask me five questions about this codebase that I can only answer correctly if I understood the request path and the danger list; then grade my answers against the code"). Wrong answers send you back into the repo — which is the point. The output artifact of an exploration session is a short architecture brief: skeleton, core-flow trace, danger list, open questions. Written down, it becomes reviewable by a teammate who knows the system — the cheapest possible verification — and it becomes the seed for the onboarding docs later in this module.
Exploration sessions are where long context earns its keep, but don't dump the repo into the window and hope. Agentic exploration — the agent greps, opens files, follows imports — consistently beats bulk-pasting source, because the agent retrieves what the question needs instead of drowning in what it doesn't.
The failure mode of AI-assisted comprehension is fluent wrongness about code the model skimmed. Symptoms: architecture claims without file citations, descriptions of "typical" patterns your repo doesn't actually use, and confident summaries of files the agent never opened — Sana's phantom apply_discount was all three at once. The citation rule exists because these failures are invisible without it.
Your first 15 minutes in any unfamiliar repo: run one exploration pass that demands a file path and a symbol per claim, then open two cited files at random — if either citation doesn't support its claim, you've caught the agent narrating instead of reading, and every later answer stays suspect until you tighten the scope.
Every serious coding tool now reads a persistent instruction file from the repo: Claude Code reads CLAUDE.md, the cross-tool AGENTS.md convention is honored by a growing set of agents, GitHub Copilot reads .github/copilot-instructions.md (plus scoped *.instructions.md files, which as of GitHub's July 2026 changelog also condition Copilot code review), and Cursor has its rules directory. Same idea everywhere: a prompt fragment prepended to every session, versioned in git, shared by the whole team. This is the highest-leverage file-to-effort ratio in your repo — and most teams write it badly.
The file is paid for out of the context window on every run, so every line must earn rent. Three categories earn it:
Result type, never raise across service boundaries," "all timestamps UTC, stored as timestamptz," "never edit src/generated/ — regenerate via make codegen."pytest -x -q tests/unit will run it; agents that don't will guess or skip verification.What stays out: anything the agent can discover faster than you can maintain it (full directory listings — they rot), anything generic ("write clean code" — burns tokens, changes nothing), and long style essays that a formatter already enforces mechanically.
A production-shaped CLAUDE.md / AGENTS.md for a Python service — note that nearly every line is a correction of observed agent behavior, not aspiration:
# payments-service — agent instructions
## Commands
- Test: `pytest -x -q` (unit only; integration needs Docker: `make test-int`)
- Lint + types: `ruff check . && mypy src/` — must be clean before done
- Never run `make deploy` or anything under `scripts/prod/`
## Conventions
- Errors: return `Result[T, PaymentError]` from service functions;
raising across module boundaries is a review-blocker
- Money is `Decimal` end to end. Introducing `float` for currency
is always wrong here.
- DB access only through `src/payments/repo/`. No ORM calls in handlers.
- New endpoints: copy the pattern in `src/payments/api/refunds.py`
## Boundaries
- Do not modify files in `migrations/` — propose migration SQL in the
plan instead and wait for approval
- `src/generated/` is codegen output; change the proto, run `make codegen`
- Tests that hit the network are forbidden; use fixtures in `tests/fakes/`
The same content works almost verbatim as .github/copilot-instructions.md; for Copilot's scoped variant, split path-specific rules into e.g. .github/instructions/api.instructions.md with an applyTo glob so the API conventions only load when API files are in play — scoped loading is the built-in defense against the context-rot problem covered below.
An instruction file is a claim ("this changes agent behavior") and claims get tested. The method is a before/after trial: pick three tasks the agent historically fumbles in your repo (e.g., "add an endpoint" — does it copy your conventions or invent its own?). Run each task in a fresh session without the file, save the diffs. Add the file, fresh sessions, same tasks, save the diffs. Count convention violations in each. If a rule is still being violated, the rule is too vague — "follow our error-handling style" fails where "return Result, never raise across boundaries, see refunds.py" succeeds. If removing a rule changes nothing, delete it: it was paying rent for nothing. Treat the file like code — reviewed in PRs, updated when a convention changes, pruned quarterly.
Instruction files are corrections, not documentation. The authoring loop is: watch an agent make a mistake in your repo → write the one line that would have prevented it → verify the line prevents it → commit. Files written that way stay short, true, and effective; files written as aspirational essays are ignored by agents and humans alike.
Instruction files tell agents what to do; the repo's ergonomics determine whether they can verify they did it. An agent's edit-run-fix loop is only as good as the feedback signals the repo emits — which is why the practitioner guidance (Simon Willison's coding-agent setup notes, October 2025) and DORA 2025's finding that quality internal platforms amplify AI gains converge on the same checklist. The properties that matter:
ruff/ESLint and mypy/tsc convert whole classes of AI mistakes — hallucinated attributes, wrong argument types, unused imports — into immediate, machine-readable errors the agent fixes itself before you ever see the diff. Typed interfaces are the single cheapest upgrade: every type annotation is a constraint the agent must satisfy rather than a convention it must remember.make test, make lint, make run — or the package.json/justfile equivalent. Every step that requires tribal knowledge ("oh, you need to source that env file first") is a step where the agent stalls or guesses.The compounding observation: every one of these makes human onboarding better too. Agent-friendliness is not a new discipline — it is engineering hygiene with a second constituency that, unlike your teammates, will actually run the linter every single time. Budget note for restricted or $0 environments: everything in this list is free and open source; agent-friendliness requires no AI spend at all.
When an agent repeatedly fails in your repo, the instinct is to blame the model; the professional move is to ask what signal the repo failed to emit. No type on the function it misused? No test covering the behavior it broke? No instruction line naming the convention it violated? Fix the repo and the failure class disappears for every future run — and usually for every future human, too.
For services companies especially — new client codebase every engagement, ramp-up time directly billable — the exploration protocol has a productizable output: a codebase tour for newcomers. The prompt shape, run by an agent with repo access:
Produce an onboarding tour for a senior engineer new to this repo:
1. Read this first: the 5 files that explain the system, in order,
with one sentence on why each matters
2. The life of a request: our main flow, file-by-file
3. How to run it: exact setup and verification commands (verify these
yourself by checking they exist in the repo's config/scripts)
4. Gotchas: non-obvious conventions, historical wrinkles, danger areas
(use evidence: TODO/HACK comments, suspicious complexity, files with
heavy churn)
Cite file paths for every claim. If unsure, say UNSURE — do not guess.
Two disciplines separate a useful tour from a liability:
The same generate-verify-diff pattern extends to architecture diagrams (Mermaid from actual code) and runbooks later in this track.
Two failure modes corrupt everything above, and both are invisible until you know to look.
Long agent sessions degrade. As the window fills — with earlier exploration, failed attempts, tool output, and dead ends — models attend less reliably to any given fact in it; your instruction file's rules and the actual task competes with pages of stale history. Symptoms: the agent re-reads files it already read, contradicts its own earlier findings, "forgets" a constraint from the instruction file it honored an hour ago, or drifts back to an approach you explicitly rejected. Defenses:
CLAUDE.md/copilot-instructions.md is context rot you committed to git — it degrades every session, forever, until pruned. Scoped instruction files (*.instructions.md with path globs, per-directory AGENTS.md/CLAUDE.md in larger monorepos) load rules only where they apply.Every model's knowledge of your dependencies froze at its training cutoff — and it will not volunteer this. Ask for code against a fast-moving library (LLM SDKs are themselves the worst offenders, alongside frontend frameworks and anything pre-1.0) and you'll get fluent code for a version that may be two majors stale: renamed parameters, deprecated auth patterns, removed methods — all rendered with total confidence. This is the Common Core's stale knowledge failure mode with a compiler-shaped blast radius. Defenses:
validator patterns").mypy/tsc and a fast test run catch stale-API code at generation time, converting a silent hazard into a red squiggle the agent fixes itself.Context rot and training cutoff produce the same surface symptom — an agent confidently doing the wrong thing — with opposite fixes. Rot: the context window is degraded → fresh session, externalized state. Cutoff: the model's knowledge is stale → supply current docs and versions. Diagnose before treating: restarting a session cannot fix a model that has never seen Pydantic v2.
Check yourself: An agent hands you a confident architecture summary of a service you don't know, with no file paths cited. Why is that summary a liability rather than a head start, and what single rule converts it into something you can trust?
CLAUDE.md/AGENTS.md or copilot-instructions.md for a repo you own, using only the corrections-not-documentation method: at least five rules, each traceable to a real agent mistake. Run the before/after trial on three tasks and record convention violations in each condition. Delete any rule the trial shows to be inert.This module's companion playbooks cover legacy-codebase comprehension and architecture-brief production, instruction-file authoring and maintenance for the major agent tools, the agent-friendly repo checklist, and onboarding-tour generation with drift protection. Do this at work this week → pb-01 Map an Unfamiliar Codebase Before You Change It (Sana's read-only exploration protocol, productized), pb-04 Instruction Files That Make Generated Code Match Your Conventions (the corrections-not-documentation CLAUDE.md/AGENTS.md method), and pb-09 Make Your Codebase Agent-Friendly (the five ergonomic properties as a scored audit). Its labs include the legacy comprehension sprint on a provided unfamiliar service (brief + danger list, quiz-graded), the instruction-file authoring lab with measurable before/after behavior change, and the repo agent-readiness lab.