OpenCode Configuration Guide: Safety, Quality, and ROI in AI-Assisted Delivery

Why configuration quality matters

AI coding tools are easy to adopt and easy to misuse. In client work, the goal is not maximum automation at any cost. The goal is dependable throughput: faster iteration, fewer avoidable defects, and tighter operational risk controls.

A good configuration acts like an engineering operating model. It encodes who can do what, under what conditions, and with what approval gates.

Core architecture in this setup

The config separates agent identity from agent behavior:

• .opencode/agents/*.md defines each role's purpose, model, and operating instructions.
• .opencode/opencode.jsonc defines behavior controls such as permissions, delegation rules, temperatures, and step budgets.

This split keeps role definitions readable while making enforcement centralized and auditable.

Role design: specialized agents over one "do everything" agent

The stack uses purpose-built roles instead of a single unconstrained assistant:

• Chat for read-only discussion and reasoning.
• Plan for executable implementation plans.
• Build for plan execution and code changes.
• Review as an orchestrator that delegates to code-review, security, and documentation specialists.
• Explore, General, and Scout for scoped support tasks.
• GitHub-read and GitHub-publish for tightly controlled remote operations.

This reduces context switching, gives each model a clear job, and improves review quality because each stage is explicit.

Security and risk controls built into the config

• MCP split by intent: separate read-only GitHub access from a minimal publish surface.
• Tool allowlists: only named MCP tools are exposed, not broad capability groups.
• Global deny-first posture: GitHub tool families are denied by default and re-enabled only per role.
• Approval gates: potentially costly or state-changing actions are set to ask-before-run.
• Destructive command denies: force push, hard reset, clean, and other high-risk commands are blocked.
• Delegation depth limit: subagent depth is constrained to prevent recursive task spawning.

How this improves ROI for real projects

ROI in AI-assisted engineering is mostly operational, not hype-driven. This setup targets three outcomes:

1. Higher throughput: planning, implementation, and review can be decomposed and parallelized safely.
2. Lower rework cost: specialist review catches defects and documentation drift earlier.
3. Reduced blast radius: explicit permissions and approval flows make accidental destructive operations less likely.

The practical effect is predictable cycle time and cleaner handoffs, which is what clients usually value most.

Implementation principles I recommend

• Default deny; then grant only what each role truly needs.
• Keep read and write paths separate for external systems.
• Require human approval for publication and irreversible operations.
• Use role specialization to improve consistency and accountability.
• Document the workflow so teams can audit and evolve it deliberately.

Final note

AI agents are most effective when treated like constrained teammates operating inside an intentional system. The configuration is the system. When built well, it turns AI from novelty into reliable leverage.