← Home

Repository Context Is a Dependency, Not a Prompt Attachment

Jul 18, 2026

“Give the agent the repository” sounds safe because it sounds complete. In practice it often means the agent receives stale generated files, unrelated local edits, duplicate instructions, and just enough information to make a plausible mistake.

Repository context is a dependency of a change. Like any dependency, it needs a declared version, a bounded surface, and a way to detect when it is no longer the thing the change was reviewed against.

Start with the contract, not the tree

For a small bug fix, the useful context usually includes:

That is more valuable than indiscriminately pasting every Markdown file, vendor lockfile, and build artifact into a prompt. Large, undifferentiated context does not make an agent careful. It makes conflicting signals easier to miss.

Git already offers a useful analogy. Sparse checkout lets a worker materialize only selected paths; submodules and worktrees make repository identity explicit. Agent tooling need not use those exact mechanisms, but it should preserve their lesson: scope is part of the environment, not a presentation preference.

Refresh after state changes

An agent that inspected main before another worker pushed has a stale baseline. An agent that read source before generation may be looking at a different truth than one that edits emitted files. The recovery is not “remember harder”; it is to re-read the narrow facts that affect the next mutation:

before edit:   current ref, status, target file ownership
before commit: staged diff, current parent
before push:   remote ref, expected ancestry

This is not an argument for turning every edit into a ceremony. It is an argument for placing fresh evidence at the boundaries where stale context causes irreversible mistakes.

References

Final take

Context is not a blob handed to an agent. It is a dependency graph that should be scoped before a change and refreshed before a consequential action.

Changelog