Last reviewed: 2026-05-14.
Who this is for
This guide is for maintainers who want more than one coding-agent attempt without losing control of the repository. It covers the context files that teach an agent how the repo works and the Git worktree pattern that keeps parallel attempts isolated.
The goal is not to run as many agents as possible. The goal is to make each attempt narrow, auditable, and easy to accept or reject.
Key takeaways
- Context files are part of the product surface for coding agents.
- Put priority order, architecture, required checks, and forbidden side effects in files the agent can read.
- Use Git worktrees when two implementation attempts need separate branches.
- Assign file ownership before parallel work starts.
- Merge only after reviewing each diff and running the acceptance checks.
- Do not parallelize tightly coupled product decisions just because the tooling allows it.
The repository context stack
A coding agent needs enough local truth to avoid guessing. The stack can be small:
| File | Purpose | What the agent should learn |
|---|---|---|
AGENTS.md or equivalent | Non-negotiable rules | Required reading, forbidden commands, secret handling, handoff format. |
README.md | Fast architecture map | Runtime boundaries, main workflows, and where to look next. |
docs/ROADMAP.md | Current direction | Accepted phase gates and things that are intentionally out of scope. |
docs/STATUS.md | Generated readiness report | Current blockers, live state, queue counts, and capability coverage. |
docs/SOP_EXECUTION_LOG.md | Acceptance history | What changed, which checks ran, and what remains unresolved. |
The exact filenames may differ by tool. Anthropic documents project memory and instruction files for Claude Code, while OpenCode documents agent configuration in its own workflow. The durable principle is the same: make the repo teach the agent, then verify the agent’s work with commands.
What belongs in context files
Include operational facts that change agent behavior:
- Current architecture and runtime boundaries.
- Which files are generated and which files are hand-edited.
- Secret-handling rules.
- Required tests, lint checks, build checks, and smoke checks.
- Branching, staging, committing, deploy, and PR expectations.
- Stop conditions for paid actions, production writes, browser automation, domain changes, or destructive commands.
- Known blockers and human inputs.
Leave out real secrets, huge stale logs, private customer data, and aspirational features that look like accepted work. An agent that reads a wish list as a roadmap will implement the wrong thing with great confidence.
Context validation prompt
Before editing, make the agent prove it has the context:
Read the repo instructions, README, roadmap, status report, and execution log.
Name the current runtime boundaries.
Name the files you would touch for this task.
Name the checks you will run.
Do not edit files yet.
If the answer misses a runtime boundary or proposes unrelated cleanup, fix the context or narrow the task. Do not reward a weak context read by giving the agent broader write access.
Parallel agents need ownership
Parallel work becomes dangerous when two agents believe they own the same file. Before delegation, define ownership:
| Ownership item | Example |
|---|---|
| Branch | codex/content-quality-gate |
| Worktree directory | ../comet-satellite-content-quality |
| Write scope | scripts/check_static_content_quality.py and docs only |
| Verification | python3 scripts/check_sop_foundation.py and git diff --check |
| Merge rule | No merge until diff and checks are reviewed |
That ownership table is not bureaucracy. It is the cheapest way to avoid lost work, accidental reversions, and confusing Git state.
Git worktree pattern
Use git worktree when two agents need independent implementation attempts:
git worktree add ../agent-a -b codex/agent-a
git worktree add ../agent-b -b codex/agent-b
Then give each agent a separate target:
- Agent A owns the content quality checker.
- Agent B owns the documentation and status updates.
- Agent C investigates a failing check without writing files.
Each worktree has its own working directory and branch while sharing repository objects. That is cleaner than cloning the repository repeatedly and safer than letting multiple agents write inside one checkout.
When not to parallelize
Do not split work when the next action depends on one result, when two changes touch the same schema, or when the hard part is product judgment. Parallel agents are useful for bounded implementation slices. They are less useful for deciding strategy, naming public APIs, or changing a shared content gate that every publishing path depends on.
If the change is cross-cutting, keep one agent responsible for the final integration. Otherwise each branch can be locally correct and globally incoherent.
Merge discipline
Run this before merging any agent worktree back:
git -C ../agent-a status --short
git -C ../agent-a diff --stat
git -C ../agent-a diff --check
Then inspect the changed files, run the acceptance checks, and copy the final summary into the PR or execution log. Delete a worktree only after the branch is integrated or intentionally abandoned:
git worktree remove ../agent-a
Do not use a worktree as a trash can for unresolved changes. If the branch is rejected, record why so the next agent does not rediscover the same failure mode.
Real failure modes
| Failure mode | What it looks like | Prevention |
|---|---|---|
| Context drift | The agent follows old docs over fresh status | Keep source priority explicit and regenerate status after workflow changes. |
| Shared-file collision | Two agents edit the same script or CSV | Assign file ownership before spawning work. |
| Hidden generated output | A build changes tracked public files unexpectedly | Name generated outputs and require git status --short. |
| Review overload | Five branches arrive with no test evidence | Require each agent to report exact checks and changed files. |
| Stale demo content | A canary page bypasses queue, source, and review ledgers | Require static content quality gates before public builds. |
The last row is now a standing rule for this project: public canaries must be quality-gated. A demo page that gets indexed is no longer just a demo.
Reader next step
Start with the setup and model-routing guide, then use this page to decide whether a second agent should run in a separate worktree. When the implementation is ready, finish with the test repair and PR workflow.
The core CTA target remains intentionally blocked until a human approves it. Do not invent a conversion URL just to make a dashboard look complete.
Sources checked
- Claude Code memory documentation, checked 2026-05-14, for project memory and instruction-file context.
- Claude Code documentation, checked 2026-05-14, for terminal coding-agent workflow context.
- OpenCode documentation, checked 2026-05-14, for terminal agent configuration and operation context.
- Git worktree documentation, checked 2026-05-14, for worktree commands and branch isolation.
- GitHub pull request documentation, checked 2026-05-14, for review and merge workflow context.