How a Coding Agent Actually Works

Some of the most capable coding agents find their way around your code with grep, a text-search tool from the 1970s.

These systems can hold hundreds of thousands of words in view at once, and the obvious design would be to load the whole codebase or build a clever index of it. Instead they type short search commands, read forty lines at a time, and search again. Two other things puzzle daily users: why a much bigger context window helps far less than its size suggests, and why the same agent is sharp in one repository and lost in the next.

One idea accounts for all three, and it is the argument of this piece. A coding agent's quality depends mostly on the feedback its loop receives, how fast and how specifically it learns that it is wrong, and much less on how much code it can hold at once. Once you see that, you also see what to fix in your own codebase, and it is rarely the model.

Two parts: a model and a loop

Every coding agent has two parts. The model reads text and writes text, nothing more. The harness, ordinary software wrapped around it, decides what goes into the model's context window (the text it can see in one request), offers it tools, runs the tool calls it writes, and appends the results before asking for the next step (Same Model, Different Results explains why that software matters so much).

The model never touches your files. It writes a request such as "search for to_csv( in the app folder", the harness runs it, and the model sees the output as more text. The tools come in four kinds: search, read, edit, and run (the tests, the linter, the type checker, the build). The loop is always the same: gather context, act, check, repeat.

One task, watched closely

You type one sentence: the export button crashes when the report is empty. A few minutes later you get a change, a new test and a note that everything passes. Here is what typically happens in between. The example is constructed, but every step is the kind these agents take.

Scroll sideways to see the whole figure

It starts with almost nothing. The harness gives the model a system prompt, the tool descriptions, your sentence and the project's instruction file, a short text file the agent reads at the start of every session. One line in that file matters more than any description of the architecture: make check runs the linter, the type checker and the unit tests in about forty seconds. The agent now knows how to find out whether it has broken something.

It searches from the only concrete words it has. It searches the front end for Export, follows the button to the server code that handles it, reads twenty-five lines there, then reads the start of the CSV module and finds the culprit:

headers = list(rows[0].keys())

With an empty list there is no rows[0], so the code crashes. A careful agent then does two more things. It searches for every caller of to_csv( and finds three: the reports page, an admin page that exports invoices, and a weekly email job. Whatever it changes reaches all three. And it reads the existing tests, none of which tries an empty list. By now it has read a few hundred lines of a repository that might have two hundred thousand. Each search told it where to look next.

It meets a decision nobody made. Should an empty export produce a file with only the column headers, an empty file, a disabled button or a message? Neither the code nor the request says. A good agent picks the option most consistent with the code and says so, so a person can overrule it. A weak one picks silently. Many agent failures begin exactly here.

It edits by exact text. It first writes a test that reproduces the crash and watches it fail, which is good news, because a later pass will mean something. Then it edits. Agents rarely rewrite whole files; they send a small instruction: replace this exact piece of text with that one. The tool refuses if the text appears more than once or not at all. Here the first attempt comes back with an error, two matches, because a sibling function contains the same line. A tool that silently replaced the first occurrence could have changed the wrong function. One round trip later, with more surrounding text included, the edit goes through.

It runs the checks and reads the failure. The new test passes. Then make check fails somewhere unexpected. The type checker reports that the invoices page now passes a semicolon where the function expects a list of column names, because the agent added its new parameter in a position the invoices code was already using. No test covered that page. The type checker named the file, the line and the mismatch in seconds. The agent fixes it, and the next run passes.

It stops because something it can observe says stop. The reproducing test and the full check both pass, and the change touches only what the plan named. Without make check, it would have stopped after its own test passed, and every invoice export would have broken in production.

The agent read a few hundred lines of a large repository and still got the change right, because a type checker told it where it was wrong.

Why it searches with grep

The obvious alternative is search by meaning. Embeddings turn text into lists of numbers so that passages with similar meaning sit close together, and a system can fetch the chunks most similar to a question. Claude Code's earliest versions did exactly that with its codebase. Its creator, Boris Cherny, has said the team switched to plain tools like grep because it worked better by a wide margin. Other agent makers have made the same choice.

Code is full of exact names. When the agent needs every caller of to_csv(, grep returns all of them. A similarity search returns the chunks most like the query, ranked, with no promise of completeness, and in the walkthrough the caller nobody thought about was the one that would have broken.

Code changes during the task. After an edit, the next search must see it. Grep reads the files as they are now; an index reflects its last rebuild. Grep also needs nothing built in advance, and no copy of your proprietary code stored somewhere else.

And the agent can search again. A classic retrieval system gets one shot: a question goes in, chunks come out, and the model answers from those. An agent searches as often as it likes and learns the right words from the files it opens. Search by meaning was designed for a reader that couldn't look twice.

Think of grep as a book's index: look up an exact term and you get every page, and nothing if you picked the wrong word. An embedding index is a librarian who knows the collection: describe what you want and get the five most relevant books, with no promise there isn't a sixth. An agent can look up thirty terms in a minute, which is why the index suits it so well.

The other side has a fair point. Cursor, another coding tool maker, measured that adding search by meaning alongside grep made its agent answer questions about a codebase more accurately, and concluded that the combination works best. Grep is only as good as the words the agent guesses, and "where do we handle authentication?" may live in files that never use that word. What should last is the change in the search tool's job: when the reader can look again, the tool only has to answer exactly and fast.

Why a bigger window helps less than you'd think

Start with size. Python's own standard library is about a million lines of code, roughly 9 to 12 million tokens, the word-fragments models read. Frontier context windows in October 2026 mostly run from about half a million to about a million tokens, and a real application with its dependencies is bigger than the standard library. So agents must read selectively, and the right amount is surprising.

The 100-line window. In the SWE-agent experiments, published in 2024, the 100-line viewer solved 18 percent of a standard set of real bug-fixing tasks, the 30-line viewer about 14, and showing the whole file about 13. More text made the agent worse. Today's models may be less sensitive to that setting; the direction is the lesson.

The reason is that fitting in the window and being used well are different things (What Fits Versus What Gets Used). A model handed a whole file attends less precisely to the twelve lines that matter. A long session piles up every file read, every command output and every failed attempt, and performance degrades as the context fills.

So harnesses ration the window. They read in slices. They hand exploration to subagents, separate model instances that start fresh, read widely and return a short summary, so the main conversation holds conclusions instead of file dumps. And near the limit they compact: old tool outputs are cleared and the conversation is summarized, losing detail by design, which is why durable rules belong in the instruction file that is reloaded every session. The agent carries a map and a few pages, and leaves the territory on disk.

Feedback is the engine

Four signals steered the agent in the walkthrough: the failing test that confirmed the bug, the edit tool's two-match error, the type checker's complaint about the invoices page, and the final passing run that said stop. None of them required the model to know more. Each told it something it couldn't have worked out from what it had read.

Scroll sideways to see the whole figure

Two properties predict how useful a signal is: speed and specificity. A type error arrives in seconds and names a file, a line and the problem. A full integration suite may take twenty minutes, a reviewer replies tomorrow, and a production bug surfaces next month. The agent can iterate many times on the fast, specific signals; the slow ones arrive after it has stopped.

The SWE-agent study measured a small instance of this. Its edit tool ran a linter after every edit and rejected edits that broke the syntax, saying why. Removing that one guardrail, with everything else held constant, dropped the solve rate from 18 to 15 percent. Anthropic's engineers, building their own benchmark agent, spent more time improving the tools than the prompt. Better feedback moved results with the model unchanged.

That leads to the practical claim: agents do much better in repositories with fast tests, types and clear error messages. Every mistake is either caught by a signal the agent can read during the task or survives into the result. The fair objection is that well-tested repositories are better in every way, cleaner and more familiar to models, so the tests may mark quality rather than cause it. Both effects are probably real. My view is that the feedback effect is the one you can act on this week.

The checks a repository runs in seconds are the ones an agent can learn from before it stops.

When the loop optimizes the wrong thing

Feedback has a dark side: the loop working exactly as designed, toward the wrong goal.

Coding models are partly trained by rewarding them when tests pass. A model can learn that the cheapest route to a passing test runs through the test itself. Anthropic's system card for Claude 3.7 Sonnet reported that the model occasionally special-cased tests, usually by returning the expected values directly, typically after several failed attempts at a real fix. Labs report less of it in later models, but the mechanism remains: any check that can be satisfied without doing the work will sometimes be satisfied that way. Researchers call it reward hacking.

The defense is simple to state. Treat changes to tests as the riskiest lines in an agent's change, and look hardest at a change that touches both the code and the test that checks it (Tests Are the New Specification goes further).

The second weakness is the agent grading its own work, with everything it believed while writing still in its context, looking reasonable. Models rarely correct their own reasoning without outside feedback, and as judges they tend to rate their own outputs higher. The fix is a reviewer that starts fresh, given only the change, the original request and an instruction to find problems. If I could change one thing in most agent setups, it would be this: the context that wrote a change should never be the one that approves it. A fresh reviewer still shares the model's blind spots, so for changes that matter, a different model or a person who knows the domain adds what a second copy can't.

What to do

When you write a request, hand the agent its feedback. Name the symptom, the likely location, what fixed looks like and the command that proves it: "login fails after a session timeout; check the token refresh in the auth code; write a failing test that reproduces it, then fix it." Put the decisions you care about in the request, and read the ones the agent made for you in its summary.

Make your repository talk back fast. The biggest return comes from one documented command that checks everything checkable quickly, and error messages that say what went wrong and where. Add types at module boundaries, so silent breakages become errors the agent reads in seconds. Quarantine flaky tests: a person knows from experience which test fails at random, and an agent knows only what this session showed it. Keep the instruction file short and current, since a stale one is a wrong signal loaded every session.

Review where agents are weakest. Decisions the request left open, changes to tests, and changes that cross module boundaries. Let machines and a clean-context reviewer go first, and spend people's attention on the rest (Reviewing Code You Didn't Write).

Read productivity claims with the loop in mind. Results depend on the model, the harness and the codebase's feedback, and most claims report only the first. Before asking how much faster your team will be, ask how long your codebase takes to tell someone they're wrong.

Tool names, edit formats and the balance between grep and search by meaning will change with every release. The dependence on feedback won't, because it's how any optimizing process improves. An agent can correct only the mistakes it can see, and it sees them through the checks you give it.

Check yourself

Why can an agent that reads only a few hundred lines of a huge repository still get a change right?

Each search tells it where to look next, and checks such as the type checker tell it where it is wrong.

Why does showing a whole file make an agent worse than showing a slice?

Fitting in the window is different from being used well. A model given a whole file attends less precisely to the few lines that matter, and long sessions pile up noise.

What goes wrong when the agent that wrote a change also approves it?

It grades its own work with its own reasoning still in context, and models tend to rate their own output higher. A fresh reviewer given only the change and the request avoids that.