☕️ Команда, два репо (фронт и бэк), три разных агента: как не утонуть в хаосе

Пытаемся настроить совместную разработку с AI-агентами — для команды, где у каждого свой инструмент: кто на Claude Code, кто на Codex, кто на Cursor. Два репозитория, фронт и бэк. Задача — чтобы агенты хорошо навигировались по коду, писали правильно с первого раза и жгли минимум токенов.

Минимальный джентельменский

— AGENTS.md как единый источник правды. Это «README для агентов», открытый стандарт, который читают Codex, Cursor, Copilot и другие. Claude Code исторически читает CLAUDE.md, но его легко подружить через одну строчку @AGENTS.md. Правило: один файл, всё остальное на него только ссылается. Никаких четырёх копий инструкций, которые неизбежно разойдутся.

— Короткий файл вместо энциклопедии. Раздутый AGENTS.md работает хуже короткого: LLM игнорирует половину, Codex вообще обрезает по лимиту. Держите до 150–200 строк. Архитектуру выносите в docs/ — агент подгрузит, когда понадобится.

— Навигируемая структура. На реальной кодовой базе агент тратит большую часть токенов не на написание кода, а на попытки его понять. Имя файла должно честно говорить, что внутри: booking.repository.ts лучше, чем utils/data.ts. Грамотный context engineering снижает расход токенов в 5–6 раз на одной и той же задаче.

— Contract-first для фронта и бэка. Договоритесь о формате данных до того, как писать код. Контракт API (файл openapi.yaml) — это список: какие запросы есть, какие поля приходят в ответ и какого они типа. Сначала команда фиксирует этот список, и только потом фронт и бэк пишут код — каждый под него. Из контракта автоматически собираются типы (фронт сразу знает структуру ответа), заглушки-моки (фронт работает, пока бэка ещё нет) и тесты, которые проверяют, что код не разошёлся с договорённостью. Бонус для агента: он не сможет обратиться к полю, которого нет в контракте, — среда подсветит ошибку сразу.

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

С чего начать
— завести AGENTS.md в корне каждого репо — руками, коротко
— связать CLAUDE.md и правила Cursor через симлинк или @-импорт
— вынести контракт API в отдельный репо, запретить править сгенерированный код
— для параллельной работы — worktrees, изолировать БД и порты

И принцип, который держит всё живым:

Каждая ошибка, которую агент совершил дважды, должна превратиться в строчку AGENTS.md или в проверку в CI.

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


#agents #claude #vibecoding #tips