Skip to content
agents.cli

Rules (AGENTS.md)

You’ve already watched it happen. You ask OpenCode to add a new feed source, and it writes a fetch loop that hammers the upstream server with no delay between requests — the exact politeness gap you fixed by hand two sessions ago. You ask it to record when an item was last seen, and it stores 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. Every session it re-derives feedmill’s conventions from scratch, and every session it gets some of them wrong in the same places. The agent isn’t getting dumber. It just 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), 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.

The chapter we’ll follow

Section titled “The chapter we’ll follow”

We’ll turn the mistakes OpenCode keeps repeating into rules it can’t miss, then push on the edges of how it finds and loads those rules — because feedmill is a self-hosted Go project with parsers in subdirectories, and the discovery behavior has teeth you’ll hit in a real repo. Three moves:

  • Write feedmill’s first AGENTS.md — capture the politeness delay, the UTC rule, and the integer-cents-style conventions 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 your working directory that combines every AGENTS.md from your cwd to the repo root (not just the nearest one), why project and global user rules also combine, what “first match wins” really scopes over, and the trap that combining sets for feedmill’s parsers/ subtree — 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, and meet the sharp edge that @path imports inside AGENTS.md 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 one whose rules are silently added to a subtree you forgot they’d reach, because nested files combine rather than replace — or referenced 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 simply there, and you never review that same mistake again.