Stop Letting the Main Thread Do Dirty Work: Practical Subagents Workflow Guide

Subagents are an isolation layer, not outsourcing

Subagents act as an isolation layer for the main thread: they perform exploration, testing, or log analysis and return only a concise summary. OpenAI Codex Subagents documentation and Claude Code Subagents documentation state that each subagent has its own context window, system prompt, tool access, and permission boundaries, making them suitable for tasks that would otherwise flood the main conversation with raw data.

When to use subagents

Each subagent adds token, time, and coordination cost, so use them only when the signal indicates a benefit.

Read many files, logs, test output → subagent

Multiple independent investigation directions → subagent

Need a second‑view review of the current plan → subagent

Phases must run sequentially → subagent (serial)

Frequent real‑time direction changes → main thread

Many stages share large context → main thread

Small quick fix → main thread

Latency more important than isolation → main thread

Anthropic’s experience notes that exploring more than ten files or having three or more independent sub‑tasks usually justifies a subagent. The ultimate test is whether the task would pollute the main thread.

Main‑thread responsibilities

User’s true goal – prevents sub‑tasks from drifting.

Confirmed constraints – file boundaries, permission limits, style, acceptance criteria.

Current decisions – which hypothesis is adopted, which path is rejected.

Final artifact – code, report, PR description, retrospective conclusions.

Subagents handle the noisy work, filter evidence, and return structured summaries.

Good delegation prompt example

请启动一个只读 subagent，调查 checkout 页面提交失败的问题。

范围：
- 只读 apps/web/src/checkout、apps/api/src/order 和相关测试。
- 不要修改任何文件。
- 不要查看无关模块。

目标：
- 找出提交失败最可能的 1‑2 个根因。
- 给出支持证据，而不是直接修复。

输出格式：
- 结论：一句话说明最可能根因。
- 证据：列出文件路径、函数名、日志或测试失败信息。
- 排除：说明已经查过但不支持的方向。
- 不确定：列出还缺少什么证据。
- 下一步：建议主线程应该先验证哪一项。

The prompt emphasizes three constraints: limit input range, limit tools/permissions, and limit return format (Conclusion / Evidence / Exclusion / Uncertainty / Next Step).

Common patterns

Parallel exploration

When a problem spans independent modules, launch separate read‑only subagents and merge their concise summaries.

用三个只读 subagent 并行调查这个登录异常：
1. 前端 agent：检查登录页状态流和错误展示。
2. API agent：检查 auth endpoint、session refresh、错误码。
3. 数据 agent：检查 user/session 表结构和最近 migration。

等待三个 agent 全部返回后，由主线程合并判断。
每个 agent 只返回：结论、证据、排除项、不确定项。

If sub‑tasks depend on each other, parallelism is unsuitable.

Serial pipeline

For multi‑stage tasks, hand off subagents sequentially (explorer → worker → reviewer → verifier). Each stage writes an artifact that the next stage consumes.

先让 explorer subagent 只读梳理调用链，主线程确认根因后，再让 worker 做最小修复。
修复完成后，让 reviewer 用新上下文审查 correctness、regression、missing tests。
最后由主线程决定是否收尾。

Artifacts such as notes.md, review.md, and verification.md prevent information loss between stages.

Cold‑start review

After implementing a feature, launch a read‑only reviewer subagent to perform an unbiased code review that focuses on correctness, security, regressions, and test coverage.

Custom agents: narrow first, then wide

Define reusable custom agents in ~/.codex/agents/ or .codex/agents/. A typical read‑only reviewer definition:

name = "reviewer"
description = "Read-only reviewer for correctness, security, regressions, and missing tests after implementation."
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings and file references.
Do not make code changes.
Avoid style‑only comments unless they hide a real bug.
"""

Anthropic notes that the description field influences routing; it should describe trigger conditions rather than a vague role title.

Permissions and cost design

Two main risks: permission loss and cost explosion.

Parallel agents default to read‑only; write‑capable agents should be single‑instance and require explicit main‑thread approval.

Each additional agent adds token usage. Codex provides agents.max_threads and agents.max_depth (default max_depth=1) to limit recursive splitting.

最多启动 3 个只读 subagent，每个负责一个明确模块。
如果某个方向需要继续深入，先返回主线程，由主线程决定是否追加。

Cooperating layers: Rules, Skills, Subagents

Three layers work together:

Rule files (e.g., AGENTS.md) decide *when* to split work and which directories are off‑limits.

Skills encode repeatable processes such as code review, release checks, or triage steps.

Subagents are the specialist agents invoked by the main thread or a Skill to perform a concrete chunk of work.

Example rule snippet:

## Code Review
When asked to review a branch or PR, use a read‑only reviewer subagent first.
The reviewer must prioritize correctness, security, regressions, and missing tests.
Findings must include file references and reproduction evidence when possible.

Minimal rollout plan

Write a temporary delegation prompt for the immediate task.

Define a reusable read‑only reviewer custom agent.

Add a trigger rule to the project’s rule file (e.g., "for every PR review, first invoke the reviewer subagent").

When the delegation prompt grows into a stable template with checklists and failure branches, promote it to a Skill.

Conclusion

Delegating noisy, read‑heavy work to well‑scoped subagents keeps the main thread focused on goal, constraints, evidence, and final artifact. This isolation turns AI agents into a reliable engineering system rather than a chat window overloaded with raw data.

References:

[1] Chroma Context Rot technical report: https://www.trychroma.com/research/context-rot

[2] OpenAI Codex Subagents documentation: https://developers.openai.com/codex/concepts/subagents

[3] Claude Code Subagents documentation: https://code.claude.com/docs/en/sub-agents

[4] Anthropic subagents article: https://claude.com/blog/subagents-in-claude-code

[5] Codex documentation: https://developers.openai.com/codex/subagents