Structuring project documentation helps build a good knowledge base, but it's not enough to work effectively with the codebase. In practice, agents also need extra instruction files: AGENTS.md and SKILLS.md. Let's start with AGENTS.md: what it is for and how to cook it properly.
AGENTS.md is a markdown file that provides context, instructions, and guidelines for AI coding agents working with the repo.
Its content is added to the initial prompt (system context) when LLM session is created. What matters that this is a standard that widely adopted by different agents such as Cursor, Codex, Claude Code and many others.
Common structure:
🔸 Project overview: project description, tech stack with particular versions, key folders and dependencies.
🔸 Commands: list of build and test commands with required flags and options.
🔸 Code Style: describe preferred code style.
🔸 Testing: commands to run different types of tests and linters.
🔸 Boundaries: do's and don'ts (e.g., never touch secrets, env configs).
🔸 Extra: PR guidelines, git workflow details, deployment instructions, etc.
Common recommendations:
🔸 Keep it short (~150 lines)
🔸 Continuously update it with code changes
🔸 Be specific, prefer samples over description
🔸 Improve it iteratively by adding what really works and removing what doesn't
🔸 Use nested AGENTS.md files in large codebases. The agent reads the closest file to the work it is doing.
Sample:
# Tech Stack
- Language: Go 1.24+
- API: gRPC
- Database: PostgreSQL 18
- Message Queue: RabbitMQ 4.2, Apache Kafka 4.1.x
- Observability: OpenTelemetry, Jaeger, Prometheus, Grafana
- Security: JWT, OAuth2, TLS
- Deployment: Docker, Kubernetes, Helm
# Build & Test Commands
- Build: `go build -o myapp`
- Test `go test`
# Boundaries
- Never touch `/charts/secrets/` files.
- Avoid adding unnecessary dependencies.
# PR Submission
## Title Format (MANDATORY)
Issue No: User-facing description
Samples from opensource projects:
- RabbitMQ Cluster Operator
- Kubebuilder
- Airflow
- Headlamp
Additionally I recommend reading How to write a great agents.md: Lessons from over 2,500 repositories from Github blog. I didn't get how they measured the effectiveness of analyzed instructions, but anyway the overall recommendations can be helpful.
#ai #agents #engineering #documentation
