The AGENTS.md file

As a review

Let’s refresh some concepts on how to start OpenCode, switch models, and send a prompt to the AI Agent.

If you have a noaa-tides folder you were working on last week, continue working on that one.
- If you don’t, clone the repo we have set up for you using git clone https://github.com/UCSBCarpentry/noaa-tides-example.git (Or ask the AI to help)
Start OpenCode in the noaa-tides folder
Select Gemini 3.5 Flash as your model

Imagine you are new to this project and want to understand it. You ask OpenCode:

What is this project about? What were the latest changes made?

A response might look like:

✱Glob "*" (100 matches)

→Read README.md 

I will run git log to see the history of recent changes in this repository.

# Runs git log to view recent commits.
$ git log --oneline -10
93b6f00 Add MHW plotting script and output directory
f1eacd3 Add uv for dependency management
bc30d94 Initial commit

→Read code/download_mhw.py 
→Read code/plot_mhw.py 

What this project is about
This project is designed to download, compile, and visualize monthly Mean High Water (MHW) data for NOAA tide stations along the California coast over a decade (2014–2024) using the NOAA CO-OPS API.
Key components:
[...]
Based on the repository's git commit history, the most recent developments are:
[...]

There is a lot to unpack here:

LLMs are very good at summarizing a large amount of information quickly. In a few seconds, it read the files in our project and gave us an overview to get started.
It shows how the AI Agent called tools like Glob and Read, and it ran a git Shell command. Unlike a standard chat-based AI tool, the AI Agent was able to access the files in our project and call tools to gather additional information.
To answer our question, the agent used Git to track our project’s history. AI coding agents make version control both easier and more essential, giving us access to valuable historical context, while serving as a crucial safety net in case the AI messes up the project.

If we open a new chat session with the /new command, the AI Agent would have to read the files again just to have a brief overview of the project, wasting precious time and tokens.

What if there was a file the AI always has access to with the most relevant information about our project?

The AGENTS.md file

AGENTS.md is a special file that is always included at the start of the conversation with the coding agent, without the user having to mention it.

Just like a README file describes a project to a human reader, the AGENTS.md file gives the AI a high level description of the project so it doesn’t have to read multiple files with every new conversation. It also gives the AI clear guidelines on conventions, coding styles, or workflows you want it to follow.

We can ask our AI Agent to get us started with an AGENTS.md using the /init command.

As you can see, it is a human-readable, plain markdown file. It can have any sections you feel are relevant to your project, but aim to keep it concise and focused on guiding the AI through specifics of your project.

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

Project overview: A short and high-level 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: For example, the Git and GitHub workflow you want to follow, conventions for naming new branches or commit messages.

Challenge: 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.9 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:
- data
  - data-raw
  - data-processed
- code
- docs
- output
  - figures
  - tables

## 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 adjustmenting it, make sure the project is actually following these conventions and test how it works. Let’s use this prompt:

Make sure my project follows the guidelines stated on the @AGENTS.md file.

Challenge: Testing our AI Agent

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

Open code/plot_mhw.py or another Python script and in the import section add import random, an unused import in the project.
Ask the AI Agent: “Please commit my recent changes with a generic message.”
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?