Сучасныя ШІ-мадэлі маюць адно вельмі непрыемнае абмежаванне — памер кантэксту (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 годзе выглядаў так:
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 — аўтаматычна працуе з усімі вашымі інструментамі. Больш ніякай фрагментацыі.
💡 Лайфхак для зваротнай сумяшчальнасці:
Калі старая версія інструмента ўсё яшчэ шукае свой вендарны файл, проста стварыце сімвалічную спасылку:
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):
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 абзацы!) растлумачце, з чаго складаецца кодавая база. Асабліва важна для манарэпазіторыяў.
1# Архітэктура
2Манарэпазіторый на TypeScript.
3- `packages/core` — бізнэс-логіка (без залежнасцей ад DOM).
4- `apps/web` — Next.js 15 App Router (толькі UI-слой).
5- `apps/api` — Express + tRPC (API Gateway).
2. 🔧 Тэхналагічны стэк
Дакладна ўкажыце інструменты. Агент не павінен гадаць, які менеджэр пакетаў выкарыстоўваць.
1# Стэк і інструменты
2- Менеджэр пакетаў: ТОЛЬКІ `pnpm`. НЕ `npm`, НЕ `yarn`.
3- Фарматаванне: Biome (НЕ Prettier, НЕ ESLint).
4- Стан: Zustand для client state, TanStack Query для server state.
3. ⚡ Каманды
Дакладныя CLI-каманды — рэцэпты, якія агент можа капіпасціць у тэрмінал.
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), а не абстрактныя апісанні.
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. 🚫 Чырвоныя лініі (абмежаванні)
Тое, што агенту забаронена рабіць. Гэта, бадай, найважнейшы раздзел.
1# Чырвоныя лініі
2- НІКОЛІ не рэдагуй файлы ў `src/generated/`.
3- НІКОЛІ не выдаляй існуючыя тэсты.
4- НЕ дадавай новыя npm-залежнасці без яўнага дазволу.
5- НЕ мяняй канфігурацыю CI/CD пайплайна.
6. ✅ Верыфікацыя
Як агент павінен праверыць сваю працу перад тым, як лічыць задачу выкананай.
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:
1. Праз саміх ШІ-агентаў (Найбольш папулярны падыход)
Самы просты і эфектыўны спосаб — папрасіць ваш ШІ-інструмент (Cursor, Claude Code, Gemini CLI ці ChatGPT) стварыць драфт файла на аснове існуючага рэпазіторыя:
Промпт для ШІ:
"Прааналізуй структуру майго праекта, залежнасці, скрыпты зборкі/тэстаў і згенеруй лаканічны драфт AGENTS.md па стандарце AAIF. Уключы каманды для зборкі, тэставання, лінтынгу і ключавыя канвенцыі."
2. Open-source CLI-генератары
- agentseed — невялікі open-source CLI-інструмент, які робіць статычны аналіз праекта і генеруе пачатковы
AGENTS.md з аўтаматычна вызначанымі камандамі зборкі і тэстаў.
⚠️ Важна: Аўтагенератары і промпты — гэта толькі пачатковы крок. Аўтаматычна згенераваны файл заўсёды трэба прагледзець і дапоўніць уручную: выдаліць лішні шум і дадаць сапраўдныя «чырвоныя лініі» вашай каманды.
Заключэнне: Чэк-ліст для вашага AGENTS.md
AGENTS.md — гэта не яшчэ адзін бюракратычны файл у рэпазіторыі. Гэта кантракт паміж вамі і вашым AI-агентам. Ён вызначае, ці будзе агент ствараць прадукцыйны код у стылі вашай каманды — ці будзе ён генераваць тэхнічна правільны, але абсалютна чужародны код, які вам давядзецца перапісваць уручную ці змарнаваць тоны токенаў.
Перад камітам праверце:
Дарэчы, вядзенне AGENTS.md мае нечаканы пабочны эфект: калі вы сядзеце і пішаце дакладныя правілы для AI-агента, вы адначасова фармалізуеце стандарты сваёй каманды. Тыя негалосныя дамоўленасці, якія жылі ў галовах трох тэхлідаў і перадаваліся вусна на код-рэв'ю, раптам матэрыялізуюцца ў адным файле, які можна прачытаць, абмеркаваць і абнавіць.
І гэта, мабыць, найвялікшая каштоўнасць AGENTS.md — ён робіць нябачнае бачным. Не толькі для машыны, але і для людзей.
Карысныя рэсурсы і спасылкі
