跪拜 Guibai
← Back to the summary

The Five-Layer Harness That Makes Claude Code Work at Million-Line Scale

Foreword

What's it like to be asked "How do you run Claude Code well in a million-line codebase?" three times in an interview? The candidate froze on the spot. They usually run it smoothly in modules of tens of thousands of lines, but they genuinely had no hands-on experience with a giant monorepo. After going back to study the official blog, they realized that users of small projects most easily miss the "different set of rules" for scaled scenarios.

Whether Claude Code works well in a large codebase is mainly not about the model itself, but about how well the harness built around the model is configured—five extension layers plus three configuration patterns. This is what truly determines the upper limit in a million-line scenario.

Let's reconstruct that interview dialogue. The interviewer's logical chain of questioning was very clear:

👔 Interviewer: How would you use Claude Code well in a project with a million lines of code?

🙋‍♂️ Candidate: To be honest, I've only run it on small modules of tens of thousands of lines. I don't have experience with millions of lines. Could you share your insights?

👔 Interviewer: Then let me ask you, why doesn't Claude Code follow the RAG embedding index route?

🙋‍♂️ Candidate: Because it navigates directly in the file system, reads files, uses grep for precise location, and always faces the latest code. The index never expires.

👔 Interviewer: Then why would it fail when searching for a fuzzy pattern in a billion lines?

🙋‍♂️ Candidate: Because initially, it doesn't have enough context to know where to look, and the context window gets exhausted very quickly.

👔 Interviewer: So what determines performance isn't just the model itself. What is the ecosystem built around the model called? What are the five extension points?

This conversation basically filters out 80% of people—only those who can answer the "five extension layers" are qualified to discuss scaled implementation. This question tests not "whether you can use it," but "whether you've thought about how the tool lands in a scaled scenario."

After reading this article, you'll understand: why the RAG indexing approach fails in large codebases and which path Claude Code took; what the five harness extension layers—CLAUDE.md / Hooks / Skills / Plugins / MCP—do and why the construction order matters; how the two auxiliary capabilities, LSP and Subagents, cooperate with the five layers; the three recurring configuration patterns (navigable, maintain configuration, dedicated agent manager); six engineering trade-offs from an architect's perspective; and the gap between a 60-point and a 90-point interview script.

Whether you're a developer who only runs Claude Code on small modules of tens of thousands of lines, an engineer who has struggled with tool implementation in a large monorepo, or a candidate preparing for an AI Agent position, you should save this. Let's dive in!

1. Why Claude Code Isn't Afraid of "Codebases That Are Too Large"

First, let's clarify why Claude Code isn't afraid of "codebases that are too large." This is the premise for all subsequent discussions. Most AI programming tools follow the RAG route: embedding the entire codebase, building an index, and retrieving relevant snippets during queries. This approach works fine for small projects, but problems arise when applied to large-scale, high-frequency iteration teams.

1. The Fatal Flaw of the RAG Indexing Approach

The embedding pipeline cannot keep up with the speed of code commits. By the time you query it, the index might reflect the code state from weeks or even hours ago. The retrieved function might have been renamed last week, and the referenced module might have been deleted in the last iteration—the "relevant snippets" you get are already stale data. The larger the codebase, the higher the cost of index rebuilding and the more severe the lag. The code itself is alive, but the index is a snapshot from hours ago. AI navigating with an outdated map will frequently hit walls.

2. The Path Claude Code Takes

Claude Code doesn't build indexes or upload codebases. Instead, it navigates directly in the file system like a real engineer: reading files, using grep for precise location, and tracing code references all the way down. It always faces the live, latest code, so there is no index drift problem.

The benefits of this approach are obvious—it sees the code exactly as it is. But the cost is also real: Claude's navigation ability largely depends on whether it initially has "enough context to know where to look."

3. Why Searching for a Fuzzy Pattern in a Billion Lines Fails

If you ask it to find a fuzzy pattern in a billion lines of code, the context window might be exhausted before it even starts working. This is the ceiling of the "on-demand navigation" route—it relies on a priori navigational direction. Blind searching without a sense of direction in a large codebase will quickly exhaust the budget.

This is why the official blog repeatedly emphasizes that teams that truly do well have invested significant effort in the "readability" of their codebase. Giving Claude clear clues about "where to look" from the start is the engineering prerequisite for this approach to work. One of the core goals of the subsequent five-layer harness is to provide Claude with this sense of direction.

2. The Five-Layer Harness: What Determines Performance Isn't the Model Itself

There's a common misconception here. Many people think Claude Code's capability depends entirely on the model used—swap in a stronger model, and the results improve linearly. But that's not actually the case. The entire ecosystem built around the model, the so-called harness, is the key factor determining how well it performs in actual projects.

1. What Are the Five Layers and Why Does the Order Matter?

This harness consists of five extension points, and the construction order is critical because each layer builds upon the previous one:

Why this order? Because if CLAUDE.md isn't written well, Claude lacks a sense of direction from the start, rendering the next four layers useless. If Skills haven't been established, the content packaged in Plugins is empty. Each layer is the foundation for the next.

Insert image description here

2. Two Auxiliary Capabilities Beyond the Five Layers

Besides these five extension points, two capabilities deserve separate mention:

These two aren't "extension points," but they cooperate with the five layers. LSP gives Claude "semantic eyes," and Subagents give Claude "cloning ability." The five layers are horizontal expansion (increasing knowledge and capability sources), while LSP and Subagents are vertical enhancement (improving the quality and capacity of single navigation).

3. Why "What Determines Performance Isn't the Model Itself"

The model is the foundation, but it provides "general capability." Throw a model with strong general capability into a completely unconfigured million-line codebase, and it will still exhaust its context window. What the harness does is direct that general capability—telling it the repository conventions, giving it specialized tools, connecting it to external data sources, and providing a safety net for error prevention.

An analogy: the model is the engine, and the harness is the chassis and navigation. No matter how strong the engine is, without navigation, it will still circle around in an unfamiliar city. This is why the following chapters will dissect the five layers and discuss the three configuration patterns—these are what truly create a gap in scaled scenarios.

3. Layer 1: CLAUDE.md — The Context File Automatically Loaded Every Session

The first layer is the CLAUDE.md file, the deepest foundation of the entire harness. It is a context file automatically loaded at the start of every session, essentially giving Claude a "beginner's manual for this codebase."

1. Global in Root, Local in Subdirectories

The layering mechanism of CLAUDE.md: the root directory holds global information, and subdirectories hold local conventions. For example, the root directory might state "This is a TypeScript monorepo using pnpm workspaces; you must run pnpm lint before committing," while services/auth/CLAUDE.md states "This service uses OAuth2; all tokens must go through Redis cache."

Why layer? If everything is piled into the root, every session loads all content, and local conventions of submodules pollute the global context. The benefit of layering is—Claude only loads the layer for the subdirectory it enters to work in. The global information from the root is always present, and local information is loaded on demand.

2. Content Must Be Concise, Otherwise It Drags Down Performance

This is the most easily overlooked iron rule of CLAUDE.md: it loads every session, so the content must be concise. Anthropic repeatedly emphasizes in the original text—many people treat CLAUDE.md as a document library, writing thousands of lines. As a result, every session must first stuff these thousands of lines into the context window, leaving less budget for actual work.

The correct approach is to only include three types of information: navigation clues (where is the codebase entry point, how are module boundaries divided, key naming conventions), hard constraints (what must be done, what cannot be done), and tacit knowledge that cannot be inferred from the code itself (like why a certain legacy module cannot be touched).

3. It Solves the "Where to Look" Sense of Direction Problem

Looking back at the "searching for a fuzzy pattern in a billion lines fails" problem from Chapter 1, CLAUDE.md is the layer that provides it with a sense of direction. It doesn't give Claude the answer, but gives Claude a map—telling it where the skeleton of this repository is, which areas are high-risk zones, and which conventions cannot be violated.

Claude Code without CLAUDE.md is like throwing a new employee into a million lines of code and letting them figure it out themselves—they can run, but efficiency is extremely low, and the context window gets consumed by meaningless exploration. CLAUDE.md is the layer that turns a "new employee" into an "employee with onboarding documents."

4. Layer 2: Hooks — The Hooks That Allow the System to Continuously Evolve

The second layer is Hooks. Many people's understanding of hooks stops at the script level of "preventing Claude from doing wrong things"—like forbidding it from deleting certain directories or forcing it to run tests before committing. But in the original text, Anthropic emphasizes a more valuable use: allowing the entire system to continuously evolve.

1. Error Prevention Is Only the Lowest-Level Use of Hooks

Error-prevention hooks are certainly useful: intercepting Claude before it executes dangerous operations, forcing it to run lint after writing code, checking commit message format before committing. These are "hard constraints," implementing unbreakable rules in code rather than prompts. But if hooks are only used for error prevention, their true capability is wasted—error prevention is "stopping errors from happening," while continuous evolution is "letting the system learn from errors."

2. The More Valuable Use: Letting the System Continuously Evolve

The core idea of continuous evolution hooks is: reverse-precipitate the problems exposed in each session into new rules or skills. For example, if Claude repeatedly tries a wrong API usage, the hook captures this failure pattern and automatically writes it into the "Common Mistakes" section of CLAUDE.md; if Claude misses an edge case in a refactoring, the hook abstracts it into a new Skill after the test fails; if Claude uses a non-compliant dependency, the hook intercepts it and adds the dependency to the forbidden list.

This usage upgrades hooks from "static guardrails" to a "dynamic learning loop"—the system understands this codebase better each time it runs.

3. Why Hooks Are the Second Layer

Hooks depend on the foundational context provided by CLAUDE.md. If CLAUDE.md hasn't clearly defined the repository conventions, there's no standard for what hooks should intercept or learn. First, there must be a definition of "what this repository should look like" (CLAUDE.md), and then hooks can be used to verify "whether the actual execution matches this." If the order is reversed, hooks become water without a source, either over-intercepting or missing interceptions. This is why Anthropic is very strict about the construction order: CLAUDE.md must come before Hooks.

5. Layer 3: Skills — Progressive Disclosure for On-Demand Loading of Expertise

The third layer is Skills. The core idea is to load specialized knowledge on demand through "progressive disclosure," avoiding stuffing every session with unused content.

1. What Progressive Disclosure Means

The core of progressive disclosure is: specialized knowledge is not stuffed into the context all at once, but loaded on demand. Claude initially only sees a "title + one-line description" of a skill. The full content is only loaded when the task genuinely requires that skill.

For example, a large codebase might have dozens of specialized skills like "How to handle payment callbacks," "How to debug Kafka consumers," "How to run end-to-end tests." If all were written into CLAUDE.md, every session would load the full content of these dozens of skills, immediately blowing up the context window. The progressive disclosure approach is—CLAUDE.md only lists a skill directory. Claude only loads the full documentation for the "Payment Callback" skill when it encounters a payment callback task.

2. The Division of Labor Between Skills and CLAUDE.md

These two are not substitutes but a layered relationship: CLAUDE.md holds "always present" information—codebase skeleton, global conventions, hard constraints—loaded every session; Skills hold "on-demand present" information—specialized knowledge for specific scenarios, operation manuals for specific modules—loaded only when the task matches. The engineering value of this division is: the context window is a scarce resource. CLAUDE.md occupies the "fixed overhead," and Skills occupy the "variable overhead." Fixed overhead must be minimized, and variable overhead must be triggered on demand.

3. Why Skills Are the Third Layer

Skills depend on the first two layers: they need CLAUDE.md to provide the codebase skeleton (so they know which scenarios need skills), and they need Hooks to provide the precipitation mechanism (so new scenarios encountered can be automatically abstracted into new Skills). Without the first two layers, Skills are just a static document library without the ability to grow dynamically.

Insert image description here

4. The True Value of Skills Lies in Scaled Scenarios

In small projects, the value of Skills isn't obvious—the codebase is small enough that everything can be piled into CLAUDE.md and it still runs. But at the million-line level, Skills become a necessity. The number of scenarios in a large codebase grows exponentially—payments, orders, inventory, risk control, logging, monitoring, deployment, rollback—each scenario has its own specialized knowledge and list of pitfalls. Without progressive disclosure, the context window simply cannot hold it all. This is why Anthropic places Skills as the third layer—it is the core mechanism for "specialized knowledge management" in scaled scenarios, the key watershed from "small projects can run" to "large projects run well."

6. Plugins, MCP, LSP, and Subagents: Packaging, Connection, and Assistance

The first three layers are covered. Now let's dissect the remaining two extension points, Plugins and MCP, plus the two auxiliary capabilities, LSP and Subagents.

1. Layer 4: Plugins — Packaging Extensions into Installable Units

Plugins package skills, hooks, and MCP configurations into an installable unit. In large organizations, different teams need different combinations of extensions—the payment team needs "Payment Callback Skill + Risk Control Hook + Internal Accounting MCP," while the frontend team needs "Component Library Skill + ESLint Hook + Design System MCP." Plugins package a set of matching extensions into distributable units. A new project can get the full configuration with one plugin install command. It solves the "how to distribute" problem, hence it's placed fourth—you must have content in the first three layers to package before you can pack.

2. Layer 5: MCP — Connecting Internal Tools and Data Sources

MCP servers allow Claude to connect to external data sources like Jira tickets, Confluence documents, internal monitoring, CI/CD, and databases. If Claude can only read the file system, it sees "what the code looks like," but not "which ticket reported this bug" or "when this service was last deployed." MCP brings these in, upgrading Claude from "only understanding code" to "understanding code and context"—in large codebases, the root cause of many bugs isn't in the code itself, but in the relationship between the code and historical changes, tickets, and monitoring.

3. LSP and Subagents: Two Vertical Enhancements

The five layers are horizontal expansion (increasing knowledge and capability sources), while LSP and Subagents are vertical enhancement (improving the quality and capacity of single navigation). The cooperation of all seven constitutes the complete harness for running Claude Code well in a large codebase. Insert image description here

7. Three Recurring Configuration Patterns

Anthropic, combining multiple successful deployment cases, summarized three recurring patterns. These three are not isolated techniques, but engineering paradigms for "using the five-layer harness."

1. Pattern 1: Making the Codebase Navigable at Scale

Two typical practices: First, write CLAUDE.md concisely and in layers—the root directory only contains the global skeleton, subdirectories contain local conventions, and content is limited to three categories: "navigation clues + hard constraints + tacit knowledge," not piling up documents. Second, don't start from the repository root, but start from a specific subdirectory—starting from the root of a million-line monorepo means facing the complexity of the entire codebase immediately; cd into the subdirectory you want to work in before starting, and Claude's initial context is limited to this submodule, narrowing the navigation scope and significantly improving efficiency.

The essence of this pattern is actively narrowing Claude's search space—the complexity of a large codebase objectively exists, but the work scope of a single session can be artificially controlled, reducing the macro problem of "a million lines" to the micro problem of "a few thousand lines in the current submodule."

2. Pattern 2: Actively Maintain CLAUDE.md as Model Capabilities Evolve

Rules written for the limitations of an old model might become shackles when switching to a new model. Things the old model couldn't do (like cross-file type inference) might already be achievable by the new model. If CLAUDE.md still states "must manually list all related files because the model can't find them," the new model might actually be misled by this rule.

The original text suggests doing a configuration review every three to six months. The question to ask during the review isn't "Is CLAUDE.md still there?" but "Are the rules inside still necessary?"—which ones the new model can already handle autonomously, which are outdated, and which need to be added.

3. Pattern 3: Clearly Define Who Is Responsible for Managing and Promoting Claude Code

The teams that spread the fastest often invest in a small team (sometimes even just one person) to set up the toolchain before opening it up for large-scale use.

Insert image description here

Claude Code is not a tool that "works well right after installation." The five-layer harness needs someone to design, maintain, and promote it. If everyone starts using it simultaneously, everyone repeats the same mistakes, no one consolidates experience, and tool diffusion becomes chaotic and inefficient. Some organizations have seen the emergence of a new role: agent manager—specifically responsible for managing and promoting this toolchain: maintaining CLAUDE.md, collecting team pitfalls and abstracting them into Skills, deciding which scenarios should be packaged with Plugins, and driving configuration reviews.

The essence of this pattern is that scaled implementation of tools requires dedicated personnel. It's not "whoever uses it is responsible," but "someone is responsible for the overall health of the tool"—this is the same logic as needing SREs in the DevOps era and data governance leads in the data era: new tool paradigms require new roles.

8. Six Engineering Trade-offs for Claude Code in Large Codebases from an Architect's Perspective

The previous chapters covered the five-layer harness and the three configuration patterns, but "knowing what exists" and "knowing how to choose" are two different things. This chapter dissects six engineering trade-offs from an architect's perspective—each is an unavoidable decision point when implementing in a large codebase.

1. RAG Indexing vs. File System Navigation: Don't Try to Implement Both

Some teams want to "implement both"—build an index and allow file system navigation, thinking they can complement each other. This is a false proposition: running two in parallel brings consistency issues. When the index says one thing and the file system says another, which should Claude believe? Moreover, maintaining two systems costs far more than one. The judgment is: since you've chosen the file system navigation route, fully commit to the supporting setup—CLAUDE.md for direction, LSP for semantic precision, Subagents for capacity expansion. Don't waver on the fundamental route.

2. CLAUDE.md Conciseness vs. Exhaustiveness: Fixed Overhead Must Be Minimized

A common misconception is "the more detailed it is, the better Claude understands." In reality, for content loaded every session, the more detailed it is, the larger the fixed overhead, and the less context budget remains for actual work. The judgment criterion is: does this piece of information only have value if it's "always present"? If it's "occasionally used" specialized knowledge, it should go through Skills for on-demand loading. Design CLAUDE.md as the "entry fee for each session"—the lower the entry fee, the more budget left for the main task.

3. Hooks for Error Prevention vs. Evolution: Don't Just Use Them as Guardrails

If Hooks are only used as error-prevention guardrails, the system's capability is static—every run is the same. To allow the system to continuously evolve, Hooks must take on the role of "learning from mistakes," reverse-precipitating failure patterns into new rules. Error-prevention Hooks are the baseline; evolutionary Hooks are the upper limit. The baseline is necessary (preventing deletion of databases, preventing commits of untested code), but a system with only a baseline and no evolution runs a hundred times with no difference from the first run.

4. Skills Granularity: Too Coarse Won't Trigger, Too Fine Triggers Too Frequently

Skills that are too coarse (one skill covering the entire payment system) lead to inaccurate triggering; too fine (one skill only explaining one function) leads to too frequent triggering, filling up the context instead. The judgment criterion is: a Skill should correspond to an "identifiable work scenario." For example, "Handling Payment Callbacks" and "Debugging Kafka Consumers" are scenarios with clear trigger signals (keywords, file paths, error types) that Claude can judge: "Am I in this scenario right now?" The essence of granularity is "scenario identifiability," not the amount of content.

5. MCP Access Scope: More Is Not Better

A common misconception is "connect everything that can be connected." But each MCP server increases Claude's tool selection space. When there are too many tools, Claude's tool selection accuracy decreases (this is a common ailment of LLM tool invocation). The judgment is: only connect data sources "strongly related to code work." Jira tickets (linking bug context) and CI/CD status (linking deployment history) are strongly related; company-wide calendars and HR systems are weakly related and should not be connected. The MCP access scope should be filtered by "can this data source help Claude better understand or modify the code?"

6. Dedicated Responsibility vs. Full Autonomy: Scaled Implementation Requires an Agent Manager

Full autonomy works in small teams (everyone modifies CLAUDE.md), but at scale, it becomes a "tragedy of the commons"—everyone adds rules, no one deletes outdated ones, CLAUDE.md becomes increasingly bloated, Skills become increasingly fragmented, and Hooks conflict with each other. Beyond a certain scale threshold (e.g., more than 50 users), an agent manager role is necessary. This role is not an "administrator" (not enforcing permission control), but a "toolchain maintainer"—responsible for configuration reviews, Skills deduplication, Hooks coordination, and Plugins packaging.

9. Interview Script: What the Examiner Wants to Hear

Back to this interview question itself. When the examiner asks, "How do you run Claude Code well in a million-line codebase?" what do they really want to hear?

1. Two Common Wrong Answers

Wrong Answer 1: "Just switch to a stronger model."—This simplifies the problem of scaled scenarios into a model capability issue. The bottleneck in large codebases is never that the model isn't strong enough, but that the harness isn't configured well. Throw an even stronger model into a million-line monorepo without CLAUDE.md, Skills, or MCP, and it will still exhaust its context window.

Wrong Answer 2: "Just build a RAG index for the codebase."—This exposes a fundamental misunderstanding of how Claude Code works. Claude Code doesn't follow the RAG route; it navigates directly in the file system. Suggesting a RAG index for it is fundamentally the wrong direction. Moreover, the index staleness problem in large codebases is precisely why Claude Code chose file system navigation.

2. High-Score Answer Template: Three Layers Plus One Elevating Statement

Layer 1 (Basic Principle): "Claude Code doesn't follow the RAG embedding index route. It navigates directly in the file system, reads files, uses grep for precise location, and traces references down, always facing the latest code. So no matter how large the codebase is, it doesn't need to build an index, and there's no index drift problem."

Layer 2 (Detailed Why): "But direct file system navigation has a ceiling—if there isn't enough context initially to know where to look, blind searching in a billion lines will quickly exhaust the context window. So what truly determines performance is the harness built around the model, the five extension layers: CLAUDE.md provides direction, Hooks prevent errors and enable continuous evolution, Skills load on demand through progressive disclosure, Plugins package and distribute, and MCP connects to external data sources. Plus LSP provides semantic precision, and Subagents save the main context."

Layer 3 (Design Philosophy): "Anthropic summarized three recurring configuration patterns: making the codebase navigable (concise, layered CLAUDE.md plus starting from subdirectories), actively maintaining configuration as models evolve (review every three to six months), and clearly defining dedicated responsibility (the agent manager role). The essence of these three patterns is—whether Claude Code works well in a large codebase is configured, not innate."

One Elevating Statement: "So this question tests not whether you can use Claude Code, but whether you've thought about how the tool lands in a scaled scenario."

3. 60-Point vs. 90-Point Comparison Table

Follow-up Point 60-Point Answer 90-Point Answer
Why not RAG? "RAG index expires" "The embedding pipeline can't keep up with commit speed. Index drift is severe in large codebases. Claude Code chooses direct file system navigation, always facing the latest code."
Why does it fail in a billion lines? "Context gets exhausted" "On-demand navigation relies on a priori direction. Without CLAUDE.md providing direction, blind searching quickly exhausts the budget—this is precisely the problem the five-layer harness solves."
What are the five extension layers? Can name two or three Can fully state the five layers in construction order and explain why this order (each layer is the foundation for the next).
How to configure in a large codebase? "Write a good CLAUDE.md" Three configuration patterns: Navigable (layered + subdirectory start), Maintain Configuration (three-to-six-month review), Dedicated Responsibility (agent manager).

4. Bonus Points

If time permits, bringing up the following points earns bonus marks:

Being able to fully articulate the "five extension layers" and "three configuration patterns" basically gets you to 90 points. Being able to additionally bring up the cooperative relationship of LSP/Subagents and the judgment criterion for Skills granularity pushes you above 95 points.

Summary

Looking back at this interview question, it fundamentally asks not "Do you know how to use Claude Code?" but "Have you thought about how the tool lands in a scaled scenario?" The core message is very simple—whether Claude Code works well in a large project is largely "configured," not "innate."

This is the gap between "having used the tool" and "understanding how the tool lands in a scaled scenario." It's not shameful to fail to answer this question in an interview. Go back, fill in this knowledge gap, and next time you're asked, you can at least talk from the "five extension layers" all the way to the "agent manager role" and keep the conversation going.

Welcome to discuss in the comments the pitfalls you've encountered using Claude Code in large codebases, or how your team configures this harness.