How to Build a Production-Ready AI Agent Harness with OpenCode
OpenCode is an open-source AI coding agent that supports 75+ LLM providers, MCP server integrations, and allows self-hosting, making it a flexible alternative to proprietary coding harnesses like Claude Code and Cursor The core problem addressed is "AI slop" — developers waste hours fixing poorly generated code because they haven't customized their AI harness to their specific domain, architecture, and constraints AGENTS.md is the most critical configuration file: it defines project rules, archi
Analysis
TL;DR
- OpenCode is an open-source AI coding agent that supports 75+ LLM providers, MCP server integrations, and allows self-hosting, making it a flexible alternative to proprietary coding harnesses like Claude Code and Cursor
- The core problem addressed is "AI slop" — developers waste hours fixing poorly generated code because they haven't customized their AI harness to their specific domain, architecture, and constraints
- AGENTS.md is the most critical configuration file: it defines project rules, architecture principles, stack references, and explicit prohibitions that the agent must follow in every session
- MCP (Model Context Protocol) servers extend OpenCode's capabilities with external tools (GitHub, Supabase, etc.), but should be selectively enabled to avoid bloating the context window
- A production-ready template repository has been published that bundles the recommended architecture, including custom agents (e.g., @security-auditor), skills system, and a granular permissions model
Why It Matters
This guide addresses a growing pain point in AI-assisted development: the gap between raw LLM capability and production-grade code quality. As more developers adopt agentic coding tools, the differentiator is no longer access to an AI — it's how well the harness is configured for the specific project. The OpenCode harness architecture provides a replicable, open-source blueprint that any team can adopt to reduce AI-generated errors, enforce domain safety, and streamline onboarding.
Technical Details
- OpenCode Architecture: Terminal/IDE/desktop-based AI coding agent with a TUI, supporting 75+ LLM providers (Anthropic, OpenAI, OpenRouter, local models). Configurations are merged across multiple precedence levels: remote (.well-known/opencode), global (~/.config/opencode/opencode.json), custom (env var $OPENCODE_CONFIG), and project-level (opencode.json in project root).
- AGENTS.md System: A rules file automatically loaded into every session, containing project overview, architecture principles, stack references, key design decisions, and explicit "what NOT to do" prohibitions. It takes precedence over global configs and can reference external files via lazy-loading to conserve tokens.
- MCP (Model Context Protocol) Integration: Enables external tool access (GitHub, Supabase, Cloudflare, etc.) through configurable servers. Heavy servers like GitHub are recommended to be disabled globally and enabled per-agent to manage context window costs. Configuration uses
{env:VAR}syntax for secrets. - Custom Agents & Skills: Five built-in agents (build, plan, general, explore, scout) plus support for custom agents defined in
.opencode/agents/. Skills are reusable knowledge chunks stored asSKILL.mdfiles in.opencode/skills/, loaded on-demand rather than pre-loaded, covering database schemas, API contracts, and domain-specific reference material. - Permissions Model: Granular permission system with defaults of "allow" for most operations but "ask" for
doom_loopandexternal_directory..envfiles are hard-blocked by default. Best practice recommends settingbashcommands to "ask" with specific allowlists for safe commands likegit status,git log, andnpm run.
Industry Insight
- The shift from "prompt and hope" to "configure and constrain" represents a maturation in AI-assisted development. Teams that invest in proper harness configuration (AGENTS.md, custom agents, MCP scoping) will see dramatically higher ROI from agentic tools, while those that don't will continue burning time on AI-generated code rework.
- Open-source coding harnesses like OpenCode are emerging as a strategic counterweight to proprietary tools (Claude Code, Cursor, Codex), offering flexibility, self-hosting, and vendor-agnostic LLM support — critical for organizations with security, compliance, or cost constraints.
- The skills and lazy-loading pattern described here is likely to become a standard architectural pattern across AI coding tools, as token efficiency and context management become increasingly important with growing codebase sizes and multimodal tool integrations.
Disclaimer: The above content is generated by AI and is for reference only.