Qoder Subagent Context for Codebases

Qoder Subagents do not automatically share the main session's full context or one another's intermediate work. Give each role an explicit evidence packet containing the repository revision, task boundary, relevant paths, architecture constraints, approved findings, expected output, and verification commands. Treat the final handoff as a reviewable artifact, not as shared memory.

This design lets planning, implementation, testing, and review agents use consistent repository facts without loading the same raw conversation into every context. It also preserves isolation: each Subagent receives only what it needs and operates within its own tool, permission, runtime, and workspace boundaries.

Why Subagents Rebuild Context

Qoder CLI defines a Subagent as a specialized agent with its own conversation context, system prompt, tool registry, transcript, and compression flow. Its intermediate search and reasoning do not directly enter the main conversation. The main session coordinates the task and receives the Subagent's result.

Isolation keeps exploration details from crowding the coordinator's context, but it creates an information-transfer problem. A planner may discover that an API handler is generated, yet an implementation agent will not know that fact unless the handoff says so. A tester may find an undocumented consumer, while a reviewer sees only the patch unless that evidence is carried forward.

The same problem appears when a Subagent starts from a broad instruction such as “review this migration.” It may have to rediscover:

• the repository commit and working-tree state;
• which package owns the behavior;
• the approved architecture boundary;
• callers, schemas, generated outputs, and external consumers;
• commands that produce a representative test result;
• decisions already made and questions that remain open.

Repeated discovery consumes tool calls and increases inconsistency. Two agents can inspect different files, trust different documents, and produce individually plausible but incompatible recommendations.

Qoder's optional auto-memory is not a substitute for a handoff. It is enabled separately, stores selected local Markdown facts, and can become stale. Project AGENTS.md and rules provide durable guidance, but they do not contain every task finding. A reliable Qoder subagent context workflow therefore distinguishes stable repository knowledge from temporary evidence and role-specific reasoning.

Define Shared Repository Knowledge

Shared repository knowledge should be a small, versioned contract that every role can verify.

A useful evidence packet contains:

Field	What to record	Why it matters
Revision	Commit, branch, and relevant uncommitted-state note	Prevents agents from reasoning over different snapshots
Objective	Requested outcome and explicit non-goals	Limits scope expansion
Relevant paths	Entry points, likely owners, tests, and documents	Reduces duplicate scanning without hiding source
Architecture constraints	Approved boundaries and decision records	Preserves design intent
Relationship evidence	Callers, imports, schemas, generators, and consumers	Supports impact analysis
Permissions	Allowed tools, paths, commands, and network access	Keeps each role inside its authority
Verification	Focused tests, broader checks, and acceptance conditions	Gives every role the same definition of done
Open questions	Uncertain, stale, dynamic, or cross-repository facts	Stops inference from becoming a silent decision

Store durable commands, conventions, ownership, and review requirements in maintained project memory. Qoder CLI supports project AGENTS.md, machine-local AGENTS.local.md, and focused .qoder/rules files. Store the active task packet separately so temporary paths, logs, and hypotheses do not become permanent instructions.

When relationships are expensive to rediscover, a separately maintained repository index or knowledge graph can supply a shared query layer. The graph is external evidence, not automatic Qoder AI agent memory. Every important edge should identify its source and indexed revision, and the receiving agent should inspect current code before acting.

The broader shared-context workflow for coding agents explains how to keep common evidence portable across tools. The Qoder CLI context-engineering guide owns the underlying memory and document layers.

Split Planning, Implementation, Testing, and Review Context

Give every Qoder agent one responsibility and the least context needed to fulfill it.

Role	Receives	Produces	Recommended boundary
Planning	Objective, revision, architecture records, relationship leads	Impact map, candidate files, risks, test plan, unresolved questions	Read and search tools; no source edits
Implementation	Approved plan, exact paths, constraints, acceptance conditions	Focused patch, changed-path list, deviations, local validation	Edit only approved areas; isolated worktree for parallel edits
Testing	Patch or commit, impact map, test commands, known risks	Reproducible results, uncovered paths, failures, environment notes	Read plus approved test commands; no product-code changes by default
Review	Original objective, approved plan, diff, test evidence, open risks	Findings, evidence links, approval or required revisions	Read-only source and diff inspection

Qoder CLI supports project-level Subagent definitions under .qoder/agents/*.md and user definitions under ~/.qoder/agents/*.md. The current /agents interface and qodercli agents list show what the installed version discovered. Built-in roles can vary by version and enabled features, so a workflow should refer to verified role names instead of assuming a universal list.

The role prompt should say what information the Subagent receives and what its response must contain. For example, an implementation handoff should require changed files, decisions made, assumptions, commands run, failures, and any departure from the approved plan. A final answer that says only “done” is not a usable context transfer.

Do not pass the planner's private reasoning as authority. Pass its cited findings, unresolved questions, and approved plan. This keeps downstream work auditable and gives another agent enough information to challenge an incorrect conclusion.

Reduce Duplicate Scans and Conflicting Changes

The coordinator should perform one evidence preflight, then distribute role-specific views of the same packet.

Start by locking the revision, objective, ownership, and acceptance criteria. Ask a read-only planning role to locate evidence and mark uncertainty. After approval, freeze a plan identifier or digest so implementation and review can confirm they are evaluating the same scope.

For parallel work, divide by non-overlapping ownership rather than by arbitrary file count. Qoder Subagents can use isolation: worktree, which gives an editing role a separate Git worktree. Worktree isolation reduces accidental file collisions; it does not make two architectural decisions compatible. Assign one integration owner to order changes, resolve overlapping contracts, and decide which result becomes canonical.

A compact handoff log should record:

1. task and plan identifiers;
2. source and output revisions;
3. agent role and effective tool boundary;
4. evidence inspected and key findings;
5. files changed or tests executed;
6. assumptions, failures, and unresolved questions;
7. next owner and required decision.

Reuse verified relationship queries rather than copying large tool transcripts. A graph result can identify a dependency path, while the packet records the path, provenance, and files checked. The next agent can validate the claim without repeating the entire scan.

For a product-neutral design across many parallel workers, see agent swarm codebase context. The Qoder-specific workflow remains smaller: use discovered Subagents, explicit packets, scoped tools, and one accountable coordinator.

Permission and Drift Risks

Shared evidence reduces repeated work, but it can also spread a wrong assumption faster.

Use these safeguards:

• Pin the snapshot. Put the repository revision and packet timestamp in every handoff.
• Mark authority. Separate current source, approved decisions, generated graph findings, test output, and model inference.
• Limit tools. Configure each Subagent with the tools required for its role; do not give a reviewer write access by habit.
• Check permission inheritance. If a Subagent omits its permission mode, Qoder documents that it inherits the current parent mode. Inspect the effective boundary rather than trusting a prompt label.
• Protect parallel edits. Use worktrees for independent implementation tasks and inspect every returned diff before integration.
• Expire task context. Close or refresh packets when the source revision, architecture, ownership, or acceptance criteria change.
• Re-run evidence. Test output and graph paths should be reproducible from the recorded revision.
• Escalate decisions. Security, data, public contracts, deployment, and cross-team boundaries need the responsible human owner.

Qoder permissions control whether tools can act; they do not prove the correctness of a plan or patch. Likewise, an AGENTS.md instruction is context rather than enforcement. Put mandatory path, command, and tool restrictions in permission rules or Hooks, then verify behavior with tests and review.

Avoid putting secrets, customer data, credentials, or unrelated private material into a shared packet. The coordinator should also exclude speculative reasoning that downstream agents could mistake for an approved fact.

FAQ

What should subagents not share?

Do not share secrets, credentials, customer data, unrestricted environment dumps, private reasoning, unrelated source, or stale conclusions. Keep role-specific scratch output isolated. Share only evidence and decisions needed for the next role, with provenance, revision, authority, and explicit uncertainty.

How should teams log handoffs?

Use a structured record tied to the task and repository revision. Include the role, effective tools and permissions, evidence inspected, findings, changed files, commands and results, assumptions, deviations, open risks, and next owner. Store durable decisions in approved project documentation rather than leaving them only in a conversation transcript.

When should one agent own a decision?

Use one decision owner when parallel tasks touch the same public contract, schema, package boundary, migration order, generated artifact, or deployment sequence. Specialized agents can provide evidence, but the coordinator or responsible human owner should select the canonical plan and integration order.

Conclusion

Qoder Subagents provide useful context isolation, configurable tools and permissions, parallel execution, and optional worktree separation. Those capabilities help divide repository work, but they do not create automatic shared repository knowledge.

Build Qoder subagent context around explicit, revision-locked evidence packets. Give planning, implementation, testing, and review roles different inputs and authority. Log every handoff, refresh stale evidence, inspect worktree diffs, and keep one owner accountable for decisions that cross boundaries.

The decision rule is straightforward: share verified facts and approved constraints, not entire transcripts. If the next role cannot reproduce a claim from the recorded source, it should treat that claim as unresolved.