Writing an AGENTS.md

The real goal of the AGENTS.md file is to save yourself from having to retype the same information into each new session. So at the end of the day, the most important criterion for deciding what goes into it is:

"What do I want to tell the agent every time I start a new session?"

So, let's go over common sections your AGENTS.md might have, and what to include in them.

Include code patterns that you do and don't like. As you're coding with AI, whenever you notice it writing code you don't like, fix it, but also tell it to update this section with the example. A brief explanation and an example are perfect.

- Avoid unnecessary destructuring. Use dot notation to preserve context.

```ts
// Good
obj.a;
obj.b;

// Bad
const { a, b } = obj;
```

This section should include how and when to write tests, but also any instructions about how to run them, and how to set up dependencies if there are any.

- Avoid using mocks to the extent possible. Refactor functions to make business logic more easily testable without them.
- Use `go test` to run tests, but only test the specific function you're working on when iterating; our test suite is large.

Depending on your project's setup, it might be simple enough to point the agent at your migration files or ORM models to give it an understanding of the schema. If your schema lives outside the codebase, I'd recommend finding some way to make it easily accessible to the agent, and telling the agent how to find it here.

Give a very high-level overview of the repo so the agent knows where to look for things.

- `cmd/` – CLI entrypoints
- `internal/api/` – HTTP handlers
- `internal/store/` – Database layer (PostgreSQL)
- `migrations/` – SQL migration files

This section may live in the project repo, but it may also be a better fit in your personal (global) ~/.config/opencode/AGENTS.md if it contains personal preferences rather than team preferences. It should explain how you want your agent to interact with Git (if at all) when making a change. For example, I use this:

- Never assume that you should stage or commit a change unless I ask you to. I like to review your changes unstaged.
- When I ask you to commit and push, push to a new feature branch (not `main`) if you aren't already on one.
- Rebase off of the `main` branch before pushing, unless I ask for something else.
- Look at the `git log` after rebasing. If there are any sloppy "wip" or "fixup" commits, squash them into the most logical commit message before pushing.
- Use short, single-sentence conventional commit messages.
- Never create a pull request without being asked to.

We'll talk more about some alternative strategies for tools and scripts later, but if you have some that you want your agent to use on a very regular basis, it makes sense to list them here.

For example, at Boot.dev, we have a custom script that formats the Markdown files of our lessons in a specific way, and we point it out to the LLM here.

• Don't duplicate what's already in your README.md or other documentation. Just tell your agent where to find those files if they're needed.
• Don't be redundant; state each rule once with just one or two examples.
• Don't put secrets or credentials in here (duh). This file should be committed.
• Omit anything that the base model likely already knows. You don't need to re-teach it how to write Python code, for example.

Tell OpenCode to rewrite the root AGENTS.md around four things: a brief project layout, the four validation commands, when to add regression tests, and a link to docs/spec.md for language behavior.

Tell OpenCode to run and submit the CLI tests from the project root.