AGENTS.md: A Single Source of Truth for AI Agents

**AGENTS.md is the main cheat sheet for the AI assistant in the project. In it, we write in simple words: where you can go, where you can not, how everything is arranged in our country. A beginner or an agent takes 5-10 minutes to read and doesn’t break the project.

## The simplest AGENTS templates. md

I almost always start with a template. When the project is new, I just take the workpiece, change a couple of lines to my stack, and I can work.

Now I have three options. They cover the most frequent cases: From a simple site to a more complex backend with data and integrations.

Importantly, these patterns are not a “universal solution.” I show them as examples from my projects, so that there is something to start from, not to copy blindly.

AGENTS.md I don’t write at the beginning. First, at least some kind of project plan should appear – it is usually born directly in a dialogue with AI: what we do, why, in what order.

And only when this plan becomes clear, I fix it in AGENTS.md. In fact, this is a way to preserve the agreement: How we decided to do this project and where you can't start "smarting up.".

At the end, I just wrote how to build Agents.md for my project. It is based on a plan, not on abstract rules.

** Template 1 - for a lightweight web project (landing, blog, Next.js without extra) **

AGENTS.md – Our Simple Rules

Project: a site for displaying content, without complex features.
Wibe: Quick, readable, for beginners.

Stack:
- frontend: Next.js, Tailwind CSS
- backend: if needed - Express.js

What can I do?
Add pages to app/or components/
Change styles in Tailwind
Write simple API routes in api/

What you can't do without my glasses:
Add new libraries like Zustand or Redux
Create a global state - only useState
Change navigation to something other than Next Link
Write console.log only in dev, and it is rare.

Files are kept short: up to 200 lines.
If the idea seems complicated, ask, “Is it still easy or is it overkill?”

** Template 2 – for mobile or Telegram-bot (WebApp with UI and logic) **

AGENTS.md - how we work with the bot

Project: Telegram WebApp with screens and data.
Vibe: smooth, no lags, easy to understand.

Stack:
- client: JavaScript, possibly React
- src: Node.js for API and bot

Switching screens:
- Only through our NavigationManager
Page render: RenderManager with token verification

Scrolling:
Only in #mainContent, do not touch the body.

Logs:
No console.log, just logger. js

What can I do?
Add buttons and forms to existing pages
Call the API via ApiClient
Track events in analytics/track

What can't be:
Bypass NavigationManager
Add direct DOM changes
Introduce new layers like middleware for no reason

If you’re not sure, ask, “Will this break the gesture back or the render?”

** Template 3 – for data project (data analysis, scripts in Python) **

AGENTS.md – rules for data

Project: scripts for data processing, graphs, reports.
Vibe: clean, reproducible, without unnecessary dependencies.

Stack:
- Python with Pandas, Matplotlib
If ML is Scikit-learn, it's not complicated.

What can I do?
Read data from CSV/Excel via Pandas
- graphing in Matplotlib
Write functions for calculations

What you can do without ok:
Add new packages like TensorFlow
Change the data structure to complex classes
Write cycles instead of vector operations
Ignore mistakes and always process them

Files: One script = one task, up to 300 lines.
Ask, if in doubt, “Is it still effective or is it slow?”

** Template 4 - for backend with API (server, integration as in e-commerce)**

AGENTS.md - backend rules

Project: API server with routes, payments, webhooks.
Vibe: Safe, minimal, no hacks.

Stack:
- Node.js, Express
- routes in src/routes/

Key areas:
- auth: auth.router only. js
Payments: in payments.js, do not touch without tests
Webhooks: yookassa/bitrix in webhooks. js

What can I do?
Add routers to existing files
- update models in db/
- logger

What can't be:
- hardcode keys or env
- bypass middleware
Introduce new bases without discussion
- change production without deplo

All changes are made with the docs update.
If the idea is risky, ask, “Is it safe to produce?”

## What if I'm new?

Even if you don’t know React, Next.js, navigation, routers and other technical words, you can still do it.
Just write what is important to you in human language: “I want to quickly”, “do not complicate”, “so that I do not get confused later”.
The AI itself will understand and turn your simple desires into clear rules for itself.

## The easiest way is to tell the AI what you want to feel

You don't have to know the terms. Just tell the agent something like this:

“I am new to programming.
I want to make a Telegram bot or a simple app in a telegram.
It is important to me that:

• everything was simple and clear
• the code didn't get huge and confusing
• i could figure it out in a month
• you didn't offer complicated things that i don't understand
• i didn't add a bunch of new libraries without my permission

Write me the AGENTS.md file in simple words, as if you were writing to a beginner friend.
So that you can work on it yourself and not complicate my life

AI will almost always produce a normal file. This is what usually happens after such a request.

## An example of AGENTS.md is what AI does when you say, “I’m a beginner, it’s simple.”

AGENTS.md - our simple agreements

We're doing a project for me new.

The main wish:
See results quickly
- the code is short and clear
- so I can change things myself without fear.

What can be done:
- add new buttons, text, pictures
- change colours and inscriptions
Correcting the mistakes I see
Write comments to make it clear what each part does.

What to do without my “yes”:
Add new libraries and packages
Create many new files and folders
Write very long functions (more than 30-40 lines – ask already)
- Invent a complex login system, unless I asked
Change everything at once (better a little).

If you think you can make it more beautiful or faster, ask first:
"Do you want me to do this?" Will it be easier or harder for you?

If in doubt, it is better to ask than to redo.

## Another option is when you're tired of saying "let's add..."

Tell the agent this:

I don’t know what Zustand, Redux, Context, etc. are.
Every time you offer something like that, I'm scared and confused.
Write AGENTS.md, which will say that we use only the simplest methods.
And if something seems complicated, you have to ask me first.
Make the text very simple, without technical words

It goes something like this:

AGENTS.md - rules for beginners

We agreed: everything is as simple as possible!

It is forbidden to offer:
Zustand.
- Redux.
- Context API
- useReducer
- any words I don't understand

Allowed:
- the usual useState for data storage
Transmit data via props
If you have a lot of data, ask me before you come up with a solution.

If you want to do something adult, write:
“I know a better way, but it’s a little more complicated. Do you want to try it or just leave it?

Purpose: so that I am not afraid to open the code and can fix something myself.

## A universal query that almost always works

If you do not know what to say, just throw it:

“I'm completely new.
I don't know how to code properly.
I want you to help, but not complicate it.
Write me AGENTS.md, which will remind you:

• talk to me in simple terms
• offer only the easiest ways
• always ask if the decision seems difficult
• keep the code short and clear

Make the file short, friendly, without scary words

## What to do after an AI has written a file

1. Read it (usually 10-20 lines).
2. If you don’t like something, say, “Please add that files shouldn’t be longer than one page” or “Put out the word Zustand, I don’t even know it.”.
3. Save as AGENTS.md in the folder with the project. (you can ask the AI to save it)
4. Every time you start a new conversation with AI, start a message with: Analyze our AGENTS.md, follow it. After that, AI usually becomes much calmer and clearer.