Why Coding Agents Fail on Real Repos (and What the Session Trace Shows)

The Short Answer

Coding agents fail on real repositories for three structural reasons: they burn their first minutes and a slice of their context window orienting in projects that answer nothing up front; the orientation itself pollutes the context they need for the actual task; and when they finally make a change, the repo gives them no reliable way to verify it. All three are properties of the repository, not the model — which is why the same agent that looks brilliant in a demo repo looks lost in yours.

This is measurable, not anecdotal. Below is what an actual session trace looks like in a repo with no agent configuration, and what each failure mode costs.

What Does an Agent Actually Do in an Unprepared Repo?

Here is the verbatim opening of a real coding-agent session in a small, popular, well-maintained open-source package — a repo with no AGENTS.md, no CLAUDE.md, no agent scaffolding at all. Before writing a single line, the agent issued thirteen orientation calls:

find . -maxdepth 2 | sort — map the layout.

find . -iname '*.yml' -o -iname '*.yaml' — hunt for CI config.

Read package.json, then .github/workflows/main.yml, then readme.md, then test.js, then index.js, then .npmrc.

cat .editorconfig, head license, git log --oneline, cat index.d.ts, ls -la .github, cat security.md, git log --all --oneline | wc -l.

Thirteen tool calls, every one of them answering a question the maintainer could have answered in a five-line AGENTS.md: how do I install, how do I test, what are the conventions, what should I not touch. Multiply that by every session, every agent, every contributor's agent — the repo charges this tax to everyone, forever, because the answers live nowhere a machine can read them first.

Why Does Orientation Hurt More Than the Time It Takes?

The deeper cost is context pollution. Anthropic's Claude Code guidance states it plainly: LLM performance degrades as the context window fills — as it approaches capacity, the model may start forgetting earlier instructions or making more mistakes. Every file the agent reads while orienting occupies context that the actual task needs.

So orientation is not a fixed startup fee; it degrades the quality of everything that follows. An agent that spent its early context reading your CI config and license file has less room for the code it is actually changing, the test output it needs to reason about, and the instructions you gave it. This is why the same task succeeds in a prepared repo and derails in an unprepared one: the prepared repo answers the orientation questions in one small file, and the agent spends its context on the work.

Why Can't the Agent Verify Its Own Changes?

The third failure mode appears at the end of the session. The agent has made a plausible change. Now: is it correct? In a repo without a runnable, trustworthy test command, the agent has three bad options — declare success unverified, write ad-hoc verification of dubious value, or ask a human, which defeats the point of autonomy.

The repo properties that make verification possible are mundane: a lockfile so the environment is the same one CI runs; one documented command that runs the tests; tests that assert behavior rather than snapshotting output; and CI on pull requests so an independent check confirms the result. Repos missing these do not make agents slightly worse — they convert every agent change into an unreviewed guess.

There is also a sharper edge here: in repos with committed credentials or unscoped ignore files, an autonomous agent does not just work badly, it works dangerously — reading secrets into context or editing generated files that will be overwritten. This is why readiness scanners treat a committed secret as an automatic cap rather than one finding among many.

Is This the Model's Fault or the Repo's?

The consistent pattern across scans: failure clusters around repository properties, not model choice. The same model exhibits both behaviors — competent in a repo that answers its questions, erratic in one that does not. Model upgrades raise the ceiling; the repo decides how much of the ceiling you get.

That is actually the optimistic conclusion, because repo properties are cheap to change. The thirteen-call orientation above collapses to reading one file. Context pollution drops when scoped ignores keep generated code out of reach. Verification exists the moment one test command works. None of these require touching application code — they are an afternoon of scaffolding, and they pay back on every agent session afterwards.

The way to find out where your repos stand is to measure: a scan produces the score, the per-section evidence, and the ordered fix list — including the trace of what an agent actually did while auditing your repo, so you can watch the orientation tax yourself.