How coding agents read your code (and how to write for them) | Modem Blog<br>Loading...

Back arrowAll postsPart 1 of Writing Code for Agents: how agents navigate your repo by string search, and how to write code they can actually find, parse, and trust.

When we founded Modem in early 2025, we believed that AI coding was real, that it would rapidly accelerate software development, and that legacy product processes would become the new bottleneck for execution.

To commit to that future, we built Modem with AI codegen tools from day one - back when Sonnet 3.7 was the leading coding model. A year later, Modem is a real product with paying customers: 360,000 lines of TypeScript application code and another 320,000 lines of test code, 99.9% of it generated by LLMs.

Getting Modem to a functional codebase wasn't easy. It required experimentation, trial and error, and continuous investment to learn how to work effectively with agentic codegen. In this blog post series, Writing Code for Agents , we're going to share some of the tips we've learned along the way.

Part 1 - this post - covers how to write your code so that agents navigate, parse, and read it more effectively: the names you choose, the types you define, and where you put your explanations. The results aren't hypothetical; in our tests, following the tips in this guide led to fewer tokens and fewer agent turns spent performing code retrieval, a higher rate of bug detection , and fewer confidently wrong answers .

But to understand how that's possible, we need to first understand: how do agents even search code?

How agents search code (spoiler: it's text search)

Your coding agent frequently searches your repository for code. For example, want to rename a function? Claude Code, Codex, OpenCode, etc. will all search your code to find all the references to that function that might need updating.

em]:not-italic [&_a]:font-medium [&_a]:text-inherit [&_a]:underline">Claude Code session UI while the agent searches the repository.<br>What's happening is a lot simpler than you might think: Claude Code is just running grep (or rather, its faster cousin ripgrep, aka rg) to rip through your code and find matching text references. The agent reads what comes back, and if it isn't enough context, repeats scanning your code until it has what it needs.

$ rg -l 'formatDuration' --type ts<br>packages/common/src/duration.ts<br>packages/common/src/duration.test.ts<br>apps/dashboard/src/lib/utils/dates.ts<br>apps/slack/src/lib/rate-limit.ts<br>...<br>em]:not-italic [&_a]:font-medium [&_a]:text-inherit [&_a]:underline">Claude Code running Fable 5 looking for references of formatDuration in the Modem repo.<br>Grep isn't the only probe, but the other one is barely different: agents also search by filename, and that glob usually resolves to the very same ripgrep (rg --files), capped at the same 100 hits. So your file and directory names are search terms too, not just the symbols inside them — a session-broker/ directory is a hit ripgrep returns before the agent opens a single file.

There's no compiler feeding it a dependency graph, no language server resolving symbols (usually, more on this below). Boris Cherny, Claude Code's creator, has said they tried embeddings and a vector database early on and threw them out because plain text search worked better. The academic agents landed in the same place; SWE-agent got its results by giving the model purpose-built keyword search tools and nothing fancier.

task'fix duration formatting bug'

search$ rg formatDuration

read a window around the best hit

decideenough context? [y/n]<br>edit> start editing<br>Loop back to search with a better queryn · better query

em]:not-italic [&_a]:font-medium [&_a]:text-inherit [&_a]:underline">The agent navigation loop: search with rg, read a window around the best hit, loop back with a better query if needed, then start editing.<br>Even frontier models, given capable tools, often navigate with what is essentially grep. And notice that the loop has one of the most important inputs the code's author controls: whether the words in your code and the names on your files make good search terms.

What about language servers (LSPs)?<br>p]:my-0 [&>p+p]:mt-4 [&>table]:my-4 [&>table]:w-full [&>table]:border-collapse [&_th]:border-b [&_th]:border-gray-750/50 [&_th]:px-3 [&_th]:pb-2 [&_th]:text-left [&_th]:text-sm [&_th]:font-medium [&_th]:text-light-cream/90 [&_td]:whitespace-nowrap [&_td]:border-b [&_td]:border-gray-750/30 [&_td]:px-3 [&_td]:py-2 [&_td]:text-sm [&>ul]:my-0 [&>ul]:mt-4 [&>ul]:pl-5 [&>li]:text-base [&>li]:leading-relaxed [&>li+li]:mt-2 [&_a]:font-medium [&_a]:text-inherit [&_a]:underline [&_code]:text-teal">Editors solved code navigation with the Language Server Protocol years ago, and coding agents can use LSP servers to resolve code symbols (some natively and some via MCP). But that requires extra config everywhere you run your agents: an LSP server per language, on every machine and for every checkout. And even if you have...