Дать AI-агенту доступ к репозиторию — это пять минут работы. Получить от него правки, которые не ломают проект — совсем другая задача. Между этими двумя состояниями помещается вся инженерная работа с агентными системами в 2026 году.

Проблема не в качестве модели. Проблема в том, что кодовая база показывает, что уже сделано, но почти не отвечает на вопрос, почему именно так и где нельзя импровизировать. Агент читает файлы, видит структуру, находит зависимости — и всё равно ошибается на уровне смысла. Не синтаксиса, а намерения.

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

Что это

Память проекта — это не документ. Это система из нескольких слоёв, каждый из которых решает свою задачу. Представьте, что вы объясняете новому разработчику, как тут всё устроено. Вы не даёте ему один файл на 50 страниц. Вы показываете, где лежат архитектурные правила, где UI-ограничения, какие проверки работают автоматически, а какие требуют человеческого глаза. С AI-агентом — та же логика, только файлы должны быть устроены чуть строже, потому что агент не умеет догадываться.

Корневой файл — обычно AGENTS.md — работает как маршрутизатор. Он отвечает на три вопроса: какой это проект, куда агенту идти за правилами и в каком режиме принимать решения. Всё остальное — reference-файлы, линтеры, примеры и тесты — живёт глубже, рядом с кодом, к которому относится.

MCP (Model Context Protocol — открытый протокол, через который модели подключаются к внешним инструментам и данным) часто путают с самой памятью проекта. На самом деле MCP даёт агенту доступ к инструментам: почитать документацию, открыть тикет, обратиться к базе знаний. Но он не объясняет, как этими инструментами пользоваться в конкретной команде. Два проекта подключат один и тот же набор через MCP — и получат разное качество, потому что у одного есть правила принятия решений, а у другого — только право что-нибудь вызвать.

Зачем нужно

Любой репозиторий, который живёт больше года, набит неявными правилами. Почему здесь нельзя тянуть новую библиотеку ради одной формы. Почему этот экран использует только один паттерн навигации. Почему ревью безопасности идёт раньше, чем UI-полировка. Эти правила живут в головах, в PR-комментариях, в Slack-тредах — везде, кроме кода.

Агент не видит этого фона. Он видит код и делает выводы. Иногда правильные. Иногда — технически рабочее решение, которое ломает внутренний договор команды. Добавляет второй источник состояния, потому что так короче. Прокладывает прямой вызов в обход общего клиента, потому что так проще пройти задачу. Формально компилируется. По факту — новый слой хаоса.

Память проекта закрывает этот разрыв. Она даёт агенту доступ к причинам, ограничениям и критериям качества. Не к файлам — к контексту, который стоит за этими файлами.

Как устроено

Четыре слоя, каждый со своей ролью.

Правила и reference-файлы

Слой, который объясняет агенту, как команда думает о коде и продукте. Архитектурные ограничения, naming conventions, границы между слоями, требования по безопасности, допустимые паттерны. Главное правило здесь — конкретика вместо абстракций. Не «пиши аккуратно», а «не добавляй новый state manager без согласования». Не «делай хороший UX», а «для двух-трёх фиксированных вариантов используй radio, а не select».

Линтеры и автоматические проверки

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

Примеры удачных и неудачных решений

Агенту полезно видеть не только абстрактное правило, но и конкретные случаи. PR, где хорошо реализован destructive flow. Экран, где грамотно устроена обработка ошибок. Рядом — плохие примеры: что ломало UX, что усложняло поддержку, какие решения пришлось откатывать. Этот слой — мост между правилом и реальностью.

Coverage gaps и evals

Если команда ещё не решила, как стандартизировать часть интерфейса или процесса — лучше зафиксировать этот пробел явно. Coverage gaps честно говорят агенту: здесь не принимай слишком смелых решений, стандарта пока нет. А evals (оценочные сценарии) позволяют проверить, реально ли улучшилось поведение агента после того, как вы обновили правила. Инструкция стала лучше — а правки в проекте? Evals отвечают на этот вопрос.

Инсайт: память проекта — не документ, а система. Правила объясняют, линтеры исполняют, примеры показывают, evals проверяют. Каждый слой решает свою задачу, и только вместе они работают.

Как связаны MCP, инструменты и проектная память

Путаница начинается с того, что MCP кажется решением проблемы качества. На самом деле он решает задачу доступа — стандартизованное подключение модели к инструментам, данным и workflow. Читать документацию, обращаться к CMS, открывать внутренние сервисы, искать артефакты, запускать безопасные действия.

Но сам по себе MCP не отвечает на вопрос, как всем этим пользоваться. Он подводит к шкафу с инструментами. Память проекта объясняет, какой инструмент брать, в какой момент, кто потом проверяет результат и что считается ошибкой. Без памяти проекта получается либо слепой исполнитель с доступом ко всему, либо хорошо информированный теоретик, который не знает, что именно здесь принято делать.

Когда использовать

Признаки, что агенту не хватает контекста:

  • Он делает технически корректные, но семантически неправильные правки — код работает, но ломает негласные правила команды
  • Команда раз за разом пишет одни и те же замечания в ревью — одно и то же объяснение в третий раз — кандидат в память проекта
  • AGENTS.md превратился в длинную простыню, которую никто не читает и не поддерживает
  • Правила в документах расходятся с реальным кодом — агент не понимает, чему верить, и начинает мимикрировать под ближайший пример

Как собрать такую систему без бюрократии

Не нужен комитет по агентной архитектуре. Достаточно приземлённого вопроса: какие замечания команда пишет в ревью снова и снова? Если в третий раз объясняете, что в проекте нельзя обходить общий API-клиент — это кандидат в память. Если дизайнеры и разработчики спорят об одном и том же паттерне пустого состояния — значит, правило ещё не упаковано.

Дальше — маленькими слоями, по мере накопления:

  • Шаг 1. Короткий AGENTS.md как маршрутизатор: где архитектурные правила, где UI-ограничения, где security, когда просить человека.
  • Шаг 2. Повторяющиеся решения вынести в reference-файлы рядом с кодом.
  • Шаг 3. Посмотреть, что можно превратить в линтер или в тест — что можно проверить детерминированно, уходит в автомат.
  • Шаг 4. Добавить exemplars, anti-exemplars и evals. Без них система остаётся набором деклараций без обратной связи.

Ещё один приём — хранить правила рядом с местом применения. Не складывать всё в папку «docs about AI», а держать интерфейсные решения у дизайн-системы, архитектурные — у backend-схемы, ограничения по изменениям — в корневом маршрутизаторе. Память проекта не должна быть музеем. Она — часть рабочего репозитория.

Пример

Так может выглядеть структура репозитория с многослойной памятью:

repository/
├── AGENTS.md                          # Маршрутизатор: какой проект, куда идти за правилами
├── .agents/
│   └── skills/
│       └── product-design/
│           ├── AGENTS.md              # Локальный контракт: порядок загрузки, валидация
│           ├── SKILL.md              # Runtime: режимы (shape/implement/review/copy/harden)
│           ├── references/
│           │   ├── product-judgment.md
│           │   ├── interface-quality.md
│           │   ├── resilience.md
│           │   ├── surfaces.md
│           │   ├── surfaces-{surface}.md
│           │   ├── copy.md
│           │   ├── rules.md
│           │   ├── glossary.md
│           │   ├── patterns.md
│           │   └── coverage-gaps.md  # Где стандартов пока нет
│           └── exemplars/
│               └── pr-{name}.md      # Удачные и неудачные примеры из реальных PR
└── tooling/
    └── scripts/
        └── evals/
            ├── fixtures.json          # Тестовые сценарии
            ├── rules-checklist.json   # Чеклист правил для автоматической проверки
            └── <fixture>/
                ├── before/
                └── after/

Корневой AGENTS.md говорит агенту, когда загружать skill. Локальный AGENTS.md внутри skill определяет порядок загрузки и валидацию. SKILL.md владеет runtime: сначала определяет режим запроса — shape, implement, review, copy или harden — затем маршрутизирует к нужным reference-файлам. Это не догма, а отправная точка: замените пути и стандарты на свои.

Ограничения

Ограничения

Что учитывать при внедрении.

Один файл — не система — AGENTS.md работает как входная дверь, но не заменяет многослойную память.

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

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

Память проекта требует поддержки, как и любой другой код.

Автоматизация не заменяет суждение — Линтеры, skills и evals работают на повторяемых правилах.

Они не заменяют инженерное и продуктовое суждение. Как только меняется продукт — меняются и правила.

Антипаттерны

Антипаттерны

Чего не делать.

Вера в волшебный файл — Огромный AGENTS.md со всеми правилами сразу.

Полезный сигнал растворяется в тексте, документ перестаёт поддерживаться через пару спринтов.

Неактуальные правила — Инструкции расходятся с реальным кодом.

Агент начинает мимикрировать под ближайший пример, а команда винит модель. Проблема не в модели — в противоречивом контексте.

Полная автоматизация продуктовых решений — Попытка один раз формализовать всё и выключить людей.

Память проекта должна быть живой системой с владельцами, а не архивом пожеланий.

Складывать всё в одну папку — Папка «docs about AI» отрывает правила от места применения.

Держите интерфейсные решения у дизайн-системы, архитектурные — у backend-схемы, ограничения — в корневом маршрутизаторе.

Чеклист

Чеклист

Проверка перед запуском.

AGENTS.md маршрутизирует, не дублирует — Корневой файл отвечает на три вопроса: какой проект, куда идти за правилами, в каком режиме принимать решения.

Сами правила — в reference-файлах.

Правила конкретные, не абстрактные — Не «пиши аккуратно», а «не добавляй новый state manager без согласования».

Не «хороший UX», а «для двух-трёх фиксированных вариантов — radio, а не select».

Что можно проверить — линтерится — Все детерминированные проверки уходят в автоматические линтеры.

Не в усталого ревьюера вечером в пятницу.

Есть exemplars и anti-exemplars — Хорошие и плохие примеры из реальных PR рядом с правилами.

Агент видит не только абстракцию, но и конкретные решения.

Coverage gaps зафиксированы — Где стандарта пока нет — явно отмечено.

Агент знает, что здесь нельзя принимать слишком смелые решения.

Evals запущены — Проверка, меняется ли поведение агента после обновления правил.

Инструкция стала лучше — а правки улучшились? Если нет — правило не работает.

Ссылки

Ссылки

По теме

По теме