Building with Claude Code Subagents (My Beloved Minions)

I tried Claude Code’s subagents after its recent launch. The feature unlocks more power with Claude Code by allowing me to transition from a general-purpose AI assistant to a specialized “team” of experts. Each expert has a specific role, context, and toolset, which makes my workflows more efficient and reliable — especially for complex tasks like refactoring or debugging.

My Old Workflow: The Generic Task Launcher

Before subagents, my process was simpler, but less specialized. I’d use the CLAUDE.md to set general rules, like an autoscaling policy: min 2, max 5 agents as applicable.

• It was good for running tasks in parallel, but it was generic.
• There was no specialization. No custom context window for each agent.
• The system prompt was the same for everything. It worked for quick, simple tasks.

What are Claude Code Subagents?

Subagents are specialized AI agents within Claude Code. Instead of one general-purpose agent, now you can define each with their own roles and tools. (Imagine "minions" Bob, Kevin, Stuart etc..).

They're a great way to divide up complex problems into smaller, more manageable tasks, each handled by an expert agent.

• Custom Roles: I define a specific role and behavior for each agent in a system prompt.
• Dedicated Context: Each agent has its own context window. This keeps it focused and prevents, say, refactoring info from cluttering a testing task.
• Specialized Tools: I can give an agent access to only the tools it needs, including any connected MCP server tools. For example, one agent gets access to Supabase MCP tools, but might not need specialised tools used for UI testing.

An Unexpected Benefit: Learning Together

Subagents don't just help me get stuff done, they teach me. Working with them has become a powerful learning tool. As they suggest new frameworks, development tools, or design patterns, I'm constantly expanding my own knowledge. New term or idea that’s unheard of? That's a new learning cue!

This new way of working has been a huge boost for my own growth and development - a happy side effect I wasn't expecting (although sometimes it could be intimidating with information-overflow).

To ‘summon’ a specific minion, you can call its name in the prompt. Its Description tells Claude when to call on Bob, Kevin, or Stuart.

How to Set Up a Subagent

Setting one up is pretty straightforward. You use a built-in command and define its configuration.

• Run the /agents command in Claude Code.
• Select "Create New Agent."
• Choose between a project-level or user-level agent.
• Define the agent's name, description, system prompt, and tools.

Example Usage: Minions in Action
You can set up agents to handle a development workflow. These minions can function as a team that knows how to hand off tasks to each other. For example:

Kevin the Architect-Specialist

Kevin is my go-to for big, complex changes. He's an expert at planning and systematic refactoring.

• He plans first, always. My prompt forces Kevin to create a detailed plan and get my approval before he changes a single line of code.
• He thinks critically. He uses Zen MCP tools like planner and challenger to think through every angle.
• He even gets to ‘discuss’ different perspectives from other models, like Gemini, to avoid rushing into action especially on major changes. (With Zen MCP we can leverage each Model’s specific strengths - for example Extended thinking with Gemini Pro, fast iteration with Flash etc.). I had fun observing 2 LLMs "debating" with the consensus tool.
• He knows how to use Context7 MCP to pull in the latest documentation and check for outdated patterns
• Safety is his number one rule. His prompt makes sure he considers security and backward compatibility before starting.

So instead of asking a generic Claude Code agent to "refactor this," I hand the task to Kevin.

When we reach a consensus, we move on to implementation. But if I hit a bug, I have a different minion for that:

Bob the Debugger

Bob is my detective. He's excellent at finding the root cause of an error

• He digs deep. I give him a bug, sometimes he'll ask me for more questions and data points to get to the root cause.
• He uses Zen MCP's debug and tracer tools to analyze the code and the call flow.
• For example, if it looks like a data problem, he'll use the Supabase MCP tool to check the database schema, config, or policies.
• He proposes a small, targeted fix and even suggests a test to confirm it's gone for good

That's when he hands the task over to...

Stuart the Code-Reviewer

Stuart is my meticulous code reviewer. He makes sure all my changes are up to the project's standards.

• He's been trained on the project's CLAUDE.md file, so he knows all the architectural patterns and best practices.
• He's my second set of eyes. He checks for proper usage depending on the framework and looks for critical security issues that are easy for me to miss.
• He once surprised me by discovering the Zen MCP secaudit tool on his own when I was working on some changes related to auth, which sent us down the entire OWASP rabbit hole lol.

Dave the Test-Writer

Dave is my expert QA automation engineer. His job is to validate that a feature works correctly from the user interface down to the database.

• He designs the test. I tell Dave what I need to test, and he designs a comprehensive test plan that covers UI, database validation, and edge cases.
• He writes the scripts. Dave uses the Zen MCP Playwright tool to run tests, and write scripts that simulate real user interactions and the Supabase tool to write read-only queries that validate the database state. There are even auto screenshots that save automatically into folders for functional tests.
• He reports the results. After running the tests, he gives me a clear report with pass/fail statuses and specific details on any failures.

You can have more agents based on specialty, for example:

• A security agent that runs secaudit and other security tests.
• A UX/UI agent that specializes in better user experience and design, incorporating accessibility testing.

Beyond these individual agents, I'm also looking into building a more established workflow - For example, after Kevin kick started, I ask the agent to break down to plan work into phases and workstreams. [More on this later and sharing on my good and bad experience and learning]