Правила для ИИ-ассистента: 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-проекта о репозитории, с которого команда стартует.