Scaling Claude Code for Large Codebases

Moving Beyond RAG for Codebase Navigation

Coding agents fail on large projects when relying on RAG-based approaches, which embed the entire codebase and perform semantic search. This method often leads to hallucinations of non-existent modules due to context pollution. Modern agents, including Claude Code, now use file-system-based navigation. By utilizing bash tools like ls and grep, the agent interacts with the codebase similarly to a human developer, loading only the necessary snippets into the context window.

Building a Scalable Agent Harness

The quality of output depends on the harness surrounding the model rather than the model itself. A robust harness for large-scale projects requires several specific components:

• Modular claude.md: Keep the root claude.md under 300 lines. For monorepos, place specific claude.md files in subdirectories to ensure the agent progressively loads relevant instructions only when working in those areas.
• Hooks: Use shell scripts to force agent behavior where instructions fail. Implement session-start hooks to load context, pre-tool hooks to prevent unauthorized file edits, and stop hooks to force the agent to reflect on session outcomes and update documentation.
• Skills and Plugins: Use skills.mmd files for specialized tasks. These load on-demand and can be scoped to specific file paths to prevent context bloat. Bundle skills, hooks, and MCPs into plugins to distribute consistent configurations across team members.
• LSP Integration: Configure Language Server Protocol (LSP) for all languages, especially unconventional ones. This allows the agent to navigate code via symbol definitions and imports rather than relying on text pattern matching.
• Sub-agents: Delegate tasks to sub-agents to isolate context windows. This allows for parallelized work and prevents the main orchestrator agent from being overwhelmed by unnecessary information.

Maintenance and Organization

To sustain performance as models evolve, maintain a codebase map for unconventional languages to act as a table of contents. Separate tests into subdirectories to avoid timeout issues and improve scoping. Finally, review the entire harness every few months to remove obsolete instructions that newer models may no longer require, and utilize .ignore or .aagentignore files to protect sensitive or irrelevant directories.