mirror of
https://github.com/anomalyco/opencode.git
synced 2026-07-13 16:48:29 +00:00
124 lines
4.7 KiB
Text
124 lines
4.7 KiB
Text
---
|
|
title: "Instructions"
|
|
description: "Give OpenCode global, project, and directory-specific guidance."
|
|
---
|
|
|
|
Instructions are privileged context that guide an agent throughout a session.
|
|
V2 combines built-in context, discovered `AGENTS.md` files, and dynamic sources
|
|
such as skill, reference, MCP, and session context into a durable instruction
|
|
baseline.
|
|
|
|
## AGENTS.md
|
|
|
|
Use `AGENTS.md` for persistent guidance such as build commands, architecture,
|
|
code conventions, and verification requirements. Commit project files so the
|
|
whole team receives the same instructions.
|
|
|
|
V2 loads:
|
|
|
|
1. The global file at `$XDG_CONFIG_HOME/opencode/AGENTS.md`, normally
|
|
`~/.config/opencode/AGENTS.md`.
|
|
2. Every `AGENTS.md` from the current Location up to and including the project
|
|
root.
|
|
|
|
For example, when the Location is `packages/web`, OpenCode can load all three
|
|
project files below:
|
|
|
|
```text
|
|
my-project/
|
|
├── AGENTS.md
|
|
└── packages/
|
|
├── AGENTS.md
|
|
└── web/
|
|
└── AGENTS.md
|
|
```
|
|
|
|
The files are combined rather than selecting a single winner. They are rendered
|
|
in this order: global, then project files from the Location toward the project
|
|
root. OpenCode does not resolve conflicts between their contents, so keep broad
|
|
guidance global and put scoped guidance in the relevant project directory.
|
|
|
|
If the Location is outside the project root, only the global file is loaded.
|
|
Setting `OPENCODE_DISABLE_PROJECT_CONFIG=1` also skips project `AGENTS.md`
|
|
discovery but does not disable the global file.
|
|
|
|
<Note>
|
|
Current V2 discovery only recognizes `AGENTS.md`. The `CLAUDE.md` fallback
|
|
and related precedence described by older OpenCode documentation do not apply.
|
|
</Note>
|
|
|
|
### Nested instructions
|
|
|
|
An `AGENTS.md` below the Location is not part of the initial upward scan. When
|
|
the read tool successfully reads a file or lists a directory, OpenCode discovers
|
|
`AGENTS.md` files from that target upward to, but not including, the Location.
|
|
It adds newly discovered files to the session in nearest-first order.
|
|
|
|
Each nested file is injected once per session and recorded in durable session
|
|
history. Reading the same area again does not inject it again. Consequently,
|
|
editing an already injected nested `AGENTS.md` does not replace its earlier
|
|
session entry automatically; start a new session if the updated text must apply
|
|
immediately.
|
|
|
|
## Config entries
|
|
|
|
The V2 config schema accepts an `instructions` array of strings:
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"instructions": [
|
|
"CONTRIBUTING.md",
|
|
"docs/guidelines/*.md",
|
|
"https://example.com/shared-instructions.md"
|
|
]
|
|
}
|
|
```
|
|
|
|
Configuration is loaded from global through project-local files. If more than
|
|
one config defines `instructions`, the highest-precedence, closest config's
|
|
entire array is selected; arrays are not merged.
|
|
|
|
<Warning>
|
|
V2 currently parses and retains this field but does not resolve its entries
|
|
into instruction sources. Local files, glob patterns, and HTTP or HTTPS URLs
|
|
in `instructions` therefore do not reach the model yet. Use `AGENTS.md` for
|
|
active V2 instructions. URL fetching and timeout behavior documented for V1
|
|
are not supported by the current V2 implementation.
|
|
</Warning>
|
|
|
|
See [Config](/config) for config locations and general precedence.
|
|
|
|
## Ordering
|
|
|
|
The selected agent or provider system prompt is sent first. OpenCode then sends
|
|
the session's instruction baseline, composed in this order:
|
|
|
|
1. Built-in environment and date context.
|
|
2. Ambient `AGENTS.md` discovery.
|
|
3. Available skill, reference, and MCP guidance.
|
|
4. Session-specific instruction entries supplied through the API.
|
|
|
|
These sources are combined; ordering is not an override mechanism. Nested
|
|
`AGENTS.md` files discovered by reads are chronological session entries rather
|
|
than part of the baseline.
|
|
|
|
## Changes
|
|
|
|
Before each model step, V2 compares live instruction sources with what that
|
|
session's model was last told:
|
|
|
|
- A new or changed ambient `AGENTS.md` aggregate is announced as a system update
|
|
that replaces the previous ambient aggregate.
|
|
- Removing all ambient files announces that the previous ambient instructions
|
|
no longer apply.
|
|
- A temporary read or discovery failure preserves the session's last known
|
|
instructions instead of treating them as deleted. If no baseline exists yet,
|
|
the first model step waits until required sources are available.
|
|
- Completed conversation compaction creates a fresh baseline from the current
|
|
sources. Moving a session or committing a revert also resets its instruction
|
|
checkpoint so the next step establishes a new baseline.
|
|
|
|
Updates are durable session history. OpenCode does not rewrite the original
|
|
baseline on every change; it records the change so subsequent model steps see
|
|
both the established baseline and the chronological update.
|