Правила для ШІ-асистента: 12 файлів замість здогадок
Асистент, який вигадує ім’я методу, коштує циклу рев’ю. Він пише Auth::login() там, де в рушії login_with_secret(), рев’юер це ловить, а наступна підказка повторює помилку. Правила для ШІ-асистента знімають це коло, бо модель читає справжню сигнатуру до того, як друкує.
Код: Atomic-Framework-Skills, ліцензія GPL-3.0.
Дванадцять файлів описують по одній області фреймворку на PHP 8.1, у ядрі якого 25 тек компонентів і 44 документи.
Що замінює такий файл
Він замінює здогад, на який модель приречена, коли репозиторій не вміщується в підказку. Без файлу модель бачить кілька відкритих вкладок і загальне знання PHP, і загальне знання це джерело вигаданого методу.
З файлом асистент отримує назви класів, ланцюг завантаження, домовленості про маршрути й список помічників, які існують. Відстань від підказки до робочого коду скорочується до відстані від файлу до першоджерела рушія, і цю відстань автори звіряють руками.
Дванадцять областей замість одного документа
Поділ повторює будову фреймворку: огляд, ядро, застосунок і авторизація, дані, командний рядок і API, події з хуками й перекладами та поштою, м’ютекси й сесії, черга з планувальником і телеметрією, шаблони теми, плагіни, інструменти з WebSocket і карта документації.
Файл на область це рішення про контекст, а не про порядок у теці. Підказка, у яку завантажено один файл на триста рядків про сесії, дає кращі відповіді за ту, куди завантажили все й сподіваються, що модель знайде потрібний абзац.
Файл огляду існує, щоб його читали першим, а карта документації потрібна в момент, коли агенту треба знайти документ, а не метод.
Чому правила мусять іти з першоджерела
У настанові репозиторію правило записане прямо: не додавай методи й помічники, яких немає в першоджерелі. Навичка з однією вигаданою функцією гірша за жодну, бо їй вірить асистент і їй вірить рев’юер.
Там же просять дописувати позначку ## Guardrails, коли помилка легко повторюється. Це і є та частина, яку більшість наборів правил пропускає: нотатка про те, де модель помиляється саме тут, написана після того, як вона помилилася, варта абзацу загальних порад.
Як файли підключаються
У VS Code шлях вписують у github.copilot.chat.skills.instructionFilesGlob із вказівкою на skills/**/*.md. Агент не читає їх усі: він вибирає за полем description у заголовку, або ви викликаєте файл за назвою.
Цю поведінку варто зрозуміти до того, як на неї покластися. Розмитий опис веде до завантаження не того файлу, а не той файл дає впевнені відповіді про чужу підсистему.
Чого правила не роблять
Вони не пишуть функцію, не запускають тести й не знають предметної області клієнта. Вони й не оновлюються самі: файли звіряють із рушієм руками, і випуск, який змінює сигнатуру, лишає навичку застарілою, доки хтось її не поправить.
Що перевірити в чужому наборі правил
Запитайте, звідки взяті сигнатури, і відкрийте одну навмання поруч із першоджерелом. Якщо файл не зводиться до рядка коду, це проза про фреймворк, а не довідка по ньому.
Потім подивіться описи. Набір, у якому всі файли звучать однаково, завантажить не той файл, і провал виглядатиме як слабка модель, а не як слабка бібліотека.
Третя перевірка це дата. Навичка без звірки після останнього випуску фреймворку небезпечніша за порожнє місце: вона впевнено називає метод, який перейменували.
Що це змінює в оцінці
День на написання і звірку правил економиться на кожному тікеті, який стосується незнайомої підсистеми. Вимірювана частина це час рев’ю: менше циклів на метод, якого не було, і менше розмов про те, чому асистент упевнений і неправий.
Поруч: фреймворк для бізнес-додатків про фреймворк, який ці правила описують, і скелет PHP-проєкту про репозиторій, з якого команда стартує.