Working with AI quickly teaches one lesson: the quality of the output depends as much on context as it does on the model itself.

Without understanding the project, AI starts making reasonable assumptions that are wrong for your codebase. It may suggest a different technology stack, reorganize the repository, or introduce unnecessary abstractions.

To avoid that, I use AGENTS.md.

What Is AGENTS.md

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

It lives in the repository and describes how the project should be approached.

Its purpose is simple: provide the context that would otherwise have to be explained at the beginning of every new conversation.

What Problem Does It Solve

Without context, AI has to guess.

That often leads to suggestions such as:

  • introducing tools that are already in use
  • breaking established engineering conventions
  • reorganizing the project structure without a reason
  • making simple solutions unnecessarily complex

Most of these mistakes are not caused by the model itself. They are caused by missing project context.

Why I Started Using It

During the day, I switch between multiple projects.

Each has its own technology stack, repository structure, and engineering conventions.

Repeating that context over and over again became inefficient.

It is much easier to describe it once and keep it close to the code.

Where AGENTS.md Lives

I usually place the file in the root of the repository.

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

That way it evolves together with the project.

What AGENTS.md Usually Contains

The exact content depends on the project, but I usually keep:

  • a short project description
  • the technology stack
  • the repository structure
  • engineering conventions
  • project constraints
  • documentation rules
  • writing guidelines

That is enough for AI to understand how the project is organized and how it should work with it.

Conclusion

At first, I thought of AGENTS.md as documentation for AI.

Over time, I realized it is something more.

It is a way to make project context explicit.

In my experience, that is the foundation for predictable work-not only for AI, but for any engineer opening the repository for the first time.