Developer Productivity Agent.

On first invocation, run a one-time codebase-context loader: language(s), framework, top entry points, dependency graph. Cache to .claude/context-cache.json. The lead agent loads this on every subsequent task instead of re-discovering. Saves ~4K tokens per turn.

# scripts/profile_codebase.py
import json, subprocess
from pathlib import Path
from collections import Counter

def profile() -> dict:
    profile = {"languages": [], "framework": None, "key_dirs": [], "top_imports": []}

    if Path("package.json").exists():
        pkg = json.loads(Path("package.json").read_text())
        profile["languages"].append("typescript")
        deps = list((pkg.get("dependencies") or {}).keys())
        if "next" in deps: profile["framework"] = "next.js"
        elif "react" in deps: profile["framework"] = "react"

    if Path("pyproject.toml").exists():
        profile["languages"].append("python")

    # Top 50 imported modules across the repo
    imports = Counter()
    for ext, regex in [("ts", r"^import .* from ['\"]"), ("py", r"^(import|from) ")]:
        for f in Path(".").rglob(f"*.{ext}"):
            if "node_modules" in f.parts or ".venv" in f.parts:
                continue
            for line in f.read_text(errors="ignore").splitlines()[:50]:
                if line.startswith(("import", "from")):
                    imports[line.split()[1].rstrip(',')] += 1
    profile["top_imports"] = [m for m, _ in imports.most_common(50)]

    profile["key_dirs"] = [
        p.name for p in Path(".").iterdir()
        if p.is_dir() and not p.name.startswith(".") and p.name not in ("node_modules", "dist")
    ]

    Path(".claude/context-cache.json").write_text(json.dumps(profile, indent=2))
    return profile

if __name__ == "__main__":
    print(json.dumps(profile(), indent=2))

The single biggest exploration anti-pattern is Read on every file in a directory. Instead, Grep finds the symbol or pattern across the repo (returns matched files + line numbers); Glob narrows by path; only Read the files that matched. On a 1000-file repo searching for a function name, this is the difference between 1000 Reads and 12 Reads.

One 15-tool agent routes worse than three 5-tool specialists. Define Reader (Grep + Glob + Read), Reviewer (Read + Grep + Bash test/lint), Doc-Generator (Read + Write + Glob). Each runs in its own context. The lead agent coordinates and merges results. Routing accuracy stays high because each specialist has a clear domain.

If the reviewer shares context with the writer, it inherits the writer's assumptions and rubber-stamps. The fix is structural: the reviewer subagent runs with a fresh messages array, fresh system prompt, no inherited tool history. It sees only the diff + the project rules. The independence is the entire point. Confirmation bias is structural, not philosophical.

Long productivity tasks (rename across 50 files, refactor 3 services) span many turns. Don't try to keep all state in the message history. Write it to .claude/scratchpad.md. The lead agent reads it at the start of every turn, updates it after each subagent returns, and trims old entries. The scratchpad is the agent's working memory; the message history is the audit trail.

Multi-language repos benefit from language-specific MCP servers. pyright for Python types, tsc --noEmit for TS, eslint and prettier for JS, ruff for Python lint. Don't load all MCP servers at session start. Route by file extension when a tool needs them. Keeps context lean, reduces overhead.

Delegation (agent proposes), Description (clear output), Discernment (human reviews), Diligence (human approves). The 4D Framework. Code-changing actions are gated behind explicit human approval. The agent presents the diff + the reviewer's verdict + a one-paragraph summary; the human clicks approve or rejects. No auto-merge for productivity tasks; the gate exists because the cost of a bad merge is far higher than the friction of one click.

Tools that emit JSON (gh pr diff --json, git log --pretty=format:%H%x09%s, npm test --reporter json, eslint --format json) replace fragile prose-parsing. Even simple commands have structured-output flags (git status --porcelain, ls -la --time-style=long-iso). Always prefer them. Regex on free-form output is the reason most agent pipelines break in the third week of production.