Инструкции на уровне агента
Последний месяц привожу в порядок rules/skills на внутренних проектах в kts.tech, включая те, где их раньше вообще не было, и тут такая штука, что агенты заставили нас формализовать доку к каждому проекту, правда, чтобы они же работали по нашим правилам. Смысл документации остается прежним: чем она полнее, тем яснее процесс разработки на проекте. Про качество кода нужно писать отдельно.
Зачем? Инструкции помогают агенту быстрее ориентироваться в проекте, меньше переспрашивать, реже лезть не в ту сторону. Каждая такая инструкция больше не бесплатна. Агент читает ее на каждый вызов и по сути ведет проект. Как корабль назовешь, так он и поплывет)
Цена
У агента инструкции читаются один раз за сессию и держатся в кэше, так что цена не растет линейно с каждым вызовом. Но кэша нет при новой сессии и при апгрейде модели, и в этот момент весь объем считается заново.
В феврале ETH Zurich и LogicStar.ai прогнали четыре модели на 100+ реальных задачах и сравнили три сценария: без контекстного файла, с файлом от модели, с файлом от человека (https://arxiv.org/abs/2602.11988, ссылка выглядит скамно, простите). Файлы в среднем не увеличивают долю решенных задач, а стоимость вызова модели растет больше чем на 20%. Держится это на разных моделях и агентах, и для сгенерированных файлов, и для написанных руками.
Агенты следуют написанному буквально, даже когда это вредит задаче. В одном из замеров инструмент, просто упомянутый в файле, использовался в 160+ раз чаще, чем в сценарии без файла. Агент цепляется за него просто потому, что он описан на проекте, хотя инструмент был устаревшим и вредил проекту (https://arxiv.org/pdf/2606.20512/, стр. 2).
НО аккуратно собранный AGENTS.md на точечных изменениях дает меньше времени выполнения и меньше выходных токенов. Но там меряли скорость, а не корректность решения.
Разница
Можно сравнить два проекта, на которые нужно было добавить rules и skills:
- на одном документации не было вообще. Поднимал проект локально, пролистывал сотню файлов, чтобы понять стиль и стек, и уточнял детали по последним коммитам. Rules и skills пришлось собирать с нуля: агент собирает их по коду проекта, но не все процессы видны в коде.
- на другом есть папка docs с ADR, описанием локальной разработки, структурой проекта и даже списком контрибьюторов. Смотрел по коммитам и там было видно, что доку дописали уже по готовому проекту (сейчас важно собирать ее еще на этапе разработки, чтобы агент понимал, что мы вообще пытаемся сделать). Rules и skills заводятся на таком проекте с пары запросов.
Границы
У инструкции для агента есть две границы:
- нижняя: отвечает за то, без чего агент вообще не сможет нормально работать. Это где лежит код, как запускать тесты и к кому уходит ревью. Ее приходится писать всегда, и чем хуже документация в проекте, тем она тяжелее и дороже.
- верхняя: это все, что уже написано для человека и просто оказалось пригодным для агента. Те же ADR, та же инструкция локального разворота, README с объяснением зачем вообще существует сервис, гайд по неймингу веток и коммитов и т.п.
Актуальность
Поддерживать документацию актуальной получается не всегда, а с приходом ИИ отчасти закрывается само: агент часто сам актуализирует доку при изменениях, а если нет, можно попросить об этом сразу после выполнения задачи.
Когда вышел скилл react-best-practices, то многие читали его как учебник и внедряли на проекты и смотрели, как результат становился лучше. То есть ценность стала заметнее, и люди начали создавать похожик скиллы под свои нужды, то есть писать инструкции, создавая документацию к проекту.
Соответственно, задача не в том, чтобы наращивать слой инструкций, а в том, чтобы сдвигать нижнюю границу как можно ближе к верхней. Не плодить skill'ы, а наполнять проект документацией, которая и так должна быть в проекте.
#ai
Последний месяц привожу в порядок rules/skills на внутренних проектах в kts.tech, включая те, где их раньше вообще не было, и тут такая штука, что агенты заставили нас формализовать доку к каждому проекту, правда, чтобы они же работали по нашим правилам. Смысл документации остается прежним: чем она полнее, тем яснее процесс разработки на проекте. Про качество кода нужно писать отдельно.
Зачем? Инструкции помогают агенту быстрее ориентироваться в проекте, меньше переспрашивать, реже лезть не в ту сторону. Каждая такая инструкция больше не бесплатна. Агент читает ее на каждый вызов и по сути ведет проект. Как корабль назовешь, так он и поплывет)
Цена
У агента инструкции читаются один раз за сессию и держатся в кэше, так что цена не растет линейно с каждым вызовом. Но кэша нет при новой сессии и при апгрейде модели, и в этот момент весь объем считается заново.
В феврале ETH Zurich и LogicStar.ai прогнали четыре модели на 100+ реальных задачах и сравнили три сценария: без контекстного файла, с файлом от модели, с файлом от человека (https://arxiv.org/abs/2602.11988, ссылка выглядит скамно, простите). Файлы в среднем не увеличивают долю решенных задач, а стоимость вызова модели растет больше чем на 20%. Держится это на разных моделях и агентах, и для сгенерированных файлов, и для написанных руками.
Агенты следуют написанному буквально, даже когда это вредит задаче. В одном из замеров инструмент, просто упомянутый в файле, использовался в 160+ раз чаще, чем в сценарии без файла. Агент цепляется за него просто потому, что он описан на проекте, хотя инструмент был устаревшим и вредил проекту (https://arxiv.org/pdf/2606.20512/, стр. 2).
НО аккуратно собранный AGENTS.md на точечных изменениях дает меньше времени выполнения и меньше выходных токенов. Но там меряли скорость, а не корректность решения.
Разница
Можно сравнить два проекта, на которые нужно было добавить rules и skills:
- на одном документации не было вообще. Поднимал проект локально, пролистывал сотню файлов, чтобы понять стиль и стек, и уточнял детали по последним коммитам. Rules и skills пришлось собирать с нуля: агент собирает их по коду проекта, но не все процессы видны в коде.
- на другом есть папка docs с ADR, описанием локальной разработки, структурой проекта и даже списком контрибьюторов. Смотрел по коммитам и там было видно, что доку дописали уже по готовому проекту (сейчас важно собирать ее еще на этапе разработки, чтобы агент понимал, что мы вообще пытаемся сделать). Rules и skills заводятся на таком проекте с пары запросов.
Границы
У инструкции для агента есть две границы:
- нижняя: отвечает за то, без чего агент вообще не сможет нормально работать. Это где лежит код, как запускать тесты и к кому уходит ревью. Ее приходится писать всегда, и чем хуже документация в проекте, тем она тяжелее и дороже.
- верхняя: это все, что уже написано для человека и просто оказалось пригодным для агента. Те же ADR, та же инструкция локального разворота, README с объяснением зачем вообще существует сервис, гайд по неймингу веток и коммитов и т.п.
Актуальность
Поддерживать документацию актуальной получается не всегда, а с приходом ИИ отчасти закрывается само: агент часто сам актуализирует доку при изменениях, а если нет, можно попросить об этом сразу после выполнения задачи.
Когда вышел скилл react-best-practices, то многие читали его как учебник и внедряли на проекты и смотрели, как результат становился лучше. То есть ценность стала заметнее, и люди начали создавать похожик скиллы под свои нужды, то есть писать инструкции, создавая документацию к проекту.
Соответственно, задача не в том, чтобы наращивать слой инструкций, а в том, чтобы сдвигать нижнюю границу как можно ближе к верхней. Не плодить skill'ы, а наполнять проект документацией, которая и так должна быть в проекте.
#ai