Rules (AGENTS.md)

Every coding agent has a memory problem, and it is structural: nothing carries over on its own. A new OpenCode session does not inherit what you told it in earlier sessions; each new session starts from what it can read in your repository plus whatever you type again. feedmill - the course’s illustrative scenario, a small self-hosted Go feed aggregator that pulls RSS, Atom, and JSON feeds into one reading queue - makes the problem concrete, because its conventions are real but mostly unwritten. Ask OpenCode to add a new feed source and it may write a fetch loop that hammers the upstream server with no delay between requests. Ask it to record when an item was last seen and it may store a local-time time.Time straight into the queue, even though everything else in feedmill is UTC and the dedupe logic quietly depends on that. The agent isn’t getting dumber. It has no memory of the project’s hard-won rules, because those rules live in your head and in scattered review comments, not anywhere it can read.

This chapter fixes that the durable way: you write the rules down once, in a file OpenCode reads on every session. That file is AGENTS.md - and the thing worth knowing up front is that it’s not an OpenCode invention. It’s the agents.md open standard, whose adopter list names both OpenCode and Codex (alongside Cursor, Zed, Gemini CLI, and others) as of September 2026, so the same file travels across tools with no changes. If feedmill ever passes through a teammate on Codex, the rules travel with the repo untouched. OpenCode has no separate “rules file” of its own; AGENTS.md is the rules layer, and a project CLAUDE.md is read only as a fallback when no AGENTS.md exists (rules documentation).

Writing rules that actually load

We’ll turn the mistakes above into rules that load in every session, then push on the edges of how OpenCode finds and loads those rules - because feedmill is a self-hosted Go project with parsers and a sync server in subdirectories, and the discovery behavior has teeth you’ll hit in a real repo. The chapter’s pages:

• Write feedmill’s first AGENTS.md - capture the politeness delay and the UTC rule as project rules, plus a personal rule or two that follow you across every repo - Write feedmill’s AGENTS.md
• Learn how OpenCode finds the file - the walk-up from where you start OpenCode that loads every AGENTS.md up to the repo root, why a subdirectory’s file can be missing when you start above it, and why project and global user rules combine - Discovery and the nesting walk
• Point at more instruction files - split long-lived conventions out of AGENTS.md using the instructions field in opencode.json (OpenCode’s config file), and meet the sharp edge that @path imports (Claude Code’s file-include syntax) are not automatically parsed by OpenCode - Point at more instruction files

The reason to do this as one continuous task, rather than dropping a quick AGENTS.md in the root and moving on, is that the discovery rules decide whether your rules actually fire. A perfectly written file in the wrong place - or a nested file that is not loaded at startup because you started OpenCode above it - or a reference with an @path OpenCode never parses - is rules the agent reads in the wrong scope, or never reads at all, which is worse than no rules, because you think you’re covered. By the end you’ll have feedmill’s conventions written once, loading reliably from the right place, and split across files in a way that scales as the project grows - so the next time you add a feed source, the politeness delay and the UTC timestamp are already in the agent’s context instead of depending on you to repeat them. Those rules are guidance, not enforcement: the model usually follows them, but nothing stops an edit that breaks one. Where a slip corrupts data quietly, as a local-time timestamp breaks dedupe, back the rule with a test that fails on it.