AI agents don't understand your system - they search it.
This gist breaks down the cause-and-effect chain from grep-based code discovery to architecture decisions, showing why:
- naming > abstraction
- locality > layering
- predictability > cleverness
A mental model for building codebases that work with AI, not against it.
AI agents do not understand the whole codebase
→ They approximate understanding via search
→ Poor structure = noisy search results
→ Noisy search = wrong context
→ Wrong context = incorrect code
💡 Therefore: Code structure directly affects correctness, not just speed.
AI agents rely heavily on text-based search (grep / ripgrep)
→ Codebases must be search-friendly (grep-friendly)
→ Search-friendly code requires:
- explicit naming
- predictable structure
- localized context
→ This leads to structuring code into bounded, cohesive modules (feature-oriented / DDD-inspired)
→ Within each module, files should follow consistent naming conventions:
*.use-case.ts*.repository.ts*.entity.ts
→ As a result, relevant code can be located quickly and deterministically (⚡)
→ This reduces:
- search time
- context reconstruction effort
→ Which leads to faster task execution by the agent (⚡)
→ And fewer tokens required (📉):
- less code to read
- less ambiguity
→ Which lowers inference cost and improves response quality (💰)
→ Resulting in cheaper and more reliable feature implementation
→ Ultimately reducing engineering costs for the company (💰) (and potentially improving team efficiency and rewards)
You are no longer designing just for humans - you are designing for search-driven reasoning systems.