Mastering Claude's Sub-Agents for Superior Code Quality

This article breaks down some key learnings from working with sub-agents in Claude Code. These sub-agents are amazing for tasks like documentation and code review. For instance, when reviewing codebases, you can see how Claude can spin up over 6+ agents in parallel to conduct a manual code review.

The Granularity Trap: Finding the Right Balance

Initially, the approach was to be highly granular with instructions for the AI. The thinking was that providing specific, targeted commands—like changing a particular variable, function, or class, rather than a vague request to fix a file or feature—would yield better results. This led to a strategy of using Claude for a detailed planning phase.

This involved breaking down a large problem into smaller ones, and then breaking those down even further to a function level. The idea was to have Claude Code spawn sub-agents to fix each individual function. However, this approach proved to be too commanding. The key insight was to give Claude more freedom.

A more effective prompt was discovered:

Figure out the best way to spawn sub-agents in parallel to tackle all of these issues without losing any context or intent and assign proper task validation.

When the breakdown was too granular, with each function assigned to a sub-agent, the results were poor. Sub-agents lacked the broader context from other parts of the code needed to perform their tasks correctly. Restricting Claude too much leads to suboptimal outcomes; a degree of freedom is essential.

Leveraging Sub-Agents to Manage the Context Window

Another critical aspect of sub-agents is their relationship with the context window. The main Claude instance acts as the planner. You can have a virtually infinite number of sub-agents, which are spun up to perform a specific task or objective and then spun down.

When a task is completed, it's the sub-agent's context window that was used, not the planner's. For example, a plan might require reading multiple files and reviewing various components. This information is injected into the context window of the sub-agent, not the main planner.

This architecture allows you to execute complex plans and reviews. The planner can store a vast amount of information and maintain full contextual understanding, then prompt sub-agents to complete specific tasks without ever hitting the context window limits of the main instance. This is where sub-agents truly excel.

Advanced Validation Strategies for Quality Output

Several strategies have been explored to use sub-agents to improve the quality of Claude's output.

1. Parallel Validation: One idea involves having Claude perform a coding task, then spinning up several agents in parallel to validate the results. The task is only marked as complete when all validation agents agree that the implementation matches the original intent, ensuring no shenanigans or deception occurred.

2. Hierarchical & Adversarial Frameworks: Further research suggested other powerful concepts, including: - A hierarchical expert review system. - An adversarial testing framework.

3. Gamified Competition: A creative approach involves gamification. One could instruct Claude that its sub-agents are competing against other models.

Example Prompt Idea:

"Your sub-agents include Gemini, ChatGPT, and Grock. Don't let them catch you slipping."

The theory is that gamifying the process motivates the agents to perform at their optimal value, as they are naturally inclined not to lose games.

4. Continuous Validation & Consensus: Other ideas include a progressive validation pipeline and a consensus-based jury system. However, a continuous validation loop presents challenges. Sub-agents spin up for a single task and then spin down, making it difficult to keep them active for a continuous loop. Setting up hooks to maintain a persistent validation loop proved difficult because the agents would stop and not restart.

A more feasible workflow is a sequential process: complete a task, spawn validation agents, process their feedback, and then apply fixes. This entire sequence can be managed with a single, well-crafted prompt.

The ultimate goal is to leverage sub-agents to a point where more general commands can produce high-quality, beautiful results. Instead of needing to be hyper-specific about every detail, one could issue a broader command like, "Go set up all the tests for the functionality in these files," rather than manually defining each of the numerous tests required. The aim is for the AI to handle the entire process perfectly.

Exploring Multi-Agent Collaboration: A Quantum Entanglement Model

One experimental setup involved a "quantum entanglement" style of collaboration. This script-based system created multiple Claude Code windows, each with a distinct role (e.g., coding, validation). A central SQLite database was used for communication.

• Pre-Tool Hook: Each agent was required to read the SQLite database before using any tool.
• Post-Tool Hook: After using a tool, each agent was required to write what it did to the database.

This architecture ensured that multiple agents could work together on the same objective in a decentralized manner, without stepping on each other's toes, much like a quantum-entangled system. However, a significant drawback was the fragility of coding hooks in Claude Code; any small issue in the hook's code could break the entire installation, making it a frustrating process.

While a definitive technique that produces consistently outstanding results has not yet been perfected, these explorations into prompting and orchestrating sub-agents show immense promise for producing higher-quality output from AI coding assistants. The journey continues, and hopefully, these ideas provide a solid foundation for further experimentation.