AGENTS.md

AGENTS.md is a standard format for guiding AI coding agents with project-specific instructions.

• Machine-readable project context
• Works like a README, but for AI agents
• Used by 60k+ open-source projects
• Simple markdown format

# Project Name

## Setup

- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`

## Code style

- TypeScript strict mode
- Use functional patterns
- Prefer named exports

Most tools support both generic and tool-specific names.

my-project/
├── AGENTS.md          # Project root
├── src/
│   └── AGENTS.md      # Subdirectory override
└── packages/
    └── api/
        └── AGENTS.md  # Package-specific

Nested files override parent rules for that directory scope.

Global rules apply to all projects unless overridden.

monorepo/
├── AGENTS.md           # Shared rules
├── apps/
│   ├── web/
│   │   └── AGENTS.md   # Web app rules
│   └── api/
│       └── AGENTS.md   # API rules
└── packages/
    └── shared/
        └── AGENTS.md   # Package rules

# Project Name

Brief description of what the project does
and its main technologies.

## Tech stack

- Framework: Next.js 15
- Language: TypeScript (strict)
- Database: PostgreSQL
- Styling: Tailwind CSS

Helps AI understand the project context quickly.

## Commands

### Development

- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

### Testing

- All tests: `pnpm test`
- Single file: `pnpm test path/to/file`
- Watch mode: `pnpm test:watch`

### Linting

- Lint: `pnpm lint`
- Format: `pnpm format`

Always include runnable commands.

## Code style

### TypeScript

- Strict mode enabled
- Explicit return types on functions
- No `any` - use `unknown` instead

### Naming conventions

- `camelCase` for variables/functions
- `PascalCase` for types/components
- `UPPER_SNAKE` for constants

### Imports

- Use `@/` alias for src/
- Group: external, internal, relative

## Project structure

src/ ├── app/ # Next.js pages ├── components/ │ ├── ui/ # Primitives │ └── features/ # Feature components ├── lib/ # Utilities ├── hooks/ # React hooks └── types/ # TypeScript types

### Key files
- `src/lib/db.ts` - Database client
- `src/lib/auth.ts` - Auth utilities

## Git conventions

### Commit messages

Use conventional commits:

- `feat:` new features
- `fix:` bug fixes
- `docs:` documentation
- `refactor:` code changes
- `test:` test changes

### Branch naming

- `feat/description`
- `fix/issue-number`
- `refactor/description`

### PR requirements

- All tests must pass
- Require code review
- Squash merge to main

## Error handling

### Patterns

- Use Result types for expected errors
- Throw for unexpected errors
- Always log with context

### Example

```typescript
// Good - explicit error handling
const result = await fetchUser(id);
if (result.error) {
  logger.warn("User not found", { id });
  return { error: "NOT_FOUND" };
}
```

## Best practices
{: .-two-column}

### Do's

- **Be specific** - Include exact commands
- **Use code blocks** - Make commands copy-pasteable
- **Keep it current** - Update when project changes
- **Use headings** - Make sections scannable
- **Include examples** - Show, don't just tell
- **Test commands** - Verify they actually work
{: .-four-column}

### Don'ts

- **Don't be vague** - "Follow best practices" is unhelpful
- **Don't duplicate README** - Focus on AI-specific guidance
- **Don't include secrets** - Never put credentials here
- **Don't over-constrain** - Allow AI flexibility
- **Don't forget updates** - Stale docs cause issues
{: .-four-column}

## Templates
{: .-three-column}

### Minimal template

```markdown
# Project Name

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`

## Code style
- TypeScript strict mode
- Prettier for formatting

Good for small projects.

# Project Name

Brief description here.

## Tech stack

- Framework: [name]
- Language: [name]
- Database: [name]

## Commands

- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`

## Code style

- [Guideline 1]
- [Guideline 2]

## Project structure

- `src/` - Source code
- `tests/` - Test files

# Project Name

## Overview

[Description and purpose]

## Tech stack

[Technologies used]

## Commands

[All development commands]

## Code style

[Formatting and conventions]

## Project structure

[Directory layout]

## Testing

[Test patterns and commands]

## Git conventions

[Commit and PR guidelines]

## Architecture decisions

[Key design choices]

<!-- Claude-specific syntax -->

### Memory

Claude Code remembers context
from previous sessions.

### @ mentions

Reference files with @filename
in conversations.

### Slash commands

- /init - Initialize CLAUDE.md
- /memory - View memory

Supports CLAUDE.md and AGENTS.md.

<!-- .cursorrules example -->

You are an expert in TypeScript
and React development.

Always use:

- Functional components
- TypeScript strict mode
- Tailwind for styling

Never use:

- Class components
- CSS modules
- Default exports

Also supports .cursorrules file.

<!-- COPILOT.md features -->

## Instructions

Copilot reads these as
persistent instructions.

## Code patterns

Include examples of preferred
patterns for suggestions.

Supports workspace-level instructions.

# My Next.js App

## Commands

- Dev: `pnpm dev` (localhost:3000)
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Code style

- React 19 with Server Components
- TypeScript strict mode
- Tailwind CSS for styling
- shadcn/ui components

## Structure

- `app/` - Next.js App Router
- `components/ui/` - UI primitives
- `lib/` - Utilities
- `hooks/` - React hooks

## Conventions

- Server Components by default
- "use client" only when needed
- Colocate tests with source

# API Service

## Commands

- Dev: `pnpm dev` (watch mode)
- Test: `pnpm test`
- Build: `pnpm build`
- DB migrate: `pnpm db:migrate`

## Code style

- Node.js 20 with ESM
- TypeScript strict mode
- Zod for validation
- Drizzle ORM

## API patterns

- RESTful endpoints
- JSON:API format
- JWT authentication
- Rate limiting enabled

## Error handling

- Return proper HTTP codes
- Use problem details format
- Log all errors with context