The Repo Is the Only Thing Your Agent Can See
Understand how an AI coding agent interacts with a repository as its primary information source and why repository design is critical for agent reliability. Learn to identify and fix common failure types like unreachable code or conflicting documentation, ensuring new agent sessions recover essential project knowledge independently.
The next morning, Wrenfold replayed the failure: a fresh agent session at 09:06, the same ticket, CLIN-482, add recurring appointments for six weeks.
The agent searched for appointments, found src/routes/appointments.ts, and wrote the endpoint there. It also wrote a new overlap helper beside the route. Ninety minutes later, a developer reviewing the change asked one question: why did it ignore src/availability/index.ts?
The agent had no answer. The module already exposed overlaps() and isSlotFree(), and had been in the repository for eighteen months. The ticket said “appointments,” the route said “appointments,” and the module the agent needed said “availability.” Nothing connected those names.
The code was present. It was still functionally invisible.
Didn’t the right code already exist?
Existence is the weakest form of documentation.
The results of an agent do not absorb a repository when the session starts. It opens a few files, follows names and links, runs searches, and builds a working model from those actions. A file ten directories away may as well be absent if no path to it exists when the decision is made.
An agent sees more than the repository. It has a task prompt, tool output, and sometimes an issue tracker. But prompts expire, tool output scrolls away, and external access changes between environments. The repository is the one context the team and the agent can both inspect from the same commit.
That makes the repository the reliability side of the course’s distinction: model capability decides whether the agent can understand overlaps(), and repository design decides whether it finds the module before writing another one.
When does repository knowledge count?
Knowledge helps a fresh session only when three conditions hold.
Present: The fact exists in a file or executable artifact the session can access. Wrenfold’s overlap invariant cannot live only in a planning call or a developer’s memory.
Reachable: The session has ...