Контекст оказался важнее модели

Есть довольно понятная реакция, когда AI в очередной раз делает что-то не так.

Может, Claude справится лучше?

Не справился.

Тогда попробую Codex.

Стало немного иначе, но тоже не идеально.

Наверное, нужно дождаться следующей модели.

И какое-то время я действительно довольно много внимания уделял именно этому. Какая модель лучше пишет PHP. Какая лучше понимает большой проект. Какая аккуратнее рефакторит. Какая реже придумывает несуществующие методы. Какая лучше следует инструкциям. Какая способна дольше самостоятельно работать над задачей.

Это вполне нормальные вопросы. Модели действительно отличаются.

Но постепенно я заметил странную вещь. Иногда одна и та же модель на одном и том же проекте могла выглядеть то почти как хороший разработчик, то как человек, который открыл кодовую базу пять минут назад.

И разница была не в модели. Разница была в том, что она знала до начала работы.

Я долго пытался решить организационную проблему заменой модели

Сценарий был довольно типичным. Я отдаю задачу. AI делает странную реализацию. Я смотрю на результат и думаю: он вообще не понял, как здесь всё устроено.

После этого естественно открыть другой инструмент и попробовать там. Иногда результат действительно становился лучше. И это укрепляло ощущение: вот, эта модель просто умнее.

Но затем происходила другая задача, на которой всё переворачивалось. Claude находил хорошее решение там, где Codex уходил не туда. Или наоборот. Потом появлялась новая версия модели, и хотелось повторить эксперименты ещё раз.

В какой-то момент это начинало немного напоминать поиск идеального программиста: вот сейчас найдётся модель, которой я просто отдам задачу, и она сама всё поймёт.

Проблема была в том, что понимать часто было нечего. Нужная информация существовала только у меня в голове. Про это я уже писал, когда маленькая задача внезапно оказывалась большой — не из-за diff, а из-за неявного контекста.

Модель видела код, но не видела проект

Эту разницу я раньше недооценивал. Можно дать AI доступ ко всему repository. Формально у него есть проект. Он может искать файлы. Читать классы. Смотреть зависимости. Запускать команды.

Но это ещё не означает, что он понимает систему так же, как разработчик, который работает с ней несколько лет. Для меня проект — это не только файлы. Это ещё и набор знаний:

почему система устроена именно так
какие части legacy лучше пока не трогать
какие соглашения приняты в команде
что считается публичным API
какие тесты обязательны
какие команды нужно запускать
где находится настоящий source of truth
какие архитектурные решения мы больше не используем
какие ограничения пришли от бизнеса
какие компромиссы были сделаны намеренно

В Git repository всё это представлено очень неравномерно. Что-то есть в коде. Что-то в документации. Что-то в тестах. Что-то в issue tracker. Что-то осталось после обсуждения трёхлетней давности. А что-то просто живёт в головах людей.

Для AI всё, чего нет в доступном контексте, практически не существует.

Самый простой эксперимент оказался довольно показательным

Можно взять одну и ту же задачу. Например:

Добавь новый способ экспорта заказов.

В первом варианте дать только эту фразу. AI начинает исследовать проект с нуля. Находит какой-то export service. Смотрит controller. Создаёт новую реализацию. Возможно, всё даже работает.

Теперь попробуем ту же задачу, но в проекте уже есть нормальный контекст. Например:

README.md
AGENTS.md
docs/architecture.md
docs/orders.md

А внутри записано:

экспорты реализуются через существующий pipeline
controller не содержит бизнес-логики
новые форматы оформляются отдельными exporter
для изменений заказов обязательны integration tests
команда тестов: composer test
команда статического анализа: composer phpstan
публичные DTO менять нельзя
legacy exporter используется внешней интеграцией и пока не рефакторится

Модель та же. Задача та же. Проект тот же. Но поведение становится совершенно другим. Не потому, что AI внезапно поумнел. Он просто перестал угадывать.

Хороший контекст убирает пространство для случайных решений

Когда AI ничего не знает о проекте, перед ним существует огромное количество технически допустимых вариантов. Можно написать новый сервис. Можно расширить старый. Можно использовать event. Можно добавить listener. Можно положить логику в controller. Можно сделать trait. Можно создать ещё одну abstraction.

И многие варианты будут выглядеть вполне разумно. Но в конкретном проекте команда, возможно, давно решила: вся такая логика идёт через application service.

Если это правило нигде не записано, модель должна либо сама вывести его из кода, либо угадать. Иногда угадает. Иногда нет. А потом мы говорим: эта модель плохо понимает архитектуру. Хотя архитектурное правило мы ей просто не сообщили.

README неожиданно перестал быть формальностью

Раньше README для меня в основном был входной точкой для человека. Как развернуть проект. Какие переменные окружения нужны. Как запустить приложение. Где посмотреть документацию.

С coding agents его роль стала шире. Хороший README позволяет довольно быстро ответить на базовые вопросы: что это за система? Из каких крупных частей она состоит? Какие технологии используются? Как её запускать? Как проверять изменения? Где искать дополнительную документацию?

Это всё ещё документ для человека. Но одновременно это отличный первый слой контекста для AI. И внезапно качество README начинает напрямую влиять на качество работы агента.

Потом появился AGENTS.md

Следующим логичным шагом для меня стали отдельные инструкции именно для AI. Не огромный файл со всеми знаниями человечества о проекте. Скорее набор правил, которые разработчик проекта считает очевидными, а агенту важно сообщить явно.

Например:

Перед изменением существующей функциональности сначала найди связанные тесты.
Не добавляй новую зависимость без необходимости.
Не меняй публичные API без отдельного согласования.
Используй существующие Value Objects вместо primitive values.
Новые database migrations должны быть обратимыми.
После изменений запускай:
composer test
composer phpstan
Не исправляй unrelated проблемы в рамках текущей задачи.

Ни один из этих пунктов сам по себе не делает модель умнее. Но вместе они заметно уменьшают количество странных решений. И это оказалось гораздо интереснее постоянного переключения между моделями.

Особенно важными оказались команды проверки

Это вообще довольно приземлённая вещь. AI может написать хороший код и совершенно не знать, как правильно проверить его именно в этом проекте.

Допустим, он видит phpunit.xml и запускает PHPUnit напрямую. Тесты проходят. Но команда давно использует:

composer test

А внутри неё запускаются ещё дополнительные проверки. Или есть:

composer quality

где находятся formatter, PHPStan, архитектурные тесты и ещё несколько инструментов.

Для разработчика проекта это очевидно. Для AI — нет. После того как команды проверки оказываются явно записаны в инструкциях, меняется даже само значение фразы «проверь реализацию».

Теперь она означает не абстрактное «сделай что-нибудь, чтобы убедиться, что всё нормально». У агента есть конкретный checklist.

Архитектурные правила оказались ещё важнее coding style

Сначала легко увлечься правилами вроде:

используй readonly
предпочитай constructor injection
следуй PSR-12
используй strict_types

Это полезно. Но довольно быстро я понял, что гораздо важнее другой уровень инструкций.

Например: domain layer не зависит от Symfony. Или: изменение состояния заказа происходит только через state transition service. Или: интеграции с внешними системами должны идти через adapters. Или: controllers только преобразуют HTTP request в application command.

AI вполне способен самостоятельно написать красивый PHP. Настоящие проблемы чаще начинаются не с formatting. Они начинаются, когда хороший PHP оказывается написан не в том месте системы.

Поэтому архитектурный контекст для меня постепенно стал важнее инструкций по стилю.

Контекст — это не один огромный файл

Здесь тоже была крайность, в которую довольно легко попасть. Если проблема в недостатке контекста, значит нужно создать огромный AGENTS.md и записать туда всё.

Через некоторое время получится документ на несколько десятков страниц. И возникнет новая проблема. Самое важное потеряется среди сотни правил.

Поэтому сейчас мне больше нравится многоуровневая схема. Что-то вроде:

README
    ↓
общее понимание проекта
AGENTS.md
    ↓
правила работы агента
architecture docs
    ↓
ключевые инженерные решения
module docs
    ↓
особенности конкретной области
tests
    ↓
исполняемое описание ожидаемого поведения

И дальше агент должен находить нужный контекст в зависимости от задачи. То есть задача не в том, чтобы дать AI максимальное количество информации. Задача — дать ему правильную информацию в правильный момент.

Я стал иначе относиться даже к тестам

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

Иногда тест говорит о системе гораздо больше, чем комментарий. Например:

it_cannot_cancel_an_order_after_shipping

Название уже сообщает важное бизнес-правило. А сам тест показывает: какое состояние считается исходным; какое действие выполняется; какой результат ожидается.

Если AI перед изменением читает связанные тесты, он получает кусок контекста, который иначе пришлось бы объяснять словами. В этом смысле хороший test suite становится ещё и своеобразной базой знаний о системе.

Ограничения особенно полезно записывать явно

AI очень любит улучшать. Иногда слишком сильно. Ты просишь небольшую feature. А он замечает рядом старый код и решает заодно привести его в порядок. И технически часто прав. Этот код действительно можно улучшить. Проблема в том, что сейчас это может быть совершенно не нужно.

Поэтому контекст проекта — это не только «вот как правильно». Очень часто это ещё «вот чего делать не нужно».

Например:

Не рефактори соседний legacy-код без необходимости.
Не меняй database schema в этой задаче.
Не добавляй новый package.
Не меняй формат существующего API response.
Не удаляй deprecated method — его использует старый клиент.
Не заменяй текущий механизм очередей.

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

Одна и та же модель начала вести себя как другой разработчик

Это, наверное, больше всего повлияло на моё отношение к выбору моделей.

Когда проект почти ничего не объясняет агенту, модель часто ведёт себя как талантливый разработчик в первый рабочий день. Он умеет программировать. Он знает framework. Он способен читать код. Но не знает, как принято делать здесь.

После появления нормального контекста поведение постепенно меняется. Не потому, что AI приобрёл настоящую память о проекте. А потому, что ему больше не приходится каждый раз восстанавливать правила по косвенным признакам.

Вместо «наверное, здесь принято делать так» появляется: в инструкциях проекта указано, что такие изменения должны проходить через этот слой. Это огромная разница.

Конечно, модель всё равно имеет значение

Я бы не хотел делать из этой истории другой абсолютный вывод: модели вообще не важны. Важны.

Они отличаются способностью исследовать большие кодовые базы. Следовать инструкциям. Работать с инструментами. Строить планы. Понимать сложные зависимости. Проверять собственную работу. Разные модели действительно могут по-разному справляться с одной и той же задачей.

Но постепенно я перестал задавать вопрос «какая модель лучшая?» без второго вопроса: в каких условиях я её запускаю?

Потому что сравнивать мощную модель без контекста и другую модель с хорошими проектными инструкциями — довольно странный эксперимент.

Я стал сначала улучшать окружение, а уже потом менять модель

Теперь, если AI стабильно ошибается в похожих задачах, я стараюсь не сразу переключаться на другой инструмент. Сначала смотрю:

А знает ли он архитектуру проекта? Есть ли у него команды тестирования? Понимает ли он ограничения? Знает ли, какие файлы являются source of truth? Есть ли описание модуля? Есть ли понятные тесты? Не существует ли важное правило только у меня в голове?

Иногда после ответа на эти вопросы оказывается, что менять модель вообще не нужно. Нужно добавить десять строк в AGENTS.md. И следующая похожая задача уже выполняется намного лучше.

Вот это для меня стало одним из наиболее неожиданных открытий. Пара строк документации может дать больший прирост качества, чем переход на очередную новую модель.

Хороший контекст начинает накапливать ценность

У смены модели есть одна неприятная особенность. Сегодня я настроил процесс вокруг одного инструмента. Завтра появляется другой. Через месяц новая версия. Через полгода всё снова поменялось.

А качественное описание проекта остаётся.

README
архитектурные решения
правила проекта
команды проверки
ограничения
описания модулей

Они полезны Claude. Полезны Codex. Полезны Cursor. Полезны следующему инструменту, которого сегодня ещё может не существовать. И, что особенно приятно, они полезны обычному разработчику.

То есть инвестиция в контекст гораздо менее привязана к конкретной модели, чем хороший prompt под неё.

Наверное, именно здесь я начал меньше заниматься prompt engineering

Сначала хочется найти идеальную формулировку. Как правильно попросить AI сделать задачу? Написать более подробный prompt. Добавить роли. Указать последовательность действий. Сделать шаблон.

Но постепенно вопрос у меня изменился. Не «как мне каждый раз объяснять AI наш проект?», а «почему проект сам этого не объясняет?»

Если я регулярно повторяю «сначала запускай PHPStan» — значит, это должно быть записано в проекте. Если каждый раз говорю «не меняй публичные DTO» — это правило тоже должно жить рядом с кодом. Если постоянно приходится объяснять архитектуру модуля — возможно, нужно один раз нормально её описать.

Так часть prompt engineering постепенно превращается в context engineering. Я всё меньше пытаюсь написать идеальный запрос. И всё больше пытаюсь создать окружение, в котором нормального запроса будет достаточно.

Хороший проект для AI начинает немного напоминать хорошо организованную команду

Когда в команду приходит новый разработчик, можно каждый раз объяснять ему всё устно. А можно иметь понятный README, документацию, архитектурные решения, development guide, команды проверки, conventions и хорошие тесты. Во втором случае onboarding происходит быстрее.

С AI оказалось удивительно похоже. Чем меньше устройство проекта зависит от телепатии и исторической памяти отдельных людей, тем проще агенту работать самостоятельно.

И это, пожалуй, хорошая новость. Потому что означает, что подготовка проекта для AI — не какая-то совершенно новая дисциплина. Во многом это просто следующий аргумент в пользу вещей, которые мы и раньше считали хорошей инженерной практикой.

Теперь мой первый вопрос — не «какую модель выбрать»

Разумеется, я всё ещё пробую разные модели. Сравниваю. Смотрю, какая лучше подходит для исследования, какая для реализации, какая для review.

Но когда AI делает что-то откровенно странное, первая мысль у меня теперь немного другая. Не «нужно взять модель умнее», а «какой информации ему не хватило, чтобы принять правильное решение?»

Иногда ответом действительно оказывается: никакой. Модель просто ошиблась. Такое тоже случается.

Но удивительно часто обнаруживается конкретная дырка. Неописанное правило. Неочевидная команда. Скрытая зависимость. Неявное ограничение. Кусок архитектуры, который невозможно понять без истории проекта.

И тогда исправление этой дырки помогает не одной конкретной задаче. Оно улучшает следующие десять.

Контекст оказался важнее, чем я думал

Наверное, я всё ещё не готов сказать, что контекст всегда важнее модели. Слишком сильное утверждение.

Но в собственной работе я заметил другое. Я слишком долго пытался улучшать результат, выбирая более сильного исполнителя. И слишком мало думал о том, в какую среду этого исполнителя помещаю.

Можно постоянно искать модель, которая лучше догадается о правилах проекта. А можно постепенно перестать заставлять её гадать. Добавить README. Записать архитектурные решения. Создать AGENTS.md. Указать команды тестирования. Описать ограничения. Сделать важные бизнес-правила видимыми.

И тогда одна и та же модель внезапно начинает работать совсем иначе. Не потому, что стала умнее. А потому, что наконец получила возможность понять, в каком именно проекте она сейчас работает.

И в какой-то момент я понял, что следующий большой прирост качества моей AI-разработки, возможно, находится вовсе не в следующей модели. Он находится в моём собственном repository.