# Instructions

Add an `AGENTS.md` file to give OpenCode persistent project guidance. Use it for build commands, architecture notes, code conventions, and verification requirements.

```md title="AGENTS.md"
# Project instructions

- Run `bun typecheck` after changing TypeScript.
- Keep database queries in `src/database`.
- Do not edit generated files directly.
```

Commit project instruction files so everyone working in the repository receives the same guidance.

## Scope

Place `AGENTS.md` in the directory where its guidance should apply. OpenCode loads the global file followed by every `AGENTS.md` from the current workspace directory toward the home directory. For workspaces outside the home directory, it stops at the project root.

```text
~/.config/opencode/AGENTS.md
~/code/my-project/AGENTS.md
~/code/my-project/packages/AGENTS.md
~/code/my-project/packages/web/AGENTS.md  ← current workspace
```

In this example, all four files are loaded. They are combined in this order:

```text
~/.config/opencode/AGENTS.md
packages/web/AGENTS.md
packages/AGENTS.md
AGENTS.md
```

Keep guidance that applies everywhere in the global file. Put repository-wide guidance at the project root and more specific guidance closer to the code it covers. OpenCode combines the files and does not resolve conflicts between them.

If the workspace is outside the project root, only the global file is loaded. Set `OPENCODE_DISABLE_PROJECT_CONFIG=1` to skip project `AGENTS.md` discovery without disabling the global file.

<Callout type="note">
  OpenCode V2 recognizes `AGENTS.md` only. It does not use `CLAUDE.md` as a fallback.
</Callout>

## Discovery

Instruction files below the workspace are discovered as the agent explores the project. Reading a file or listing a directory loads any `AGENTS.md` files between that target and the workspace.

```text
my-project/                         ← current workspace
├── AGENTS.md                       loaded initially
└── packages/
    └── web/
        ├── AGENTS.md               loaded when this area is read
        └── src/
            └── app.ts              read target
```

Nested files are loaded nearest-first and deduplicated while their instruction entry remains in model-visible history. Reading the same area again does not normally inject them again. If compaction or a revert removes that entry, a later read can load the file again.

Edits to a nested file are not detected automatically after it loads. Start a new session when updated text must apply immediately.

## Ordering

The selected agent or provider system prompt is sent first. OpenCode then assembles initial instructions in this order:

```text
1. Agent or provider system prompt
2. Code Mode tool guidance, when enabled
3. MCP server, reference, and skill guidance
4. Global and project AGENTS.md files, then configured instructions
5. Built-in date and environment context
6. Session-specific instruction entries supplied through the API
```

These sources are combined rather than used as overrides. Nested `AGENTS.md` files discovered later are added to session history in discovery order.

## Updates

Edit a global or upward-discovered `AGENTS.md` while a session is running to update its guidance.

```bash
$ printf '\n- Run the integration suite before committing.\n' >> AGENTS.md
```

Before the next model request, OpenCode detects the change and adds an instruction update before delivering pending input:

```text
AGENTS.md changes
→ instruction update
→ next prompt
```

- Removing every ambient `AGENTS.md` tells the session that the previous ambient instructions no longer apply.
- A temporary read failure preserves the last known instructions instead of treating them as deleted.
- Moving a session retains its instruction state, so guidance at the destination is introduced as an update.
- Committing a session revert clears its instruction state and reloads instructions before the next prompt.

Instruction values remain privileged. Clients can see which sources changed, but not their contents.

## Configuration

Use the `instructions` array to add files, glob patterns, or HTTP(S) URLs alongside discovered `AGENTS.md` files:

```jsonc title="opencode.jsonc"
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines/*.md",
    "~/rules/opencode.md",
    "https://example.com/instructions.md",
  ],
}
```

Configured instructions load after `AGENTS.md` files, in the order they are listed. Entries from every config document are combined.

| Entry                   | Resolution                                                           |
| ----------------------- | -------------------------------------------------------------------- |
| Relative path or glob   | Searched in each directory from the workspace up to the project root |
| `~/` path               | Resolved from your home directory                                    |
| Absolute path           | Used as written; the file name may be a glob                         |
| `http://` or `https://` | Fetched when config loads, with a five-second timeout                |

- Local files update like `AGENTS.md` when they change. New files matching a glob load on the next config change.
- Missing files are skipped. A URL that cannot be fetched is skipped, or keeps its last fetched content.
- With `OPENCODE_DISABLE_PROJECT_CONFIG=1`, or when the workspace is outside the project, relative entries resolve against the global config directory.

A connected [OpenCode Console](/console) workspace can also share instructions.

See [Config](/config) for configuration locations and precedence.