Overview
Anthropic's Claude Code is not "a better RAG"—it abandons RAG entirely. In large codebases (tens-of-millions-line monorepos, decades-old legacy systems, multi-repo microservices), RAG indexes can never keep up with engineers' commit velocity. Claude Code instead lets the AI work like a real engineer: traverse the filesystem, grep, and follow references—shifting from "retrieval-augmented" to "real-time Agentic Search." More importantly, Anthropic found that the Harness (tooling ecosystem) matters more than the model itself. Seven extension layers—CLAUDE.md → Hooks → Skills → Plugins → LSP → MCP → Subagents—form the infrastructure for enterprise AI coding. Stripe migrated 10,000 lines of Scala to Java in 4 days (estimated 10 engineer-weeks); Wiz completed an estimated 2-3 month Python→Go migration in ~20 hours.
Why RAG fails in large codebases
- Ghost module problem: An index built last week may still reference modules that were renamed or deleted weeks ago, so the AI confidently points to files that no longer exist.
- Embedding pipelines can't match commit velocity: Batch index updates lag by hours or days at large organizations.
- Broken reference chains: Retrieving one or two file fragments loses "which function calls this" and "where is this type defined" context.
- A 2025 Columbia University study of 8 AI search tools found Perplexity had a 37% error rate and Grok 3 reached 94%—largely from retrieving outdated information.
- Today: create a root
CLAUDE.mdwith navigation pointers and key conventions; add local CLAUDE.md files in busy subdirectories. - This week: add a stop hook that analyzes session errors and proposes CLAUDE.md updates.
- This month: extract recurring workflows into Skills (security review, onboarding, deploy); install LSP servers for your main languages (typescript-language-server, pyright, clangd, jdtls).
- Next quarter: package stable skills/hooks/MCP configs into a plugin (
plugin.json+ directories) and distribute via an internal marketplace. - Context window remains a bottleneck: fuzzy searches in billion-line codebases still overflow; layered CLAUDE.md also breaks down with hundreds of thousands of directories or non-git legacy systems.
- Maintenance cost: 3-6 month config reviews easily become deferred tech debt.
- Learning curve: Claude Code is intentionally low-level—more like Vim than Copilot's out-of-the-box experience.
- Security & compliance**: access control (
permissions.deny), exfiltration risk via MCP-connected external tools, and license contamination of AI-generated code. - Original article: https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start
- Claude Code docs: https://code.claude.com/docs/en/best-practices
- Anthropic engineering blog: https://www.anthropic.com/engineering/claude-code-best-practices
- Claude Code product page: https://www.anthropic.com/product/claude-code
Claude Code's answer: no embedding pipeline, no vector index, no central server—just local, real-time Agentic Search. The trade-off is the AI needs enough starting context to know where to begin searching, which is where the Harness comes in.
The seven-layer Harness
1. CLAUDE.md — a knowledge map loaded hierarchically (repo root gives the big picture; subdirectory files give local conventions). Keep root files lean: pointers and key pitfalls only; reusable expertise belongs in Skills.
2. Hooks — scripts at key moments. Beyond blocking mistakes, a Stop hook can detect repeated error patterns and propose CLAUDE.md updates; deterministic checks (lint/format) beat relying on the model remembering rules.
3. Skills — progressive disclosure of domain expertise, loaded only when relevant, optionally scoped to paths (e.g., a payments deploy skill that never loads outside services/payments/).
4. Plugins — package Skills, Hooks, and MCP configs into distributable bundles so new engineers get veterans' setups on day one; updates via managed marketplace.
5. LSP — symbol-level navigation (go-to-definition, find-references) instead of string grep; especially valuable for C/C++ and multi-language monorepos.
6. MCP Servers — connect internal search, docs (Confluence/Notion), tickets (Jira/Linear), monitoring (DataDog/Grafana), and BI tools.
7. Subagents — isolated Claude instances with their own context windows, e.g., a read-only subagent explores and writes an architecture doc before the main agent edits; also enables writer/reviewer and parallel workflows.
Three success patterns
1. Make the codebase navigable: lean layered CLAUDE.md; launch Claude in subdirectories (cd services/payments && claude) so it auto-loads ancestor files; specify per-directory test/lint commands; use .ignore and permissions.deny in .claude/settings.json to exclude generated code; build a codebase map; run LSP servers.
2. Actively maintain CLAUDE.md: instructions written for older models may now limit newer ones (e.g., "only change one file at a time"). Review configs every 3-6 months and after each major model release—Anthropic's own Perforce p4 edit hook became redundant once native support shipped.
3. Invest at the organizational level: pre-deploy infrastructure with a small team so developers' first experience is productive; adoption then spreads naturally.
Enterprise results
| Company | Scenario | Result | |---|---|---| | Stripe | 1,370 engineers deployed | 10,000-line Scala→Java migration in 4 days (est. 10 engineer-weeks) | | Ramp | Workflow integration | 80% reduction in incident investigation time; non-engineers query data warehouses in natural language | | Wiz | 50,000-line Python→Go migration | ~20 hours of active work (est. 2-3 months manual) | | Rakuten | Team-wide rollout | Average feature delivery from 24 working days to 5; engineers run multiple concurrent Claude Code sessions |
These are "Harness miracles," not model miracles.
Getting started roadmap
Limitations
Conclusion
The blueprint is a methodology, not just a tool: abandon RAG for Agentic Search; the Harness matters more than the model; treat configuration as code; organizational investment is indispensable. Large-scale refactoring is shifting from "too risky to attempt" to "feasible"—not because AI writes faster, but because the methodology for taming code monsters has matured.