Як працюють AI-агенти

Репозиторій як система знань для людей і агентів

Коли інженер або агент відкриває новий репозиторій, йому не потрібна вся історія проєкту за один раз. Йому потрібно зрозуміти, де почати, як знайти…

Глава 27Заморожене українське видання

Питання глави й результат навчання

Коли інженер або агент відкриває новий репозиторій, йому не потрібна вся історія проєкту за один раз. Йому потрібно зрозуміти, де почати, як знайти знання саме для своєї зміни, яка версія документа чинна і хто відповідає за її зміст. Репозиторій може зберігати код, пояснення, рішення та перевірки в одній версійованій історії. Але він не перетворює кожен текст усередині на авторитетну політику, поточний виробничий стан або дозвіл виконати дію.

Після глав 24–26 читач уміє відрізняти контекст, який реально передано моделі, від повного репозиторію; шукати джерело, авторитетне саме для цього питання; передавати роботу разом із посиланнями на стан і межі дозволу. Тепер ми розберемо, як організувати репозиторій так, щоб потрібне знання можна було відкрити, зрозуміти, перевірити та оновити без обов'язкової однакової структури для кожної команди. Глава 28 окремо розбирає, як інструкції потрапляють до агента, як продукт описує їхню взаємодію і який контроль справді обмежує дію.

Усі репозиторії, команди, рішення, автори, записи й результати в навчальних сценаріях нижче вигадані. Публічний репозиторій OpenAI Codex використано лише як конкретний відкритий приклад документації, а не як модель, яку треба копіювати. Динамічні твердження про продукти звірено з офіційними сторінками 26 вересня 2026 року; фіксовані дати комітів у прикладах репозиторіїв стосуються саме тих знімків.

27.1. Що репозиторій зберігає — і чого не доводить

Репозиторій — це кероване Git сховище файлів та історії їхніх змін. Кожен коміт називає точний знімок файлів; гілки дають змогу порівнювати й переглядати запропоновані зміни; історія зберігає записані в коміт дані автора, комітера, часу та опису зміни. Ці поля корисні для історії, але самі по собі не є незалежною перевіркою особи чи фактичного часу. Коміт може закріпити версію інструкції або рішення поруч із версією коду, до якої вони стосуються. GitHub описує репозиторій як сукупність файлів і історії їхніх ревізій, а постійне посилання на commit — як спосіб відкрити конкретний вміст замість рухомої гілки [Git: модель даних коміту; GitHub: репозиторії та постійні посилання].

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

Однак «є в Git» не означає «єдине правильне джерело». Репозиторій не вимірює сам собою, яка конфігурація завантажена в чинному сервісі; не підтверджує, що клієнт погодив текст у чернетці; не зберігає автоматично дозвіл на кожну дію; не забороняє автору додати помилкову вимогу. Коміт доводить, що певний файл був у конкретному знімку історії. Він не доводить, що файл схвалено власником політики, що зміст відповідає поточному стану даних або що його вже прочитав агент.

Тому до кожного документа ставлять чотири питання:

Питання Що треба встановити Типова відповідь
Для якого питання цей запис авторитетний? Його предмет і межі README пояснює, як почати; запис схваленої політики визначає правило; код реалізує поточну версію поведінки.
Хто відповідає за зміст? Власник рішення, домену або процесу Власник продуктового правила схвалює його зміст; технічна команда описує межі реалізації.
До якої версії та середовища він належить? Гілка, коміт, реліз, продукт, середовище або інший діапазон Інструкція для пакета billing/ у гілці X; процедура для сервісу версії Y; схвалена політика станом на дату Z.
Як помітити, що його треба оновити? Подію, яка запускає перевірку Зміна команди збірки, публічного контракту, схеми даних, вимоги або регламенту.

Це продовжує розрізнення з глави 25: джерело визначають під твердження, область і час. Наприклад, Jira може бути джерелом вимог задачі; коміт у Git — джерелом коду на цій ревізії; база даних — джерелом поточного доменного запису; журнал розгортання — доказом, який артефакт запустили. Репозиторій може посилатися на інші системи, не роблячи їх вміст своєю копією.

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

27.2. Кілька різних документів замість одного універсального

Документаційні файли мають різні читачів і обов'язки. Структуру варто добирати за запитаннями команди, а не за модним шаблоном.

  • README.md — вхідна точка для людини: що це за проєкт, кому він потрібен, як запустити або використати, куди перейти далі. Він має швидко відкрити маршрут до технічних і предметних джерел. README не зобов'язаний зберігати всі архітектурні деталі чи бути єдиним актуальним регламентом.
  • ARCHITECTURE.md або відповідний документ у docs/architecture/ — карта меж системи, основних компонентів, потоків даних, важливих обмежень і посилань на рішення. Назва не є форматом стандарту: у невеликому проєкті достатньо розділу в README, а у великому краще мати кілька предметних записів. Карта повинна посилатися на код і контракти, а не створювати паралельне джерело їхніх поточних значень.
  • AGENTS.md — інструкції для продуктів, які підтримують цей файл, наприклад Codex та інші агентні інструменти з сумісністю до AGENTS.md. Там доречні короткі робочі домовленості, важливі межі, маршрути читання й команди, що важко вивести із коду. Сам текстовий файл не є системною політикою доступу та не примушує будь-який агент його читати.
  • CLAUDE.md — інструкції та проєктний контекст для Claude Code. Це не загальна назва для правил усіх агентів і не гарантія, що Codex прочитає цей файл. Так само AGENTS.md не є автоматично взаємозамінним із CLAUDE.md у кожному Claude Code середовищі. Механізми завантаження залежать від конкретного продукту та його конфігурації; приклад у підрозділі 27.8 показує одну актуальну конфігурацію.
  • Запис архітектурного рішення (ADR, Architecture Decision Record) фіксує контекст важливого вибору, розглянуті альтернативи, вибране рішення та його наслідки. Він зберігає, чому команда обрала варіант, а не тільки коротке «так робимо». Зразок ADR не стає схваленим рішенням без визначеного автора/власника та статусу.
  • Специфікація (spec) описує очікувану поведінку, контракт або обсяг робіт для конкретного продукту. Її стан треба назвати: пропозиція, чернетка, схвалена вимога чи замінена редакція. Код реалізації не завжди відповідає поточній схваленій специфікації, а чернетка не визначає правило користувача.
  • План виконання (execution plan) відповідає на питання, у якій послідовності виконавець збирається робити конкретну зміну. Він залежить від рішення, що обґрунтовує зміст, та від стану коду. Це тимчасовий інструмент роботи, а не автоматичне джерело продуктової політики.
  • Перевірки (testing) пояснюють або запускають перевірку поведінки: стратегію тестування, межі набору тестів, фікстури, команди чи вимоги до доказу. Машинний статус проходження підтверджує лише перевірений набір і ревізію; текстова сторінка не замінює результат запуску.
  • Операційний посібник (runbook) підказує дії під час повторюваної операційної задачі чи інциденту. Він має бути обмежений сервісом і умовами, показувати точку ескалації та не містити секретів або дозволу на ризикову операцію, яку власник не схвалив.
  • Безпека (security) охоплює модель загроз, правила роботи з даними, спосіб повідомити про вразливість, вимоги зберігання чи доступу, якщо ці відомості дозволено тримати в репозиторії. Реальна політика організації може жити в іншому канонічному джерелі; тоді в Git має бути безпечне посилання і межі застосування.

Ці ролі можна змішувати в малому проєкті, якщо зрозуміло, який розділ за що відповідає. У великому монорепозиторії, де багато команд працюють незалежно, документи зазвичай поділяють за доменом, пакетом або типом рішення. В обох випадках читачеві треба бачити шлях від стартового README до первинного доказу. Дублювати одну інструкцію цілком у README, ARCHITECTURE, AGENTS.md і CLAUDE.md — короткий шлях до суперечностей: змінюється код або команда запуску, а копії зберігають різні відповіді.

Відкритий репозиторій Codex дає конкретний, але обмежений приклад. У зафіксованому коміті README починає з того, що це інтерфейс командного рядка (CLI, command-line interface) Codex, розрізняє термінальну програму, інтегроване середовище розробки (IDE, integrated development environment), desktop і web та веде до окремої документації, внесків і збирання. У тій самій ревізії docs/agents_md.md майже повністю спрямовує читача до офіційного документа про AGENTS.md. Натомість AGENTS.md містить спеціальні робочі обмеження для codex-rs, а docs/contributing.md окремо пояснює, що зовнішні внески коду не приймаються, і куди подавати відтворювані звіти. README не дублює кожен технічний припис; продуктове пояснення, інструкція виконавцю й правила внесків мають різні місця. Це приклад взаємно пов'язаних файлів на конкретній ревізії openai/codex, а не рекомендоване дерево для будь-якого репозиторію [OpenAI/codex, README; AGENTS.md; docs/agents_md.md; docs/contributing.md].

27.3. Як розподіляти документи й відповідальність

Каталог допомагає знайти документ, але сам шлях не робить його чинним. Файл docs/security.md може бути старою чернеткою; запис ADR може бути відхиленим; README може посилатися на іншу редакцію. До того ж прикладне дерево не є універсальним стандартом. Нижче наведено класи документів, які можна поєднувати або розносити залежно від розміру й типу проєкту.

Клас знання Приклад розміщення Власник змісту Коли переглядати або оновлювати
Орієнтація та старт README.md, docs/index.md Власник репозиторію або відповідальна технічна команда Коли змінюються призначення, спосіб запуску, основні маршрути, публічний вхід або каталог документації.
Продуктова поведінка docs/product/ Власник продукту чи політики Коли погоджено або змінено поведінку, критерії приймання, термінологію чи обмеження для користувача.
Архітектура та контракти docs/architecture/, docs/specs/ Власник системи, сервісу чи контракту Коли змінено межу компонента, потік даних, схему, зовнішню взаємодію або технічний інваріант.
Архітектурні рішення docs/adr/ або зручна для пошуку альтернатива Людина чи команда, відповідальна за саме рішення Коли рішення приймають, замінюють або відкривають повторно; статус і посилання на його заміну теж оновлюють.
План конкретної роботи docs/exec-plans/ або задача поза Git Виконавець плану й власник рішення, від якого план залежить Коли змінюється scope, послідовність, blocker, актуальне рішення чи стан задачі; після завершення позначити історичним.
Перевірки та їхня стратегія docs/testing/, конфігурація перевірок, каталог тестів Власник якості або команда, що підтримує відповідний набір Коли змінюється поведінка, контракт, тестова фікстура, середовище чи команда запуску. Самі результати зберігати разом із точним запуском.
Операційні процедури docs/runbooks/ Власник сервісу або зміни Коли змінюється команда дії, середовище, залежність, точка ескалації чи рівень доступу; переглянути після інциденту.
Безпека та чутливі межі docs/security/ або захищена база політик Власник безпеки, даних або відповідності вимогам Коли змінюється модель загроз, класифікація даних, межа довіри або політика зберігання. Не переносити в публічний Git конфіденційні матеріали.
Код і машинні контракти src/, схеми, конфігурація, міграції Власник відповідного пакета чи сервісу Разом зі зміною поведінки або структури. Документація має пояснювати інваріанти; код і схема залишаються точним записом реалізації на заданому коміті.

Структура на кшталт docs/product, docs/architecture, docs/adr, docs/specs, docs/exec-plans, docs/testing, docs/runbooks і docs/security — набір можливих полиць, а не вимога створити кожну з них. Невеликому вебзастосунку можуть вистачити README, короткого опису архітектури, інструкцій запуску й кількох записів рішень. Якщо в каталозі немає документів цього класу або потреби, порожня папка нічого не додає. У монорепозиторії ті самі класи можуть мати власні місця в підпроєктах, а центральний індекс дає на них посилання.

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

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

План не замінює рішення

Виконавчий план відповідає: «якими кроками ми збираємося дійти до результату за нинішніх передумов?» Рішення відповідає: «який варіант обрано, ким, у межах чого й чому?» Специфікація відповідає: «яку поведінку схвалено?» Усі три тексти можуть бути корисними, але не мають однакового статусу. План часто змінюється під час роботи; коли припущення плану конфліктує з чинним схваленим рішенням, виконавець не повинен трактувати план як нове рішення лише тому, що він докладний або був відкритий останнім.

Для активного плану зазначайте ключ задачі, власника виконання, статус, дату знімка, залежні рішення, пов'язані файли чи контракти, відкриті питання, наступний крок і умову зупинки. Статус може бути, наприклад, «чернетка», «схвалено», «в роботі», «заблоковано», «завершено», «замінено». Це приклади ясних міток, а не глобальна схема, яку всі мають прийняти.

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

Progressive disclosure: короткий маршрут до потрібної глибини

Поступове розкриття (progressive disclosure) означає, що читач спочатку бачить короткий маршрут і лише далі відкриває матеріал, потрібний для поточної задачі. Для репозиторію це може бути:

  1. Кореневий README відповідає, що це за продукт і де точка входу.
  2. Короткий індекс знань називає домени, системних власників, активні правила та межі доступу.
  3. Документ домену показує деталі й посилається на підтверджене рішення або контракт.
  4. Першоджерело, код чи перевірка дозволяють перевірити конкретне твердження.

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

Індекс має бути картою, не ще одним повним дублікатом. Він може містити: назву теми, посилання на канонічний запис, власника, область, поточний статус і тригер оновлення. Якщо документ розміщений в іншій системі, зазначте стабільне посилання, рівень доступу та дозволений шлях до читання. Не кладіть у AGENTS.md нескінченний каталог, який уже є в README, або всю архітектуру, яку треба згадувати лише під час змін конкретного сервісу.

27.4. Правила завантаження залежать від продукту

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

Станом на 26 вересня 2026 року офіційна документація Codex описує ланцюг AGENTS.md: спершу користувацькі інструкції, потім від кореня проєкту до поточного робочого каталогу (CWD). Якщо продукт не може встановити корінь проєкту, він перевіряє лише CWD. У кожному каталозі перевіряється AGENTS.override.md, потім AGENTS.md і налаштовані альтернативні імена; береться не більше одного непорожнього файла з кожного каталогу. Тексти з кореня до CWD поєднуються, а ближча інструкція може уточнити ширшу. За замовчуванням сукупний розмір має межу 32 КіБ. Отже, важливі CWD, шлях запуску, назви файлів та їхня фактична присутність у зібраному контексті [Codex, Custom instructions with AGENTS.md].

В Claude Code свої правила: CLAUDE.md завантажується для відповідного рівня проєкту, а внутрішні файли можуть завантажуватися під час звернення до цього піддерева. Документація дозволяє @path/to/file як імпорт іншого джерела в CLAUDE.md, з правилами розв'язання відносного шляху та обмеженням глибини імпортів; вона також описує .claude/rules/ для тематичних або обмежених за каталогом правил. За типової конфігурації, коли в робочій директорії чи предках немає CLAUDE.md, .claude/CLAUDE.md або CLAUDE.local.md, Claude Code може читати AGENTS.md; якщо файли Claude присутні, AGENTS.md може не завантажуватися без явного імпорту чи іншого режиму Project instructions. Пряме читання AGENTS.md підтримується від версії 2.1.277, але до 2.1.281 окремі сесії — зокрема через Bedrock або з вимкненою телеметрією — могли читати лише CLAUDE.md. Налаштування Project instructions можуть обрати один формат або обидва. Отже, перевіряйте точну версію, конфігурацію й фактичний контекст; це поведінка Claude Code, а не всіх продуктів Anthropic чи агентів [Claude Code, How Claude remembers your project].

Тому спільні файли мають зберігати факти, спільні для продуктів, а тонкі файли — продуктову маршрутизацію. Наприклад, docs/development-setup.md може бути єдиним місцем для фактичних команд установки й запуску. AGENTS.md вказує, для яких робіт варто читати цей файл, і може містити Codex-специфічну межу. CLAUDE.md описує Claude Code-specific правила та, якщо це доречно, імпортує той самий короткий файл команд. Якщо завантажувати його автоматично для кожного завдання немає сенсу, CLAUDE.md може лише вказати шлях, а агент читає setup при роботі з локальним запуском. Немає універсальної вимоги імпортувати один файл у другий; вибір залежить від того, скільки інформації справді потрібно на старті.

Усі фактичні значення в місці налаштування все одно мають збігатися з реальними джерелами: маніфестом пакета, файлом блокування залежностей, сценаріями безперервної інтеграції (CI, Continuous Integration) та поточним кодом. Якщо технологічний стек змінився, старий рядок в інструкції — це не новий факт через те, що його автоматично завантажили. І навпаки, наявність правильного README не допоможе інструменту, який його не відкривав.

Інструкція, skill, workflow, перевірка й право доступу — різні речі

  • Довідка пояснює. Вона може сказати, що сервіс зберігає часовий пояс, або чому команда використовує міграцію. Текст сам по собі не примушує агента чи сервер дотримуватися правила.
  • Інструкція задає очікуваний стиль роботи для конкретного агентного продукту: що прочитати, які команди використовувати, які межі не переступати без рішення. Для різних інструментів це різні файли й різні способи підключення. Інструкція залишається контекстом для агента; її виконання не замінює доступ-контроль.
  • Правило або rule-файл може мати спеціальне значення для певного агента. Наприклад, Claude Code документація підтримує .claude/rules/ і конкретний механізм зіставлення правила із шляхом. В іншому продукті rules.md може бути звичайним файлом, поки його не налаштували або не відкрили.
  • Навичка (skill) — це упакований повторно використовуваний матеріал чи процедура для конкретного типу роботи, іноді разом із ресурсами або скриптом. У Claude Code навички розміщуються у відповідних SKILL.md директоріях і завантажуються за механізмом цього продукту; Codex також має власну документацію навичок. Не треба стверджувати, що всі агенти шукають один формат або викликають навички однаково [Claude Code, Extend Claude with skills; OpenAI, Build skills].
  • Робочий процес (workflow) — повторювана послідовність дій. Він може бути лише інструкцією в Markdown або виконуваним автоматизованим процесом, як-от файл конфігурації GitHub Actions. Якщо крок не запускається системою автоматично, не називайте його захистом, що діє без людини.
  • Виконувана перевірка — тест, перевірка посилань, форматувальник, лінтер, схема чи статичний аналізатор із визначеним входом і результатом. Вона може зловити формальну помилку, але перевірка посилань не знає, чи рішення застаріло семантично, а тест, якого немає, не перевіряє те, чого не охоплює.
  • Політика прав доступу — контроль, реалізований файловою системою, системою керування репозиторієм, sandbox-середовищем, обліковим записом або зовнішнім сервісом. Доступ «тільки читати» чи заборона злиття мають існувати у відповідному механізмі. Речення «ніколи не зливай» у файлі — корисна вказівка, але не технічна заборона для користувача, застосунку або агента з надмірним доступом.

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

27.5. Свіжість: дата перевірки, власник і зміна поруч із кодом

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

Коли зміна коду змінює поведінку, зовнішній інтерфейс, спосіб розгортання, сценарій тестування або вимогу, пов'язану документацію треба розглядати в тій самій зміні. У PR (Pull Request — запиті на включення змін) переглядають реалізацію, документацію, її статус і посилання як один diff. Це допомагає рецензенту помітити, наприклад, що новий endpoint ще має стару документацію, що план спирається на іншу схему або що README досі пропонує вилучену команду. Окремий документальний PR може бути слушним, якщо зміст справді незалежний і власник погодив послідовність; важливо зафіксувати зв'язок між зміною та наступним оновленням.

Копії теж мають власників і споживачів. У зафіксованій ревізії AGENTS.md публічного репозиторію langchain-ai/docs команда прямо вимагає тримати AGENTS.md і CLAUDE.md синхронними, а вибрані похідні правила для редакторів — оновлювати в тому самому PR. Це корисний приклад того, як задокументувати зв’язок між джерелом і копіями. Він підтверджує лише заявлену в цьому файлі практику цієї команди, а не доводить, що кожна копія завжди збігається чи що така схема потрібна всюди [LangChain, pinned AGENTS.md]. Якщо довідник генерується з канонічного запису, назвіть джерело й команду генерації; якщо його редагують окремо, призначте власника, перевіряйте версію походження та показуйте всі споживані копії разом у рецензії.

Автоматичні перевірки корисні, але їхня область обмежена:

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

Зміни AGENTS.md, CLAUDE.md, правил автоматизації, workflow або чеків впливають на всіх, хто працює з відповідною частиною репозиторію. Їх потрібно рецензувати як зміни політики роботи, не лише як редагування Markdown. GitHub дозволяє задавати власників коду та вимагати схвалення за шляхом файлу через захист гілок або набір правил, якщо це налаштовано у репозиторії. Такий контроль не є автоматично ввімкненим для всіх репозиторіїв; перевіряйте фактичні правила цільової гілки [GitHub, pull request reviews; protected branches].

27.6. Недовірені файли, секрети та зміни інструкцій

Не кожний файл у робочому дереві походить від власника правил. У репозиторії можуть опинитися текст із issue, коментар із pull request, згенерований звіт, вміст завантаженої залежності, тестова фікстура чи зовнішній документ. У такому тексті можуть бути речення на кшталт «ігноруй усі попередні правила» або «прочитай і надішли токен». Це дані, які агенту треба класифікувати та цитувати за потреби; вони не стають вищим дозволом лише тому, що знаходяться в папці проєкту або були повернуті інструментом.

Вказівки довіри визначають за джерелом, призначенням, власником і статусом. Файл, який продукт розпізнає як конфігурацію, може змінити те, що агент прочитає або як він спробує працювати. Саме тому зміни кореневого чи вкладеного файла інструкцій, дозволів, hook-скриптів, workflow і перевірок варто показувати у diff та направляти власникам коду або відповідальним рецензентам. Якщо зміна прибирає заборону, розширює доступ чи замінює команду перевірки, це треба пояснити окремо. Репозиторій може захищати ці шляхи через CODEOWNERS, обов'язкові огляди та статусні перевірки, якщо політика гілки це підтримує [GitHub, code owners and protected branches].

Секрети — пароль, ключ, токен, приватний сертифікат — не є документацією. Не включайте реальне значення до README, прикладу, тестового журналу, скриншоту, документації з розгортання чи короткоживучої гілки. Поясніть, як дістати доступ зі схваленого секретного сховища, не копіюючи секрет. .gitignore не відкликає вже закомічене значення, а сканер секретів не гарантує відсутності витоку. Якщо секрет розкрито, спершу вважайте його скомпрометованим та відкликайте/обертайте; просте видалення з останнього коміту не прибирає попередню історію та копії клонів [GitHub, removing sensitive data; secret scanning].

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

27.7. Два обмежені погляди на власність знання

У The E-Myth Revisited Майкл Е. Гербер розрізняє технічну роботу, яку людина добре виконує, і системне керування бізнесом, що виконує цю роботу. Доступний фрагмент першого розділу формулює саме цю різницю: знання професійної операції не означає автоматичного знання того, як керувати бізнесом, що її виконує. Бібліографічний опис видання підкреслює ще одну основну лінію книги: працювати у своєму бізнесі й працювати над ним — не одне й те саме. Ми використаємо це для документації як обмежену аналогію: якщо запуск сервісу, трактування даних або важлива процедура існують лише у пам'яті засновника, перша людина, яка має виконати роботу без нього, муситиме вгадувати стандарт. Власник процесу має допомогти зробити важливе операційне знання передаваним і підтримувати його разом зі змінами.

Окрема пізніша стаття EMyth описує їхній підхід до систем: записати кроки, пояснити причини, передати процедуру іншій людині, побачити розбіжність у результаті, оновити стандарт і повторно перевірити; відповідальність за систему лишається в її власника, але учасники допомагають виявляти прогалини [EMyth, How to Design Systems for Your Small Business]. Це пізніший матеріал компанії, а не цитата з тексту книги. А наша думка, що технічний власник має так само оновлювати setup-документ або runbook після зміни реалізації, — це перенесення принципу на репозиторій.

У другої редакції Team Topologies Меттью Скелтон і Мануель Паїс присвячують значну увагу ясній меті, руху цінності та когнітивному навантаженню команд. Як аналогія для знань це нагадує, що документація має свої межі: користувачам пакета має бути зрозумілий публічний інтерфейс; команда-власник має бути визначена; сторонньому споживачеві не потрібні всі внутрішні кроки реалізації. Зміна, що повторно перекладає обов'язки між командами, може вимагати оновлення не тільки коду, а й документаційного маршруту та власника [Skelton і Pais, Team Topologies, 2nd edition].

Обидві ідеї допомагають запитати: «Хто підтримуватиме це знання і як інший виконавець зрозуміє стандарт?» Вони не встановлюють каталогів репозиторію, правил завантаження агентом чи вимог до розміру інструкцій. Організаційна когнітивна складність команди — не те саме, що ліміт вікна моделі; репозиторій не тотожний команді; не треба імітувати чотири типи команд Team Topologies папками. Аналогія допомагає приймати рішення про межу та відповідальність, але не доводить, що конкретна схема підійде кожній системі. Межі доступу до книжок і висновків зазначено в джерелах.

27.8. Три повні приклади

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

Приклад 1. Невеликий репозиторій системи бронювань

Ситуація

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

Проблема

Переглядати всі файли та запам'ятовувати весь продукт буде марно. Однієї README-сторінки теж недостатньо: вона не повинна бути одночасно продуктовою політикою, ADR, планом виконання та аварійною процедурою. Якщо зручно покласти все в AGENTS.md, воно може завантажуватися навіть для не пов'язаного завдання, а дуже довгий файл приховає ключове правило серед другорядних деталей.

Варіанти

  1. Один великий README. Дешевий старт, але з часом README змішує аудиторії й не показує, який розділ є погодженим правилом, а який — планом.
  2. Створити повне універсальне дерево наперед. Полегшує класифікацію у великій системі, але у невеликій команді породжує порожні каталоги, формальні документи й зайвий пошук.
  3. Мінімальна точка входу плюс окремі змістовні записи. Додає полицю тільки для знання з окремим власником, життєвим циклом або ризиком.

Рішення й дія

Команда обирає третій підхід. Одне можливе текстове дерево виглядає так:

booking-service/
  README.md
  ARCHITECTURE.md
  AGENTS.md
  CLAUDE.md
  docs/
    index.md
    product/
      rescheduling-policy.md
    adr/
      0007-time-zone-for-bookings.md
    exec-plans/
      active/
        BOOK-418-reschedule.md
      history/
    testing/
      booking-change-checks.md
    runbooks/
      booking-write-failure.md
    security/
      booking-data-handling.md
  src/
    bookings/
  tests/
    bookings/

Це запропонована форма саме цього прикладу, не обов'язковий шаблон. У ньому кожне місце має свій маршрут і відповідального:

  • README.md коротко пояснює службу та веде до docs/index.md; власник репозиторію оновлює його, коли змінюються мета, шлях запуску чи важливе посилання.
  • ARCHITECTURE.md містить межі сервісу та потоки між заявкою на бронювання й сховищем. Технічний власник переглядає його при зміні межі сервісу, каналу збереження чи контракту.
  • AGENTS.md стисло називає підтверджену команду перевірок і вказує, що для зміни бізнес-правил треба прочитати відповідну політику та ADR; власник інженерних правил переглядає його, коли змінюється реальний workflow агентів. Цей файл не містить доступу до сервера чи пароля.
  • CLAUDE.md містить лише налаштування й маршрутизацію для Claude Code; якщо команда хоче імпортувати спільну коротку документацію, це робиться підтримуваним для Claude Code механізмом і перевіряється в конкретній версії. Один лише файл не впливає автоматично на всі продукти.
  • docs/product/rescheduling-policy.md зберігає схвалені строки, часові межі та видимі користувачеві правила; власник продуктового рішення переглядає його після затвердженої зміни правил.
  • docs/adr/0007-time-zone-for-bookings.md документує, як команда прийняла часовий пояс бронювання й які наслідки розглядала; власник цього рішення або його наступник позначає новий ADR, якщо вибір замінюється.
  • docs/exec-plans/active/BOOK-418-reschedule.md — тимчасовий план конкретної задачі, а не джерело політики; виконавець позначає його завершеним або заміненим і переносить з активного індексу після закінчення роботи.
  • docs/testing/booking-change-checks.md описує потрібні класи перевірки, включно з межами тестових фікстур; власник набору тестів оновлює його разом зі зміною поведінки. Реальний статус запуску лежить у результаті, прив'язаному до ревізії.
  • docs/runbooks/booking-write-failure.md містить безпечну процедуру діагностики невдалого запису, перевірки повтору й маршруту ескалації; власник сервісу переглядає її після зміни операційного інтерфейсу програмування застосунку (API, application programming interface) або інциденту.
  • docs/security/booking-data-handling.md посилається на дозволену класифікацію даних і метод доступу; власник даних перевіряє її, якщо змінюється поле, передавання чи режим зберігання.

Агент починає з README, прочитує короткий індекс, а потім відкриває тільки правила перенесення, рішення про часовий пояс і потрібні перевірки. Якщо його зміна торкається даних бронювання, він додатково читає вимоги з обробки даних. Перед складанням плану він звіряє поточний статус Jira та код, на який посилаються документи. Коли зміна впливає на дозволену межу чи зовнішню операцію, він перевіряє, що може зробити інструмент, а що вимагає окремого людського рішення.

Спостережуваний результат

Рецензент може пройти від README до політики й ADR та знайти окремі власників для вимоги, рішення й тестової процедури. Він бачить, що BOOK-418 — план у роботі, а не схвалення зміни бізнес-правила; актуальна поведінка про часовий пояс посилається на ADR; runbook не містить секретного значення. Якщо при наступній зміні команди тесту оновлено код і AGENTS.md, але не setup-сторінку, різниця видима в одному PR.

Чому так і межі

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

Приклад 2. AGENTS.md і CLAUDE.md не погоджуються щодо setup

Ситуація

У вигаданому TypeScript-репозиторії є інструкції для двох інструментів. У AGENTS.md сказано запускати проєкт командою pnpm dev і використовувати Node.js 22. У CLAUDE.md написано npm start та Node.js 20. Обидва документи мають чинний вигляд, а задача просить додати невеликий екран налаштувань. Інженер читає README, де сказано лише «див. інструкції розробки».

Проблема

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

Варіанти

  1. Запускати обидві команди навмання. Це може створити дві конфігурації залежностей, змінити lock-файл і приховати першопричину суперечності.
  2. Вважати один формат універсально головним. Наприклад, вирішити, що AGENTS.md завжди сильніший, або що новіший файл автоматично замінює інший. Для різних інструментів механізм виявлення файлів відрізняється; новіша копія могла бути чернеткою.
  3. Звірити обидві інструкції з виконуваними джерелами, встановити власника та прибрати подвійне канонічне значення. У репозиторії мають бути одна спільна setup-інструкція та окремі короткі маршрути для продуктів, якщо їхня поведінка справді різна.

Рішення й дія

Агент спершу не виконує ні npm start, ні pnpm dev. Він читає package.json, lock-файли, .nvmrc або файл версії Node, конфігурацію безперервної інтеграції (Continuous Integration, CI) та інструкцію з розробки, на яку посилається README. Для цього вигаданого прикладу ці первинні свідчення узгоджено називають pnpm версії 9.15.0 і Node.js 22: є pnpm-lock.yaml, поле packageManager вказує [email protected], файл версії й середовище CI налаштовані на Node.js 22, а package.json містить відповідний скрипт dev. У репозиторії немає актуального package-lock.json, що підтверджував би окремий шлях через npm.

Ці файли показують відтворювану конфігурацію для збірки, але самі по собі не дають агенту дозволу завантажувати довільні пакети чи змінювати середовище. Якщо команда, версія або конфігурація суперечили б одне одному, агент зупинив би setup-дію, зафіксував суперечність і звернувся до власника розробницького процесу. Тут власник setup підтверджує, що правильні значення — Node.js 22 та pnpm; CLAUDE.md містив застарілу копію з попереднього стану проєкту.

Команда додає один канонічний docs/development-setup.md із необхідними передумовами, послідовністю першого запуску та датою/контекстом перевірки. Кореневий AGENTS.md містить короткий маршрут до нього і підтверджену команду для цього інструмента. CLAUDE.md лишає лише те, що є специфічним для Claude Code, та імпортує спільний setup через механізм @..., описаний у документації Claude Code, якщо команда перевірила таку поведінку в цільовій версії. За іншої конфігурації той самий документ може бути посиланням, а не імпортом; не треба покладатися на синтаксис, який конкретний продукт не підтримує. У PR команда прибирає суперечливі npm start і Node.js 20, додає посилання на спільний файл та направляє цей шлях до власника setup.

Поведінка завантаження має бути перевірена окремо. У поточній документації Codex описано, як продукт складає інструкції AGENTS.md від загального рівня до робочого підкаталогу. Документація Claude Code каже, що за наявності обох назв у відповідній ієрархії типовим є завантаження CLAUDE.md; AGENTS.md треба імпортувати явно. Відмінність не розв'язує конфлікт по суті, а лише показує, який текст міг отримати конкретний агент. Власник перевіряє, що обидва шляхи ведуть до однакового спільного правила в тих продуктах і версіях, які підтримує команда.

Спостережуваний результат

Після злиття один setup-документ називає версії Node.js і pnpm, що узгоджені з lock-файлом та CI. Кореневі інструкції короткі, дві команди, які суперечили одна одній, більше не подаються як рівноправні. У перевірці на чистій гілці версія команди й команди встановлення відтворюють визначені файлом налаштування умови; результат перевірки можна прив'язати до коміту. Для роботи прикладу не стверджується, що Codex чи Claude Code реально запустилися: це сценарій рішення, а не звіт тестування.

Чому так і межі

Виконувана конфігурація та CI допомогли знайти факт про те, що збирається, але власник пояснив, яке правило призначене підтримуватися. Єдиний setup-зміст зменшує шанс розходження; окремі продуктні файли лишають місце для справжніх відмінностей. Утім lock-файл не описує кожний дозволений спосіб роботи, а зелений CI не затверджує політику доступу чи продуктові вимоги. Інший репозиторій може обґрунтовано підтримувати і npm, і pnpm; тоді треба документувати окремі середовища та причини, а не нав'язувати один варіант. Текстові інструкції та імпорти треба перевіряти саме у версії відповідного продукту.

Приклад 3. Старий план пропонує змінити рішення про історичні дані

Ситуація

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

Проблема

План описує шлях виконання, а ADR — схвалене доменне рішення. Вік плану, його статус active або близькість до поточного коду не дають йому права скасувати схвалення. Але й власник ADR міг змінити свою думку після схвалення; одна стара копія документа не може говорити від імені людини про нове рішення. Якщо агент вибере одну версію без перевірки, він може незворотно знищити зв'язок між матчами різних сезонів і клубом.

Варіанти

  1. Дотриматися старого плану. Це швидкий крок, але він суперечить поточному схваленому рішенню й може втратити ідентичність клубу в історії.
  2. Вважати ADR абсолютною істинною назавжди. ADR пояснює рішення на конкретний час і контекст. Власник може його переглянути; старий запис не замінює нового схвалення, якщо рішення змінилося.
  3. Перевірити статус і власника ADR, не виконувати руйнівну операцію, а потім оновити план та посилання відповідно до підтвердженого рішення. Якщо власник не доступний або відповідь нечітка, виконати тільки безпечне дослідження та попросити уточнення до зміни схеми.

Рішення й дія

Агент читає текст ADR до кінця, перевіряє його схвалений статус, дату та посилання на власника; відкриває історію змін і поточну задачу; перевіряє код схеми й міграцій, щоб зрозуміти наслідки. Ці кроки доводять лише те, що в репозиторії є схвалене рішення та застарілий план. Вони не дозволяють вигадати, що власник скасував ADR. Агент явно описує суперечність у коментарі до робочої задачі та адресує її власнику доменного рішення. Він не виконує міграцію, яка видаляє club_id, доки власник не прийме нове рішення.

Власник відповідає, що стабільний ідентифікатор залишається потрібним; сезонні назви — це атрибут відображення, а не ідентичність клубу. Якщо б власник ухвалив протилежне, потрібен був би новий ADR або нова схвалена версія того самого рішення, чітко позначена як така, що замінює попереднє. У даному навчальному сценарії власник підтримує чинний ADR. Автор зміни позначає старий план як замінений, переміщує його до історичних планів або знімає зі списку активних, ставить посилання на ADR і пояснює, які кроки плану тепер неактуальні. У новому плані лишається лише послідовність реалізації затвердженого правила: лишити club_id, відокремити сезонні назви для відображення, перевірити матчі з попередніх сезонів і не розривати історичний зв'язок.

Перш ніж виконати зміну, команда звіряє індекс і посилання на цей план, відкриті PR, що могли на нього покладатися, і перевірки схеми. Ті матеріали, які ще потрібні для історії, не видаляють так, ніби старого плану не було; їм надають правильний статус і шлях до чинного ADR. Якщо якісь похідні довідники в репозиторії показували назву як унікальну ідентичність клубу, їх оновлюють у тому самому PR. Зміна документа поруч із кодом дає рецензенту змогу побачити, що причина зміни й схема узгоджені.

Спостережуваний результат

У дифі реалізації немає видалення стабільного ідентифікатора; статус історичного плану видимий; новий план посилається на підтверджений ADR. Схемні перевірки прикладу зберігають зв'язок матчів із club_id, а демонстраційний сценарій перейменування показує дві сезонні назви для того самого ідентифікатора. У PR видно, хто підтвердив доменне рішення та які документи було оновлено. Це очікуваний результат вигаданого прикладу, не твердження про реальне виробниче сховище.

Чому так і межі

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

27.9. Мінімум достатньої документації

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

Практична політика знань може відповідати на п'ять питань:

  1. Що де зберігається? Назвіть першоджерело для вимоги, архітектурного рішення, коду, доменного запису, схваленого зовнішнього матеріалу, перевірки й обговорення. Посилання ведуть до джерела; копія, яка не є канонічною, позначена як витяг, кеш, згенерований матеріал або довідник.
  2. Хто схвалює та підтримує кожну категорію? Назвіть роль чи команду, а не тільки людину, яка колись написала файл. Власник може прийняти внесок іншої команди, але незрозуміла відповідальність — привід запитати, а не вгадати.
  3. Яка подія запускає оновлення? Зміна CLI, параметрів конфігурації, зовнішнього контракту, продуктового правила, дозволу доступу чи інцидент має змусити перевірити відповідний документ. Призначайте повторну перевірку лише там, де швидкість старіння виправдовує це.
  4. Як виправити застарілу або суперечливу копію? Знайдіть першоджерело, перевірте власника й статус, оголосіть конкретний конфлікт, потім оновіть канонічний запис і посилання чи похідні копії. Не робіть багатосторінкову правку кожної копії без розуміння того, хто нею користується.
  5. Що підлягає особливому перегляду? Інструкції агента, дозволи, workflow та перевірки впливають на виконання коду або дії. Направляйте такі зміни призначеним рецензентам та вказуйте поведінкову різницю. Доступ контролюється платформою і налаштуваннями репозиторію, а не самою документацією.

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

Індекс також вимагає утримання: автоматизуйте перевірку зламаних посилань, якщо індекс великий; призначайте відповідального за зміст; видаляйте або позначайте дубль після зміни. Перевірка адреси вебресурсу (URL, Uniform Resource Locator) не знаходить семантичного дрейфу — посилання може відкриватися, але вести до правила, яке більше не відповідає коду. Зіставляйте критичні документи з власниками, відкритими вимогами, версією коду та результатом перевірки, а не довіряйте одному автоматичному сигналу.

Репозиторій — це корисна версійована поверхня домовленостей, не заміна всім системам компанії та не машина, яка перетворює текст на істину. Його документація стає робочим знанням тоді, коли кожен важливий запис відповідає на три запитання: для якого питання він призначений, на яку ревізію або область поширюється, і хто оновить його після зміни. Коли відповідь незрозуміла, спершу знайдіть джерело й власника. Не маскуйте суперечність оновленим timestamp, зручним переказом або впевненим тоном агента.

Джерела та межі прочитаного

Наведені нижче посилання підтверджують конкретні твердження, які використано в розділі. Мінливу онлайн-документацію перевірено 23–26 вересня 2026 року; біля кожного джерела зазначено перевірену дату, якщо вона відрізняється. Коли видима дата оновлення не вказана, так і зазначено. Репозиторій із рухомою гілкою наведено тільки через постійне посилання на перевірений коміт. Дати, версії продуктів і поведінка можуть змінитися; перед практичним застосуванням відкрийте актуальну документацію своєї версії.

  1. GitHub Docs, «About repositories» і «Getting permanent links to files». Чинна документація, дата оновлення на відкритих сторінках не вказана; доступ 23.09.2026. Використано для тверджень про файли/історію сховища та посилання на конкретний коміт. Межа: опис функцій GitHub не встановлює політику кожної організації. About repositories; Getting permanent links to files.
  2. OpenAI, Codex, «Custom instructions with AGENTS.md». Офіційна чинна документація; окрема дата оновлення на сторінці не зазначена; перевірено 26.09.2026. Використано для поточного, продуктово-специфічного порядку пошуку й об'єднання AGENTS.md у Codex, робочого каталогу та межі розміру інструкцій. Межа: пошук залежить від конфігурації й поверхні, а інші продукти можуть працювати інакше. Документація Codex.
  3. OpenAI, Ryan Lopopolo, «Harness engineering: leveraging Codex in an agent-first world», 11.02.2026. Використано як опис конкретного досвіду команди OpenAI про оформлення репозиторію, маршрут знань, довгоживучі інструкції та автоматизований контроль. Межа: це авторський звіт про один внутрішній процес, не доказ універсальної рецептури. OpenAI.
  4. OpenAI Developers, Eric Provencher, «Rethinking skills and prompts for GPT-6 Astra», 11.09.2026. Використано для актуального прикладу поступового відкриття контексту, невеликого always-on шару та поділу навичок за завданнями. Межа: продуктова рекомендація для описаної системи, не вимога до кожного репозиторію чи моделі. OpenAI Developers.
  5. Anthropic, Claude Code, «How Claude remembers your project», «Extend Claude with skills», «Settings files and precedence» та «Configure permissions». Офіційна чинна документація, дата оновлення сторінок не зазначена; перевірено 26.09.2026. Використано для визначення того, як саме Claude Code обробляє CLAUDE.md, імпорт @path, .claude/rules/, навички й окрему конфігурацію дозволів, включно з умовами читання AGENTS.md. Межа: це поведінка Claude Code, не загальне правило для інших продуктів Anthropic чи агентів. Project memory; Skills; Settings and permissions; Permission rules.
  6. GitHub Docs, «About protected branches», «About code owners» та «Removing sensitive data from a repository». Поточна офіційна документація; дата оновлення на відкритих сторінках не зазначена; доступ 23.09.2026. Використано для умовності захисту гілок і власників коду, вимог до перегляду за шляхом та обмежень простого видалення секрету з історії. Межа: ці функції діють лише коли їх налаштовано; сканування не доводить абсолютну відсутність секретів. Protected branches; Code owners; Sensitive data.
  7. OpenAI, «Understanding prompt injections». Дата публікації або оновлення на перевіреній сторінці не вказана; доступ 23.09.2026. Використано як офіційне пояснення того, чому вміст сторонніх джерел може містити шкідливі вказівки і його слід відокремлювати від дозволу виконувати дії. Межа: загальна стаття про захисний підхід, не гарантія виявлення кожного випадку та не повний стандарт для конкретного агента. OpenAI Safety.
  8. Matthew Skelton і Manuel Pais, Team Topologies, друге видання, IT Revolution, 23.09.2025; ISBN 9781966280002. Доступ 23.09.2026 до сторінки авторів і видавця, не до повного тексту книги. Використано лише описи мети, командних меж і когнітивного навантаження як обмежену організаційну аналогію. Не робимо висновків про конкретну структуру папок із книжки. Офіційна сторінка Team Topologies; Сторінка видавця.
  9. Michael E. Gerber, The E-Myth Revisited: Why Most Small Businesses Don't Work and What to Do About It, HarperCollins, перевидання 2009 року, 288 сторінок, ISBN 9780061741654. Повного тексту книги не було; бібліографічний опис і короткий переглянутий фрагмент видавничого зразка стосуються першого розділу. Використано для обмеженої тези про різницю між професійною операцією та системним управлінням нею; не приписуємо автору нашої політики документації. Google Books, видання та бібліографія; Фрагмент першого розділу, EMyth. Пізніша поточна стаття EMyth, «Implementing Small Business Systems and Processes», використана окремо як післякнижкова практична інтерпретація процесу, дата публікації на сторінці не зазначена; доступ 23.09.2026. Вона не є доказом формулювання з книги. EMyth.
  10. OpenAI, Codex, публічний GitHub репозиторій, коміт 30fc6864cc1318121eca1843c217fe00ce1212f1, датований 23.09.2026; зафіксовані README.md, AGENTS.md, docs/agents_md.md і docs/contributing.md; доступ 23.09.2026. Використано як перевірений приклад різних ролей файлів у тому самому коміті. Межа: один репозиторій і одна ревізія; це не рекомендація копіювати структуру. README; AGENTS.md; docs/agents_md.md; contributing guide.
  11. LangChain, langchain-ai/docs, зафіксований коміт 10b15a17b96744fa318eabdd83a1f0750f2f5b1c, датований 23.09.2026; AGENTS.md; доступ 23.09.2026. Використано для прикладу репозиторію, що власним інструкційним файлом вимагає підтримувати AGENTS.md і CLAUDE.md синхронно, а окремі похідні правила оновлювати в тому самому PR. Це свідчення того, що саме написала команда репозиторію, а не незалежна оцінка ефективності її процесу. Pinned AGENTS.md.
  12. Git, «Git data model» і «git-commit». Використано для пояснення того, що commit указує на дерево snapshot і містить поля автора, комітера та часу. Ці метадані є частиною запису Git, а не незалежним доказом особи чи часу. Git data model; git-commit.