Why Claude Code Needs a Strong Harness, Not Just a Bigger Model, for Million‑Line Codebases

When Claude Code works smoothly on small personal projects, it feels comfortable, but moving to a company codebase with millions of lines immediately surfaces many problems. The first question (Q1) asks whether the context overflow is caused by a too‑small model. Anthropic’s answer is that swapping models does not help; the issue lies in how Claude Code searches for code.

Opus 4.7 supports a 1 M‑token window (about two million words), yet a realistic project with millions of lines and many dependencies far exceeds this limit. No model can fit an entire repository into context, so the bottleneck is physical.

Claude Code solves precise code location with agentic search , a process that mimics a human engineer:

ls
cd auth/
grep "login"
cat middleware.ts
cat session.ts

Anthropic cites three reasons for choosing agentic search over traditional RAG (retrieval‑augmented generation): indexes become stale as the code evolves, cold‑start times for building embeddings are high, and vector similarity often returns related but incorrect symbols.

The core concept is the harness , a seven‑layer stack built on top of the model: CLAUDE.md → Hooks → Skills → Plugins → MCP , plus two enhancements— LSP and sub‑agents. This stack is unpacked through the remaining questions.

Q2 – How long should CLAUDE.md be?

Anthropic recommends keeping each CLAUDE.md file under 200 lines . A long file consumes context and makes Claude ignore later instructions. The solution is hierarchical: the root CLAUDE.md contains only high‑level pointers, while each subdirectory has its own CLAUDE.md with module‑specific rules. The founder’s slogan is “Ruthlessly edit your CLAUDE.md over time.” A practical check is to ask, “If I delete this line, would Claude still follow the rule?” If yes, delete it.

Claude Code teams should review CLAUDE.md every 3–6 months because model upgrades can render old rules obsolete.

Q3 – Why does Claude often find the wrong file?

In large, multi‑language repositories, string‑based grep returns thousands of matches. By integrating LSP (Language Server Protocol) , Claude can search by symbol instead of text, dramatically reducing false positives. For example, searching for getUser via LSP returns only the exact references, such as auth/login.ts, instead of unrelated matches.

To enable LSP, install the appropriate language server plugin (e.g., typescript‑language‑server, pyright, rust‑analyzer) from the /plugin directory and add the binary to the system.

Q4 – How to handle massive cross‑file changes?

Instead of a single long prompt, split the work into multiple sessions and use a sub‑agent to explore the codebase while the main agent keeps a clean context. The workflow:

Session 1: sub‑agent gathers findings and writes a plan.

Session 2: main agent implements a module based on the plan.

Repeat for subsequent modules.

For large migrations, Claude Code provides a built‑in /batch tool that runs many sub‑agents in parallel, each in its own git worktree, producing PRs automatically.

Q5 – How to roll out Claude Code across a team?

First, package frequent operations as skills (SOPs). Skills are loaded on demand, unlike CLAUDE.md which loads every time. Then bundle skills, hooks, and plugins into a plugin that can be installed company‑wide, ensuring every developer gets the same configuration. A plugin marketplace can distribute updates.

Q6 – How does founder Boris use Claude Code?

Boris runs 5 Claude instances locally and 5–10 on claude.ai/code in parallel. He always starts with Plan Mode to define a solution before letting Claude auto‑accept changes. He attaches a PostToolUse hook that runs format automatically, eliminating the 10 % of formatting errors that would break CI. Frequent tasks are turned into slash commands or skills, such as /commit-push-pr . The entire team shares a CLAUDE.md file in git, updating it whenever Claude makes a mistake.

Q7 – Which projects are unsuitable for Claude Code?

Claude Code is designed for “Git + engineer + standard directory” environments. It struggles with: Game engines that store large binary assets (models, textures, audio). Repositories using non‑Git version control (Perforce, Subversion, custom VCS). Codebases primarily edited by non‑engineers (product managers, designers). For these cases, Anthropic recommends custom configurations via their Applied AI team. Key takeaways: Claude Code requires a well‑built harness; it is not plug‑and‑play for large repos. The highest ROI actions are: keep CLAUDE.md under 200 lines, initialize Claude in subdirectories, and enable LSP. Anthropic provides concrete answers for large‑scale changes, team rollout, and harness maintenance; following Boris’s workflow yields the best results.