I regularly work with AI tools: ChatGPT, Codex, Gemini CLI, and local models.

They all have the same problem: lack of context.

Every new conversation starts from scratch. I have to explain the project structure, conventions, and constraints again.

Without this information, AI works without understanding the project.

To solve this problem, I use AGENTS.md.

What Is AGENTS.md

AGENTS.md is a file that contains instructions for AI agents.

It lives inside the repository and describes how to work with the project.

In practice, it is documentation for AI.

Its purpose is simple: describe the project context once and stop repeating the same instructions in every new conversation.

What Problem Does It Solve

Without context, AI often makes mistakes.

Typical examples:

  • adding unnecessary complexity
  • suggesting tools that are already in use
  • ignoring existing conventions
  • introducing extra abstractions
  • violating project constraints

The larger the project, the more visible these problems become.

This is especially noticeable in infrastructure repositories.

Why I Started Using It

During the day, I constantly switch between different tasks:

  • Kubernetes
  • CI/CD
  • infrastructure repositories
  • documentation
  • internal engineering projects

Repeating the same context over and over again turned out to be inefficient.

It is much easier to describe the rules once and keep them up to date.

This reduces cognitive load and makes the results more predictable.

Where AGENTS.md Lives

I usually keep it in the root of the repository.

project/
├── AGENTS.md
├── README.md
├── docs/
├── src/
└── ...

The file becomes part of the project and evolves together with it.

What People Usually Put in AGENTS.md

The content depends on the project, but it usually includes:

  • the project’s purpose
  • the technology stack
  • the repository structure
  • engineering conventions
  • constraints and restrictions
  • documentation rules
  • writing style guidelines
  • decision-making principles

This is neither a README nor technical documentation.

Its only job is to quickly explain how the project works and how AI should interact with it.