PathruleEsta página está disponível apenas em inglês.
Why Not Just Let Your Coding Agent Grep?
Agentic search won the argument for code: Cursor turned down its embeddings index in July in favor of grep.
The question left is what a search can return when the thing your agent needs was never written down.
Resposta curta
For finding code, grep is the right default: Claude Code, Codex and now Cursor all lean on it. What grep cannot return is knowledge that was never written in the files: a decision against an approach, the reason behind a shape, a lesson from a failed command. That part has to reach the agent another way, before it edits.
O que este artigo aborda
- Cursor published research in November 2025 showing that semantic search raised answer accuracy by 12.5% on average over grep alone, then in July 2026 turned down its embeddings index in favor of grep-based retrieval; its docs now describe Instant Grep, built locally, and say Cursor stores no embeddings of the codebase for search.
- Grep returns the code as it is, which makes it exact and never stale, but it cannot return knowledge that was never written in the files: decisions against removed code, the reasons behind a shape, lessons from failed commands and preferences said in chat.
- In a codebase halfway through a migration, the old pattern often has more call sites than the new one, so an agent that learns conventions from search results tends to copy the majority.
- Claude Code's best-practices page draws the same line: CLAUDE.md is for context Claude cannot infer from code, such as architectural decisions and gotchas, and should leave out anything Claude can figure out by reading the code.
- In PathruleBench, a Claude Code arm with the full repository but nothing carried between sessions passed 16% of memory probes across the published runs, against 88% with CLAUDE.md files and 97% with Pathrule.
- Pathrule files decisions, rules and lessons at the path they apply to, and on Claude Code and Codex a hook hands them to the agent before it edits a file there, whether or not the agent searched for them.
Comparação
| What the agent needs to know | Example | Can a search find it? | Where it should live |
|---|---|---|---|
| Where something is defined and who calls it | chargeCustomer and its callers | Yes, exactly and never stale | Nowhere else: let the agent search |
| The current value of a setting | the request timeout in config | Yes | Nowhere else: a copy in a note will drift |
| Which of two patterns is the decision | four withRetry call sites, one backoff policy | It finds both, and the majority looks like the rule | A dated decision at the folder: which one, since when |
| A decision against something removed | the date library the team dropped | No: the code that used it is gone | A dated decision near the code it governs |
| The reason behind a shape | amounts are integer cents after a rounding bug | Only if someone left a comment | A comment beside the code, or a note at the folder |
| A lesson a command taught | the suite needs an environment variable to pass | Only if someone scripted it | A script or a check; otherwise a note the agent sees first |
| A preference said in chat | a one-line docstring on every new test | No: it was never in a file | Somewhere that outlives the session |
Before you write a line down, ask whether search can find it
- Can an agent find it by searching today's code: a function, a call site, a config value, an error string? Leave it out. A copy in a note will drift; the search result will not.
- Is it a decision against something no longer in the code? Write it down with the date and the reason, at the folder it governs.
- Is the code halfway through a migration? Say which pattern is the decision, so the majority in the search results does not win.
- Is it the reason behind a shape the code already has? A one-line comment beside the code if it fits; otherwise a note at that folder.
- Did a command teach it by failing? Turn it into a script or a check if you can; if not, write the lesson where the agent sees it before it runs that command.
- Can a machine check it? Make it a lint rule, a test or a CI step instead of a sentence.
- Is it a preference you keep repeating to the agent? Write it once where every session starts, not in the chat.
The search worked. The edit was still wrong.
You ask the agent to add retries to a call in services/billing. It searches the repository, finds four call sites wrapped in the old withRetry helper and one that uses the newer backoff policy, and writes a fifth withRetry. Every step was reasonable. The team decided in the spring to move off that helper, and the decision lives in a meeting note and a few people's heads, not in any file a search could match. The code outvoted the decision four to one.
When we described this kind of miss on Reddit, the sharpest reply was a question: why not just let the agent grep? Didn't Anthropic show that recent models do better searching for context themselves than working from a retrieval index? It is a fair question, and most of the honest answer is yes.
Search won for code, and the agents say so
Anthropic's engineering team describes Claude Code as a hybrid: CLAUDE.md files go into context up front, and tools like glob and grep let the agent find files just in time, when it needs them. The tools reference shows how literal that is. Claude Code's Grep tool is built on ripgrep, and on macOS, Linux and WSL Claude now searches with find and grep through its shell, which run embedded versions of bfs and ugrep.
Codex works the same way. Its base instructions tell the model to prefer rg and rg --files when it searches for text and files, because ripgrep is much faster than plain grep.
Cursor is the telling case, because it ran the experiment the other way. In November 2025 it published research showing that semantic search over an embeddings index raised the agent's answer accuracy by 12.5% on average, between 6.5% and 23.5% depending on the model, compared with grep alone. By July 2026 Cursor staff explained on its forum that models had become good enough at grep that the separate semantic path no longer helped in a meaningful way, and that embeddings indexing was being turned down. Its search docs now describe Instant Grep, which builds its index on your machine, and say Cursor does not store embeddings of your codebase for search.
So for finding code, let the agent grep. It is exact, it is cheap to keep current, and the agents people use most have settled on it. We made the case against vector retrieval for code in an earlier post. The question here is a different one: what can a search return when the thing the agent needs was never written into the files?
A search returns the code as it is
Grep answers one kind of question very well: what is in these files right now. Where a function is defined, who calls it, which key sets the timeout, what the error string looks like. Its answer is never stale, because it is read from disk at the moment of the search. A note about the code can drift out of date; a search result cannot.
That strength is also the limit. The files show the current shape of the code, including every place the team has not cleaned up yet. Halfway through a migration, the old pattern usually has more call sites than the new one, and an agent that learns conventions from search results learns the majority. Nothing in a list of matches marks four of them as the past and one as the decision.
Claude Code's own best-practices page draws the line in the same place. It describes CLAUDE.md as the home for context Claude can't infer from code alone. What to include: architectural decisions specific to your project, environment quirks, gotchas that are not self-evident. What to leave out starts with anything Claude can figure out by reading the code. Read the other way round, that table is a list of what grep can't reach.
Four kinds of knowledge that are not in the files
A decision against something. When the team removed a library, the code that used it went with it, so there is nothing left to match. The next agent that needs what the library did finds no trace of it and adds it back, or adds its closest cousin.
The reason behind a shape. The code says amounts are integers. It does not say they are cents because a float once rounded a refund wrong, or that every new money field must follow the same rule. An agent adding a field can see the pattern and still not know it is a rule rather than the habit of one file.
A lesson a command taught. The test suite that only passes with an environment variable set, the migration that must run before the seed. Someone learned it by watching a command fail. Unless they turned it into a script, it is in no file an agent would think to search.
A preference said in passing. Give every new test a one-line docstring; run the single test, not the whole suite. Said to the agent once, in a chat that ended with the session.
Some of this can move into the code, and should. A comment beside the integer amount, a commit message that says why the helper is going away: a comment sits next to what it explains and goes stale in plain sight. But a removed library leaves no line to comment on, and an agent does not run git log -S on every name before it types it.
A search needs a question first
Grep finds what it is asked for, and the agent asks when it suspects something is there. It looks up the function it is about to call. It does not look up whether the team ruled out the pattern it is about to write, because nothing tells it a ruling exists. A developer on r/ClaudeCode described the result: an agent with no instinct to look something up "will happily reinvent the wheel".
We measured how much of a team's knowledge comes back when the agent has the whole repository to search and nothing else. In PathruleBench, the none arm is the same Claude Code with the same tools, prompts and hidden checks as the other arms, but nothing carries from one session to the next. Across the published runs it passed 16% of the memory probes, against 88% with CLAUDE.md files and 97% with Pathrule.
Read that number with its caveat. Every session in the benchmark starts from a fixed repository state, so what the agent was told or did in an earlier session is deliberately not in the files to find. In a real repository, some of what you said last week shows up in the code. It is a floor, not a forecast. But it is the right floor for this question: the decisions, habits and lessons that lived outside the code mostly did not come back by searching.
What to write down, and what to leave to search
The split is simple to say: let search find the code, and write down only what search cannot find. Most of what goes wrong with instruction files comes from ignoring one half of it. A file full of things grep could have found goes stale and is read on every turn; a file missing the decisions leaves the agent to infer them from whatever has the most call sites.
The table and the checklist at the top of this post are the test we apply to each line. The useful question is not whether something is important. It is whether an agent searching today's code would find it.
Hand over the rest before the agent writes
Every agent above already pairs search with something it reads first. Claude Code reads CLAUDE.md at the start of every conversation, and Codex reads AGENTS.md files before doing any work, from the repository root down to the working directory. That is the right shape: search for the code, a file for what is not in it. Its weak point is that the file is read whole, in every session, so the decision about services/billing arrives in a session about the mobile app, and the billing session gets it among a hundred unrelated lines.
Pathrule keeps that knowledge outside the code and files it at the path where it applies. When Claude Code or Codex is about to edit a file under services/billing, the Pathrule hook hands it the rules and decisions filed for services/billing, whether or not it thought to search for them, and a strict rule with an approved block pattern can stop a matching edit and name itself as the reason. Cursor, GitHub Copilot and Windsurf get the same knowledge over MCP, as guidance rather than a block.
In PathruleBench at 2,000 items of team knowledge, a habit said once was followed in later sessions 97% of the time with Pathrule and 78% with CLAUDE.md, and what a failing command taught was still known in 78% of chains against 33%. Keep letting your agent grep. Give it the part grep can't find before it writes: the quickstart sets up Pathrule Local with no account.