This file is an extracted example from ~/.codex/AGENTS.md. It documents the user-scope instruction policy that makes Codex use subagents only when their output has a clear consumer in the main lane.
The policy intentionally avoids "parallel for its own sake". It makes subagent usage contract-driven for complex, multi-axis work while keeping edits coordinated through explicit ownership boundaries.
For non-trivial tasks, first decide whether subagents would produce independent results that the main lane will actually consume. Do not spawn simply because the task is large.
Subagent spawning does not require an explicit user request. A direct request for parallel work is a strong positive trigger, but the normal decision is still contract-based: independent, consumable, bounded, and worth the coordination cost.
Prefer:
- local sequential work for cheap discovery and immediate blockers;
- subagents only for independent evidence, review, docs checking, test discovery, and validation with a named consumer decision;
- one final implementation lane;
- parallel implementation only when edit boundaries are clearly disjoint.
Do not spawn a read-only lane that overlaps with the main lane's current search. Do not parallelize tightly coupled edits. Do not let multiple agents edit the same files. Spawn the smallest useful number of subagents: usually 0 for local tasks, 1 for one bounded evidence lane, 2-3 only for complex tasks with distinct outputs, and 4-6 only for broad audits/reviews.
Do not use "the user did not explicitly ask for subagents" as a no-spawn reason. If independent investigation axes exist and no subagents are spawned, justify sequential execution only when the user asked about parallelization or the choice changes the plan.
Use a contract-first workflow for complex software engineering tasks.
The goal is not to parallelize everything. The goal is to let Codex deliberately decide when independent investigation, review, testing, or implementation lanes can run concurrently and when their results must be consumed before moving on.
Default assumption:
- simple, tightly coupled, or single-file tasks should stay local and sequential;
- complex, multi-axis, multi-module, review-heavy, test-heavy, or research-heavy tasks should be evaluated for subagents, but only after a consumer decision is named;
- parallel exploration is preferred over parallel editing;
- only one agent should usually apply the final patch unless edit boundaries are clearly disjoint.
Before doing substantial work, classify the task by dependency shape.
Use parallel subagents when:
- subtasks are independent or mostly independent;
- each subtask has a concrete output that will feed a named decision, test, edit, or release gate;
- different agents can inspect different modules, layers, files, test suites, logs, or documentation without blocking each other;
- the task benefits from independent evidence before implementation;
- the task involves PR review, bug triage, regression analysis, large-codebase exploration, migration planning, test discovery, API/docs verification, or multi-module auditing.
Do not use parallel subagents when:
- the task is small and local;
- the next step depends on immediate local context;
- the work is mostly a single sequential reasoning chain;
- the main lane is already inspecting the same files, logs, commands, or question;
- the subagent's output would be nice-to-have but not consumed before a decision;
- multiple agents would edit the same files;
- the acceptance target is unclear;
- the cost of coordination exceeds the benefit of parallelism.
For every non-trivial task, do the following internally before acting:
- Identify the task intent.
- Identify constraints, likely touchpoints, and unknowns.
- Define acceptance criteria:
- What must be true at the end?
- Which command, test, artifact, or manual check proves success?
- Classify the dependency structure:
- independent axes -> parallel lanes;
- shared-file or prerequisite-heavy work -> staged/sequential execution;
- unclear dependency graph -> do a short focused exploration first.
- Decide whether to spawn subagents.
- For every candidate subagent, name the consumer decision where the main lane will use the result.
- If spawning subagents, choose the smallest useful number of lanes.
- Continue only non-overlapping work while subagents run.
- Wait for or explicitly cancel the relevant subagent before crossing its consumer decision.
- Synthesize evidence.
- Apply the smallest safe change.
- Validate against the acceptance criteria.
When inspecting background terminals or processes after an interruption, do not stop them merely because they look unrelated or consume CPU. First determine ownership and whether they block the active request by holding a required lock, port, artifact, disk budget, or by polluting the target output. Stop them only when they belong to the current task, directly block required work, risk corrupting the active artifact, or the user explicitly asks.
Choose the number of subagents based on the number of genuinely independent axes, not based on task size alone.
Default limits:
- 0 subagents: trivial/local task.
- 1 subagent: one bounded evidence lane with a clear consumer while the main agent works elsewhere.
- 2-3 subagents: normal complex task with several independent investigation axes that feed distinct decisions.
- 4-6 subagents: broad review, migration, audit, or multi-module investigation.
- More than 6 only when the task is explicitly batch-like and the work items are independent.
Prefer fewer high-quality lanes over many vague lanes.
Spawn subagents by role, not by arbitrary count.
Good lane types:
- code-path explorer
- test-discovery agent
- regression-history agent
- API/docs researcher
- security reviewer
- performance reviewer
- compatibility reviewer
- frontend/backend/module-specific explorer
- implementation worker for a clearly disjoint edit boundary
- validation/test runner
Bad lane types:
- "figure it out"
- "implement whatever is needed"
- "check everything"
- multiple agents editing the same file without coordination
Parallel exploration is safe by default. Parallel editing is not.
Use this hierarchy:
- Read-only subagents for evidence.
- Main agent synthesizes.
- One implementation lane edits.
- Additional implementation lanes only if file/module ownership is clearly disjoint.
- Main agent integrates and validates.
Never allow multiple agents to independently rewrite the same files.
If two lanes propose conflicting changes:
- stop parallel implementation;
- compare evidence;
- choose one minimal patch;
- explain the tradeoff if relevant.
When spawning a subagent, give it a bounded task.
Every subagent prompt should include:
- role;
- scope;
- files/modules/tests to inspect if known;
- whether it may edit files;
- the consumer decision where its result will be used;
- expected output format;
- confidence/risk requirement;
- stop condition.
Preferred output format:
Summary:
Evidence:
Relevant files/symbols:
Recommendation:
Risk/uncertainty:
Validation suggestion:
For read-only lanes, explicitly say:
Do not edit files. Return evidence and recommendations only.
For implementation lanes, explicitly say:
Only edit within this boundary: <files/modules>.
Avoid unrelated refactors.
Return changed files, rationale, and validation performed.
Use parallelism aggressively for:
- independent read-only investigation with clear consumer decisions;
- review;
- grep/search across independent concepts not already owned by the main lane;
- docs/API verification;
- test discovery;
- independent test commands;
- multi-module audits.
Use parallelism cautiously for:
- implementation;
- refactors;
- formatting large areas;
- dependency upgrades;
- generated code;
- shared configuration files;
- lockfiles.
Avoid parallelism for:
- single-file fixes;
- tightly coupled algorithm changes;
- tasks requiring a single coherent design decision;
- changes where one result determines the next step.
When parallel lanes were used, summarize:
- which lanes ran;
- what each found;
- what decision was made from their evidence;
- whether any lane was cancelled, ignored, or made obsolete and why;
- what changed;
- what validation passed or could not be run.
Keep the final answer concise but evidence-backed.