Вашому коду потрібна інструкція для ШІ

Чому AGENTS.md може стати початком нового шару архітектури програм

Раніше код пояснював себе розробникам. Тепер йому треба пояснювати себе і машинам.

Коротко

• AGENTS.md це звичайний Markdown-файл у корені репозиторію, який пояснює ШІ-агентам, як працювати з проєктом: команди, обмеження і правила, яких не видно з коду.
• Його читають понад двадцять інструментів для програмування, серед них Codex, Cursor, Gemini CLI і Copilot. З 18 вересня 2026 року його читає і Claude Code.
• З грудня 2025 року AGENTS.md розвивається в Agentic AI Foundation під крилом Linux Foundation, разом із MCP.
• Дослідження ETH Zürich показує, що більше контексту не означає краще: короткі файли, написані людьми, трохи допомагають, а довгі чи згенеровані додають вартості без користі.
• Найцінніші рядки в такому файлі це не правила коду. Це уроки бізнесу, про які код сам не розповість.

ЯК МИ ПОЧАЛИ

Раніше, ніж це стало новиною

У PERETZ ми не працюємо всередині однієї екосистеми ШІ. У різних проєктах різні моделі й різні середовища розробки. Іноді вибір залежить від завдання, іноді від етапу проєкту, а іноді ми просто знаємо, що одна модель робить щось краще за іншу.

Середовище розробки з ШІ давно перестало бути автодоповненням із вікном чату. Сучасні агенти вивчають репозиторій, шукають у файлах, запускають команди, правлять код, проганяють тести і проходять багатокрокові завдання. Claude став для нас особливо корисною частиною цієї роботи, і я свідомо називаю його асистентом, а не інструментом. Інструмент чекає, поки ним скористаються. Агент сам дивиться на завдання, вивчає код, вносить зміну, перевіряє результат і йде далі.

Довгий час кожному агенту потрібні були свої інструкції. Codex, Cursor та інші вже читали AGENTS.md, а Claude Code читав лише свій CLAUDE.md. 18 вересня, у версії 2.1.277, Claude Code почав читати й AGENTS.md: якщо в папці немає CLAUDE.md, він бере AGENTS.md.

Ми почали користуватися цим майже одразу, і зараз впроваджуємо в кількох проєктах: у старому інтернет-магазині на OpenCart, на сайті міжнародної професійної організації і на медичній освітній платформі. Тепер один файл пояснює проєкт будь-якому агенту, який у ньому працює. Більше не треба щоразу пояснювати проєкт з нуля чи тримати ті самі інструкції в кількох місцях.

Попрацювавши з цим на практиці, а не просто прочитавши, ми можемо сказати більше, ніж «виглядає багатообіцяюче»: це працює. Не магічно і не ідеально, але працювати з агентами стало помітно зручніше. А за цим невеликим покращенням стоїть значно більша зміна.

РОЗРИВ

Самого коду недостатньо

Уявіть, що ви прийшли розробником у великий проєкт. Вам дали репозиторій. Можна шукати по всьому коду, дивитися базу даних, читати опис API і запускати застосунок. Технічно у вас є все.

Але знаєте ви не все.

Ви не знаєте, що дивну функцію оплати не можна переписати, бо стара ERP-система залежить від однієї конкретної відповіді. Не знаєте, що на вигляд зайвий сервіс існує через інтеграцію з клієнтом, яку ніхто не хоче зламати. Не знаєте, які домовленості є архітектурними рішеннями, а які історичними випадковостями. І головне, ви не знаєте чому.

Людина зазвичай дізнається це в розмові. «Це не чіпай». «Ми вже пробували». «Так вимагає клієнт». «Виглядає дивно, але на те є причина».

Тепер додамо ШІ-агента. Він читає кожен файл, шукає швидше за будь-яку людину і бачить закономірності в тисячах рядків коду. Він навіть може запропонувати чистішу архітектуру.

Але чистіше не означає правильніше. Агент розуміє код. Він може не розуміти бізнес, який цей код створив.

Агент розуміє код. Він може не розуміти бізнес.

ДАЛІ ЗА README

README писали для людей

Десятиліттями README був найближчою подобою інструкції до проєкту. Встановіть це. Запустіть це. Зберіть це. Ось що робить застосунок. Корисно, але написано передусім для людей.

ШІ-агенту потрібен інший шар інформації. Не обов'язково більше інформації. Інша інформація.

Що можна чіпати? Чого не можна чіпати ніколи? Як тестувати застосунок? Яким шаблонам має слідувати новий код? Де живе бізнес-логіка? Які залежності залишено навмисно? І, можливо, найважливіше питання: коли агент має зупинитися і спитати людину, а не вирішувати сам?

Саме тут AGENTS.md стає цікавим. Це радше договір між репозиторієм і агентами, які в ньому працюють, ніж документація у звичному сенсі.

ОДИН ПРОЄКТ

Різні агенти, один проєкт

Уявіть проєкт, де один розробник працює в Claude Code, другий віддає перевагу Codex, а третій Cursor. Моделі різні. Інтерфейси різні. Доступні інструменти різні.

Але проєкт той самий. Архітектура, бізнес-правила, обмеження викатки і те, що в жодному разі не можна зламати, однакові для всіх. Навіщо кожному агенту відкривати все це заново?

Тому те, що індустрія сходиться на AGENTS.md, важливіше за будь-який окремий анонс. Формат оформили в серпні 2025 року OpenAI разом із Google, Cursor і Factory. У грудні 2025 року Linux Foundation створив Agentic AI Foundation, і AGENTS.md став одним із трьох її перших проєктів, поруч із Model Context Protocol від Anthropic і goose від Block. З приходом Claude Code у вересні 2026 року основні агенти для програмування читають той самий файл.

Це все ще радше домовленість, ніж формальна специфікація: простий Markdown-файл без обов'язкової структури. Але іноді домовленості важливіші за стандарти, бо ними справді користуються.

Іноді домовленості важливіші за стандарти.

НАША ІНСТРУКЦІЯ

Що написано в нас

Файли клієнтських проєктів ми показати не можемо. Але можемо показати свій. Ось частина AGENTS.md з репозиторію сайту PERETZ:

## Never
- Never add noindex, nofollow or an X-Robots-Tag header, and never edit
  public/robots.txt. The live site must stay open to search engines.
- Never block AI crawlers (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot).
- Never regenerate APP_KEY on an existing environment.
- Never change the URL or alias of an existing page. If it is unavoidable,
  add a 301 redirect and ask first.

## Before deleting anything
Code that looks unused may be called from database content, cron scripts
or external integrations. Search for usages and ask before removing it.

Жоден із цих рядків насправді не про код. Кожен із них урок бізнесу.

Правило про noindex існує тому, що один тег, доданий «тимчасово» під час розробки, може тихо прибрати сайт із Google. Правило про ШІ-роботів існує тому, що сайту, який не можуть прочитати ChatGPT і Perplexity, для дедалі більшої частини покупців просто немає. Правило про адреси існує тому, що кожна адреса, змінена без переадресації, викидає роки пошукової історії.

А правило про видалення коду ми поставили б у кожен AGENTS.md. «Виглядає зайвим, видали» це цілком розумний інженерний рефлекс і напрочуд дорога помилка для бізнесу. На сайті, де контент живе в базі даних, код, на який не посилається жоден файл, може використовуватися щодня.

Саме таке знання зазвичай і зникає з проєктів: не те, як влаштований код, а те, чого бізнес навчився на власних помилках.

ВЛАШТУВАННЯ

Як ми це влаштували

Якщо ви працюєте з Claude Code, важлива одна деталь. Він читає AGENTS.md, лише якщо ні в цій папці, ні вище немає CLAUDE.md. Якщо CLAUDE.md є, Claude Code читає його й ігнорує AGENTS.md.

Тому ми розділили файли за адресатом:

• AGENTS.md містить усе, що потрібно будь-якому агенту: стек, команди, жорсткі правила, неочевидні особливості проєкту і випадки, коли треба спитати людину.
• CLAUDE.md починається з одного рядка @AGENTS.md, який підключає спільний файл, і далі містить лише те, що стосується нашої власної роботи з Claude: як ми підключаємося до сервера, як зберігаємо і викатуємо зміни.

У підсумку в нас одне джерело правди. Розробник у нашій команді може працювати з іншим агентом, і той дотримуватиметься тих самих правил, що й наш.

І ще одне правило для обох файлів: жодних паролів, ключів і адрес серверів. Інструкція для агентів однаково лишається файлом у репозиторії, і її має бути безпечно читати будь-кому, хто бачить код.

СТАРИЙ КОД

Зі старим кодом складніше

Старі системи часто зберігають історію бізнесу. Хтось зробив обхідний шлях. Хтось додав виняток. Хтось залишив дивну відповідь API, бо від неї залежала інша система. Розробник, який ухвалив це рішення, міг піти багато років тому. Код залишився.

Тому модернізація старої системи це не просто «знайти старий код і замінити його кращим». Це археологія. Треба зрозуміти, що мусить залишитися, перш ніж вирішувати, що може зникнути. Детальніше ми писали про це у статті «Оновлення старого сайту на Laravel чи PHP у 2026 році».

ШІ-агент робить цю роботу і потужнішою, і небезпечнішою. Він вивчає стару систему значно швидше, знаходить закономірності й модернізує однотипні конструкції. Але він може не знати, який некрасивий шматок коду несе на собі невидиму вимогу бізнесу.

ШІ читає код. А хто читає бізнес?

Добрий AGENTS.md сам по собі цієї проблеми не розв'яже. Але він дає команді одне місце, де можна записати той бізнесовий та архітектурний контекст, який агенту справді потрібен, поки люди, які його пам'ятають, ще поруч.

МЕНШЕ КРАЩЕ

Роман нам не потрібен

Природна реакція: написати величезний файл, де буде кожна домовленість, кожне історичне рішення, кожен виняток і застереження. Найімовірніше, це хибний напрямок.

У 2026 році SRI Lab в ETH Zürich перевірила файли контексту на кількох агентах, зокрема Claude Code і Codex, на сотнях реальних завдань із GitHub. Загалом файли не підвищили частку розв'язаних завдань і збільшили вартість роботи більш ніж на 20%. Агенти справді дотримувалися інструкцій: більше тестували і вивчали більше файлів. Але зайві вимоги робили завдання складнішими.

Деталі ще корисніші. Файли, написані людьми, покращили результат у середньому приблизно на 4%. Файли, згенеровані моделлю, дали результат трохи гірший, ніж зовсім без файлу. А огляди структури папок, якими заповнена більша частина згенерованих файлів, не допомогли агентам швидше знаходити потрібні файли.

Контекст має ціну, і більше контексту не означає кращий контекст. Висновок самих дослідників: файли контексту, написані людьми, мають описувати лише мінімальні вимоги.

Отже, мета не інструкція, в якій зібрано все, що люди знають про проєкт. Мета в тому, щоб дати агенту ті небагато речей, які він інакше дізнався б лише через повторювані помилки. Наш власний файл коротший за п'ятдесят рядків, і ми написали його вручну.

НОВИЙ ІНТЕРФЕЙС

Репозиторій як інтерфейс

Зазвичай ми думаємо про інтерфейс як про щось для користувача: екран, кнопка, API. Але ШІ-агенту теж потрібен інтерфейс до системи, з якою він працює. Йому треба знати, як влаштований репозиторій, що йому дозволено, де шукати і коли зупинитися.

У цьому сенсі AGENTS.md не стільки функція документації, скільки частина нового інтерфейсу між програмами і машинами, які з ними працюють. Сьогодні це Markdown-файл. Завтра до нього можуть додатися структуровані метадані, навички, дозволи й автоматичні перевірки.

У цієї історії є й інший бік. Інструкція допомагає агентам будувати ваші програми. Але агенти починають користуватися і самими сайтами: шукати товари, порівнювати пропозиції, заповнювати форми, оформлювати замовлення. Для цього потрібне інше: сайт, який відкриває машинам свої дані й дії, а не лише сторінки людям.

Ми зіткнулися з цим на тому самому старому магазині на OpenCart. Щоб підключити до нього ШІ-агентів, спершу довелося оновити сам сайт. До цього боку історії ми незабаром повернемося.

ЩО ДАЛІ

Чим це закінчиться

Говорити, як усе виглядатиме за п'ять років, ще зарано. Інструменти досі мають свої системи правил: хтось використовує CLAUDE.md, хтось .cursor/rules, хтось AGENTS.md, хтось усе одразу.

Роками зв'язок між людьми і кодом був простим. Тепер це не так:

Різні моделі, різні можливості, той самий репозиторій, той самий бізнес і ті самі наслідки, коли щось ламається.

Ми навіть можемо хотіти, щоб різні агенти підходили до одного завдання по-різному. Але розуміти вони мають ту саму реальність.

Назва файлу може змінитися. Принцип, найімовірніше, залишиться. Коли машини працюють усередині нашого коду, коду потрібен спосіб говорити зі своїми новими співавторами.

Назва файлу може змінитися. Принцип, найімовірніше, залишиться.

ІНСТРУКЦІЯ

Інструкція для ШІ

Ми почали користуватися AGENTS.md, бо це було практично. Продовжили, бо працювати з різними агентами стало простіше. А сама ідея виявилася цікавішою за файл.

У програм з'являється ще одна аудиторія. Не лише розробники і не лише користувачі, а й машини, які вміють розробляти програми. Це змінює те, як ми думаємо про документацію, про архітектуру і про старий код.

Добре спроєктована система завжди намагалася зробити свою логіку зрозумілою людям, які її підтримують. Тепер у неї є ще один обов'язок: зробити потрібні частини цієї логіки зрозумілими агентам, які працюють поруч із людьми. Не все, не наосліп, не в тисячі рядків. Рівно стільки контексту, щоб знати те, чого код не може розповісти сам.

Якщо ваша команда починає працювати з ШІ-агентами або ваша система надто стара, щоб вони могли безпечно в ній працювати, саме з таких завдань починається наша робота з модернізації сайтів. А якщо ви ще вирішуєте, скільки довірити ШІ, прочитайте статтю «Чи потрібен мені розробник, чи вистачить ШІ?»

FAQ

Питання та відповіді

Що таке AGENTS.md?

Звичайний Markdown-файл у корені репозиторію, який пояснює ШІ-агентам, як працювати з проєктом: команди, обмеження, домовленості і коли треба спитати людину. По суті, це README для агентів.

Чи читає Claude Code файл AGENTS.md?

Так, починаючи з версії 2.1.277 від 18 вересня 2026 року, але лише якщо ні в папці, ні вище немає CLAUDE.md. Щоб використовувати обидва файли, почніть CLAUDE.md з рядка @AGENTS.md.

Чим AGENTS.md відрізняється від CLAUDE.md?

AGENTS.md не прив'язаний до конкретного інструмента, його читає більшість агентів для програмування. CLAUDE.md читає Claude Code. На практиці зручно тримати спільні правила в AGENTS.md, а в CLAUDE.md лише те, що стосується Claude.

Якої довжини має бути AGENTS.md?

Короткий. Дослідження ETH Zürich показало, що зайвий контекст підвищує вартість роботи більш ніж на 20% без покращення результатів, і радить описувати лише мінімальні вимоги. Наш файл коротший за п'ятдесят рядків.

Що не варто писати в AGENTS.md?

Паролі, ключі й адреси серверів, довгі огляди структури папок, які агент знайде сам, і все, що згенеровано автоматично й не перевірено людиною.

Джерела

• Anthropic decides to support OpenAI's markdown instructions spec, The Register
• Claude Code now supports AGENTS.md natively, DEV Community
• Linux Foundation forms Agentic AI Foundation, SD Times
• OpenAI and Anthropic donate AGENTS.md and MCP to the Agentic AI Foundation, InfoQ
• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, SRI Lab, ETH Zurich
• Does AGENTS.md Actually Help Coding Agents?, DAIR.AI Academy