10. AGENTS.md — Project Instructions

10.1 What is AGENTS.md?

AGENTS.md is a persistent instruction file for OpenCode.

It is useful for:

• Build commands
• Architecture notes
• Coding conventions
• Testing requirements
• Security rules
• Repository-specific constraints

10.2 Basic example

Create:

AGENTS.md

# Project Instructions

## Technology

- TypeScript
- React
- Node.js

## Commands

npm install
npm test
npm run build

## Coding

- Use TypeScript.
- Prefer small functions.
- Reuse existing utilities.

## Testing

Run the relevant tests after changing application code.

## Security

Never hardcode secrets.

## Git

Do not push changes automatically.

10.3 Directory-specific instructions

You can use more specific AGENTS.md files for parts of a repository.

Conceptually:

project/
|
+-- AGENTS.md
|
+-- frontend/
|   |
|   +-- AGENTS.md
|
+-- backend/
    |
    +-- AGENTS.md

This allows more specific guidance closer to the code it covers.

10.4 What belongs in AGENTS.md?

Good:

Run pytest after backend changes.

Database access belongs in src/database.

Generated files must not be edited manually.

Less useful:

Thousands of lines of API documentation

Keep stable instructions concise.

10.5 AGENTS.md vs README.md

README:

Explains the project to people.

AGENTS.md:

Gives an AI agent project-specific working instructions.

They can complement each other.

10.6 AGENTS.md best practices

Use:

• Short rules
• Exact commands
• Architecture constraints
• Verification requirements
• Security rules

Avoid:

• Duplicating the whole documentation
• Temporary task instructions
• Huge logs
• Secrets

Exercise

Create an AGENTS.md for your own project with:

1. Technology
2. Architecture
3. Commands
4. Coding rules
5. Testing
6. Security
7. Git rules