Subagent Design and Practices for AI-Assisted Programming

In AI-assisted programming, a single conversational assistant can solve many local problems, such as explaining a piece of code, generating a function skeleton, locating a simple error, or adding test cases. However, when the task expands to complex engineering work—understanding an unfamiliar repository, completing a cross-module refactor, analyzing a failure root cause and proposing a fix, or performing a security review of a change—a single session often exposes problems such as mixed context, drifting reasoning goals, difficult permission control, and outputs that are hard to verify.

The value of the subagent mechanism lies in breaking complex tasks into independent work units with clear responsibilities and boundaries. The main agent understands user intent, creates a plan, assigns tasks, and integrates results. Subagents focus on a limited objective and use isolated context to complete retrieval, analysis, coding, testing, or review. This collaboration model is closer to a real software engineering team: architecture design, code implementation, quality assurance, and security review can be divided among different roles, but final acceptance and decisions must still be made by a unified owner.

What Is a Subagent?

A subagent can be understood as an independent intelligent execution unit that the main agent starts on demand for a specific task.

It is not merely the main agent “saying a few more things” or “dividing one question into several paragraphs.” It is a task instance with a relatively independent operating boundary. A well-designed subagent usually includes the following core elements:

1. Independent context

   A subagent has its own task context and does not need to inherit all content from the main conversation. The main agent provides only the materials needed to complete the task, such as directory structure, relevant interfaces, error logs, design constraints, or specified file contents.

   This isolation prevents irrelevant information from interfering with reasoning. For example, a subagent analyzing a database migration plan may not need to see discussion records about frontend style changes; a subagent responsible for security review should not be flooded with unrelated requirement details.

2. A clear system role

   A subagent should have a clear responsibility description. For example:

   • Code reading agent: organizes module responsibilities, call chains, and dependencies;
   • Implementation agent: modifies code within a specified scope according to an established plan;
   • Testing agent: adds tests, analyzes failing cases, and verifies boundary conditions;
   • Review agent: finds logic defects, compatibility issues, and potential risks;
   • Documentation agent: turns implementation details into interface descriptions, change records, or operational documentation.

   The clearer the role, the more stable the output. Vague task descriptions such as “help me see what is wrong with this project” often lead to generalized conclusions, missing priorities, and even large amounts of ineffective advice.

3. Controlled tool permissions

   Different subagents should have different permissions. A read-only analysis agent can read code, search files, and view logs, but should not have permission to modify files or execute high-risk commands. An implementation agent can write code in restricted directories. Deployment or operations-related actions require stricter approval and isolation.

   The principle of least privilege is essential. A subagent’s capabilities should not aim for “the more it can do, the better,” but should follow the principle of “only the minimum permissions required to complete the current task.”

4. Verifiable deliverables

   A subagent should not return only a broad conclusion. It should submit structured artifacts, such as:

   • A list of involved files;
   • Key call chains;
   • Risk levels and evidence;
   • Modification suggestions or patches;
   • Test results;
   • Assumptions that have not yet been verified;
   • Questions that require a decision from the main agent.

   Verifiable output allows the main agent to integrate multiple results effectively and helps developers trace the source of conclusions.

Why Complex Development Tasks Need Subagents

Complex engineering tasks usually involve multiple objectives, multiple constraints, and multiple stages. Consider “adding permission checks to an existing service.” The actual work may include:

• Finding entry interfaces and route configurations;
• Analyzing the existing authentication flow;
• Identifying resource access scopes for different roles;
• Modifying business code;
• Adding unit tests and integration tests;
• Checking whether caching, logging, and exception handling leak sensitive information;
• Assessing backward compatibility of old interfaces;
• Updating interface documentation and change notes.

If all this work is handled by the same agent in one long context, three types of problems easily arise.

1. Context expansion

As code snippets, logs, configurations, and requirement changes accumulate, truly critical information can be buried. The agent may forget earlier constraints or treat outdated discussion as current fact.

Subagents alleviate this problem through “task-level context trimming.” Each subagent receives only information relevant to its own goal, reducing noise and improving analytical focus.

2. Interference between reasoning and execution

Planning, coding, testing, and review require different modes of thinking. The design stage emphasizes global constraints and trade-offs. The coding stage emphasizes interface consistency and implementation details. The testing stage emphasizes counterexamples, boundaries, and repeatable verification. The review stage focuses more on omissions and risks.

Separating these roles reduces the chaotic process of “designing while modifying, and modifying while rejecting,” making the overall workflow more controllable.

3. Difficulty isolating risk

If an agent can read the entire project, modify arbitrary files, execute commands, and directly trigger external operations, a single misunderstanding can cause significant impact.

With subagents, permissions can be set according to the nature of the task. For example, a code review subagent can be read-only; a testing subagent can execute only in an isolated environment; a writing agent can modify only specified directories; actions involving production environments must be confirmed by humans.

Collaboration Model Between the Main Agent and Subagents

A mature multi-agent workflow is not simply “the main agent throws out tasks and waits for results.” A more reasonable model is: the main agent handles global governance, and subagents handle local problem solving.

The whole process can be abstracted into four stages.

Stage 1: Task clarification and decomposition

The main agent first converts user requirements into executable goals and identifies uncertainties. For example:

• What is the goal?
• Which modules may be affected?
• Are there compatibility requirements?
• Is it necessary to modify data structures?
• Does it involve security, permissions, performance, or release risks?
• Which facts are still unconfirmed?

The main agent then decomposes subtasks by task type. Decomposition should follow the principle of “low coupling, high cohesion”: each subagent handles a relatively complete piece of work, avoiding multiple agents modifying the same core file at the same time.

For example, a feature change can be divided into:

Task A: Read existing code and output call chains and impact scope
Task B: Analyze data model and interface compatibility
Task C: Define the implementation plan and risk list
Task D: Complete code changes within the specified module
Task E: Add tests and execute verification
Task F: Review the change from security and maintainability perspectives

Among these, A, B, and C can run in parallel; D should run after the plan is confirmed; E and F run after code changes are made.

Stage 2: Pass the minimum necessary information to subagents

A subagent task description cannot be just “analyze this problem.” A high-quality task instruction should include at least:

• Task objective;
• Input scope;
• Output format;
• Operations that are not allowed;
• Judgment criteria;
• Known constraints;
• How to handle uncertainty.

An example template is as follows:

Role: Code reading and impact analysis agent
Objective:
Map the call chains related to “user permission checks” and identify modules that may be affected.
Input scope:
Read only the specified directories and their direct dependencies. Do not modify any files.
Output requirements:
1. List entry points, core services, data access layers, and exception handling locations;
2. Provide call chains;
3. Mark permission rules that require further confirmation;
4. Output potential compatibility risks;
5. Attach corresponding code locations or evidence explanations to each conclusion.
Constraints:
Do not modify code, do not perform external operations, and do not speculate about business rules based on information not provided.

Such constraints can significantly improve output quality and reduce the probability of unauthorized actions by subagents.

Stage 3: Result collection and conflict handling

Conclusions from different subagents may conflict. For example, an analysis agent may believe an interface can be deprecated directly, while a compatibility agent finds that the interface is still called by multiple modules. An implementation agent may propose a change, while a testing agent finds that it causes exceptions under boundary conditions.

The main agent cannot simply “take a majority vote.” It should handle conflicts based on evidence. The following approach is recommended:

1. Require subagents to provide the basis for their conclusions, not just judgments;
2. Distinguish facts, inferences, and recommendations;
3. Launch a review subagent for high-risk disputes;
4. Confirm issues involving business rules with users or human owners;
5. Clearly preserve assumptions and unverified items in the final plan.

Stage 4: Unified acceptance and delivery

The main agent ultimately needs to integrate the results from multiple subagents into a complete deliverable for developers, including:

• Implementation plan;
• Scope of changes;
• Key code changes;
• Test coverage;
• Risks and rollback recommendations;
• Follow-up tasks.

Note that subagent output can only serve as a basis for decisions and cannot replace final acceptance. In particular, tasks such as code modification, data changes, and security policy adjustments still require human review and repeatable testing.

Typical Use Cases

1. Quickly understanding an unfamiliar codebase

When facing a large project, the most common problem is not “how to write code,” but “where should the change be made.” At this point, multiple read-only subagents can be started, each responsible for:

• Organizing directory and module responsibilities;
• Tracing core business flows;
• Analyzing configurations and environment variables;
• Analyzing data models and storage relationships;
• Organizing the testing system and build process.

The main agent then summarizes these results into a project map. Compared with having one agent read the entire repository at once, partitioned analysis makes it easier to form a clear and reusable cognitive structure.

2. Separating feature development from code review

The goal of an implementation agent is to “make the feature work,” while the goal of a review agent is to “find why it may fail.” The two should not be conflated.

After implementation is complete, an independent review subagent should focus on checking:

• Whether existing interface contracts are broken;
• Whether there are boundary issues such as null values, concurrency, or duplicate submission;
• Whether there are unhandled exceptions;
• Whether logs contain sensitive data;
• Whether input validation is complete;
• Whether unnecessary complexity is introduced;
• Whether tests truly cover core branches.

Independent roles reduce the tendency to assume that “the code I wrote is correct by default.”

3. Troubleshooting and root cause analysis

Production incidents often involve fragmented information: monitoring metrics, logs, change records, call chains, and exception stacks may be intertwined. Different subagents can focus on:

• Log timelines and exception clustering;
• Correlation between recent changes and incident time;
• Resource metrics and capacity changes;
• Dependency failure points in call chains;
• Possible rollback paths and mitigation measures.

However, it is essential to note that root cause analysis conclusions should clearly distinguish between “confirmed causes” and “hypotheses to be verified.” Subagents can propose investigation directions, but they must not treat correlation as causation.

Context Management: What Subagents Can and Cannot Solve

The independent context of a subagent is its core advantage, but this does not mean that less context is always better.

If too little information is provided, the subagent lacks a basis for judgment and easily produces generic conclusions. If too much information is provided, the isolation benefit is lost. Therefore, the principle of “minimum sufficient context” should be followed.

An effective context package usually includes:

• Background and objectives of the current task;
• Relevant files or code summaries;
• Clear interface constraints;
• Known problems and error symptoms;
• Output format and acceptance criteria;
• Rules that must not be violated.

At the same time, the following content should not be passed indiscriminately to all subagents:

• Complete chat records unrelated to the task;
• Unredacted keys, tokens, or personal information;
• Large amounts of code from unrelated modules;
• Speculative conclusions that have not been confirmed;
• Unnecessary high-privilege operation instructions.

Subagents can alleviate context confusion, but they cannot automatically guarantee correctness. Incorrect task decomposition, vague constraints, and distorted input materials can cause incorrect conclusions to be amplified more efficiently.

Permission Governance and Security Boundaries

In engineering practice, subagent permissions should be managed in layers.

1. Read-only layer

Suitable for code reading, dependency analysis, log retrieval, document organization, and risk assessment. Such agents should not modify files or execute operations that affect environment state.

2. Restricted write layer

Suitable for tasks such as generating patches, adding tests, and updating documentation. Writable directories and file types should be restricted, and all modifications should be traceable and reversible.

3. Isolated execution layer

Suitable for build, test, and static analysis tasks. These should be completed in an isolated environment to prevent test scripts from accidentally accessing sensitive resources or affecting shared environments.

4. High-risk operation layer

Operations involving data deletion, permission adjustment, release, network access, or production environment changes should not be completed automatically by subagents. Such operations must go through explicit approval and retain complete audit records.

Permission boundaries are not only a security requirement; they also improve the credibility of results. A conclusion from a read-only analysis agent is easier to review because it did not modify the scene. Results from a testing agent in an isolated environment are also easier to reproduce and verify.

Common Pitfalls and Improvements

Pitfall 1: Treating subagents as unlimited parallel resources

Parallelism does not always improve efficiency. If multiple agents analyze the same files at the same time, they may duplicate work. If they modify interdependent modules at the same time, they may cause conflicts.

The improvement is to first map dependencies: run parallelizable work in parallel and run tasks with sequential dependencies in stages. For modification tasks, divide non-overlapping file boundaries as much as possible.

Pitfall 2: Writing only one sentence in the task description

“Help me fix this problem” cannot define the repair standard or limit the scope of changes. A subagent may break other logic in order to eliminate a surface-level error.

Provide the problem symptoms, expected behavior, allowed modification scope, constraints that must not be broken, and verification methods.

Pitfall 3: Directly accepting subagent conclusions

A subagent may misread code, miss hidden dependencies, or make inferences based on incomplete information. Especially in high-risk areas such as security, data consistency, and concurrency control, its results must be treated as “engineering artifacts awaiting verification,” not final facts.

Pitfall 4: Ignoring standardization of result formats

If every subagent outputs free-form text, the main agent will find it difficult to compare and integrate results. A unified output framework is recommended:

Conclusion:
Evidence:
Impact scope:
Risk level:
Recommended plan:
Verification method:
Unconfirmed items:

Standardized output reduces integration costs and also supports subsequent automated processing and auditing.

Recommendations for Building Reliable Multi-Agent Workflows

To make subagents genuinely serve development efficiency rather than increase coordination costs, the following principles can be followed:

1. Plan first, execute later
   For complex tasks, build a task graph before starting execution-oriented subagents, avoiding blind code modifications from the beginning.

2. Single role, specific goal
   A subagent should ideally assume only one core responsibility, such as analysis, implementation, testing, or review.

3. Least privilege, minimum context
   Do not provide unnecessary data, and do not grant unnecessary tool capabilities.

4. Require evidence and verification
   Any key conclusion should be traceable to code, logs, tests, or explicit rules.

5. Preserve human decision points
   Business rules, architecture trade-offs, security boundaries, and production changes cannot be fully delegated to automated agents.

6. Treat failures as observable signals
   A subagent failing to complete a task, conflicting results, or failed tests do not mean the process is ineffective; these phenomena are themselves important signals of unclear requirements, complex architecture, or missing knowledge.

Conclusion

The essence of subagents is not simply adding multiple intelligent assistants, but establishing a collaboration mechanism for complex development tasks that is divisible, isolated, verifiable, and auditable. The main agent takes responsibility for planning and governance, while subagents take on clearly bounded professional tasks. Together they form a closed loop through structured input and output.

For developers, what really matters is not “how many subagents to start,” but how to decompose tasks, control context, limit permissions, verify results, and balance automation efficiency with engineering reliability. When these principles are applied to daily coding, testing, review, and troubleshooting workflows, multi-agent collaboration can move from concept demonstrations to stable engineering productivity.