The AGENTS.md file

The AGENTS.md file

AGENTS.md is a dedicated instruction file automatically loaded into an AI coding agent’s context at the start of a session.

Just as a README file describes a project to a human developer, AGENTS.md provides an AI model with essential high-level project architecture, coding conventions and workflow guidelines. It also supplies critical operational commands (like how to run tests, build, or lint), preventing the AI from burning tokens scanning files or guessing project rules.

Create an AGENTS.md file

You can ask OpenCode to get you started with an AGENTS.md file using the /init command. This prompts the AI agent to analyze your repository and generate a baseline configuration.

You can also pass custom constraints directly with the command:

/init use uv as the package manager, and ruff as the linter. Do not use pip, conda, or poetry directly.

The resulting prompt sent to the agent will look similar to this:

Create or update `AGENTS.md` for this repository.

The goal is a compact instruction file that helps future OpenCode sessions avoid mistakes and ramp up quickly. Every line should answer: "Would an agent likely miss this without help?" If not, leave it out.

User-provided focus or constraints (honor these):
use uv as the package manager, and ruff as the linter. Do not use pip, conda, or poetry directly.

## How to investigate
*[more lines...]*

Once generated, open AGENTS.md to review it. As a plain Markdown file, you can customize it with any sections relevant to your repository, keeping it concise and focused on agent-specific guidance.

Some common sections you’ll find in AGENTS.md files:

  • Project overview: A short and high-level project description.
  • Tools / Tech stack: AI tools can be very opinionated about what programming languages and tools they use. Being specific about your stack helps guide the AI without having to repeat yourself in every prompt.
  • Project structure / architecture: Having the directory structure of your project helps the AI to know where to save and find files.
  • Code style guidelines: Any particular preferences you and your team follow in your coding project.
  • Workflows: Expectations for Git and GitHub workflow you want to follow, conventions for naming new branches or commit messages.
TipChallenge: Discuss real AGENTS.md examples

Take a look at the following three examples of AGENTS.md files:

Discuss with the person next to you:

  • Did you find an AGENTS.md file, a CLAUDE.md file, or both?
  • What did you see they have in common?
  • How many lines does each file have?

Customize the AGENTS.md file

The /init command was a great start, but you should personalize it and add important considerations for your project.

Let’s add the following to the AGENTS.md file we have until now.

## Environment & Tooling

- Language: Python (>=3.11 recommended)
- Package manager: **uv** — do not use pip, conda, or poetry directly.
  - Install dependencies: `uv add <package>`
  - Sync environment from lockfile: `uv sync`
- Always keep `pyproject.toml` and `uv.lock` in sync; commit `uv.lock`.
- Do not manually edit `uv.lock` — regenerate it via `uv lock` or `uv sync`.

## Directory structure

Always consider this directory structure to find and create files in this project:
.
├── code/
├── data/
│   ├── data-processed/
│   └── data-raw/ # should never be overwritten
├── docs/
└── output/
    ├── figures/
    └── tables/

## Session & Context Management

To keep chat sessions lightweight and avoid context bloat (>250k tokens):

- **Minimal file outputs:** Never reprint full files or large codeblocks. Always output concise targeted line edits or `git diff` snippets.
- **Truncate command outputs:** Summarize test/build outputs. Do not dump massive stack traces or long terminal logs unless directly relevant to an error.
- **Task modularity & session resets:** Treat each chat session as single-task focused. Upon completing a distinct task, pull request, or major bugfix, remind the user to start a new chat session (e.g., `/new`) before moving to the next task.
- **Summarize progress:** When context feels long or complex, provide a 3-bullet task summary so the user can easily copy it into a fresh session.

## Workflows

### Before committing any changes

Always run the following checks before creating a commit. Do not commit if any step fails — fix the issues first (or ask the user if a fix isn't obvious).

1. Format code:
   `uv run ruff format .`
2. Lint and auto-fix what's safe to fix:
   `uv run ruff check --fix .`
3. Re-run lint to confirm no remaining errors:
   `uv run ruff check .`

### Commit message conventions

Keep it short and descriptive, e.g. `add sliding window aggregation for signal preprocessing`. No strict format required — just make it clear what changed and why, so it's easy to trace back for reproducibility.

### General rules

- Never commit directly to `main`. Create a branch (`git switch -c <branch-name>`) if one doesn't already exist for the current task.
- Never force-push (`git push --force`) without explicit user confirmation.
- If `ruff` reports errors that can't be auto-fixed, stop and explain the issue rather than silently ignoring or suppressing it.

After adjusting it, make sure the project is actually following these conventions and test how it works. Let’s use this prompt:

Audit the repository against @AGENTS.md. Run the pre-commit linter checks and list any code formatting or structural violations, but don’t move or refactor files without asking first.

TipChallenge: Testing our AI Agent

Let’s test if the AI really obeys our new workflow rules.

  1. Open code/plot_mhw.py or another Python script and in the import section add import random, an unused import in the project.
  2. Ask the AI Agent: “Please commit my recent changes with a generic message.”
  3. Watch the agent’s output. Did it run ruff check? Did it refuse to commit until the issue was fixed, or did it auto-fix it for you?