Карта репозитория для агентов, пишущих код, которая сокращает неверные правки файлов

Почему агенты правят не те файлы

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

Папка billing, другая payments и помощник invoice_service — все они могут выглядеть правильно. Агент часто выбирает файл, в котором встречаются слова из запроса, а не тот, который реально контролирует поведение в рантайме.

Проблема усугубляется, когда код инициализации находится далеко от папки с фичей. Запрос может начинаться в api/routes, проходить через middleware, загружать конфиг из bootstrap и только потом попадать в сервис, который вы хотели изменить. Люди со временем запоминают эти прыжки. А агенты не запоминают, если репозиторий этого явно не показывает.

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

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

• Где начинается этот поток?
• Какой модуль отвечает за это поведение?
• Что ещё запускается при изменении этой функции?

Типичный пример делает проблему очевидной. Команда просит агента «исправить дублирующие письма приветствия». Агент правит шаблон или класс отправки, потому что имена подходят. Настоящая ошибка может быть в логике повторных попыток регистрации внутри воркера и одном idempotency‑проверке в сервисе аккаунта. Дифф выглядит чисто, а поведение в продакшне остаётся сломанным.

Без карты репозитория инструмент продолжает угадывать по именам и близости. Даже короткая карта повышает шансы. Она показывает, какие файлы владеют фичей, где начинается выполнение и какие правки могут повлиять на логи, письма, очереди или записи. Ревьюеры тратят меньше времени на детективную работу и больше — на оценку, действительно ли фикc правильный.

Что включить в карту репозитория

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

Если billing отвечает за счета и подписки — укажите это. Если dashboard только рендерит UI и не должен содержать платёжные правила, тоже напишите это. Часто достаточно одного простого предложения на модуль.

Важно давать топ‑уровневые заметки, потому что агенты часто выбирают файл, который выглядит «достаточно близко». Ревьюеры затем теряют время, спрашивая, почему изменение UI затронуло бизнес‑логику или почему обновление биллинга попало в общий хелпер. Короткая заметка о владельче предотвращает много дрейфа.

Далее назовите точки входа. Большинство репов имеют несколько: веб‑запросы, CLI‑команды, воркеры очередей, cron‑задачи и скрипты миграций. Агенты плохо угадывают, когда не видно, где начинается выполнение и какие процессы работают в фоне. Если фича стартует в api/orders, разрастается в воркер и заканчивается на отправке письма, сделайте этот путь очевидным.

Общие библиотеки тоже требуют предупреждений. Некоторые файлы выглядят безобидно, но лежат под большой частью продукта. Маленькая правка в auth, логировании, загрузке конфигов, feature flags или хелперах БД может распространиться по множеству фич. Отметьте такие места, чтобы люди замедлялись перед изменением.

Не нужна длинная документальная сводка. Короткая карта может выглядеть так:

• app/ отвечает за интерфейс и обработчики запросов
• workers/ запускает фоновые задания, ретраи и планировщики
• lib/auth влияет на вход во всю систему
• services/payments списывает карты и пишет записи биллинга
• legacy/importer содержит старые правила и ненадёжные тесты

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

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

Начните с модулей и границ

Полезная карта начинается с модулей, у которых есть чётная задача. Дайте каждому одно предложение простым языком: "Billing создаёт charges и invoices." "Auth логинит пользователей и проверяет сессии." Если для объяснения модуля нужно три предложения, граница, вероятно, размыта.

Затем отметьте, где данные входят и выходят из модуля. Держите просто: что приходит, что уходит и куда дальше идёт. Модуль orders может принимать checkout‑запрос, записывать order и отправлять событие в billing. Такая маленькая заметка помогает агенту выбрать правильный файл и помогает ревьюеру заметить изменения, которые пересекают границы.

Хорошая документация репозитория также говорит, какие файлы нельзя править в лоб. Некоторые файлы выглядят простыми для патча, но потом создают проблемы. Миграции БД, проверки прав, общие типы и низкоуровневый storage код — типичные проблемные места. Если другие модули не должны править их напрямую, напишите это. Заметка вроде "править только когда задача явно называет этот файл" часто достаточна.

Полезно разделять стабильный код и быстро меняющийся код. Стабильный код — это правила схемы, денежная логика, контроль доступа и всё, что тихо может сломать продакшн. Быстро меняющийся код — это текст UI, feature flags, шаблоны писем и шаблоны промптов. Агенты часто сопоставляют по именам, а когда оба типа кода находятся рядом, они могут затронуть неверный уровень.

Небольшая команда может уместить это на одной странице. Модуль checkout владеет суммами корзины и созданием заказов. Модуль email шлёт квитанции и обновления статуса. Правила ценообразования меняются редко. Шаблоны квитанций меняются часто и безопаснее для правок. Эта граница сама по себе делает ревью с помощью ИИ гораздо быстрее, потому что ревьюер сначала проверяет выбор модуля, а потом уже смотрит дифф построчно.

Отметьте точки входа и пути выполнения

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

Карта репозитория должна перечислять места, где начинается выполнение: файлы маршрутов, CLI‑команды, воркеры очередей и cron‑задачи. Если у приложения несколько рантаймов, перечислите их явно, не полагаясь на названия папок.

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

Например:

• Веб‑запрос: файл маршрутов -> middleware -> handler -> service
• CLI‑задача: точка входа команды -> парсер аргументов -> обработчик команды
• Воркер: консьюмер очереди -> обработчик задания -> бизнес‑логика
• Запланированная задача: определение cron -> раннер -> функция задачи

Назовите хендлер, который владеет каждым путём. "Orders API" — слишком расплывчато. src/api/orders.ts -> createOrder() -> services/orders/create.ts гораздо лучше. Агент получает реальный след, а ревьюер — быстрый способ проверить правку.

Сделайте так же для конфига. Маленькие файлы конфигурации часто меняют поведение сильнее, чем код фичи. Отметьте env‑файлы, feature flags, регистрацию роутов, настройку dependency injection, расписания задач и любые per‑environment настройки, которые влияют на то, какой код выполняется.

Код запуска тоже важен. Если приложение загружает middleware, патчит глобалы, регистрирует сервисы, прогревает кэши или читает конфиг до того, как запрос попадёт в handler — запишите это. Агенты часто пропускают слои инициализации и затем "фиксируют" не тот файл.

Компактная запись для каждого пути может включать пять фактов:

• имя точки входа
• файл старта
• первый обработчик или раннер
• код запуска, который выполняется до бизнес‑логики
• конфиги, которые могут изменить поведение

Если эта часть карты актуальна, ревьюеры значительно реже будут спрашивать: "Почему агент правил этот файл?"

Записывайте побочные эффекты и рискованные места

Файл может выглядеть безобидно и при этом выполнять дорогие или опасные операции. Здесь агенты часто ошибаются. Они меняют handler, модель или воркер и не замечают, что тот же путь отправляет письма, списывает деньги, удаляет записи или меняет доступ клиентов.

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

Во многих случаях достаточно короткой заметки рядом с именем модуля: "Пишет в Stripe и отправляет письмо‑квитанцию" — это сигнал и для агента, и для ревьюера притормозить.

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

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

• Что может изменить этот код?
• С какими внешними системами он взаимодействует?
• Что нужно держать в синхронизации?
• Кто может это вызвать?

Проверки прав требуют такого же отношения. Если контроллер, middleware или сервис применяют role‑check, напишите об этом. Иначе агент может переместить логику в общий хелпер и незаметно обойти правило для админов.

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

Представьте, что команда меняет лишь текст кнопки "отменить подписку". Маршрут делает не только обновление текста: он также останавливает будущие инвойсы, лишает премиум‑доступа, очищает запись в кэше и пушит событие в очередь поддержки. Если карта перечисляет эти побочные эффекты, агент правит нужные файлы, а ревьюер сначала проверяет рискованный путь.

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

Соберите карту за пару коротких проходов

Полезная карта не требует недели диаграмм. Большинство команд могут сделать первую версию за час‑два, если будут практичны и сосредоточатся на том, как код реально выполняется.

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

Затем выберите одно реальное пользовательское действие и проследите его от входа до выхода. Возьмите что‑то обычное: "пользователь входит", "клиент завершает покупку" или "админ экспортирует отчёт". Трассируйте запрос через handler, сервисы, воркеры и слой хранения. Карта становится лучше, когда идёт по пути, которым люди пользуются каждый день, а не по выдуманному примеру.

По мере трассировки отмечайте общий код и побочные эффекты. Общий код — это место, где агенты чаще всего сбиваются с пути и правят больше, чем нужно. Побочные эффекты — это то, что удивляет ревьюеров: записи в БД, обновления кэша, очереди, письма, вебхуки, файловые записи, feature flags и аналитические события.

Простой первый проход может выглядеть так:

• Перечислите топ‑уровневые модули и за что они отвечают.
• Проследите одно обычное действие через код.
• Отметьте общие хелперы на этом пути.
• Пометьте все побочные эффекты и рискованные зависимости.
• Попросите ревьюера переформулировать размытые строки.

Последний шаг важнее, чем кажется. Тот, кто лучше всего знает репозиторий, сразу увидит слабые заметки. "Обрабатывает биллинг" — расплывчато. "Создаёт invoice, пишет запись биллинга, вызывает налоговый сервис" — гораздо понятнее.

Сохраните карту там, где её увидят до открытия кода. Положите рядом с начальной документацией репо, инструкциями для агентов или в чеклист ревью. Если вы используете AI‑помощь в GitLab или подобном потоке, раннее расположение помогает: и агент, и ревьюер читают одну и ту же карту до того, как изменения разойдутся по неправильным файлам.

Держите первую версию лаконичной. Если она помогает кому‑то выбрать нужный файл с первого раза — она уже полезна.

Простой пример из продуктовой команды

Команда получает задачу: изменить формулировку и время отправки писем со счётом. Звучит просто, но агенты часто блуждают, когда репозиторий не даёт карты. Они ищут "invoice", находят генерацию PDF, админские экраны, старые cron‑задачи и начинают править файлы, не относящиеся к потоку отправки писем.

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

Три короткие заметки достаточны:

• воркер биллинга отвечает за планирование и доставку писем по счетам
• папка шаблонов контролирует subject и тело письма
• аудит лог фиксирует попытки отправки и изменения статуса

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

Карта также говорит агенту, чего игнорировать. PDF‑код может упоминать инвойсы, но он только собирает вложение. Админские экраны показывают статус счета, но не отправляют письмо. Отметив эти области как не связанные, агент перестаёт догадываться и оставляет их нетронутыми.

Ревьюер сразу почувствует разницу. Вместо того чтобы открывать двадцать файлов из‑за слова "invoice", ревьюер проверит три файла и поймёт весь путь за минуту‑две. Это делает ревью с ИИ спокойнее: меньше шума, меньше откатов и меньше комментариев "почему это поменялось?".

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

Ошибки, которые тратят время на ревью

Команды часто думают, что документация готова, как только перечислены топ‑уровневые папки. Это редко помогает. Имя папки вроде services, core или utils почти ничего не говорит о содержимом, владельце или причине изменения.

Хорошая карта репозитория требует ещё один уровень смысла. Если в billing лежат правила инвойсов, обработчики вебхуков и логика ретраев — напишите об этом. Если api только экспонирует маршруты и не должен содержать бизнес‑логику — укажите это тоже.

Ещё одна распространённая ошибка — спрятать рискованные побочные эффекты в большой заметке типа misc или gotchas. Ревьюерам не стоит искать предложение, где сказано, что маленькая правка триггерит письма, инвалидирует кэш, пишет аудит или вызывает внешний API. Помещайте побочные эффекты рядом с модулем, который их вызывает.

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

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

Карта теряет ценность, если она устаревает после рефакторов. Если логика checkout переехала три месяца назад, а документ всё ещё указывает на старые файлы, люди перестают ей верить.

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

Если ревьюер может просканировать заметки за меньше чем минуту, ревью ускоряются, а агенты реже ошибаются.

Быстрые проверки перед передачей задачи агенту

Перед тем как давать задачу агенту, проверьте карту с тем, кто её не писал. Если человек не сможет проследить одну реальную фичу от экрана до хранилища за ~5 минут, карта всё ещё оставляет слишком много места для догадок.

Короткая карта должна быстро выявлять рискованные пути. Ревьюерам не нужно рыться в десяти папках, чтобы ответить на вопросы: "затрагивает ли это биллинг?" или "может ли изменение записать данные клиента?"

Простая проверка:

• Попросите нового коллегу проследить одну обычную фичу от начала до конца.
• Убедитесь, что пути по оплатам, авторизации и записям данных видны сразу.
• Каждая заметка должна называть реальный файл или директорию.
• Сравните карту с недавними рефакторами.
• Держите верхний слой коротким и добавляйте детали под владельцем модуля.

Допустим, агент получает задачу "исправить неудачные ретраи checkout'а". Ревьюер должен мгновенно найти точку входа checkout, ретраевый воркер, адаптер оплаты и путь записи заказа. Если карта указывает на старые имена файлов или прячет ретраевый воркер в общей заметке jobs, агент может залатать не тот файл, и ревьюеру придётся доказывать это вручную.

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

Если быстрая проверка провалилась — исправьте карту до того, как передавать задачу. Это обычно быстрее, чем править неверную правку позже.

Что делать дальше

Выберите один поток в продукте, который постоянно создаёт шумные PR. Логин, биллинг и фоновые задания — хорошие места для старта. Если ревьюеры часто спрашивают "почему файл поменялся?", начните с этого потока.

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

Затем внедрите это в повседневные привычки команды. Попросите автора проверить карту перед передачей задачи агенту. Попросите ревьюера сопоставить изменённые файлы с картой. Обновляйте карту, когда точки входа движутся или модуль получает новый побочный эффект. Если изменение кода меняет поведение рантайма — обновляйте карту в том же PR.

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

Будьте строги в одном правиле: если пути выполнения или побочные эффекты меняются, меняется и карта. Команды часто пропускают этот шаг, и документ вводит в заблуждение.

Если ваша команда часто использует ИИ‑инструменты и ревью всё ещё шумят, Oleg Sotnikov at oleg.is помогает стартапам и небольшим компаниям с AI‑первым процессом разработки, структурой репозиториев и процессами технического ревью. Краткий внешний аудит может помочь уплотнить карту и убрать паттерны, которые постоянно приводят к неверным правкам файлов.