AGENTS.md: Вучым AI-агента правілам вашага праекта

Agents

Сучасныя ШІ-мадэлі маюць адно вельмі непрыемнае абмежаванне — памер кантэксту (context window). Гэта колькасць інфармацыі са знешняй крыніцы, якую мадэль можа трымаць адначасова ў сваёй «працоўнай памяці». Звычайна гэта абмежавана некалькімі мільёнамі токенаў.

На першы погляд, мільёны токенаў — велізарная лічба. Але ёсць вялікае АЛЕ.

Мадэль не памятае, што вы пыталі ў яе ў мінулы раз. Кожны новы запыт у ШІ-чаце яна ўспрымае як поўнасцю новы — быццам бачыць вас упершыню. Таму, каб мадэль заўсёды ведала, што яна ўжо зрабіла і што збіраецца рабіць далей, яна кожны раз перачытвае ўсю перапіску: усе вашы запыты, усе свае адказы, увесь кантэкст — з самага пачатку сэсіі.

Для простага чату гэта можа і не быць праблемай. Але пры распрацоўцы кода аб'ёмы ўваходных даных рэзка ўзрастаюць. Бо акрамя вашай перапіскі мадэль атрымлівае велізарныя масівы кода: файлы, якія яна чытае, дыфы, якія яна генеруе, вынікі тэрмінальных каманд, вывад лінтараў і тэстаў. І гэта расце як снежны ком — чым больш уваходнай інфармацыі, тым больш грошай выдаткоўваецца на апрацоўку кожнага запыту, і тым менш месца застаецца для сапраўды карыснага кантэксту.

У нейкі момант гэта прывяло распрацоўшчыкаў ШІ-агентаў (рэдактараў кода) да дзвюх ключавых ідэй:

Фільтраваць кантэкст — у мадэль павінна трапляць толькі патрэбная інфармацыя, а не ўвесь рэпазіторый цалкам. Скараціць уваходныя і выходныя даныя (разам з вынікамі разважанняў).
Даваць мадэлі «памятку» — кароткі, структураваны файл з правіламі і абмежаваннямі канкрэтнага праекта, каб агент не марнаваў дарагі кантэкст на «даследванне» таго, які менеджэр пакетаў выкарыстоўваецца ці якія тэчкі нельга чапаць.

І гэтыя падыходы могуць вырашыць яшчэ адну праблему: ШІ-агенты не ведаюць патрабаванняў да вашай кодавай базы без дадатковых даследаванняў. Яны не ведаюць, што ваша каманда выкарыстоўвае pnpm, а не npm. Не ведаюць, што тэчка src/generated/ — недатыкальная "святая карова", якую генеруе CI-пайплайн. Не ведаюць, што ўсе API-адказы ў вас абгорнуты ў Result<T, E>, а не ляцяць праз try/catch. Яны геніяльныя ў цэлым, але сляпыя да кантэксту вашага рэпазіторыя.

Менавіта для вырашэння гэтых праблем і з'явіўся AGENTS.md — невялікі Markdown-файл, які расказвае штучнаму інтэлекту правілы гульні ў вашым праекце. Ён займае мінімум месца ў кантэкстным вакне, але дае мадэлі максімум карыснай інфармацыі.

Гісторыя з'яўлення: заапарк рашэнняў

Доўгі час кожны вендар вырашаў праблему кантэксту па-свойму. Cursor прыдумаў .cursorrules. Anthropic — CLAUDE.md. GitHub — .github/copilot-instructions.md. Windsurf — .windsurfrules.

Вынік? Тыповы рэпазіторый у 2025 годзе выглядаў так:

text
1my-project/
2├── .cursorrules              # Правілы для Cursor
3├── CLAUDE.md                 # Правілы для Claude Code
4├── .github/
5│   └── copilot-instructions.md   # Правілы для GitHub Copilot
6├── .windsurfrules            # Правілы для Windsurf
7├── .continue/
8│   └── config.json           # Правілы для Continue
9└── README.md                 # І яшчэ README для людзей!

Пяць розных файлаў з практычна аднолькавым зместам, якія разыходзіліся паміж сабой на працягу тыдняў. Вы абнаўляеце правіла ў .cursorrules, забываеце пра CLAUDE.md — і Anthropic-агент працягвае генераваць код у старым стылі. Класічны version drift (разыходжанне версій) — толькі не паміж кодам і тэстамі, а паміж інструкцыямі для розных ШІ.

Гэта як калі б вы трымалі пяць асобных памятак для пяці новых супрацоўнікаў, прычым у кожнай — трохі іншыя правілы. Хаос гарантаваны.

Каб спыніць гэтае шаленства, распрацоўшчыкі аб'ядналася вакол адзінага, вендара-незалежнага стандарту — файла AGENTS.md, які кіруецца Agentic AI Foundation (AAIF) пад эгідай Linux Foundation. Сярод заснавальнікаў фундацыі — AWS, Anthropic, Google, Microsoft, OpenAI і Block.

Што такое AGENTS.md? README для чалавека vs README для машыны

Ідэя элегантна ў сваёй прастаце. У кожнага праекта ёсць README.md — файл, які тлумачыць чалавеку, як праект уладкаваны, як яго запусціць і навошта ён увогуле існуе. AGENTS.md — гэта тое ж самае, але для AI-агента.

Розніца ў аўдыторыі вызначае ўсё:

	`README.md`	`AGENTS.md`
Чытач	Чалавек-распрацоўшчык	AI-агент (LLM)
Тон	Запрашальны, апісальны	Імператыўны, строгі
Мэта	Зразумець і натхніцца	Не наламаць і зрабіць правільна
Прыклад	«Мы выкарыстоўваем React 19 і TanStack Router для навігацыі»	«Заўсёды выкарыстоўвай `pnpm`. НІКОЛІ не выкарыстоўвай `npm` ці `yarn`»
Аптымізацыя	Пад візуальнае ўспрыняцце	Пад бюджэт токенаў

Звярніце ўвагу на тон: калі ў README мы пішам мяккім запрашальным стылем («Мы выкарыстоўваем…»), то ў AGENTS.md — жорсткія імператывы («Заўсёды…», «НІКОЛІ…»). AI-агент — не калега, з якім трэба быць далікатным. Гэта высокапрадукцыйны аўтамат, якому трэба дакладныя каманды, а не натхненне.

Хто ўжо падтрымлівае AGENTS.md?

Кароткі адказ: практычна ўсе. Станам на 2026 год стандарт AGENTS.md чытаюць:

OpenAI Codex — аўтаматычна чытае AGENTS.md пры старце сэсіі. Падтрымлівае шматузроўневую іерархію (ад кораня да бягучай дырэкторыі) і нават глабальны файл ~/.codex/AGENTS.md для персанальных правілаў, якія дзейнічаюць ва ўсіх рэпазіторыях.
Cursor — аўтаматычна прачытвае AGENTS.md з кораня і паддырэкторый і ўпляце яго ў кожны запыт да мадэлі. Таксама падтрымлівае ўласны фармат .cursor/rules/*.mdc для больш гранулярнага кіравання.
GitHub Copilot Coding Agent — падтрымлівае як першаснае крыніца праектных правілаў.
Claude Code — чытае і AGENTS.md, і CLAUDE.md, але калі ёсць абодва — прыярытэт у AGENTS.md.
Aider — загружае AGENTS.md як канвенцыі праекта пры старце сэсіі.
OpenHands / SWE-bench агенты — скануюць AGENTS.md для фарміравання базавага кантэксту.
Gemini CLI / Antigravity — прымаюць як кантэкстны файл для кіравання правіламі.
Goose (Block) — чытае AGENTS.md як адзін з трох ключавых праектаў AAIF.
Zed / JetBrains Junie / VS Code / Warp / Devin / Windsurf / Amp / RooCode — і яшчэ дзясяткі іншых.

Гэта азначае, што адзін файл — AGENTS.md — аўтаматычна працуе з усімі вашымі інструментамі. Больш ніякай фрагментацыі.

💡 Лайфхак для зваротнай сумяшчальнасці: Калі старая версія інструмента ўсё яшчэ шукае свой вендарны файл, проста стварыце сімвалічную спасылку:
bash
1ln -s AGENTS.md CLAUDE.md
2ln -s AGENTS.md .cursorrules
Адзін файл праўды, нуль дубліравання.

Іерархія ў манарэпазіторыях: «Бліжэйшы файл выйграе»

У вялікіх манарэпазіторыях (monorepos) адзінага AGENTS.md у корані часта недастаткова. Frontend-каманда піша на React з Vitest, backend — на Go з golangci-lint, ML-каманда — на Python з pytest. У іх розныя стандарты кода, розныя каманды запуску, розныя чырвоныя лініі.

AGENTS.md вырашае гэта праз іерархічнае разрашэнне (Hierarchical Resolution) па правіле «бліжэйшы файл у прыарытэце» (closest-file-wins):

text
1my-monorepo/
2├── AGENTS.md                 ← Глабальныя правілы каманды
3├── apps/
4│   ├── web/
5│   │   ├── AGENTS.md         ← Правілы для React / Next.js фронтэнда
6│   │   └── src/
7│   └── api/
8│       ├── AGENTS.md         ← Правілы для Go / gRPC бэкенда
9│       └── main.go
10├── packages/
11│   └── shared/
12│       └── AGENTS.md         ← Правілы для shared-бібліятэкі

Калі агент рэдагуе файл apps/api/main.go, ён:

Чытае каранёвы AGENTS.md (базавыя правілы для ўсіх).
Затым чытае apps/api/AGENTS.md — і дапаўняе або перавызначае базавыя правілы лакальнымі.

Гэта працуе як CSS-каскад: больш спецыфічнае правіла заўсёды перамагае агульнае.

Анатомія добрага AGENTS.md: 6 блокаў, якія мусяць быць

Стандарт свядома абраў чысты Markdown — ніякіх YAML-метададзеных, JSON-схем ці спецыяльнага сінтаксісу. Проста Markdown. Гэта робіць парог уваходу нулявым: калі вы ўмееце пісаць README, вы ўмееце пісаць AGENTS.md.

На аснове аналізу тысяч рэпазіторыяў вылучыліся 6 блокаў, якія робяць AGENTS.md сапраўды карысным:

1. 🏗️ Архітэктура праекта

Каротка (1–2 абзацы!) растлумачце, з чаго складаецца кодавая база. Асабліва важна для манарэпазіторыяў.

markdown
1# Архітэктура
2Манарэпазіторый на TypeScript.
3- `packages/core` — бізнэс-логіка (без залежнасцей ад DOM).
4- `apps/web` — Next.js 15 App Router (толькі UI-слой).
5- `apps/api` — Express + tRPC (API Gateway).

2. 🔧 Тэхналагічны стэк

Дакладна ўкажыце інструменты. Агент не павінен гадаць, які менеджэр пакетаў выкарыстоўваць.

markdown
1# Стэк і інструменты
2- Менеджэр пакетаў: ТОЛЬКІ `pnpm`. НЕ `npm`, НЕ `yarn`.
3- Фарматаванне: Biome (НЕ Prettier, НЕ ESLint).
4- Стан: Zustand для client state, TanStack Query для server state.

3. ⚡ Каманды

Дакладныя CLI-каманды — рэцэпты, якія агент можа капіпасціць у тэрмінал.

markdown
1# Каманды
2- Устаноўка: `pnpm install`
3- Зборка: `pnpm build`
4- Тэсты: `pnpm test`
5- Адзін тэст: `pnpm test -- path/to/file.test.ts`
6- Лінтынг: `pnpm lint && pnpm format:check`

4. 📐 Стандарты кода

Тут найлепш працуюць канкрэтныя прыклады (Good vs Bad), а не абстрактныя апісанні.

markdown
1# Стандарты
2Усе API-хэндлеры вяртаюць `Result<T, E>`, а не кідаюць exceptions.
3
4❌ ДРЭННА:
5try { await fetchUser(); } catch (e) { console.log(e); }
6
7✅ ДОБРА:
8const result = await fetchUser();
9if (!result.ok) { logger.error('Fetch failed', { err: result.error }); return null; }

5. 🚫 Чырвоныя лініі (абмежаванні)

Тое, што агенту забаронена рабіць. Гэта, бадай, найважнейшы раздзел.

markdown
1# Чырвоныя лініі
2- НІКОЛІ не рэдагуй файлы ў `src/generated/`.
3- НІКОЛІ не выдаляй існуючыя тэсты.
4- НЕ дадавай новыя npm-залежнасці без яўнага дазволу.
5- НЕ мяняй канфігурацыю CI/CD пайплайна.

6. ✅ Верыфікацыя

Як агент павінен праверыць сваю працу перад тым, як лічыць задачу выкананай.

markdown
1# Верыфікацыя
2Перад завяршэннем задачы ты МУСІШ:
31. Запусціць `pnpm typecheck` — нуль памылак TypeScript.
42. Запусціць `pnpm test` для закранутых модуляў — усе тэсты зялёныя.
53. Запусціць `pnpm lint` — нуль парушэнняў.

Лепшыя практыкі: Як пісаць AGENTS.md, каб ён сапраўды працаваў

Парада 1: Трымайце бюджэт кантэксту

Самая пашыраная памылка — запіхнуць у AGENTS.md ўсю дакументацыю каманды: гайдлайны на 50 старонак, поўны API-даведнік, гісторыю архітэктурных рашэнняў за апошнія тры гады.

Ідэальны памер — ад 50 да 200 радкоў.

Чаму гэта крытычна? Кожны радок AGENTS.md трапляе ў кожны запыт да LLM. Файл на 2000 радкоў — гэта не проста марнаванне грошай на токены. Гэта актыўнае пагаршэнне якасці генерацыі: мадэль губляе ўвагу (attention dilution) і пачынае ігнараваць як вашы інструкцыі, так і сам код.

Гэта як калі б вы далі новаму супрацоўніку памятку на 200 старонак і чакалі, што ён запомніць кожнае слова. Спойлер: ён не запомніць.

Парада 2: Паказвайце, а не апісвайце

AI-мадэлі ўспрымаюць канкрэтныя прыклады кода значна лепш, чым абстрактныя тэксты.

❌ Так не працуе:

«Заўсёды пішыце чысты код з правільнай апрацоўкай памылак і выкарыстоўвайце кастомныя хукі ў React.»

Гэта занадта размыта. Мадэль не разумее, што менавіта вы лічыце «чыстым кодам» у вашым праекце.

✅ А так — працуе:

Пакажыце два блокі кода: адзін з пазнакай ❌ BAD, другі — ✅ GOOD. Мадэль па ходзе выберыць правільны патэрн.

Парада 3: Імператыўная мова, а не рэкамендацыі

AI-агент — не калега, з якім трэба быць палітычна карэктным. Размытыя фармулёўкі («пажадана», «было б добра», «па магчымасці») — ваш вораг.

❌ Размыта	✅ Дакладна
«Было б добра выкарыстоўваць TypeScript strict mode»	«Выкарыстоўвай TypeScript strict mode. Заўсёды.»
«Па магчымасці пішы юніт-тэсты»	«Для кожнай новай функцыі стварай юніт-тэст»
«Лепш не чапаць generated-файлы»	«НІКОЛІ не рэдагуй файлы ў `src/generated/`»

Парада 4: Пішыце толькі тое, чаго мадэль не ведае

Няма сэнсу пісаць агенту «Пераменныя мусяць мець зразуметыя назвы» ці «Выкарыстоўвай async/await у JavaScript». Сучасныя мадэлі (Claude Opus, Gemini 3.6 Flash, GPT-5.6) ужо ведаюць усе агульнапрынятыя стандарты моў.

Пішыце ТОЛЬКІ тое, што унікальна для вашага рэпазіторыя: нестандартныя канвенцыі, лакальныя абмежаванні, спецыфічныя каманды.

Антыпатэрны: Як НЕ трэба пісаць AGENTS.md

❌ Prompt Bloat — раздуванне прампта

Вы ўставілі ў AGENTS.md поўны eslint.config.js на 500 радкоў, гайд па стылю на 30 старонак і архітэктурны RFC трохгадовай даўніны. Мадэль тоне ў тэксце і пачынае ігнараваць усё — і вашы правілы, і сам код.

❌ Змешванне з README

У AGENTS.md з'яўляюцца інструкцыі тыпу «Каб усталяваць праект на macOS, спачатку ўсталюйце Homebrew…» або спасылкі на HR-партнерку і Confluence. Агент — не новы супрацоўнік, які чытае анбордынг. Кожны лішні радок — гэта марнаванне вашага бюджэту токенаў.

❌ Сакрэты ў файле

Хтосьці дадаў у AGENTS.md тэставы API-ключ, пароль ад staging-базы або токен ад Slack. AGENTS.md каміціцца ў Git. Усе вашы сакрэты — цяпер у гісторыі рэпазіторыя. Назаўсёды.

❌ Супярэчлівыя правілы ў іерархіі

У каранёвым AGENTS.md напісана: «Усе тэсты на Jest». А ў apps/web/AGENTS.md — «Выкарыстоўвай Vitest». Без яўнага ўказання , што лакальнае правіла перавызначае глабальнае (хоць і павінна спрацаваць, але заўседы есць "але"...). Вынік: агент блытаецца, галюцынуе і генеруе нешта сярэдняе паміж Jest і Vitest — што не працуе ні там, ні там. (Лепш удакладняць што у гэтай тэчцы - Vitest)

❌ Забытыя інструкцыі (Stale Rules)

Праект два месяцы таму перайшоў з REST на gRPC. А ў AGENTS.md дасюль напісана «Усе эндпоінты — RESTful, выкарыстоўвай Express Router». Агент зацята генеруе Express-хэндлеры, якія больш не маюць сэнсу.

Правіла: Ставіцеся да AGENTS.md як да жывога дакумента. Кожны вялікі рэфактарынг — праверце, ці абнавілі вы інструкцыі для ШІ.

Генератары AGENTS.md: Як стварыць файл аўтаматычна

Не хочаце пісаць AGENTS.md з нуля? Існуюць CLI-інструменты, якія аналізуюць вашу кодавую базу (мовы, залежнасці, структуру тэчак, скрыпты зборкі) і генеруюць стартавы варыянт файла.

🔧 agentseed

Найпапулярнейшы генератар. Робіць статычны аналіз праекта і стварае AGENTS.md з аўтаматычна вызначанымі камандамі зборкі, тэстаў і лінтынгу. Можа таксама стварыць сімвалічныя спасылкі для .cursorrules і CLAUDE.md, каб вы далей трымалі толькі адзін файл.

bash
1# Хуткі старт — аналіз праекта і генерацыя AGENTS.md
2npx agentseed init
3
4# З выкарыстаннем LLM для больш разумнага змесціва
5export ANTHROPIC_API_KEY=your_key
6npx agentseed init --provider claude
7
8# Генерацыя файлаў для ўсіх фарматаў адразу
9npx agentseed init --format all

🧪 agents-md-generator (LobeHub)

Камбінуе статычны аналіз з інтэрактыўным Q&A: інструмент пытае ў вас удакладненні і захоўвае вашы ручныя праўкі пры паўторнай генерацыі.

🌐 Apify AGENTS.md Generator

Вэб-сэрвіс, які часова кланіруе ваш рэпазіторый, аналізуе яго з дапамогай LLM і генеруе файл праз API (Зьвяртайце увагу на бяспеку).

Проста паставіць задачу ШІ-агенту

Просты падыход, але стварае часам шмат недакладнасцяў і шуму.

⚠️ Важна: Генератары — выдатны стартавы пункт, але не фінальнае рашэнне. Аўтаматычна згенераваны файл заўсёды трэба прагледзець і дапоўніць уручную. Толькі вы ведаеце сапраўдныя «чырвоныя лініі» і негалосныя дамоўленасці вашай каманды.

Заключэнне: Чэк-ліст для вашага AGENTS.md

AGENTS.md — гэта не яшчэ адзін бюракратычны файл у рэпазіторыі. Гэта кантракт паміж вамі і вашым AI-агентам. Ён вызначае, ці будзе агент ствараць прадукцыйны код у стылі вашай каманды — ці будзе ён генераваць тэхнічна правільны, але абсалютна чужародны код, які вам давядзецца перапісваць уручную ці змарнаваць тоны токенаў.

Перад камітам праверце:

Памер — менш за 200 радкоў (калі больш — разбіце на іерархічныя файлы).
Мова — імператыўная («Заўсёды…», «НІКОЛІ…»), без «жадана» і «па магчымасці».
Каманды — дакладныя CLI-рэцэпты для зборкі, тэстаў і лінтынгу.
Чырвоныя лініі — яўна названы файлы і тэчкі, якія агенту забаронена чапаць.
Прыклады — канкрэтныя блокі кода ❌ BAD / ✅ GOOD для ключавых патэрнаў.
Бяспека — ніякіх API-ключаў, пароляў і канфідэнцыйнай інфармацыі.
Спецыфіка — выдалены правілы, якія мадэль ужо ведае па змаўчанні.
Актуальнасць — інструкцыі адпавядаюць бягучаму стану кодавай базы.

Дарэчы, вядзенне AGENTS.md мае нечаканы пабочны эфект: калі вы сядзеце і пішаце дакладныя правілы для AI-агента, вы адначасова фармалізуеце стандарты сваёй каманды. Тыя негалосныя дамоўленасці, якія жылі ў галовах трох тэхлідаў і перадаваліся вусна на код-рэв'ю, раптам матэрыялізуюцца ў адным файле, які можна прачытаць, абмеркаваць і абнавіць.

І гэта, мабыць, найвялікшая каштоўнасць AGENTS.md — ён робіць нябачнае бачным. Не толькі для машыны, але і для людзей.

Карысныя рэсурсы і спасылкі

Рэсурс	Спасылка
🌐 Афіцыйны сайт AGENTS.md	agents.md
📦 GitHub-рэпазіторый стандарту	github.com/agentsmd/agents.md
🏛️ Agentic AI Foundation (AAIF)	aaif.io
🔧 Генератар agentseed (CLI)	github.com/avinshe/agentseed
🔧 Генератар agents-md-generator	github.com/lobehub/agents-md-generator
🔧 Apify AGENTS.md Generator	apify.com/themineworks/agents-md-generator
📖 OpenAI Codex	openai.com/codex
📖 Cursor AI Rules docs	cursor.com
📖 Aider Conventions docs	aider.chat/docs/usage/conventions
📖 Zed AI Rules docs	zed.dev/docs/ai/rules
📖 GitHub Copilot Coding Agent	gh.io/coding-agent-docs
📖 Gemini CLI Configuration	github.com/google-gemini/gemini-cli
📖 Goose (Block)	github.com/block/goose
🔍 Пошук рэпазіторыяў з AGENTS.md	GitHub Search: AGENTS.md

Admin, 2026-08-12

Каментары

Ваша імя

Ваш каментар

(Каб даслаць каментар залагуйцеся ў свой уліковы запіс)