GoKawiilMetabase’s backend is big. We’re talking 500K lines of Clojure code spread across a query processor, permissions system, numerous database drivers, a notification pipeline, serialization layer, search engine, and more. And like all big codebases, each subsystem has its own idioms, gotchas, and “you just have to know” moments.
I’ve been using Claude Code for backend work on Metabase for a while now. It’s pretty good. But overloads Claude’s context window quickly. Every time Claude needs to understand a subsystem, it explores, greps, and reads files. All of that exploration eats your context window. Even when Claude spawns subagents, they will need to do a lot of extra work to get up to speed on the domain.
I built some custom subagents to fix this.
What are subagents and why did I make ten of them?
Metabase’s backend has natural domain boundaries. The query processor is a 68-stage middleware pipeline that compiles MBQL (the Metabase Query Language) to SQL across 18 database dialects. The permissions system is a multi-granularity graph that handles row-level security, database routing, and connection impersonation. The notification system renders charts to images inside a JVM. These are different worlds.
A single generalist Claude session can navigate any of them, but it pays a context tax every time it switches domains. Subagents eliminate that tax by front-loading domain knowledge into the system prompt.
Subagents are a Claude Code feature that lets you define specialized AI assistants as markdown files. They each get their own context window, system prompt, memory, toolkit, and model selection.
I used Claude to write the “job descriptions” for each agent. I described the domain and what an expert would know, and Claude helped me flesh out the codebase locations, investigation patterns, caveats, and testing strategies. Each agent ended up being roughly 2,000-3,000 tokens worth (about 150 lines of markdown) of dense, useful context that can’t be easily inferred from the code.
What’s inside an agent file?
Each agent is a markdown file that follows the same pattern of, domain knowledge → codebase locations → investigation approach → caveats → testing strategies. It’s a “here’s everything you need to be useful in this corner of the codebase” document.
... continue reading