Guide

Production and case studies

Agentic code search

Grep, glob and targeted reads beat dumping a repo or trusting a nearest-neighbor hit that looks relevant and is the wrong module.

147 of 155 · 2 min read

Repos are huge. Dumping "the whole repo" into context fails. Naive embedding search over code often misses the right symbol, because similar prose is not the correct call site. A wrong retrieval that looks relevant is worse than a miss. The model will confidently edit the wrong module.

Concept

Before you start: a coding agent is a loop that gathers context, edits and runs checks. Agentic search means the model chooses the next grep or read, the way a human would.

The big idea

Effective agents use tools the way humans do:

  • glob / file tree for layout
  • grep / ripgrep for exact symbols and strings
  • Targeted read of file ranges
  • Optional repository map (compressed outline of important symbols) as a starting index
  • Language server / go-to-definition when available

Embeddings still help for natural-language questions ("where do we handle billing webhooks?"). For "fix chargeCard callers," exact search wins. Hybrid is fine. Agentic search is the backbone.

A repository map (tree of important symbols with signatures) helps the model aim its first greps. Regenerate it on index. Do not hand-maintain it. When the map and the filesystem disagree, the filesystem wins. Tools should always be able to re-read reality.

Long-lived products also inject a short project memory file each session: how to run tests, code style, architecture boundaries, forbidden directories. Keep it small. Every token of memory is paid on every turn and can go stale. Prefer executable truth (make test) over prose essays.

Walking through a missed symbol

The issue says "fix chargeCard callers." An embedding search returns billing/ChargeService.md because the prose is about charges. The real callers are in payments/legacy_card.py. The model edits the markdown. Tests still fail.

A grep for chargeCard returns the three call sites. The model reads those ranges and patches them. Tool descriptions matter as much as the system prompt. Absolute paths, "exactly one match required for replace," and clear error messages raised SWE-bench performance when Anthropic error-proofed their edit tool.

Common mistakes

  • Pasting the repo because the window is large. You pay, and the wrong file still wins attention.
  • Trusting a semantically close hit without a grep to verify the symbol.
  • A hand-maintained repo map that disagrees with the tree. The filesystem is the source of truth.

Check yourself

  1. You need every caller of chargeCard. Which tool? grep / ripgrep for the exact symbol, not an embedding search.
  2. The repo map says a file exists and read 404s. What wins? The filesystem. Re-read reality.

Key takeaways

  • Prefer grep, glob and targeted reads over a blind embedding dump.
  • Embeddings help NL questions. Exact search wins on symbols.
  • Keep project memory short and executable (make test).
  • When map and disk disagree, disk wins.

Further learning

Once the agent found the file, it has to change it safely. That is patch edit tools.

Case study: coding agent

How coding agents work: repo context, edit tools, test loops, sandboxes and review.

Embeddings and similarity

Turning text into vectors, measuring similarity, and choosing an embedding model.

Context engineering

Deciding what goes into the context window: ordering, compaction, memory and long context vs retrieval.