Building the Agent Harness: Subdirectory CLAUDE.md Files

One Big File Doesn't Scale Claude Code reads a CLAUDE.md file at the root of your project. It's the primary way to give the agent project-specific instructions. And for small projects, it works great. For this project, it didn't. The root CLAUDE.md grew to cover architecture, testing conventions, API patterns, legacy patterns, SPA patterns, service design, migration strategy, authorization rules, database conventions, and more. The file was huge. Every time Claude started working in any part of the codebase, it loaded all the instructions into context. Two problems: Context window bloat. Instructions about database migrations are irrelevant when writing React components. But they're eating context tokens. Signal-to-noise ratio. When everything is important, nothing is. The agent has to parse 500 lines of instructions to find the 20 that matter for the current task. The solution: subdirectory CLAUDE.md files. The Harness Architecture Claude Code loads CLAUDE.md files hierarchically. If