Читаемость для агента

Один и тот же агент в одном репозитории работает уверенно, а в соседнем блуждает, дублирует код и ломает соглашения. Разница чаще всего не в сложности задачи, а в том, насколько среда читаема для агента. Этим уроком открывается модуль о направляющих: прежде чем писать инструкции, стоит сделать так, чтобы большую часть ответов агент находил в самом коде.

Что значит «читаемость»

Термин agent legibility (в официальном русском переводе — «читаемость для агента») пришёл из статьи OpenAI «Harness engineering». У него две стороны:

• Читаемость работающего приложения — агент сам видит UI, логи, метрики и может воспроизвести баг. Это тема урока о наблюдаемости.
• Читаемость репозитория — агент находит знания, понимает структуру, умеет запустить и проверить код. Об этом урок.

Исходный тезис статьи: для агента не существует того, чего он не видит в репозитории. Обсуждение в чате, решение на созвоне, знание в голове ведущего разработчика — всего этого нет. Как превратить такие знания в версионируемые артефакты, разберём в уроке о системе записи. Здесь — свойства самого кода и проекта.

Скучные технологии

Команда OpenAI сознательно выбирала зависимости, которые можно целиком понять внутри репозитория. Их аргумент: «скучные» технологии агенту моделировать проще — они композиционны, у них стабильный API и они хорошо представлены в обучающих данных. Иногда команда шла дальше и переписывала нужное подмножество функциональности, чтобы не обходить неочевидное поведение библиотеки. Их пример — собственный хелпер параллельного выполнения вместо готового пакета, интегрированный с OpenTelemetry и покрытый тестами на 100%.

Наш вывод для агентства. Первая часть переносится напрямую: при выборе стека для нового проекта «насколько это знакомо модели» — законный критерий наряду с привычными. Вторая — осторожно. Переписывать библиотеку оправдано, когда нужна малая её часть, поведение неочевидно и агент регулярно на нём спотыкается. Для типового сайта на OctoberCMS или мобильного приложения на стандартном стеке это редкость.

Типы, границы, опинионированность

Биргитта Бёкелер в «Harness engineering for coding agent users» называет это свойство harnessability: не каждая кодовая база одинаково поддаётся обвязке. Помогают строгая типизация, явные границы модулей и опинионированные фреймворки. Она приводит термин своего коллеги Неда Летчера ambient affordances — структурные свойства самой среды, которые облегчают агенту работу.

Важное наблюдение оттуда же: в greenfield читаемость закладывается выбором технологий, а в легаси обвязка нужнее всего именно там, где её труднее всего построить.

Как это выглядит на нашем стеке:

Типы — это не только корректность, но и навигация: агент по сигнатуре понимает, что передать и что вернётся, не читая реализацию. Каждый mixed и каждый массив неизвестной формы — место, где агенту придётся гадать.

Единообразие важнее идеальности

Codex воспроизводит шаблоны, которые уже есть в репозитории, включая неудачные, — это отмечают и авторы статьи OpenAI. Если в проекте три способа делать HTTP-запросы к CRM, агент выберет случайный, причём не обязательно актуальный.

Практические следствия:

• Один способ на задачу. Устаревший способ либо удаляется, либо явно помечается как устаревший, а линтер запрещает новые использования.
• Эталонные файлы. Ссылка из AGENTS.md на образцовый компонент, контроллер, экран.
• Найденное поиском. Говорящие имена, без магических строк и динамических вызовов по собранному из кусков имени: агент ищет код через rg, и то, что не находится поиском, для него почти невидимо.
• Разумный размер файлов. Файл на 3 000 строк агент читает частями и теряет связи. У OpenAI лимиты размера файлов закреплены линтером.

Как превращать такие правила в механические проверки, разобрано в уроке об инвариантах, а как бороться с накоплением плохих шаблонов — в уроке об энтропии.

Запуск и проверка одной командой

В best practices Codex среди типичных ошибок прямо названа такая: агенту не сказали, как запускать сборку и тесты. Там же — мысль, что многие проблемы качества на деле оказываются проблемами настройки.

Минимальный набор для читаемого проекта:

make setup        # поднять окружение (Docker, зависимости, сиды)
make test         # юнит- и интеграционные тесты
make test-agent   # то же с коротким выводом для агента
make lint         # линтеры и статический анализ
make e2e          # Playwright против локального стенда

Конкретные имена неважны — важно, чтобы они были одинаковыми во всех проектах команды, работали без ручных шагов и были упомянуты в AGENTS.md. Если для запуска e2e нужно «попросить у Пети дамп базы», для агента e2e не существует.

Внешние зависимости

Знания о внешних библиотеках агент берёт из обучающих данных, а они могут устареть. Команда OpenAI держит в docs/references/ файлы вида *-llms.txt для ключевых внешних зависимостей. Для агентства кандидаты — API CRM клиента, внутренняя дизайн-система, особенности конкретной версии OctoberCMS. Короткий справочник в репозитории надёжнее, чем надежда, что модель помнит нужную версию.

Не меняя файлов, ответь только по содержимому репозитория:
1) как поднять проект локально; 2) как запустить тесты и линтер;
3) где эталонный пример компонента или экрана.
Для каждого ответа укажи файл-источник. Если ответа в репозитории нет — так и напиши.