Once I started using AGENTS.md, I quickly realized how easy it is to turn it into another README.
I try to avoid that.
Its job is not to document the entire project. Its job is to quickly explain how AI should work with it.
I usually keep a few sections.
Project
A short description of the project.
One or two sentences are enough.
For example:
ashikov.ru is a public engineering knowledge base about Kubernetes, Linux, and DevOps.
Stack
The technologies used in the project.
For example:
- Hugo
- PaperMod
- GitHub
- GitHub Actions
AI should not suggest tools that are already in use.
Structure
The repository structure.
For example:
/ content/posts
/ content/pages
/ prompts
This helps AI navigate the project faster.
Conventions
Engineering conventions.
For example:
- do not create new categories without a reason
- do not add dependencies without justification
- do not change the project structure without an explicit need
Documentation
Documentation rules.
For example:
- keep it concise
- avoid unnecessary text
- show practice instead of theory
Writing Style
Writing guidelines.
For example:
- follow the principles of concise writing
- avoid marketing language
- write as an engineer for engineers
Minimal Example
# Project
ashikov.ru is a public engineering knowledge base about Kubernetes, Linux, and DevOps.
# Stack
- Hugo
- PaperMod
- GitHub Actions
# Rules
- Do not create new categories without a reason
- Do not add dependencies without justification
- Keep the text concise
- Avoid marketing language
What I Do Not Put There
I do not duplicate the README.
I do not copy technical documentation.
I do not try to describe the entire project.
The shorter AGENTS.md is, the easier it is to keep it up to date.
Its only job is to quickly explain how the project works and how AI should interact with it.