Create AGENTS.md

Guide for creating AGENTS.md files for project-specific inline rules.

When to Use AGENTS.md

• Small, project-specific instructions that should be committed in the repo
• Folder-scoped rules for specific directories
• Package-specific instructions in monorepos
• Test-specific guidance in test directories

When NOT to Use AGENTS.md

• Reusable knowledge across projects → Use skills
• Large documentation → Use skills with references
• Complex workflows → Use skills with scripts

AGENTS.md Structure

AGENTS.md is a simple markdown file without metadata:

# Project Instructions

## Code Style

- Use TypeScript for all new files
- Prefer functional components in React
- Use snake_case for database columns

## Architecture

- Follow the repository pattern
- Keep business logic in service layers

Location

• Project root: AGENTS.md – Primary, inline instructions and references for the whole project (commands, tech stack, testing, code style, architecture, safety boundaries).
• Subdirectories: subdirectory/AGENTS.md – Folder- or package-scoped instructions when local behavior meaningfully diverges from the root (e.g., a specific package, service, or test tree).
• Nested support: Agents typically combine instructions from the closest AGENTS.md with parent ones; keep root general and use nested AGENTS.md only where you truly need more specific rules.

Best Practices

• Keep AGENTS.md files small and focused
• Use for project-specific conventions
• Prefer short, concrete references over long prose:
  • Link to project docs, specs, and runbooks
  • Point to example files or directories (e.g., see src/api/users.ts for canonical pattern)
  • Include the most important commands with exact CLI invocations
• Reference existing code examples when possible
• Update as project evolves

References

For detailed best practices, see references/best-practices.md.