Why your project needs an AGENTS.md file
Daniel Opitz
16 Jun 2026
AI coding agents are becoming part of everyday development. They can write code, refactor classes, create tests, and explain complex codebases. But just like a new teammate, an AI agent needs project context before it can work well.
That is where an AGENTS.md file helps.
An AGENTS.md file is a simple project-level guide for AI agents. It tells them how the (PHP) project is structured, which commands to run, what coding style to follow, and what rules they should respect. Instead of making the agent guess, you give it clear instructions.
This can save a lot of time. For example, the file can explain how to install dependencies with Composer, how to run PHPUnit, which framework is used, which folders contain generated files, and what conventions the team follows. The agent can then make better decisions and produce code that actually fits the project.
It also reduces mistakes. Without guidance, an AI agent might use the wrong test command, ignore PSR standards, change files in vendor/, or misunderstand the application structure. With an AGENTS.md file, you give the agent useful guardrails.
The best part is that you do not have to write this document manually. If you already have an existing PHP project, you can let your AI agent inspect the repository and generate a first version for you.
Use a prompt like this:
Analyze this project and create an AGENTS.md file for it.
The file should help an AI coding agent understand how to work in this repository.
Include:
- A short project overview
- The main technologies and framework used
- The project structure
- The architecture style, for example layered architecture, MVC, hexagonal architecture, clean architecture, or another style
- Important architecture decisions and the reasons behind them, if they can be inferred from the project
- Composer commands
- Test commands
- Static analysis or coding style commands, if available
- Important coding conventions
- Files or folders that should not be edited
- Rules for adding or changing tests
- Common patterns that should be followed when adding new code
Base the document only on what you can find in the project.
Do not invent tools, commands, conventions, architecture decisions, or reasons.
If something is unclear, mark it as unclear instead of guessing.
The generated AGENTS.md could look like this:
# AGENTS.md
## Project overview
This is a PHP project managed with Composer.
## Architecture
The project appears to use a layered architecture.
Typical responsibilities:
- Controllers handle HTTP requests and responses.
- Services contain business logic.
- Repositories handle data access.
- Entities or models represent domain data.
Important decisions:
- Business logic should stay out of controllers.
- Database access should go through repositories.
- New code should follow the existing folder structure.
## Commands
- Install dependencies: `composer install`
- Run tests: `vendor/bin/phpunit`
- Run static analysis: `vendor/bin/phpstan analyse`
- Check coding style: `vendor/bin/php-cs-fixer fix --dry-run`
## Guidelines
- Follow PSR-12 coding style.
- Keep code comments in English.
- Do not edit files in `vendor/`.
- Do not edit generated files.
- Add or update PHPUnit tests when changing business logic.
- Run the relevant tests before suggesting a final change.
Think of AGENTS.md as onboarding documentation for your AI assistant. It helps the agent understand your PHP project faster, follow your rules, and produce better results.
If you already document your project for humans, documenting it for AI agents is the next logical step.