Если вы действительно поручаете реальные задачи ИИ-агентам, то структура вашего репозитория важна не меньше, чем выбранная модель. Вам необходимы четкая архитектура, строгая типизация, хорошие тесты и лаконичный файл AGENTS.md, чтобы дать агентам контекст, который они не могут почерпнуть из кода. В этой статье объясняется, как построить этот фундамент, и в заключение предлагается 90-дневный план для CTO.
Основные выводы
- Агентам требуется машино-верифицируемая обратная связь, а не просто читаемый для человека код.
- Короткий файл AGENTS.md описывает намерения, зоны ответственности и ограничения, которые код не может продемонстрировать.
- Небольшие коммиты, ограниченные права доступа и развертывания под контролем человека обеспечивают безопасность результатов работы ИИ.
- Проверка человеком смещается с синтаксиса на архитектуру.
- Монорепозитории предоставляют агентам целостное представление, которое им необходимо.
Почему традиционные кодовые базы не подходят для ИИ-агентов
Искусственный интеллект в разработке программного обеспечения уже давно вышел далеко за рамки автодополнения кода «на лету». Теперь команды поручают реальные задачи агентам (Claude Code, Augment Code, GitHub Copilot и др.) для создания набросков функций, рефакторинга сервисов и поиска багов. Проблема, с которой они при этом сталкиваются, заключается в том, что в большинстве кодовых баз автономным инструментам очень сложно ориентироваться.
На протяжении десятилетий репозитории строились вокруг человеческих привычек: неявных архитектурных решений, разделяемых знаний и племенной памяти. Агент не может подойти к коллеге и спросить, активен ли еще устаревший сервис. Попав в кодовую базу, полную скрытых предположений, он будет угадывать, тратить токены контекста и копировать плохие существующие паттерны, увеличивая технический долг.
Сегодня преимущество заключается не в том, на какую модель вы подписаны. Оно заключается в том, насколько понятно ваша кодовая база преподносит себя машине.
Что делает кодовую базу готовой к работе с агентами: верификация, границы и архитектура
Речь идет о переходе от «читаемого человеком» к «верифицируемому машиной» и определении с самого начала того, к чему агенту разрешено прикасаться (какие репозитории, какие ветки, какие окружения).
Агенты работают в замкнутом цикле: исследование, планирование, написание кода, верификация. Если вы пропустите верификацию или положитесь на ненадежную верификацию, агент решит, что тишина означает успех, и выпустит сломанную логику. Успешно пройденные тесты не означают, что код безопасен или каким-либо образом соответствует вашим стандартам, поэтому агентам необходимы три вещи:
- Четкие границы. Строгая статическая типизация и агрессивный линтинг удерживают его в строгих рамках реальности.
- Быстрая и явная обратная связь. Ваш CI/CD-пайплайн должен запускать тесты, линтинг, проверку типов, сканирование безопасности и завершаться сбоем очень заметным образом, чтобы агент мог самостоятельно исправить проблемы.
- Надежные тесты. Модульные тесты охватывают изолированное поведение, а сквозные (end-to-end) тесты защищают ключевые пользовательские сценарии.
Архитектура также имеет значение. В бэкенде на .NET 10 вы бы использовали архитектуру вертикальных срезов (vertical slice architecture, используя что-то вроде FastEndpoints). В результате каждый маршрут API является самодостаточным, и агент может понять функцию, не загружая половину кодовой базы. Добавьте трассировку OpenTelemetry, и вы получите очень четкие сигналы по мере выполнения кода. Четкие границы между вашей доменной логикой и инфраструктурой служат картой и очень сильно помогают новым разработчикам.
AGENTS.md: передаем агентам контекст, которого нет в вашем коде
AGENTS.md — это файл README для машин. Это важно, потому что помещение гигантского системного промпта в репозиторий загромождает окно контекста, снижает качество результатов и увеличивает затраты на токены.
Держите файл коротким и используйте его только для того, что код не может раскрыть. Оставьте форматирование и стиль детерминированным инструментам, таким как .editorconfig. Хороший файл AGENTS.md отвечает на следующие вопросы:
- Какова бизнес-цель этой области?
- Кто владеет ею и что агент может изменить?
- Какие внешние API находятся под запретом?
- Как запустить локальные зависимости для интеграционных прогонов?
- Какие переменные окружения и флаги функций влияют на поведение?
Используйте прогрессивное раскрытие информации: делайте файл верхнего уровня кратко и ссылайтесь на более глубокую документацию по конкретным фреймворкам, архитектурным решениям и отдельным сервисам. Поскольку этот файл находится в репозитории, он версионируется вместе с кодом и предоставляет каждому ИИ-инструменту единую точку входа.
Как обеспечить безопасность кода, сгенерированного ИИ?
Агент может затронуть десятки файлов за один проход. Три правила помогают держать это под контролем:
- Требуйте атомарных коммитов. Просите агентов делать небольшие изменения под одну конкретную задачу, причем реализация, тесты и обновления документации должны находиться в одном PR. Когда появляется регрессия, git bisect находит причину без необходимости просеивать сотни не связанных между собой строк.
- Ограничивайте права доступа. Ограничивайте агентов определенными ветками и определяйте, что им разрешено создавать или изменять.
- Контролируйте продакшн. Агенты отлично умеют писать код на Bicep или Terraform наряду с кодом приложений, но выполнение релизов должно требовать явного одобрения человека. Это защищает рабочие окружения от не верифицированных изменений и утечки секретов.
Также помните, что модели могут предлагать устаревшие API или неактуальные паттерны, что является еще одной причиной полагаться на автоматические проверки.
Оценка зрелости AI-SDLC
Пройдите оценку!
ИИ не отменяет код-ревью. Он переносит его туда, где люди приносят наибольшую пользу.
Линтеры и автоматизированные проверки теперь ловят проблемы с форматированием, именованием и отсутствием проверки на null до того, как пул-реквест попадет к ревьюеру. Это оставляет инженерам задачу оценивать архитектурное соответствие, согласованность с предметной областью и безопасность. Например, агент может легко написать запросы для Azure Cosmos DB, но человек должен решить, выдержит ли ключ разделения реальную нагрузку. Люди также привносят контекст продакшна и организации, которого нет у агентов.
Проверка архитектуры вместо синтаксиса также является наиболее эффективным средством от усталости от ревью.
Монорепозитории против полирепозиториев: почему монорепозитории дают агентам полную картину
Монорепозиторий или полирепозиторий раньше были вопросом организационных предпочтений. С появлением ИИ-агентов чаша весов сильно склоняется в сторону монорепозиториев, поскольку агент может рассуждать только о том, что помещается в его окно контекста.
В полирепозитории изменение схемы, затрагивающее несколько сервисов, заставляет агента переключаться между репозиториями, собирать частичный контекст и координировать правки изолированно. Это приводит к потере контекста, большему использованию токенов и хрупким обновлениям. Семантический поиск помогает, но агентам по-прежнему необходима четкая структура и область видимости.
В монорепозитории агент может проследить запрос от UI-компонента Blazor через сервисы приложения до уровня данных и обновить все в рамках одного PR. В любом случае сохраняйте модульные границы, так как общие контракты все равно могут незаметно ломать сервисы. Для больших монорепозиториев давайте агентам описания задач с четкими шагами, чтобы они следовали по целевым путям, не исчерпывая лимиты токенов.
90-дневный план перехода к репозиторию, готовому к агентам
Переход к дружественности к агентам — это осознанный процесс: обновление инструментов, усиление верификации и документирование институциональных знаний.
- Добавьте структурированный AGENTS.md в основные репозитории.
- Стандартизируйте линтеры и включите строгую проверку типов.
- Создайте машиночитаемую базу знаний, охватывающую владение, архитектурные решения, бизнес-правила, сущности и системных участников.
- Задокументируйте переменные окружения, стандартные команды и этапы настройки.
- Устраните нестабильные тесты, которые дают агентам ложные сигналы.
- Установите целевые показатели покрытия для критических путей (например, 80%) и добавьте сквозные тесты для пользовательских сценариев.
- Создайте собственные ИИ-навыки и команды для повторяющегося шаблонного кода.
- Ускорьте CI/CD, чтобы агенты получали быстрые результаты сборки и тестирования.
- Оцените, могут ли агенты исправлять сбои без ручной помощи.
- Изучите структуру репозитория, объединив полирепозитории в монорепозиторий там, где важен контекст нескольких сервисов.
- Предоставьте изолированные, эфемерные среды для тестирования агентов.
- Сохраняйте развертывание в продакшен под контролем человека.
Это не разовый проект. По мере совершенствования моделей и увеличения контекстных окон ваши соглашения о репозитории и файл AGENTS.md потребуют регулярной доработки. Успешные команды не будут гоняться за трюками с промптами. Они создадут документацию, тесты и соглашения, которые работают со многими инструментами ИИ, чтобы инженеры и агенты могли эффективно сотруднировать.
Инструменты программирования на базе ИИ хороши ровно настолько, насколько хорош репозиторий, в котором они работают. Хороший репозиторий имеет четкую архитектуру, хорошую типизацию, хорошие тесты и лаконичный файл AGENTS.md. Это дает агенту нужный контекст для поиска, изменения и проверки кода без необходимости гадать. Надежные защитные механизмы (атомарные коммиты, ограниченные разрешения, развертывания под контролем человека) позволяют двигаться быстро без потери контроля, а рецензенты-люди могут сосредоточиться на принятии реальных решений.
Вам не нужно делать все сразу. Начните с AGENTS.md и линтеров, затем поработайте над тестами и циклами обратной связи, и только после этого возвращайтесь к структуре репозитория. Каждый из этих шагов делает кодовую базу более удобной для работы агентов и новых разработчиков.
