What is agents.md?

agents.md is a markdown file used to give instructions and context to an AI coding agent. It helps the AI understand the project before it starts making changes.

It usually explains:

  • What the project is about
  • What the goals are
  • Coding standards
  • Folder structure
  • What it should and should not do

In simple terms, agents.md is a guidebook for the AI agent working on your project.

Simple takeaway:

Without clear project instructions, an AI coding tool has to guess more. A strong agents.md reduces that guesswork.

Why markdown works so well

The file is written in Markdown format, which is simple, human-readable, and structured enough for large language models to parse quickly.

For example:

# Heading = Big heading
## Heading = Subheading
- Bullet points
1. Numbered list

LLMs work well with markdown because it is clean, structured, and easy to understand.

Where should you place agents.md?

Most teams place agents.md in the project root folder. When the AI agent starts working, it reads that file and uses it as instructions for the rest of the task.

You can also place agents.md files inside subfolders. In that case:

  • The AI reads the agents.md in the current folder
  • Then it reads agents.md in parent folders
  • Inner folder rules override outer folder rules

This creates a hierarchy of instructions.

project/
    agents.md
    backend/
        agents.md
    frontend/
        agents.md

In that example, the frontend agent can follow different rules than the backend agent while still inheriting the overall project context from the root.

What should you write in agents.md?

A good agents.md usually contains a few high-value sections:

1. Project goal

What the AI is trying to build or improve.

2. Success criteria

What defines that the task is actually complete.

3. Coding standards

Useful standards can include rules like:

  • Write simple and readable code
  • Keep README updates short and useful
  • Only comment when it adds real clarity
  • Handle exceptions only when needed
  • Prefer specific tools such as uv instead of raw python commands when the project expects it

4. Checklist

A checklist helps the AI complete tasks step by step instead of jumping around or stopping too early.

5. Links to other documents

This can include references to database schema docs, API docs, deployment notes, or architecture guides.

Important tips for writing agents.md

The best instruction files are usually:

  • Concise
  • Clear
  • Specific
  • Focused on high-value instructions

Avoid long explanations when a short instruction will do. Every word matters because this file is part of the AI context window, and context space is limited.

Writing tip:

AI models often follow positive instructions better than negative ones. Instead of saying "Do not write long code," say "Write simple and concise code."

2025 vs 2026 AI agent mindset

There are two common ways teams think about AI agent workflows. One is more instruction-heavy and controlled. The other gives the AI a goal and expects it to self-correct more independently.

2025 Approach 2026 Approach
Carefully write agents.md Give the goal and let the AI figure out more
Control AI strictly Let AI self-correct more often
Optimize context manually Use multiple agents and broader delegation
Manual planning Agent loops and automation

The older approach focuses heavily on writing a very strong agents.md. The newer approach puts more emphasis on defining the end goal and letting the AI work more independently.

Even so, for large and serious projects, many developers still prefer the structured approach with a strong agents.md file. It creates consistency, reduces drift, and helps different AI tools behave in a more reliable way.

Final thought

If you are building real projects with AI coding tools, agents.md can make a huge difference in output quality. It acts like a project manager for the AI, guiding it on how to write code, how to structure the project, and what the final goal is.

Used well, it turns AI from a simple code generator into a more capable coding assistant.