Context Engineering for OpenCode

OpenCode context engineering means deliberately controlling what the agent knows, when it loads that knowledge, and which evidence it must verify. Use AGENTS.md for stable rules, instruction files for modular policy, @file for current evidence, skills for procedures, and a maintained graph or MCP tool for repository relationships.

The resulting workflow is easier to audit because each context layer has a named owner, refresh rule, and authority boundary instead of becoming an undocumented accumulation of prompt text.

What Context Engineering Means for OpenCode

Context engineering is not the same as writing a longer prompt. It is the design of the information system around the coding agent.

OpenCode's official documentation exposes several distinct context mechanisms:

• project and global AGENTS.md files;
• /init for generating or improving project guidance;
• opencode.json instruction paths, globs, and remote URLs;
• @file references that add selected files to the conversation;
• on-demand Agent Skills;
• local and remote MCP tools;
• specialized primary agents and subagents;
• automatic session compaction;
• cloud and local model providers, including Ollama and custom OpenAI-compatible endpoints.

Each mechanism has a different job. Problems arise when teams use one mechanism for everything—for example, pasting a repository inventory into AGENTS.md, enabling every MCP server globally, or assuming compaction creates durable project memory.

A useful context design answers five questions:

1. What stable rules should always apply?
2. What current files prove the task's facts?
3. What procedures should load only when relevant?
4. What repository relationships need a query layer?
5. What information must survive a session, model, or agent change?

OpenCode can orchestrate these layers, but its official documentation does not claim a built-in code knowledge graph or durable cross-session semantic repository memory. Those require maintained external artifacts or tools.

What OpenCode Agents Need From a Repo

OpenCode agents need concise rules, trustworthy evidence, and explicit authority boundaries.

The project-root AGENTS.md should contain stable information that future sessions are likely to need: build and test commands, architecture that is not obvious from filenames, project conventions, setup quirks, and operational warnings. OpenCode's /init command scans important files and can create or improve this guidance. Treat the generated result as a draft to review, not an infallible architecture model.

Current task evidence should come from current files and commands. OpenCode's TUI supports @file references: selecting a file adds its contents to the conversation. This is useful when the operator knows the likely source. It is less useful when the problem is discovering which file matters.

Skills package reusable procedures. OpenCode discovers SKILL.md definitions from .opencode/skills, .claude/skills, and .agents/skills at project and global scopes. A migration skill can define review steps and verification commands without loading that procedure into every conversation.

Agents also need permission boundaries. OpenCode distinguishes a Build agent with broad tools from restricted planning and read-only exploration roles. For a repository-wide change, start with a read-only exploration or planning pass, require a dependency explanation, and only then allow edits.

Finally, define source authority. A practical order is:

1. current source, schema, and tests;
2. approved architecture decisions and operational policy;
3. generated repository reports and graphs;
4. temporary task notes and model inference.

This order prevents a stale summary from overruling the code it was meant to describe.

For team use, record which layer supported each important planning claim. That small provenance trail makes review faster and exposes when an agent is relying on a remembered convention instead of current repository evidence.

Organize Architecture and Dependency Context

Keep architecture context modular and load it by need.

OpenCode's instructions configuration can include files and glob patterns such as CONTRIBUTING.md, architecture guidelines, testing standards, or package-specific AGENTS.md files. It can also load remote instruction URLs. Remote rules should be pinned or governed because their contents can change outside the repository review process.

A strong repository layout might use:

AGENTS.md
docs/
  architecture/
    index.md
    request-flow.md
    data-boundaries.md
  decisions/
    001-auth-ownership.md
  operations/
    migrations.md
    rollback.md
.opencode/
  skills/
    api-change/
      SKILL.md

The root rules file tells OpenCode where to look. Architecture files explain system intent. Decision records preserve rationale. Skills describe task workflows. Current code confirms whether the documents still match reality.

Dependency context should support questions rather than only diagrams. For every repository-wide plan, require the agent to report:

• entry point;
• downstream dependency path;
• data or schema boundary;
• generated artifacts;
• tests and verification commands;
• uncertain or stale evidence.

That report gives a human reviewer something concrete to approve.

Avoid loading every document at startup. OpenCode's own rules documentation recommends modular instruction patterns, and its MCP documentation warns that tool descriptions can consume enough context to exceed the model limit. Context should be available, not permanently resident.

Use Graphs for Planning and Impact Analysis

A code graph adds a queryable relationship layer when file references and static documents are not enough.

Useful graph entities include packages, files, symbols, routes, schemas, tests, and architecture documents. Relationships can capture imports, calls, generation, coverage, ownership, and rationale. OpenCode can query the graph before selecting source files for detailed inspection.

Graph-guided planning narrows the search, while source verification and approval control the change.

Graphify supports this pattern through generated graph artifacts, CLI queries, and MCP. Its CLI reference documents graphify opencode install, which writes project guidance to AGENTS.md, along with query, path, explain, update, watch, and MCP commands.

An OpenCode planning procedure can be:

1. Query the graph for the requested entity or behavior.
2. Trace direct and cross-package relationships.
3. Identify the source files and tests behind each important edge.
4. Open those current files.
5. Flag stale, inferred, or ambiguous graph evidence.
6. Ask for approval before repository-wide edits.
7. Run focused tests, then broader verification.

This workflow improves impact analysis without claiming that the graph replaces source inspection.

MCP is one integration option. OpenCode supports local and remote MCP servers, but its documentation notes that each server adds tool information to context. Enable only the graph tools needed for the active agent or workflow. A large global tool catalog can erase the context savings the graph was meant to create.

The graph also supports model independence. An OpenCode workflow using a local Ornith model through Ollama can query the same repository structure as a cloud-model workflow. Model changes then affect reasoning and tool performance without forcing the team to rebuild project knowledge from scratch.

Limits and Maintenance Risks

The main context-engineering risks are staleness, overexposure, and false authority.

Staleness: Review AGENTS.md when commands, architecture, or workflow constraints change. Refresh graphs after structural merges. Put a source commit and generation time on generated artifacts.

Overexposure: Do not load secrets, customer data, production credentials, or unrelated private documents. Scope MCP tools and agent permissions to the task.

Instruction drift: Remote instruction URLs and globally installed skills can change outside a project pull request. Pin sources where possible and audit updates.

Context inflation: More MCP servers, tool output, and instructions can reduce the room available for the task. OpenCode supports automatic compaction and optional pruning, but compaction is context management, not durable memory.

Local-model assumptions: OpenCode supports Ollama and custom OpenAI-compatible providers. That establishes configuration compatibility, not reliable coding performance. Test tool calling, patch quality, refusal behavior, latency, and context use on your own repository.

Unreviewed authority: A graph edge or generated summary can be wrong. Require provenance and direct-source confirmation before an edit. Assign a human approver for repository-wide changes, especially those involving security, schemas, dependencies, or deployment.

FAQ

What context should be shared across tasks?

Share stable commands, repository conventions, architecture decisions, ownership boundaries, generated-file rules, and a maintained structural map. Keep transient logs, speculative hypotheses, and task-specific file dumps inside the task unless they produce an approved decision.

Who should approve repository-wide changes?

Use the owner of the affected architectural boundary, not only the person operating OpenCode. Security, data, API, and deployment changes may require separate reviewers. The approval should cover the dependency path and verification plan as well as the diff.

How can teams avoid stale context?

Tie reviews and graph refreshes to repository events: package moves, schema migrations, route changes, dependency updates, generated-code changes, and revised architecture decisions. Record the source revision and refuse to trust context older than the paths being changed.

Conclusion

OpenCode provides the pieces for disciplined context engineering, but teams must assign each piece a clear role.

Use AGENTS.md for stable rules, modular instructions for policy, @file for exact evidence, skills for repeatable procedures, MCP for carefully scoped tools, and a maintained graph for dependency and impact questions. Use compaction to manage session pressure, not as a substitute for repository memory.

The decision rule is simple: if context cannot show its source, freshness, and authority, OpenCode should treat it as a lead to verify—not a fact to edit against.