Понять, что модель знает о твоём проекте, как агент выполняет действия и из чего складывается harness.
Чему научишься
•Объяснять, как модель получает сведения о проекте и как агент действует.
•Различать инструкции проекта, скиллы, доступы агента и действия, которые остаются за тобой.
•Выбирать, что сохранять в проекте, чтобы следующая сессия продолжила работу.
Содержание · 7ОткрытьСкрыть
В этом материале разберём, что модель знает о твоём проекте, как агент выполняет действия и из чего складывается harness. Если ты это уже знаешь, переходи к настройке проекта.
В задании ты настраиваешь проект так, чтобы новая сессия агента сама находила правила, задачи и следующий шаг. Для этого нужно понимать, какие сведения попадают к модели и что остаётся после конца сессии. Сессией называют один разговор с агентом: его историю, прочитанные файлы и результаты действий.
Что модель знает о твоём проекте
Представь, что ты просишь агента подготовить репозиторий для учебного проекта. Нужно создать его на GitHub и связать с локальной папкой. Как агент поймёт, какой проект ты имеешь в виду, где его разместить и что выполнить на твоём компьютере?
Языковая модель, или LLM (large language model, большая языковая модель), обрабатывает переданные ей сведения и по ним определяет следующий шаг. Она знает общие принципы работы с Git и GitHub.
Современные агенты многое выясняют сами. Агент видит, в какой папке он запущен. Через инструменты он может посмотреть твой профиль на GitHub и даже управлять браузером. Но полностью полагаться на это не стоит. Если тебе важно, где появится проект и в каком аккаунте будет репозиторий, скажи об этом прямо.
Всё, что модель получает для текущего шага, называют контекстом. В нашем примере в него входят:
твой запрос «подготовь репозиторий для учебного проекта»;
папка, в которой запущен агент;
история разговора в этой сессии;
инструкции проекта, если они есть и загружены;
описания доступных инструментов;
результаты уже выполненных действий.
Обрати внимание на папку запуска. Если не сказать, где разместить проект, агент, скорее всего, создаст для него новую папку прямо в ней. Если тебе нужно другое место, назови его в запросе.
От папки запуска зависит и то, какие инструкции и скиллы агент найдёт. Если запустить его в соседней или родительской папке, настройки проекта он может не увидеть. Поэтому запускай сессию для работы над проектом из папки этого проекта.
Чего в контексте нет, того модель не видит. Файл с договорённостями на диске ничего не меняет, пока агент его не прочитал. Имя репозитория и его видимость по содержимому папки не определить. Агент либо спросит у тебя, либо выберет сам.
Проверьте понимание
В корне проекта лежит файл с правилами для агента, и в нём есть строка «Решения по репозиториям лежат в docs/decisions.md». В docs/decisions.md записано, что репозиторий приватный. Ты запускаешь новую сессию в папке проекта и просишь создать репозиторий на GitHub. В какой момент решение о приватности начнёт влиять на действия агента?
1.
Когда агент запустится в папке, где лежит docs/decisions.md.
2.
Когда агент откроет docs/decisions.md и прочитает его.
3.
Когда docs/decisions.md попадёт в коммит основной ветки.
Как агент выполняет действия
Чтобы что-то сделать, модели нужен инструмент. Она формирует запрос, в котором названы операция и её параметры. Среда агента выполняет его с доступными разрешениями и возвращает результат.
У любого агента есть базовый набор инструментов. Он читает и изменяет файлы, ищет по проекту и запускает команды в терминале. Остальные инструменты подключаются отдельно.
С GitHub агент может работать по-разному. Он может открыть сайт в браузере, если среда поддерживает управление компьютером (computer use), или напрямую отправлять запросы к GitHub API. Удобнее всего GitHub CLI (command line interface, интерфейс командной строки), утилита gh для терминала. Ты один раз входишь в ней в свой аккаунт, и агент обычными командами управляет репозиториями, задачами и pull request, то есть предложениями изменений в репозиторий. Например, модель запрашивает запуск команды в терминале:
Этот вывод попадает в контекст, и модель выбирает следующий шаг. Текст «репозиторий создан» в ответе модели сам по себе ничего в системе не меняет. Меняет только выполненный вызов инструмента.
Вся работа над просьбой может выглядеть так:
Агент смотрит текущую папку и читает инструкции, если они есть.
Уточняет у тебя недостающее: имя репозитория, владельца, видимость.
Создаёт репозиторий через инструмент и связывает его с локальным проектом.
Читает результаты и проверяет, что локальный проект указывает на созданный репозиторий.
Сообщает, что получилось и какие действия выполнены.
Если GitHub вернул ошибку, следующий шаг учитывает её. Агент может уточнить причину, изменить план или спросить тебя. Поэтому работа состоит из нескольких связанных действий, а не из одного заранее написанного ответа.
Агент объединяет модель, инструменты и этот цикл: получить сведения, выбрать действие, выполнить его, изучить результат. Тем же способом он читает код, меняет файлы, запускает тесты и разбирается с ошибкой. Его возможности зависят от подключённых инструментов и разрешений.
Проверьте понимание
Ты попросил агента создать репозиторий на GitHub, и он закончил работу. Что из перечисленного подтверждает, что репозиторий создан?
1.
Итоговое сообщение агента о созданном репозитории.
2.
Ответ gh auth status об успешном входе в GitHub.
3.
Успешный вывод gh repo create с адресом созданного репозитория.
Из чего складывается harness
Harness называют всё, что ты даёшь агенту для работы, кроме самой модели. В него входят инструкции проекта, скиллы, доступы и проверки.
Инструкции проекта нужны, чтобы агент понимал, как в нём работать: что мы создаём, где искать документацию, какие действия согласовывать с тобой и как проверять изменения. Их записывают в обычные текстовые файлы в репозитории. Распространённый формат называется AGENTS.md. У выбранного агента может быть своё имя файла, например CLAUDE.md, и свой способ загрузки. Начало такого файла может выглядеть так:
# Платформа командной разработки
Создаём платформу, на которой компания работает с агентами по общим правилам.
Бриф лежит в docs/brief.md, принятые решения в docs/. Читай их перед планированием.
Задачи ведём в GitHub Issues. Перед изменением кода назови задачу, над которой работаешь.
Скилл описывает повторяемый способ работы: уточнить задачу, подготовить описание будущей работы, проверить изменение. Обычно это папка с файлом SKILL.md, где записаны назначение и инструкции. Рядом могут лежать справочные файлы и скрипты. Скилл подключается под задачу, а не читается в каждой сессии. В начале файла стоят имя и описание, по которым агент решает, когда скилл применить. Упрощённо это выглядит так:
---
name: to-spec
description: Собрать согласованные решения в спецификацию и сохранить её в трекер задач.
---
1. Прочитай итог обсуждения и документы проекта.
2. Опиши поведение, выбранное решение и способ проверки.
...
Доступы определяют, что агент может выполнить: терминал, файлы проекта, GitHub CLI. Их задаёт среда агента, а не текст инструкций. Инструкция «не удаляй ветки» подсказывает, как работать. Отсутствие права на удаление не даёт это сделать.
Доступы настраиваются. Можно запретить отдельные команды или требовать твоего подтверждения перед каждой. Можно не давать агенту вход в свой аккаунт GitHub и выполнять эти действия вручную. Запрет одной команды надёжен, только если у агента нет другого пути к той же операции. Например, удалить ветку можно и через gh api, если агент вошёл в GitHub с такими правами.
Есть действия, которые агент технически может выполнить, но которые ты хочешь решать сам. Например, слить изменения в основную ветку, выложить релиз, потратить деньги, отправить сообщение другому человеку или изменить секреты. Такие действия перечисляют в инструкциях проекта отдельным списком. Всё, чего в списке нет, агент делает сам. Запись может выглядеть так:
## Что согласуем
Перед этими действиями спроси меня: слияние в main, релиз, платные действия,
сообщения другим людям, изменение секретов.
Остальное делай сам.
Список работает как инструкция, а не как запрет. Если действие нельзя допустить ни при каких условиях, его закрывают доступом.
Проверки показывают, что результат соответствует ожиданию: тесты, запуск приложения, ревью, то есть проверка изменений отдельной сессией агента. Тесты запускают командой проверки и в CI (continuous integration, непрерывная интеграция). CI автоматически запускает проверки при изменениях в проекте.
Проверьте понимание
Агент не должен удалить ветку в GitHub, даже если неверно поймёт задачу. Какой способ это обеспечит?
1.
Ограничение на удаление веток в инструкциях проекта.
2.
Ограничение на удаление веток в правах агента.
3.
Ограничение на удаление веток в списке действий на согласование.
Почему решения сохраняют в проекте
В новой сессии прошлый разговор может быть недоступен. Договорённость, которая осталась только в чате, для следующей сессии не существует. Поэтому важные решения сохраняют в проекте, а в инструкциях указывают, где их искать.
Основные правила держат в коротком входном файле. Подробности выносят в отдельные документы, на которые он ссылается. Тогда агент читает подробный документ, только когда документ нужен задаче, и контекст не забивается лишним.
Хороший запрос не заменит документов проекта. Запрос называет цель, а документы дают требования и принятые решения.
Решения, которые придётся принять
При настройке проекта тебе предстоит принять несколько решений.
Где хранить скиллы. В проекте скиллы лежат рядом с кодом и сохраняются в Git. Глобально они устанавливаются для твоего пользователя и доступны выбранному агенту во всех проектах. Для учебного проекта скиллы храним в самом проекте. Тогда любая сессия в этом проекте работает с одним и тем же набором, и видно, какая версия набора используется.
Менять ли готовые скиллы. Скилл можно поправить под себя, это обычный текстовый файл. Свои правила можно записать и в инструкции проекта, не трогая скиллы набора.
Мой совет
Скиллы набора я стараюсь не менять, а свои правила записываю в инструкции проекта. Тогда обновление набора не затирает мои правки, а отличие новой версии от прежней видно в git diff. Скилл меняю, только когда правило в инструкциях не помогает.
Что записать в инструкции сразу. Пока нужны назначение проекта и указатели на документы; пример входного файла показывает, как это записать.
Через что агент работает с GitHub. Рекомендую GitHub CLI, потому что агенту хватает обычных команд терминала, а вход в аккаунт ты выполняешь один раз.
Какие доступы дать агенту. Чем больше агент может сделать сам, тем реже он останавливается и ждёт тебя. Чем меньше у него прав, тем больше действий остаётся под твоим контролем. Здесь каждый решает сам.
Мой совет
Я выдаю агенту все доступы, потому что так работа идёт быстрее. Действия, которые решаю сам, перечисляю в инструкциях.
Углубление
На сайте AGENTS.md описан формат инструкций и перечислены агенты, которые его читают.