Skip to content
Recipes Ecosystem Source Code Docs

Standardize Team Behavior with AGENTS.md

AGENTS.md is the single source of truth for how OpenCode (and any AI agent) should behave in your repo. When it’s well-written, every contributor — human or AI — starts with the same baseline.

When to use this recipe

  • You want consistent code style and review quality across all AI-generated PRs.
  • Onboarding a new team member (human or AI) is taking too long.
  • Different parts of the team have different conventions and PRs bounce back and forth.

Prerequisites

  • OpenCode installed in the repo.
  • A rough idea of your team’s current conventions (style, testing, error handling).
  • Willingness to iterate — the first draft will be wrong.

Steps

  1. Start from a stub

    Create AGENTS.md at the repo root with a minimal structure.

    # AGENTS.md

## Project overview
[One paragraph: what this project does and the stack]

## Build, test, lint
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Code style
[Your language-specific style rules]

## Testing rules
[When to add a test, what to cover, mocking policy]

## Commit and PR rules
[Commit message format, PR template, who reviews what]

  2. Ask OpenCode to fill in the gaps

    Point it at the existing codebase and the stub. It will infer conventions from the code.

    Read the project root and our stub AGENTS.md. For each section, fill in the rules with concrete examples from the existing code. Where the codebase is inconsistent, propose the rule we should follow and flag the inconsistency.

  3. Add a “Do not” section

    Explicit prohibitions prevent the most common agent mistakes.

    ## Do not
- Do not add new top-level dependencies without discussion.
- Do not commit generated files (build/, dist/, node_modules/).
- Do not bypass the linter to make CI green.

  4. Add a “When stuck” section

    Tell the agent what to do when it doesn’t know the right answer.

    ## When stuck
- Search the codebase first (`rg`, `grep -r`).
- Read the related test file for the expected behavior.
- If still stuck, ask in #dev-help rather than guessing.

  5. Commit and reference it in PR template

    Commit AGENTS.md and link to it from .github/pull_request_template.md so reviewers can spot drift.

  6. Iterate as you learn

    When you see a recurring PR comment, add a rule to AGENTS.md. When a rule causes friction, drop it.

Key prompt

Read the project root and our stub AGENTS.md. For each section, fill in concrete rules inferred from the existing code, with file-and-line examples. Add a “Do not” section with the most common mistakes you’d want an agent to avoid. Add a “When stuck” section that points to real sources of truth in this repo (search commands, test files, chat channels).

Verify

  • A new agent session reads AGENTS.md on startup and follows the rules.
  • Common review comments drop (style, missed tests, accidental commits).
  • The file is short (under 200 lines) — if it grows past that, the rules are too detailed to be useful.

Common pitfalls

  • Over-specifying: A 1000-line AGENTS.md is ignored. Keep it short; link out to detailed docs instead.
  • Stale rules: Conventions drift. Set a calendar reminder to review quarterly.
  • No “do not”: Without prohibitions, the agent will invent its own preferences. Be explicit.

Next up