Проблема семантической неопределенности

Современные ИИ-агенты часто совершают ошибки не из-за галлюцинаций, а из-за неоднозначности структуры репозитория. Например, агент может обновить документацию, но пропустить файл контракта, из которого генерируется внешний SDK, просто потому что в коде не указано, какой из файлов является первоисточником (canonical contract). Для агента репозиторий — это не просто хранилище текста, а среда исполнения, где каждое решение зависит от понимания того, какому артефакту можно доверять.

Существующие инструменты, такие как AGENTS.md в OpenAI, Cursor Rules или CLAUDE.md, помогают задать инструкции для агента, но они лишь лечат симптомы. Если в репозитории неясно, какой файл является актуальным, а какой — устаревшим или вспомогательным, даже самые точные инструкции не спасут от ошибок в логике изменений.

Что такое AIRepo

AIRepo (The AI-Ready Repository Framework) — это открытый фреймворк (версия 1.0.0, лицензия Apache-2.0), предназначенный для оценки и проектирования репозиториев. Он не навязывает жесткую структуру папок и не является платформой для оркестрации. Его задача — помочь разработчикам разрешить отношения между авторитетностью (authority), владением (ownership), жизненным циклом (lifecycle) и потребителями (consumers) артефактов.

Вместо того чтобы просто добавлять новые файлы инструкций, AIRepo предлагает сосредоточиться на трех ключевых аспектах:

  • Семантическая ответственность: определение того, какой артефакт действительно определяет решение.
  • Жизненный цикл: четкое разграничение между активными, историческими и сгенерированными данными.
  • Связь доказательств: проверка того, что результаты тестов или CI действительно относятся к текущему состоянию кода, а не к предыдущим коммитам.

Подход к внедрению

Фреймворк не стремится к максимальному бюрократическому контролю. Его цель — убрать ровно столько неоднозначности, сколько необходимо для принятия агентом правильного решения. Процесс оценки (assessment) начинается с фиксации конкретного объекта и его доказательств, определения активных потребителей и классификации состояния артефактов.

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