Забытый сидер. Необновлённый тест. Подписчик на событие, о котором никто не помнил. Кэш, который надо было сбросить.
Список того, что ломается в нетривиальной задаче, скучно однообразен. Ни одна из этих поломок не про сложность кода — все про то, что связь не увидели.
Агент, который ничего не делает
Из двенадцати агентов блога двое не пишут код и не запускают команды. Они читают и рассказывают.
flow-orchestrator строит карту пути запроса внутри проекта. ecosystem-orchestrator — карту влияния на соседние сайты. Оба возвращают текст, после которого я знаю, где менять и что заденет.
Идея завести исполнителя, который не исполняет, первое время казалась мне сомнительной. Убедил простой подсчёт: на трёх задачах подряд я потратил в сумме два часа на разбор последствий, которых не предвидел. Двадцать минут разведки перед каждой стоили бы часа.
Что строит карта
Тело у картографа короткое, двадцать семь строк. Основное в нём — порядок обхода.
1. Найди точки входа: routes/web.php и соседние, Filament-ресурсы и страницы.
2. Проследи путь: controller → FormRequest → service/action → model →
job/event/notification → view (Blade) или Filament.
3. Отметь затронутое: config/, database/migrations, database/seeders,
tests/, кэш и настройки сайта.
4. Передай короткую карту: где менять, что заденет, что покрыть тестами.Третий пункт — тот, ради которого всё затевалось. Первые два описывают путь по коду, и его я обычно представляю сам. Третий перечисляет то, что находится вне пути и потому забывается.
Сидеры здесь стоят не случайно. В блоге контент живёт в сидерах, и развёртывание на проде пересоздаёт базу целиком. Правка модели без правки сидера означает, что после следующего обновления сайт поднимется без нужных данных, и это выяснится не сразу.
Ограничения в теле такие же короткие:
- Не перепрыгивай через flow route→side-effect: показывай полную цепочку.
- Не предлагай абстракций, которых в репозитории сейчас нет.
- Учитывай, что контент живёт в сидерах и настройках, а не в коде шаблонов.Второе — самое ценное. Разведчик, который по дороге предлагает ввести слой абстракции, превращается в архитектора, а архитектора я не звал.
Прогон после: qa-runner
Вторая половина пары — агент, который гоняет тесты и линтер. Его тело устроено вокруг команд:
docker compose --env-file .local/.env -f .local/docker-compose.yml \
exec -T webserver php artisan test
docker compose --env-file .local/.env -f .local/docker-compose.yml \
exec -T webserver ./vendor/bin/pint --testДальше порядок работы: запусти нужный набор, прочитай настоящий вывод, локализуй причину, перегони затронутое, потом весь набор.
Строка «прочитай реальный вывод, не угадывай» появилась после случая, когда мне пересказали содержимое падения, не запуская тест. Пересказ был правдоподобный и неправильный.
И правило про честный отчёт: что упало, почему, что починено, что осталось красным. Без него отчёт сводится к «всё готово», а «всё» проверять приходится самому.
Расхождение, которое я нашёл
Готовя эту статью, я перечитал файл и обнаружил у себя противоречие.
В теле написано «диагностируешь и точечно чинишь падения» и «чини минимально и по существу». А в списке инструментов у него Read, Grep, Glob, Bash — права записи нет. То есть тело поручает починку, которую свойства агента не позволяют.
На практике это работало все эти месяцы, потому что через оболочку файлы никто править не пытался, а падения приходили ко мне с диагнозом. Но формально файл врёт сам себе, и я его поправлю: разведка и прогон возвращают информацию, правку делает пишущий агент.
Мораль отсюда некрасивая, но полезная. Свойства во фронтматтере и текст в теле живут отдельно и расходятся молча. Тело правится чаще, инструменты — почти никогда, и через несколько месяцев они рассказывают разные истории.
Порядок вызова
Схема, к которой пришёл: разведка до правки, прогон после.
разведка → план → правка → прогон → ревьюРазведка отвечает на вопрос «что заденет». Прогон — на вопрос «что сломалось». Между ними правка, и делает её тот, у кого есть право записи и чья зона затронута.
Что важно: разведка не заменяет план, а предшествует ему. Карта показывает связи, план решает, что с ними делать. Я одно время пробовал просить карту и план сразу, одним заходом — получал план, обоснованный картой, которую я не успел прочитать.
Когда разведка избыточна
Не всегда. Три случая, где я её пропускаю.
Задача целиком внутри одного файла и без побочных эффектов: поправить текст на странице, поменять цвет, добавить условие в шаблон. Карта такой задачи — одна строка, и рисовать её незачем.
Задача в зоне, которую я недавно трогал. Если карта уже была построена на прошлой неделе и с тех пор ничего не менялось, я использую её, а не строю заново.
Задача, где я и есть карта. В блоге я помню большинство связей и зову разведку только на участках, которые давно не открывал: подписанные ссылки на предпросмотр, лента, карта сайта.
Обратный признак, по которому разведку зову обязательно: задача меняет данные. Новое поле, изменение схемы, правка сидера, смена слага. Всё, что затрагивает то, что уже лежит в базе, обрастает связями быстрее, чем кажется.
Что осталось
Пара «разведка до, прогон после» стоила двух коротких файлов и окупилась на первой же задаче со сменой слага рубрики, где карта показала карту сайта, ленту и канонические адреса в трёх шаблонах.
Чего не хватает — памяти между вызовами. Карта строится заново каждый раз, хотя проект между вызовами меняется мало. Сохранять её в файл я пробовал, но она устаревает незаметно, а устаревшая карта хуже отсутствующей: по ней идут, не перепроверяя. Пока остановился на том, что карту строю заново, зато быстро.
