Project context and instruction files

Initialize project context, keep standing instructions in AGENTS.md, and use nested context files so guidance arrives where it applies.

Initializing and where files live

# from the project root, inside a session
/init
# OpenCode inspects the repository and writes an AGENTS.md you then edit

# global guidance, applied to every project
~/.config/opencode/AGENTS.md

# project guidance, committed with the repository
./AGENTS.md

/init produces a starting point, not a finished file. Delete most of it; keep the commands and the prohibitions.
The global file is for preferences that follow you - preferred test runner, commit style, how much explanation you want.
The project file is the one teammates read, so it is also the right place to record decisions that would otherwise be rediscovered every session.

# AGENTS.md

## Commands
- Install: pnpm install
- Dev server: pnpm dev
- Tests: pnpm test -- --run
- Types: pnpm typecheck
- Lint: pnpm lint --max-warnings 0

## Layout
- apps/web - Next.js front end
- packages/core - shared domain logic, no framework imports
- packages/db - Drizzle schema and migrations

## Rules
- Never edit packages/db/migrations directly; generate them.
- Server code never imports from apps/web.
- Every new endpoint needs a request schema and a test.

Nested context files

An AGENTS.md in a subdirectory applies to work in that subtree. That keeps a package's conventions next to the package instead of swelling the root file with guidance that only matters in one place.

packages/core/AGENTS.md

# Core package rules

- Pure TypeScript only. No Node built-ins beyond node:assert in tests.
- Public API is whatever src/index.ts exports; everything else is internal.
- Adding an export is a breaking-change review, not a refactor.
- Money is integer minor units with an explicit currency. Never a float.

Level	Path	Applies to
Global	`~/.config/opencode/AGENTS.md`	Every project you open
Project	`./AGENTS.md`	The whole repository
Nested	`packages/core/AGENTS.md`	Files under that directory
Explicit	`instructions` in the config	Any file you name

💡

Context files are read at the start of a session. Editing one in another window will not change a running session, so finish or restart before relying on a new rule - otherwise you will conclude the agent is ignoring instructions it has never seen.

Pulling in existing documentation

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/architecture.md",
    "docs/api/*.md"
  ]
}

Reuse documents you already maintain rather than copying them into AGENTS.md, where they will drift.
Every file listed here is loaded on every session, so keep the set small and the files current.
A stale instruction file is worse than none: the agent will confidently follow a rule you removed months ago.

# sanity check: what does the agent actually see?
opencode run --agent plan "List every instruction file currently in context, then stop."

# how much does your context cost?
/context

FAQ

AGENTS.md or a custom command?

AGENTS.md is always loaded and shapes every turn, so it should hold only what applies broadly. A command under .opencode/command is loaded when you invoke it, so put repeatable procedures there. Keeping the always-on file short is what keeps it effective.

Can I share the same setup across several repositories?

Put the shared parts in the global config and global AGENTS.md, and keep repository-specific commands and rules in each project. A shared plugin or command directory can also be installed from npm, which avoids copying files between repositories.

Plan mode versus build mode Skills, plugins and custom commands

Last refreshed 2026-09-18.

Project context and instruction files

Initializing and where files live

Nested context files

Pulling in existing documentation

FAQ

Related