This lesson's interactive features are locked, please to keep using them
AGENTS.md
It gets super tiresome to give the same instructions to your agent every time you start a new session.
The good news is you can keep your project-specific instructions in an AGENTS.md file so you don't need to copy and paste them every time!
Click to play video
Where It Lives
OpenCode automatically looks for AGENTS.md in two places:
- Project-level: OpenCode starts from your current working directory and walks up to your home directory. If your project is outside of your home directory, the search stops at the project root instead. So, if you start OpenCode in
~/project/src/and have a~/project/src/AGENTS.mdfile and another at the project root~/project/AGENTS.md, both get loaded. - Global: at
~/.config/opencode/AGENTS.md. This is for personal defaults you want across all your projects (like "Always leave changes unstaged for my review" or "You can find examples of my writing style in~/prose").
Project-level rules and global rules are combined, not replaced. The agent sees all of them.
Most agents (even Claude, finally) support AGENTS.md, but many also have their own agent-specific instructions files, like CLAUDE.md. Same exact idea, different filename.
Example
In true dog-fooding form, the OpenCode team uses OpenCode to build OpenCode, and the OpenCode repo is an S-tier example of how to use AGENTS.md files. Review an excerpt from their project-level AGENTS.md in the "Tip" section at the bottom of this page.
I like to write bullet-point-style rules, but then also list concrete examples of "good" and "bad" code that illustrate the rules. The more specific you can be, the better the agent will comply.
Assignment
Generate Sloperator's project instructions.
Tell OpenCode to run and submit the CLI tests from the project root.
Tip
At the time of writing, this is a shortened excerpt from the project-level AGENTS.md in the OpenCode repo.
- After changing the public Protocol or Server `HttpApi`, run `bun run generate` from `packages/client`. Do not edit generated client files directly.
- Keep runtime dependencies directed from Schema to Core and Protocol, then from Core and Protocol to Server. Client runtime code may depend on Schema and Protocol but never Core or Server; `sdk-next` composes Client, Core, and Server.
- The default branch in this repo is `v2`.
- Base all new branches and worktrees on `v2`, or `origin/v2` when the local `v2` ref is unavailable. Do not base them on `dev`.
- Local `main` ref may not exist; use `v2` or `origin/v2` for diffs.
## Branch Names
Use a short branch name of at most three words, separated by hyphens. Do not use slashes or type prefixes like `feat/` or `fix/`.
Examples: `session-recovery`, `fix-scroll-state`, `regenerate-sdk`.
## Style Guide
### General Principles
- Keep things in one function unless composable or reusable
- Avoid `try`/`catch` where possible
- Avoid using the `any` type
- Use Bun APIs when possible, like `Bun.file()`
- Rely on type inference when possible; avoid explicit type annotations or interfaces unless necessary for exports or clarity
- Prefer functional array methods (flatMap, filter, map) over for loops; use type guards on filter to maintain type inference downstream
```ts
// Good
const journal = await Bun.file(path.join(dir, "journal.json")).json();
// Bad
const journalPath = path.join(dir, "journal.json");
const journal = await Bun.file(journalPath).json();
```
## Testing
- Avoid mocks as much as possible, you shouldn't be using globalThis.\* at all unless it's the only option.
- Test actual implementation, do not duplicate logic into tests
- Tests cannot run from repo root (guard: `do-not-run-tests-from-root`); run from package directories like `packages/core`.
## Type Checking
- Always run `bun typecheck` from package directories (for example, `packages/core`), never `tsc` directly.