Anthropic Just Dropped a Masterclass on Building Agent Harnesses (for Large Codebases)

Overview

This video summarizes Anthropic’s ideas on how to use Claude Code / Cloud Code to work in large codebases, emphasizing the AI layer/harness needed to make coding agents effective beyond basic tutorials.

Core thesis: harness matters as much as the model

• Claude Code can struggle in large repos unless you provide the right context + tools (the “AI layer”).
• The video frames a codebase as:
  1. Code
  2. Tests
  3. The AI layer: global rules, skills/workflows, MCP/LSP/navigation tools, hooks, and sub-agents.

---

How Cloud Code navigates (no indexing required)

• Claude Code (as described) uses “genetic search” rather than typical RAG/semantic indexing.
• It navigates like an engineer using CLI-style directory/code exploration, rather than relying on a maintained index.
• Tradeoff: it works best when it has enough starting context to know what parts of the repo to focus on.

---

1) Global rules (most important): keep them lean and layered

Keep global rules small

• Large rule files (e.g., thousands of lines) can overwhelm the model and hurt performance.
• Include only essentials:
  • what the codebase is about
  • high-level tech stack / architecture
  • key commands (test, dev server, etc.)

Layer rules by directory

• Use multiple claw.md files:
  • root claw.md loads always
  • subdirectory claw.md loads when working inside that area
• Initialize Cloud Code in a subdirectory to constrain the working directory (while still inheriting root context via directory traversal).

Add a codebase map if needed

• If directory structure alone isn’t enough, include a codebase map (directory list + brief descriptions) to aid discovery.

---

2) Hooks: make the harness “self-improving”

Hooks are presented as more than safety checks—they can continuously evolve your rules/context.

Stop hook (end of session)

• Reflects on what changed
• Proposes updates to relevant claw.md files while context is still fresh
• Runs a separate headless Claude session to produce a markdown review and recommendations
• Example outcome: recommends rule updates when changes affect conventions in a subdirectory (e.g., billing service)

Start hook (beginning of session)

• Dynamically loads team/subsystem context without manual setup
• Example: loads Git/worktree state and recent commits for orientation
• Described as extendable to pulling docs from Confluence based on developer/role

---

3) Skills: reusable workflows, scoped to repo paths

• Skills are reusable step-by-step workflows (prompted processes) for common task types (e.g., “add API routes”).
• To avoid context bloat, skills use progressive disclosure (only load what applies).
• Key add-on: scope skills to specific paths so they activate only in relevant directories.

Distinction in the video

• Global rules = conventions
• Skills = workflows
• Skills overlap with subdirectory claw.md, but the goal remains: scope context to where it matters.

---

4) LSP + MCP servers: better navigation/search by symbols (not strings)

The video emphasizes giving Claude the IDE-like navigation developers rely on (e.g., go to definition, references).

Approach

• Add an MCP server that exposes LSP-like functionality.
• Enables “symbol-level” queries rather than slow/weak grep-style matching.

Demo concept

• Use MCP tool(s) like “find references” / “where used”
• Query something like “find every place X is referenced”
• Results show definitions + references, demonstrating directed search

Why it matters at scale

• Claim: in very large codebases (potentially “six digits” LOC), grep-by-string becomes slow and token-inefficient; LSP/MCP symbol search helps.

---

5) Sub-agents: split exploration from editing

• Use sub-agents to offload large exploration tasks (web research, codebase discovery).
• A sub-agent returns a summary to the main session, keeping the main session context smaller.
• The video notes that tools like Cloud Code / Codeex include built-in explorer sub-agents, so custom sub-agent creation may not be necessary.

---

Additional strategies mentioned (brief)

• Scope tests and lint commands per subdirectory
• Ignore certain files (e.g., build artifacts) so agents don’t waste time reading them

---

Plugin + practical adoption steps (review/tutorial-style)

The creator provides a demo plugin/repo to quickly bring these ideas into a project:

• installs a self-improving stop hook
• adds an explorer sub-agent
• includes a codebase search MCP server (via LSP)
• provides an example path-scoped skill

Installation method described

• Use Cloud Code plugin marketplace add, pointing to a local repo path
• Clone locally; the plugin is not hosted on npm

Alternative onboarding

• Clone the repository and point Cloud Code at it so Claude can explain/apply strategies.

---

Organizational recommendation (ownership/adoption)

Anthropic recommends assigning ownership for building the AI layer:

• Start with a small champion team building rules/skills/LSP/MCP first
• Then roll out across the wider org

Goal: avoid each team building divergent “AI layers” and prevent first-time user disappointment due to missing harness components.

---

Main sources/speakers mentioned

• Anthropic (the original article being summarized: “how to use Cloud Code to work in large codebases”)
• Claude / Claude Code / Cloud Code (the tool discussed)
• Video author/creator (speaker presenting demos and a plugin; no name provided in subtitles)