Claude Code: Orquestração e Governança de Subagentes

Understanding Subagents in Cloud Code Architecture

The Role of Subagents

• Subagents serve as a delegation mechanism within cloud code, featuring a main agent that orchestrates tasks while subagents execute specific functions independently.

• The flow of tasks is asymmetrical: the main agent sends out tasks to subagents, which return only clean summaries, isolating workload and maintaining a clear context for the main agent.

Context Management Challenges

• The finite nature of context changes how it should be viewed—not merely as a token repository but as an attention budget that can become cluttered with noise.

• Excessive logs and outputs can overwhelm the context window, leading to degradation where structured reasoning is pushed out by irrelevant data.

Anatomy of a Subagent

Key Characteristics

• A subagent operates with its own clean context, tools, model, and permissions within an isolated sandbox environment.

• This isolation allows subagents to handle chaotic or noisy tasks without affecting the main agent's focus on high-level reasoning.

Delegation Rules

• The golden rule for creating subagents: if output consists of disposable noise (e.g., extensive searches or logs), delegate it to a subagent.

• Tasks that would flood the main context with non-referential information should be handled by subagents to maintain clarity in decision-making.

Native Subagents in Cloud Code

Types of Native Subagents

• Three native self-invoking subagents exist: Explore (for code base scanning), Plan (for planning mode), and General (for multi-step tasks).

• It's crucial not to reinvent custom models when native options are available; they already facilitate reading and planning efficiently.

Governance and Permissions

Permission Management

• Each subagent operates under POSIC permissions—granting minimal necessary access based on their role ensures security.

• Misconfigurations can lead to significant risks; for instance, allowing unnecessary write permissions could compromise system integrity.

Model Selection

• Choosing the right intelligence level for each task is essential. Current models range from Opus 4.8 (deep reasoning and architecture decisions) down to Raiku 4.5 (quick lookups).

Structural Limits in Agent Architecture

Topology Constraints

• The architecture has a flat topology with a maximum depth limit of one level; subagents cannot invoke other subagents directly.

• Proper orchestration involves parallel execution rather than nesting agents within agents—a key principle for effective task management.

Handling Write Operations Safely

Isolation Strategies

• To prevent collisions during simultaneous edits by multiple agents, each gets an isolated work tree created temporarily by Cloud Code.

• Only successful attempts are merged back into the main branch after discarding unsuccessful ones through automatic cleanup processes.

Evaluator Pattern for Sensitive Changes

Ensuring Quality Control

• Implementing an evaluator pattern separates writing from evaluation; this method enhances audit quality by filtering out author biases during review processes.

Scaling Sessions Effectively

Cognitive Limitations

• Human cognitive capacity limits effective parallel sessions around four before efficiency declines due to merge complexity—known as "merge hell."

Balancing Fidelity and Speed

Information Resolution Trade-offs

• While summarizing information helps speed up processing, it may lose critical nuances needed for complex refactoring across multiple files.

• Direct reading is necessary when dealing with crosscutting concerns; thus both exploration via agents and direct reading must coexist effectively.

Conclusion on Orchestration Layers

Layered Architecture Overview

• Understanding how various layers interact—from tactical session-based operations using subagents to broader orchestration between sessions—is vital for efficient system design.