Когда команда впервые запускает AI-агента внутри репозитория, почти всегда возникает одна и та же иллюзия: если дать модели доступ к коду, она сама во всём разберётся. На короткой демке это выглядит правдой. Агент находит файл, правит компонент, запускает тесты, пишет понятный summary. Но в живом проекте быстро выясняется, что кодовой базы недостаточно. В ней есть то, что уже сделано, но почти нет ответа на вопрос, почему именно так было решено и где команде нельзя импровизировать.
25 июня 2026 года Vercel подробно описала свой подход к этой проблеме: для агентов важен не только доступ к файлам, но и слой проектной памяти, который хранит продуктовые решения, правила и способы проверки. Это хорошая формулировка для всей индустрии. Сегодня проблема уже не в том, как «подключить AI», а в том, как сделать его предсказуемым участником процесса.
Почему одного доступа к коду агенту недостаточно
AI-агент хорошо читает структуру проекта. Он может увидеть папки, зависимости, существующие компоненты, тесты и даже стиль прошлых коммитов. Но почти любой серьёзный репозиторий содержит большой объём неявных правил. Почему в этом проекте нельзя тянуть новую библиотеку ради одной формы? Почему конкретный экран должен использовать только один паттерн навигации? Почему в этом сервисе ревью безопасности обязательно идёт раньше, чем UI-полировка? Ответы обычно живут не в коде, а в головах команды, в PR-комментариях, в документах и в многолетних компромиссах.
Из-за этого агент часто ошибается не на уровне синтаксиса, а на уровне смысла. Он может предложить технически рабочее решение, которое ломает внутренний договор команды. Например, добавит второй источник состояния, потому что так короче. Или проложит прямой вызов к сервису в обход общего клиента, потому что так проще пройти задачу. Формально код компилируется. По факту в проекте появляется новый слой хаоса.
Именно здесь начинается разговор о памяти проекта. Агенту нужна не просто видимость файлов, а доступ к причинам, ограничениям и критериям качества. Иначе каждое его действие превращается в угадайку с красивым интерфейсом.
AGENTS.md это входная дверь, а не вся память проекта
На Wikivibe уже был разбор того, зачем нужен AGENTS.md. Это важный первый шаг: файл действительно работает как контракт между проектом и агентом. Он помогает быстро объяснить стек, границы, правила редактирования и запреты, которые нельзя нарушать без отдельного согласования. Для нового проекта или для первой интеграции Codex этого часто достаточно, чтобы резко сократить количество случайных правок.
Проблема начинается, когда команда пытается уместить в один файл вообще всё. Через пару недель он превращается в длинную простыню: тут и правила по архитектуре, и запреты на библиотеки, и продуктовые решения, и куски дизайн-системы, и half-broken чеклисты, которые никто не обновляет. Агент читает такой документ как сплошной шум. Человек тоже.
Поэтому полезнее смотреть на AGENTS.md как на входную дверь. Он должен отвечать на три вопроса: какой это проект, по каким маршрутам агенту ходить за правилами и в каком режиме принимать решения. А сами правила лучше раскладывать глубже: по reference-файлам, по surface-specific инструкциям, по линтерам, по тестовым сценариям, по примерам уже принятых решений. Тогда у агента появляется не одна тяжёлая памятка, а понятная карта местности.
Из чего на практике состоит память проекта
Самый полезный взгляд на память проекта такой: это не документ, а система из нескольких слоёв, каждый из которых решает свою задачу.
Первый слой — правила и reference-файлы. Это то, что объясняет агенту, как команда думает о коде и продукте. Здесь живут архитектурные ограничения, naming conventions, границы между слоями, правила для UI-сценариев, требования по безопасности, описания допустимых паттернов. Важно, чтобы эти правила были не абстрактными, а наблюдаемыми. Не «пиши аккуратно», а «не добавляй новый state manager без согласования». Не «делай хороший UX», а «для двух-трёх фиксированных вариантов используй radio, а не select».
Второй слой — линтеры и автоматические проверки. Всё, что можно проверить детерминированно, лучше отдать машине. Если в команде нельзя использовать произвольные классы для темы кнопки, это должен ловить линтер, а не усталый ревьюер вечером в пятницу. Если модалки нельзя вкладывать друг в друга, это тоже должна фиксировать автоматическая проверка. Память проекта становится сильнее, когда часть правил не просто описана, а исполняется.
Третий слой — exemplars и anti-exemplars. Агентам очень полезно видеть не только абстрактное правило, но и пример решения, которое команда уже посчитала удачным. Это может быть PR, где хорошо реализован destructive flow, или экран, где грамотно устроена обработка ошибок. Рядом полезно хранить и плохие примеры: что уже ломало UX, что усложняло поддержку, какие решения пришлось откатывать.
Четвёртый слой — coverage gaps и evals. Если команда пока не знает, как именно стандартизировать часть интерфейса или процесса, лучше зафиксировать этот пробел явно, чем делать вид, что стандарта уже достаточно. Coverage gaps честно говорят агенту: здесь нельзя принимать слишком смелые решения. А evals позволяют проверить, меняется ли поведение агента после обновления правил. Это особенно важно, когда инструкция вроде бы стала лучше, а реальные правки в проекте не улучшились.
Как связаны MCP, инструменты и проектная память
На этом месте часто возникает путаница. Многие слышат про MCP и думают, что именно он решает проблему качества агентной работы. На самом деле MCP закрывает другую часть истории. Model Context Protocol нужен, чтобы модель могла стандартизированно подключаться к инструментам, данным и workflow: читать документацию, обращаться к CMS, открывать внутренние сервисы, искать артефакты, запускать безопасные действия.
Это очень важный слой, но он не заменяет память проекта. MCP может дать агенту доступ к дизайну, тикетам, базе знаний или CI. Но сам по себе он не отвечает на вопрос, как этими инструментами пользоваться в конкретной команде. Два проекта могут подключить один и тот же набор инструментов и получить абсолютно разное качество результата, потому что в одном месте у агента есть понятные правила принятия решений, а в другом — только право что-нибудь вызвать.
Проще говоря, MCP подводит к шкафу с инструментами. Память проекта объясняет, какой инструмент брать, в какой момент, кто потом проверяет результат и что считается ошибкой. Одно без другого даёт либо слепого исполнителя, либо хорошо информированного, но беспомощного теоретика.
Как собрать такую систему без бюрократии
Хорошая новость в том, что для старта не нужен отдельный комитет по агентной архитектуре. Начать можно с очень приземлённого вопроса: какие замечания команда пишет в ревью снова и снова? Если вы уже в третий раз объясняете, что в этом проекте нельзя обходить общий API-клиент, это и есть кандидат в память проекта. Если дизайнеры и разработчики регулярно спорят об одном и том же паттерне пустого состояния, значит правило ещё не упаковано туда, где агент сможет его прочитать.
Дальше полезно двигаться маленькими слоями. Сначала собрать короткий AGENTS.md, который маршрутизирует агента: где лежат архитектурные правила, где UI-ограничения, где security-ограничения, когда нужно просить человека. Потом вынести повторяющиеся решения в отдельные reference-файлы рядом с кодом. После этого посмотреть, что можно превратить в линтер или в тест. И только потом добавлять exemplars, anti-exemplars и evals, чтобы система не была набором деклараций без обратной связи.
Ещё один практичный приём — хранить правила максимально близко к месту применения. Не складывать всё в одну папку «docs about AI», а держать интерфейсные решения рядом с дизайн-системой, архитектурные рядом с backend-схемой, а ограничения по изменениям — в корневом маршрутизирующем файле. Тогда память проекта не выглядит как отдельный музей. Она становится частью рабочего репозитория.
Какие ошибки ломают агентный workflow чаще всего
Первая ошибка — вера в один волшебный файл. Команда пишет огромный AGENTS.md, забивает туда всё подряд и рассчитывает, что агент сам разберётся, какие пункты важнее. Обычно происходит обратное: полезный сигнал растворяется в тексте, а документ перестаёт поддерживаться уже через пару спринтов.
Вторая ошибка — неактуальные правила. Агент особенно опасен там, где инструкции расходятся с реальным кодом. Если документ говорит «используем только один способ логирования», а в репозитории уже три, модель не сможет понять, чему верить. Она начнёт мимикрировать под ближайший пример, а команда будет считать, что проблема в качестве модели, хотя проблема в противоречивом контексте.
Третья ошибка — попытка полностью автоматизировать продуктовые решения. Линтеры, skills и evals отлично работают на повторяемых правилах, но не заменяют инженерное и продуктовое суждение. Нельзя один раз формализовать всё важное и дальше выключить людей из процесса. Как только меняется продукт, меняются и правила. Поэтому память проекта должна быть живой системой с владельцами, а не архивом пожеланий.
Что получает команда в итоге
Если всё сделать правильно, эффект ощущается довольно быстро. Во-первых, падает количество странных AI-правок, которые вроде бы работают, но требуют длинного ручного разбора. Во-вторых, ревью становится короче и содержательнее: обсуждение смещается от базовых запретов к реальным trade-off'ам. В-третьих, сам агент начинает работать стабильнее. Не потому что модель внезапно «поумнела», а потому что у неё появились хорошие границы и качественная карта проекта.
Для VibeCode это, пожалуй, один из главных сдвигов 2026 года. Раньше мы обсуждали, какая модель пишет лучше. Теперь всё чаще приходится обсуждать, какой контекст получает агент и как команда кодирует собственные решения. Именно здесь рождается разница между демкой, которая впечатляет пять минут, и AI-воркфлоу, который выдерживает реальный продукт.
В сухом остатке правило простое: доступ к репозиторию даёт агенту глаза и руки. Память проекта даёт ему ориентиры. А инженерный процесс решает, во что это превратится — в полезного помощника или в ещё один источник дорогих сюрпризов.
Источник и полная версия: VibeCode Wiki