# AGENTS.md (File Convention)
AGENTS.md is a file convention for providing instructions and guidelines to AI coding agents. The file is typically placed at the root of a repository and contains context, rules, and preferences that AI assistants should follow when working with the codebase.
## Purpose
The AGENTS.md file serves as a persistent memory and instruction set for AI agents, ensuring consistent behavior across sessions. It solves the problem of having to repeatedly explain project conventions, coding styles, and preferences to AI assistants.
## Common Contents
### Project Context
- Overview of the project
- Architecture decisions
- Technology stack
- Important constraints
### Coding Guidelines
- Code style preferences
- Naming conventions
- File organization rules
- Testing requirements
### Workflow Instructions
- How to handle commits
- PR conventions
- Branch naming
- Review processes
### Safety Rules
- Files or directories to avoid modifying
- Destructive operations that require confirmation
- External actions that need approval
## Usage Pattern
As suggested by David Heinemeier Hansson in [[37signals AI Recommendations (2026-01)]]:
> "Agents take revisions and direction very well. Then ask it to commit those style guidelines to the AGENTS.md file."
This creates a feedback loop where AI agents learn and codify project preferences over time.
## Adoption
The convention has been adopted by various AI coding tools:
- [[Claude Code]] - Anthropic's CLI agent
- Cursor
- GitHub Copilot Workspace
- Other AI-powered development environments
## Example Structure
```markdown
# AGENTS.md
## Project Overview
Brief description of the project...
## Rules
- Always run tests before committing
- Use conventional commits
- Never modify files in /config without asking
## Code Style
- Use TypeScript strict mode
- Prefer functional patterns
- Maximum line length: 100 characters
## Workflow
- Create feature branches from main
- Squash commits on merge
```
## Related
- [[AI Agents]]
- [[Claude Code]]
- [[37signals AI Recommendations (2026-01)]]