Lockstep предлагает выдавать AI-агентам ADR по правилам поиска

Поисковая задача: как не дать агенту отменить важное архитектурное решение

Lockstep предлагает использовать ADR — записи архитектурных решений — как рабочий слой контекста для AI-агентов, а не как архив, который лежит рядом с кодом. Практическая задача здесь простая: агент должен находить действующее решение до того, как меняет границы сервисов, хранение данных, обмен сообщениями, аутентификацию или поведение публичного API.

Автор разбирает типичный риск. Агент видит синхронный вызов биллинга, после которого код публикует сообщение в очередь. Такая последовательность может показаться дублированием: тесты проходят, а прямой вызов выглядит кандидатом на удаление. Но в старом ADR может быть зафиксировано требование сохранить вызов для немедленного подтверждения у enterprise-клиентов. Запись существует, однако агент о ней не знает — и потому предлагает технически правдоподобное, но архитектурно неверное изменение.

Материал полезен командам, которые уже используют AI coding agents в репозитории и хотят сократить число правок, требующих позднего отката или ручного объяснения контекста. Речь не о том, чтобы вставить всю историю решений в каждый промпт. Вместо этого нужно определить, где лежат решения, когда их искать и как понять, какое из них остаётся актуальным.

Как оформить ADR, чтобы агент мог его прочитать

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

Для статуса предлагаются состояния proposed, accepted, deprecated и superseded. Такое разделение важно для агента: предложенная идея не должна восприниматься как обязательное правило, а заменённое решение не должно конкурировать в поисковой выдаче с новым. Если два документа выглядят одинаково действующими, агенту трудно выбрать между ними.

Старые ADR не следует удалять или переписывать на месте. Вместо этого в них нужно поставить статус superseded и ссылку на новый документ. Так остаётся видна история причин и изменений, но актуальная позиция не теряется среди старых записей. Отдельный индекс помогает быстро просматривать набор решений, а не открывать каждый файл подряд.

Какие правила добавить в репозиторий

Автор предлагает совместить каталог docs/adr с файлами инструкций для агентов: AGENTS.md, CLAUDE.md и правилами Cursor. В этих правилах не нужно копировать журнал архитектурных решений целиком. Достаточно короткой инструкции по извлечению контекста: перед изменением определённых частей системы агент обязан найти подходящий ADR, прочитать его и проверить документы, которыми он был заменён.

Если предполагаемая правка конфликтует с принятым решением, агент должен остановиться, а не пытаться обойти правило удачной формулировкой или зелёными тестами. В такой схеме ADR отвечает на вопрос, почему код устроен именно так; правило проекта сообщает, когда искать ответ; статусы и ссылки на замену показывают, какой ответ действует сейчас.

Практический эффект зависит от точности триггеров. Формулировка «читай ADR всегда» перегружает работу лишним поиском. Формулировка о проверке перед изменением сервисных границ, сообщений, аутентификации, хранилища и публичных контрактов привязывает поиск к операциям, где архитектурный контекст особенно важен.

Как проверить, что схема работает

Lockstep предлагает не ограничиваться тем, что ADR был создан в той же сессии, где работал агент. Проверку следует проводить в новой сессии. Агенту можно предложить объяснить текущее решение, его обоснование и отвергнутые альтернативы. Затем решение меняют через обычный путь согласования и повторяют проверку.

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

Ограничения материала

Материал описывает подход Lockstep и не приводит примеров конкретной структуры файлов, запросов агента или результатов внедрения в командах. Из него нельзя вывести, какие правила поиска подойдут любому репозиторию: перечень триггеров должен соответствовать устройству проекта и принятым процессам согласования.

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