Перед правкой публичной статьи агенту предлагают «изучить весь проект». Он перечисляет контроллеры и модели, но не замечает, что обновлённый текст попадёт в RSS, а карточка останется в кэше. Полный список папок не помог понять последствия конкретного изменения.
Карта репозитория полезна, когда отвечает на рабочий вопрос. Для задачи об изменении вывода статьи это путь от сохранённого контента до публичной страницы и связанных выдач. Составлять энциклопедию приложения перед такой правкой не требуется.
Начните с действия пользователя
Сформулируйте наблюдаемое поведение: «Посетитель открывает статью и видит обновлённый блок кода; HTML остаётся очищенным, ссылки и превью работают». Эта фраза определяет область исследования лучше, чем просьба прочитать все файлы.
Дайте агенту ограниченный запрос:
Пока не меняй файлы. Найди путь вывода публичной статьи:
маршрут → обработчик → выборка записи → шаблон → очистка HTML.
Отдельно выясни:
- где проверяются статус и дата публикации;
- какие кэши или выдачи зависят от записи;
- какие тесты проверяют этот путь.
Для каждого вывода укажи файл и символ.
Отдели найденное поведение от предположений.
Если связь не прослежена, пометь её как неизвестную.Такой запрос разрешает исследовать зависимости, но не выдаёт право сразу менять их. Если необходим технический запрет записи, он задаётся настройками среды, а не только фразой в сообщении.
Фиксируйте связи, а не инвентарь
В almdev исходными точками для такой проверки служат routes/web.php, BlogController, модель Post и публичный шаблон статьи. Сам список ещё ничего не доказывает. Нужно открыть используемые методы и проследить, как запись становится HTML-ответом.
Удобный формат рабочего результата:
Вход: URL статьи по slug.
Выборка: найденный метод и фактические условия доступности.
Рендеринг: используемый Blade-шаблон и layout.
HTML: место вызова clean() и профиль очистки.
Зависимости: подтверждённые выдачи и механизм кэша.
Проверки: существующие тесты, относящиеся к изменению.
Неизвестно: связи, которые ещё не удалось подтвердить.Эта запись не заменяет код. Она позволяет рецензенту быстро открыть основания и проверить, не пропущен ли важный переход. Номер строки удобен в текущем diff, но имя метода обычно лучше переживает небольшую правку файла.
Проследите путь изменения отдельно
Путь чтения и путь записи могут расходиться. Статья выводится одним контроллером, редактируется через админку, импортируется командой и участвует в нескольких выдачах. Перед изменением сохранения нужно исследовать именно выбранный вход записи.
Проверьте, запускаются ли обработчики модели, пересчитываются ли производные поля и сбрасывается ли кэш. Нельзя заключать, что всё это происходит, лишь обнаружив соответствующий observer в проекте: конкретная операция может обходить его.
Не расширяйте карту бесконечно. Если задача меняет оформление блока кода и не затрагивает сохранение, достаточно отметить подтверждённую границу. Если меняется механизм записи, исследование становится глубже. Объём определяется возможными последствиями, а не желанием показать количество прочитанных файлов.
Что оставить следующей сессии
Постоянные особенности проекта сохраните в его руководстве: как запускать команды, где искать публичные шаблоны, какое правило очистки HTML действует. Карту текущего изменения и оставшиеся вопросы держите в задаче. Не превращайте AGENTS.md в журнал каждого исследования.
Большая архитектурная документация может оставаться отдельным материалом. Из короткой карты нужна ссылка на нужный раздел с объяснением, зачем его читать. Дублирование полного описания моделей в нескольких инструкциях создаёт лишние места устаревания.
Принцип выбора между руководством и процедурой подробнее разобран в статье об AGENTS.md и skills. Здесь важен результат: новый исполнитель должен найти актуальный источник, а не поверить сохранённому пересказу.
Учитывайте реальный загрузчик инструкций
Codex ищет инструкции по собственным правилам иерархии, описанным в руководстве AGENTS.md. У Claude Code порядок загрузки CLAUDE.md и поддержка AGENTS.md описаны отдельно: наличие CLAUDE-файла может влиять на выбор. Штатный импорт @AGENTS.md и обычная текстовая просьба открыть файл не равноценны. Условия приведены в документации Claude Code.
Поэтому локальную папку .ai/ или .devflow/ нельзя называть автоматически обнаруживаемой всеми клиентами. В проекте может быть собственный загрузчик или плагин. Его подключение нужно подтвердить, а не выводить из имени каталога.
Проверьте карту небольшим поручением
В новой сессии попросите найти место предполагаемой правки и назвать проверку её результата. Хороший ответ ссылается на действующий код и указывает неопределённость. Плохой воспроизводит карту дословно, даже если указанный метод уже переименован.
Если карта направляет к несуществующему файлу, исправьте источник и найдите другие ссылки на него. Если она заставляет читать полпроекта для маленькой задачи, сузьте маршрут. Ценность карты — в сокращении необоснованных предположений, а не в размере документа.
После реализации обновите только те части, поведение которых действительно изменилось. Отчёт о задаче сохранит историю решения; карта должна помогать следующему человеку или агенту работать с нынешним состоянием проекта.
