After I started using AGENTS.md in my projects, I quickly noticed 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 the project structure and the rules for working with it. A few sections are usually enough.

Project

This section should contain a short project description. One or two sentences are usually enough.

For example:

ashikov.ru is a public engineering knowledge base about Kubernetes, Linux, and DevOps.

Stack

This section lists the main technologies used in the project.

For example:

  • Hugo
  • PaperMod
  • GitHub
  • GitHub Actions

AI should not suggest tools that are already part of the project.

Repository Structure

This section shows the main directories.

For example:

/content/posts
/content/pages
/prompts

That is enough to help AI navigate the project and avoid creating new structure without a reason.

Conventions

This section contains engineering rules for working with the project.

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

This is not architecture documentation. It is a short set of rules that helps preserve existing decisions.

Documentation

This section describes how documentation and text should be written.

For example:

  • keep it concise
  • avoid unnecessary text
  • show practice instead of theory

If the project has separate documentation rules, AGENTS.md can link to them, but it should not duplicate them in full.

Writing Style

For projects with public content, it is useful to describe the writing style separately.

For example:

  • write clearly and concisely
  • avoid marketing language
  • write as an engineer for engineers

This helps keep the project voice consistent.

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

This example is enough to show the format without turning the article into an AGENTS.md template.

What I Do Not Put There

I do not duplicate the README, copy technical documentation, or 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 the project structure and the rules for working with it.