What Belongs in AGENTS.md

A useful AGENTS.md doesn't try to document everything about your project.

It answers a more focused question:

What does a coding agent need to know to work correctly in this repository?

A good instruction usually has at least one of these properties:

• It changes how the agent should write code.
• It tells the agent how to validate its work.
• It prevents a project-specific mistake.
• It explains an important repository convention.
• It defines a boundary the agent should respect.

Let's look at the most useful categories.

1. Project Context

Give the agent enough context to understand what it's working on.

For example:

# Project

This repository contains a Next.js application for managing customer subscriptions.

The application uses:

- Next.js App Router
- TypeScript
- PostgreSQL
- Supabase
- Tailwind CSS

This quickly establishes the environment.

But don't turn AGENTS.md into a complete product specification.

❌ Too Much

Our company was founded in 2019...

Our customers are primarily...

Our long-term vision is...

The product was originally created because...

Include business context only when it affects implementation decisions.

2. Development Commands

Commands are one of the highest-value things you can give an agent.

## Development

- Install dependencies with `pnpm install`.
- Start the application with `pnpm dev`.
- Build with `pnpm build`.
- Run linting with `pnpm lint`.
- Run tests with `pnpm test`.

Now the agent doesn't need to guess whether your repository uses:

npm
yarn
pnpm
bun

or which scripts are expected.

Better Still

Explain when commands should run.

- Run `pnpm lint` after modifying application code.
- Run `pnpm test` after changing business logic.
- Run `pnpm build` when modifying build configuration.

This is more useful than simply listing commands.

3. Coding Conventions

If your project follows conventions that matter during implementation, state them.

## Coding Conventions

- Use TypeScript for new source files.
- Prefer named exports.
- Avoid `any`.
- Use async/await instead of promise chains.
- Follow existing naming conventions.

But be careful with generic advice.

❌ Weak

- Write clean code.
- Follow best practices.
- Use meaningful names.

These sound reasonable but provide little project-specific guidance.

✅ Better

- Name React component files using PascalCase.
- Name hooks with the `use` prefix.
- Keep API response types inside `src/types/api`.

Specific instructions are easier to follow and verify.

4. Architecture Rules

Architecture is especially valuable when the correct structure isn't obvious from a single file.

Suppose your backend uses:

Route
  ↓
Controller
  ↓
Service
  ↓
Repository
  ↓
Database

Your AGENTS.md might say:

## Architecture

- Controllers handle HTTP concerns only.
- Put business logic inside services.
- Access the database through repository classes.
- Do not query the database directly from controllers.

Now when an agent adds a feature, it knows where the logic belongs.

Without this guidance, the code might work but violate your architecture.

5. Testing Requirements

Testing instructions are another high-value category.

Instead of:

- Make sure tests pass.

be specific:

## Testing

- Add unit tests for new service-layer business logic.
- Add regression tests when fixing bugs.
- Run `pnpm test` before completing changes.
- Do not remove or weaken existing tests simply to make them pass.

You can also document where tests belong:

- Place unit tests beside the source file using `*.test.ts`.

or:

- Place integration tests inside `/tests/integration`.

6. Validation Requirements

Tests aren't always the only validation step.

Your project may require:

## Validation

Before completing application changes:

1. Run `pnpm lint`.
2. Run `pnpm typecheck`.
3. Run `pnpm test`.

This gives the agent a clear definition of how work should be verified.

You can make this conditional when appropriate:

- Run database integration tests only when modifying database-related code.

That avoids unnecessary work while keeping validation explicit.

7. Repository Boundaries

Sometimes the most valuable instruction is telling the agent what not to touch.

For example:

## Repository Boundaries

- Do not modify files inside `/generated`.
- Do not edit database migration history after it has been applied.
- Do not modify vendored code inside `/vendor`.

This can prevent expensive mistakes.

Another example:

- Generate API clients using `pnpm generate:api`.
- Never manually edit files inside `src/generated/api`.

Now the agent knows both the restriction and the correct workflow.

That's much better than:

- Don't edit generated files.

8. Dependency Rules

If your project has opinions about dependencies, tell the agent.

## Dependencies

- Reuse existing dependencies when practical.
- Do not add a new production dependency without a clear need.
- Use `pnpm` when modifying dependencies.

You can be even more specific:

- Use Zod for schema validation.
- Use date-fns for date manipulation.
- Do not introduce another validation or date library.

This helps prevent unnecessary duplication.

9. Documentation Requirements

If code changes require documentation updates, state when.

## Documentation

- Update README setup instructions when development commands change.
- Add JSDoc only for public APIs where behavior isn't obvious.
- Update API documentation when adding or changing endpoints.

Again, avoid broad instructions such as:

- Document everything.

That can create unnecessary comments and documentation noise.

10. Security-Related Working Rules

AGENTS.md can contain safe coding and repository rules.

For example:

## Security

- Never commit secrets or credentials.
- Never log authentication tokens.
- Validate external input before processing it.
- Use environment variables for credentials.

Project-specific rules are even better:

- All `/api/admin/*` routes must use `requireAdmin()`.

That tells the agent something it cannot reliably infer from general programming knowledge.

Important

Don't put the actual secret in the instruction.

❌ Never:

DATABASE_PASSWORD=my-secret-password

Instead:

- Read database credentials from `DATABASE_URL`.
- Never commit `.env` files.

11. Task Workflow

You can also tell the agent how changes should normally be approached.

For example:

## Workflow

When implementing a feature:

1. Inspect the existing implementation before making changes.
2. Follow existing patterns where possible.
3. Add or update tests.
4. Run the relevant validation commands.
5. Update documentation when behavior changes.

This is useful when your team has a consistent development workflow.

But avoid turning every simple task into a huge checklist.

A Practical Structure

A real AGENTS.md might look like this:

# Project Guidelines

## Stack

- Next.js App Router
- TypeScript
- PostgreSQL
- Tailwind CSS

## Development

- Use `pnpm`.
- Start development with `pnpm dev`.

## Architecture

- Keep business logic outside React components.
- Put server-side data access inside `src/server`.
- Reuse existing components before creating new ones.

## Testing

- Add tests for new business logic.
- Add regression tests for bug fixes.
- Run `pnpm test` after modifying business logic.

## Validation

Before completing application changes:

- Run `pnpm lint`.
- Run `pnpm typecheck`.
- Run relevant tests.

## Boundaries

- Do not modify generated files manually.
- Do not commit `.env` files.

## Documentation

- Update documentation when public behavior changes.

Notice what this file does not contain.

It doesn't explain JavaScript.

It doesn't teach Next.js.

It doesn't contain the entire architecture documentation.

It focuses on information that affects how an agent should work.

How Do I Decide Whether Something Belongs?

Before adding an instruction, ask:

Question 1

Would the agent reasonably know this already?

If yes, you may not need it.

❌ React components can have props.

The agent already knows this.

Question 2

Is this specific to our repository or workflow?

If yes, it's a strong candidate.

✅ All external API calls must go through `src/services/api`.

Question 3

Would ignoring this instruction cause a meaningful problem?

For example:

✅ Never manually modify generated Prisma client files.

Ignoring this could cause real problems.

Question 4

Can the instruction be made actionable?

Instead of:

❌ Test your changes.

write:

✅ Run `pnpm test` after modifying business logic.

A Useful Rule

Think:

Project-specific
       +
Actionable
       +
Relevant to coding-agent work
       ↓
Good AGENTS.md candidate

Not every instruction needs to satisfy these perfectly, but it's a useful filter.

Common Mistake: Turning AGENTS.md Into a Knowledge Dump

It's tempting to keep adding information.

Eventually:

20 lines
   ↓
100 lines
   ↓
500 lines
   ↓
"Everything the agent might ever need"

More context isn't automatically better context.

Every instruction competes for attention with the instructions that actually matter.

Prefer:

The smallest useful set of instructions that helps the agent work correctly.

Key Takeaway

Good AGENTS.md content usually falls into a few categories:

Project Context
Development Commands
Coding Conventions
Architecture
Testing
Validation
Repository Boundaries
Dependencies
Documentation
Security
Workflow

But don't add every category just because it exists.

Add instructions when they help the agent answer:

"What do I need to know to make this change correctly in this repository?"

Up Next

What Does NOT Belong in AGENTS.md

Knowing what to leave out is just as important as knowing what to add.

Next we'll look at secrets, temporary tasks, generic programming knowledge, excessive documentation, duplicated instructions, and other content that makes an AGENTS.md worse rather than better.