Skip to main content

Project Instructions (AGENTS.md)

Project instruction files provide persistent context to coding agents across sessions. They're one of the most powerful tools for improving agent reliability and consistency.

The Most Important Principle: Iterate Ruthlessly​

Your project instructions file is a living document. Start small, refine constantly.

Before diving into what to include, understand this fundamental truth: you cannot write the perfect instructions file upfront. The best instruction files emerge through iteration.

Why Iteration Matters​

  • Don't try to anticipate every edge case on day one
  • Add instructions when you catch mistakes during code review
  • Remove instructions that aren't helping or are consistently followed anyway
  • Target around 2,500 tokens (roughly 2,000 words)—more content dilutes important instructions

Let the Agent Update Itself​

With many coding agents, you can ask the agent to update its own instructions:

  • "Add what we learned today to the project instructions"
  • "Update the instructions with the pattern we just established"
  • "The model keeps making X mistake—add a note about it"

This creates a feedback loop: catch mistake → add to instructions → mistake stops.

Track Your Corrections​

Every code review is an opportunity:

  • If you keep fixing the same issue, add it to your instructions
  • If an instruction isn't helping, rephrase or remove it
  • Aim for fewer corrections over time

The Open Standard: AGENTS.md​

In July 2025, agents.md emerged as an open standard for project instructions. Created by Sourcegraph's Amp team with collaboration from OpenAI and Google, it provides a unified way for any AI agent to understand project-specific context.

Why AGENTS.md Matters​

  • One file, any agent - Works across different coding agents and AI tools
  • Widely adopted - Over 20,000 repositories use AGENTS.md
  • Industry support - Supported by Codex, Jules, Cursor, Aider, RooCode, Zed, Windsurf, and more

CLAUDE.md for Claude Code​

Claude Code uses CLAUDE.md as its project instruction file. It serves the exact same purpose as AGENTS.md and follows the same principles. All best practices in this guide apply equally to both.

your-project/
├── .git/
├── CLAUDE.md          ← Claude Code instructions
├── AGENTS.md          ← Universal agent instructions (optional)
├── src/
└── ...

You can maintain both files, or just use one. Some teams use AGENTS.md for generic instructions and CLAUDE.md for Claude-specific optimizations.

What to Include​

Mistakes to Avoid​

Document specific errors the agent has made that you've corrected:

## Common Mistakes

- Always use `pnpm` not `npm` for this project
- Import from `@/lib/utils` not `../../../lib/utils`
- Never commit `.env` files
- Use `async/await` not `.then()` chains

Style Conventions​

Capture coding style preferences:

## Style

- Use functional components with hooks, not class components
- Prefer named exports over default exports
- Use `type` for type aliases, `interface` for object shapes
- Error messages should be user-friendly, not technical

Design Guidelines​

Document architectural decisions:

## Architecture

- All API calls go through `src/api/client.ts`
- State management uses Zustand, not Redux
- Database queries use the repository pattern in `src/repos/`

Project-Specific Commands​

Include commands the agent should know:

## Commands

- `pnpm dev` - Start development server
- `pnpm test` - Run tests
- `pnpm lint:fix` - Fix linting issues
- `pnpm db:migrate` - Run database migrations

PR Templates​

Help the agent write consistent PR descriptions:

## PR Format

Title: `[TYPE] Brief description`
Types: feat, fix, refactor, docs, test, chore

Body should include:
- Summary of changes
- Testing performed
- Screenshots if UI changes

Example Instructions File​

# Project: Customer Portal

## Overview
React + TypeScript frontend for customer self-service portal.

## Commands
- `pnpm dev` - Development server (port 3000)
- `pnpm test` - Jest tests
- `pnpm lint:fix` - Fix ESLint/Prettier issues

## Style
- Functional components with hooks only
- Use `@/` path alias for imports
- Tailwind for styling, no inline styles
- Error boundaries around route components

## Common Mistakes
- Don't use `any` type - find or create proper types
- API calls must go through `src/api/` - no direct fetch
- Always handle loading and error states in components
- Use `date-fns` for dates, not native Date methods

## Testing
- Unit tests for utilities in `__tests__/` directories
- Integration tests for API calls use MSW mocks
- E2E tests are in `cypress/` - run with `pnpm e2e`

## Security
- Never log sensitive data (tokens, PII)
- Validate all user input server-side
- Use CSRF tokens for mutations

File Locations​

You can have instruction files at different levels:

LocationScope
~/.claude/CLAUDE.mdGlobal, applies to all projects (Claude Code)
./CLAUDE.md or ./AGENTS.mdProject root, applies to this repo
./src/CLAUDE.mdSubdirectory, applies when working in src/

More specific files add to (don't replace) broader ones.

Best Practices Summary​

  1. Start small - Begin with basic project info, expand over time
  2. Keep it concise - Target ~2,500 tokens; more isn't better
  3. Document mistakes - Add errors as you catch them during review
  4. Remove what works - Delete instructions the agent consistently follows
  5. Consolidate related points - Group similar guidance together
  6. Let the agent help - Ask it to update its own instructions

Learn More​