OpenCode Agents Guide: 7 Checks for Subagents and AGENTS.md

The short answer: use AGENTS.md for repository-wide instructions and use OpenCode agents when you need a named specialist with its own prompt, model, tools, and safety boundary. Start with one agent, verify it with a read-only task, then allow write-capable tools only after the diff and rollback path are clear.

AGENTS.md is best for durable repository instructions: test commands, coding style, generated folders, review expectations, and project warnings every assistant should see. It is not the right place to describe every specialist workflow because broad instructions become hard to maintain and can overconstrain unrelated tasks.

OpenCode agents are better for role-specific behavior. Use them when the task needs a narrower system prompt, a different model, a limited tool set, or a repeatable role such as reviewer, planner, documentation editor, or migration helper. This keeps the main coding flow simple while still giving advanced work a controlled path.

A subagent is useful when the main task has a separable concern: inspect a large folder, review a risky diff, research an API, or prepare a migration checklist. If the work is a single small edit, a subagent usually adds overhead rather than clarity.

The strongest pattern is a named specialist with an explicit output contract. For example, a review agent can return findings with file references, while a docs agent can return a short patch plan and the exact pages affected. Avoid vague roles such as helper, genius, or general expert because they do not constrain behavior.

Use a stronger reasoning model for review, architecture, security-sensitive reasoning, and migration planning. Use a cheaper or faster model for summarizing files, formatting notes, or drafting simple documentation. The point is not to make every agent powerful; it is to make each agent predictable for its job.

Tool access should be narrower than the main session whenever possible. A documentation agent may only need read access and file edits in docs. A testing agent may need shell access but not secret files. A research agent may need network access but not write permission. Smaller tool sets reduce accidental changes and make failures easier to diagnose.

Team configuration belongs in files that developers can review, but secrets do not. Keep API keys, provider tokens, private endpoints, and service credentials in environment variables or the provider's credential flow. If an agent requires a token-backed tool, document the variable name and required scope instead of committing the value.

Use stable names. A name such as reviewer or docs-editor makes logs, prompts, and incident notes understandable months later. When a role is experimental, leave it disabled or document when it should be used rather than loading it into every normal session.

The first validation should not touch production code. Ask the agent to explain a file, list assumptions, or review a small existing diff. Confirm that it follows the role, stays inside the intended scope, and returns the output format you expected.

After that, allow a small write task and inspect the Git diff. If the agent changes unrelated files, ignores instructions, uses the wrong command, or cannot explain its edits, fix the prompt or tool boundary before using it in a larger repository.

1. Name the roleUse a clear name such as reviewer, planner, docs-editor, or migration-checker.
2. Write the output contractDescribe what the agent should return and what it must not do.
3. Pick the modelMatch reasoning depth and cost to the role's risk.
4. Limit toolsStart with the smallest tool set that can complete the job.
5. Run read-only validationAsk for explanation, inspection, or review before allowing edits.
6. Inspect a small diffApprove broader use only after the first write task is clean.
7. Record the ruleDocument when the agent should be used and when the main session is enough.

The most common mistake is creating too many agents before one of them has proven useful. Each extra role adds mental overhead for the developer and can create routing confusion. Start with one practical role, record the successful task, then add another only when a repeated workflow justifies it.

Another mistake is mixing AGENTS.md instructions with role-specific agent rules. Keep repository facts in AGENTS.md and role behavior inside the agent. If the same instruction appears in both places, future edits can drift and the model may receive conflicting guidance.

Agents become more valuable when combined with narrow integrations. A reviewer may use read-only GitHub or issue context through MCP. A release agent may rely on hooks that run checks before handoff. A docs agent may reuse a writing skill. The integration should serve the role instead of making the role broader.

When an integration can mutate files, issues, databases, or production systems, add one layer at a time. First prove the agent prompt, then the tool, then the write path. This sequence makes it clear which layer failed and protects the repository from a configuration that looks convenient but is difficult to audit.

{
  "agents": {
    "reviewer": {
      "model": "provider/reasoning-model",
      "description": "Review diffs and return concrete findings only",
      "tools": ["read", "grep"]
    },
    "docs-editor": {
      "model": "provider/fast-model",
      "description": "Update documentation after source changes",
      "tools": ["read", "edit"]
    }
  }
}

Team configuration belongs in files that developers can review, but secrets do not. Keep API keys, provider tokens, private endpoints, and service credentials in environment variables or the provider's credential flow. If an agent requires a token-backed tool, document the variable name and required scope instead of committing the value.