From Usable to Powerful: How Harness Boosts AI Coding Tools in Large Codebases

1. Two navigation approaches: who "reads" the code

Large codebases expose a flaw: AI tools that work like a "colleague" on small projects become "interns" on monorepos. Two main techniques exist. RAG (Retrieval‑Augmented Generation) indexing embeds the whole repository once, stores vectors, and injects the most semantically similar snippets into the model. In big repos the index quickly becomes stale because daily commits outpace the embedding pipeline, causing the model to act on outdated code.

Agentic Search (real‑time traversal) avoids a global index. Claude Code greps the filesystem, follows import paths, and always reads the latest files. Its weakness is that the model must know where to look; vague search terms can flood the context window.

2. Harness: a five‑layer extension system

Anthropic’s deployment of Claude Code revealed that the model’s raw capability is only the floor; the surrounding Harness determines the ceiling. The five layers must be built in order.

First layer – CLAUDE.md : the project "map"

Each session automatically loads a hierarchical set of CLAUDE.md files. The root file declares global architecture, key principles, and fatal zones (generated files, third‑party code). Sub‑directory files add module‑specific commands and rules. Keeping the root concise and delegating details to lower layers preserves context efficiency.

Second layer – Hooks: self‑improving scripts

Hooks run at critical events. A Stop Hook analyses a finished session and suggests updates to CLAUDE.md; a Start Hook injects team‑level context based on the current module. Hooks also enforce deterministic actions such as linting and formatting, which are more reliable than prompting the model to obey rules.

Third layer – Skills: on‑demand expert workflows

Skills encapsulate specialised workflows (security review, documentation generation, deployment) and are loaded only when triggered. They can be scoped to a directory, so a payment‑module deployment Skill never appears while editing UI code, preventing unnecessary context consumption.

Fourth layer – Plugins: distributing packaged experience

Plugins bundle Skills, Hooks, and MCP configuration into installable units. A verified plugin can be published to an internal marketplace, allowing new engineers to obtain the same proven setup instantly, avoiding the "tribal knowledge" problem.

Fifth layer – MCP, LSP, Subagents: deep extensions

MCP servers let Claude call external tools, ticket systems, or data platforms. LSP integration gives symbol‑level navigation, filtering out thousands of irrelevant grep hits in C/C++ monorepos. Subagents split exploration and modification into separate context windows, preventing the main agent from being flooded with intermediate results. These layers should be added only after the first three layers are stable.

3. Three practical configuration patterns

Pattern 1 – Make the codebase AI‑readable : keep CLAUDE.md concise and hierarchical, initialise sessions in the relevant subdirectory, use a .claude/settings.json ignore file to exclude generated code and vendor directories, and run an LSP server for precise symbol search.

Pattern 2 – Treat CLAUDE.md as a living asset : periodically (every 3–6 months or after a major model upgrade) audit rules and hooks, removing those that were written for older model limitations and adding new guidance that leverages upgraded capabilities.

Pattern 3 – Assign clear ownership : designate a dedicated person or team responsible for the hierarchy, plugin marketplace, and permission policies, ensuring consistent maintenance and preventing knowledge silos.

4. Deployment roadmap – where to start and in what order

Week 1 – Establish basic readability : create a minimal root CLAUDE.md, add sub‑directory CLAUDE.md files for the most used modules, and commit ignore rules for node_modules, build, dist, etc.

First month – Launch the self‑improvement loop : add a Stop Hook that proposes CLAUDE.md updates, enforce lint/format via Hooks, package 2–3 high‑frequency tasks as Skills, and appoint a direct‑responsible‑individual (DRI) for configuration governance.

First quarter – Scale and deepen : publish verified Skills and Hooks as Plugins, roll out LSP integration for the most common languages, introduce MCP servers for external tool access, and experiment with Subagents for multi‑step tasks. After each major model upgrade, run a CLAUDE.md audit.

5. Summary snapshot

AI coding tools in large repositories succeed when the model sets the lower bound and a well‑engineered Harness sets the upper bound. Agentic Search avoids the stale‑index failure of RAG but relies on high‑quality repository configuration. Building Harness in order – CLAUDE.md → Hooks → Skills → Plugins → MCP/LSP/Subagents – yields a self‑reinforcing feedback loop, while dedicated ownership prevents knowledge from staying isolated.