Представим вполне обычную задачу: требуется добавить поле в API.
Coding agent получает issue, изучает репозиторий и находит примерно такую картину:

repository/
├── README.md
├── docs/
│   └── architecture/
│       └── api.md
├── contracts/
│   └── api.yaml
├── src/
└── tests/

README.md отправляет разработчика в docs/architecture/api.md за описанием текущего API. Документ выглядит актуальным, потому что его регулярно обновляли вместе с кодом. В contracts/api.yaml тоже описан API. Файл живой, по Git history его периодически обновляют, но нигде явно не сказано, что это canonical contract. Agent читает документацию, меняет реализацию, обновляет api.md, добавляет тесты. Все тесты проходят.

Изменение выглядит хорошо.

Через некоторое время выясняется, что внешний SDK генерируется именно из contracts/api.yaml. Документация описывала API, но им не владела. Новое поле работает на сервере, но отсутствует в контракте, который использует потребитель.

Код правильный и тесты настоящие. Агент не галлюцинировал название файла и не проигнорировал очевидную инструкцию. Он просто сделал неправильные изменения на основании вполне правдоподобной картины репозитория. Вот этот класс ошибок в последнее время интересует меня гораздо больше, чем очередное сравнение качества генерации кода.

Неопределенность репозитория — это риск исполнения.

Здесь легко сказать: «просто добавьте нормальную документацию»

И это будет справедливое замечание. Можно также сказать, что хороший CI должен был проверить согласованность между реализацией и API контрактом.Тоже справедливо, но чтобы написать такой CI проверку, сперва надо знать, что api.yaml является canonical contract, а api.md, его описательным представлением. И конечно что внешний SDK сейчас активный потребитель контракта. Валидатор не может самостоятельно решить вопрос владения, он проверяет уже определённый сценарий. Такая же история с документацией. Можно написать:

contracts/api.yaml is the source of truth.

И во многих репозиториях этого действительно будет достаточно, но чем больше становится система, тем чаще вопрос уже не в отсутствии одной строки.

Что происходит, если roadmap живёт в Jira, часть release state — в Git, архитектурные решения — в ADR, сведения о совместимости — в манифестах, документация генерируется из нескольких источников, а часть старых артефактов всё ещё нужна одному потребителю?

Можно добавить всё это в AGENTS.md. Потом ещё немного. Потом ещё.
В какой‑то момент файл с инструкциями начинает описывать отдельную модель repository.
И возникает следующий вопрос:

а кто теперь следит, чтобы сама эта модель не разошлась с реальностью?

Я сам сначала шёл именно через иснтрукции

Это был очевидный путь. Ведь если agent неправильно работает с репозиторием, давайте дадим ему больше контекста. Так работают и основные coding‑agent среды.

OpenAI рекомендует использовать AGENTS.md, чтобы объяснить Codex, как ориентироваться в кодовой базе, какие команды запускать и какие практики соблюдать. GitHub Copilot поддерживает repository‑wide, path‑specific и agent instructions. Cursor Rules позволяют сохранять постоянный контекст проекта и workflows. Claude Code использует CLAUDE.md для project‑specific instructions, архитектурных конвенций и общих workflows.

Это хорошие механизмы. AIRepo не пытается их заменить.
Я просто постепенно пришёл к тому, что здесь смешиваются несколько разных задач.

Instructions
Как agent должен работать?

Repository_semantics
Чему здесь можно доверять?
Кто чем владеет?
Что current, historical или generated?
Какой consumer зависит от этого state?
Какое evidence действительно доказывает результат?

Runtime/policy
Что agent вообще имеет право сделать?

Если проблема в coding конвенциях, то скорее всего, нужен механизм инструкций. Если проблема в правах, то нужен runtime или policy boundary. Однако, если два артефакта выглядят authoritative и репозиторий не позволяет уверенно определить, какой из них действительно владеет решением, ещё одна инструкция лечит скорее симптом.

Меня заинтересовал именно этот средний слой.

Репозиторий перестаёт быть просто местом, где лежит код

Для человека репозиторий давно уже больше чем хранилище кода. Там живут схемы, ADR, документация, манифесты, миграции, сгенерированные артефакты, CI, конфиги, release notes и ссылки на внешние системы.

Для coding agent это ещё важнее. Agent использует репозиторий не просто как источник текста для генерации, а чтобы принимать решения.

• Какой файл открыть;

• что считать current;

• что изменить;

• что не трогать;

• как проверить результат;

• можно ли сделать вывод, что задача завершена.

Получается, что репозитрий становится частью среды исполнения и неоднозначность начинает иметь вполне ощутимые последствия. В AIRepo я выделяю несколько повторяющихся классов таких проблем:

Само расположение файла ответа не даёт.

Папка contracts/ не делает файл authoritative.
Папка generated/ не является надёжной lifecycle model.

А наличие CI run ещё не означает, что он доказывает именно тот state, о котором мы сейчас говорим.

Это один из базовых принципов AIRepo: semantic responsibility и ownership должны определяться раньше физического расположения; доказательство само по себе не превращается в authority.

Так из этой проблемы вырос AIRepo

Я не начинал с идеи создать framework для «правильной структуры репозитория». Скорее наоборот. В работе над AI‑centred системами мне снова и снова приходилось отвечать на одни и те же вопросы:

• Какой источник здесь authoritative;

• можно ли agent доверять найденному артефакту;

• что сгенерировано;
  какой потребитель ещё существует;

• какое доказательство достаточно;

• имеет ли agent право перейти от finding к mutation;

• и не создаём ли мы ради всего этого ещё один слой governance, который потом сами будем обслуживать.

Постепенно эти вопросы сложились в AIRepo — The AI‑Ready Repository Framework.

AIRepo — open, provider‑neutral repository assessment and design framework for human‑AI engineering.

Текущая публичная версия 1.0.0, Apache-2.0. Он не задаёт универсальное дерево директорий, не является agent runtime или платформой оркестрации и не заменяет architecture/governance конкретного проекта.

Мне здесь важна именно формулировка assessment and design.

AI‑ready repository для меня это не репозиторий, в который добавили специальную папку для AI. А скорее репозиторий, где для существенного набора активностей можно достаточно надёжно разрешить отношения между authority, ownership, lifecycle, consumers, provenance и evidence.

Физически два таких repositories могут выглядеть совершенно по‑разному. Я это проверил и это нормально.

Как это выглядит на практике

Возьмём исходную задачу с API. AIRepo assessment начинается не с:

Какие папки здесь неправильные?

И даже не с:

Есть ли здесь AGENTS.md?

Сначала фиксируется subject. Например:

Изменение public API контракта для конкретной ревизии репозитория.

Дальше ищутся только material assets и active consumers, которые действительно относятся к этому subject. Для нашего случая может выясниться:

contracts/api.yaml
    canonical API contract
            │
            ├──> SDK generation
            ├──> compatibility validation
            └──> docs/api.md
                    descriptive documentation

Теперь у проблемы появилась форма и нам уже не нужно говорить агенту:

Будь осторожнее.

Можно проверить конкретные отношения.

AIRepo Quick Start предлагает сначала зафиксировать exact subject и evidence snapshot, затем определить active consumers и material assets, классифицировать authority/SoR/lifecycle/generated state, разрешить применимость требований, получить недостающее evidence read‑only, а исправления проектировать только после этого.

Это важно ещё по одной причине.

Assessment сам по себе не даёт права что‑либо менять.
Агент может обнаружить authority conflict и предложить исправления, но все же finding не превращается автоматически в approval.

В framework эта граница намеренная: AI может inspect, classify, research и validate, но не должен сам выводить из этого право изменить project authority или выполнить consequential remediation. Для агентской разработки, на мой взгляд, это одна из наиболее недооценённых границ.

А теперь самое интересное: как исправить наш репозиторий?

Можно сделать красиво. Добавить:

repository-authority.yaml
artifact-registry.yaml
lifecycle-manifest.yaml
repository-validator/

После чего проблема одного API контракта превратится в поддержку ещё четырёх сущностей. Это именно тот результат, которого я не хочу от AIRepo. Если failure mode можно устранить так:

contracts/api.yaml
    canonical contract
    consumed by SDK generation

docs/architecture/api.md
    descriptive documentation
    references canonical contract

плюс добавить существующему CI проверку согласованности контрактов, то возможно, на этом стоит остановиться.

Framework прямо требует перед новым registry, manifest, validator, workflow или System of Record показать реальный active consumer или reproducible failure mode, объяснить, почему существующие механизмы недостаточны, и проверить менее необратимую альтернативу. То есть цель не: сделать repository максимально governed. А:

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

Иногда это требует архитектурного изменения.
Иногда одного прямого указания.
Иногда удаления устаревшей документации.
А иногда assessment заканчивается выводом:

Ничего менять не нужно.

Для framework про governance это, на мой взгляд, здоровый результат.

Но authority, это только половина проблемы

Есть ещё один failure mode, который мне кажется даже более неприятным.

Agent сделал изменение на commit A. CI прошёл. Потом branch rebased. Появился commit B. В PR по‑прежнему виден зелёный run. Код может даже остаться практически тем же. И возникает фраза:

Current implementation validated.

Но что именно validated? CI evidence относится к A. Claim уже относится к B. Факт «tests passed» настоящий. Просто он доказывает другой subject. Поэтому модель валидации в AIRepo строится не вокруг бинарного: CI = green, а вокруг связи:

requirement → applicability → verification intent → concrete evidence → exact subject → result → verdict

• Если доказательство отсутствует, устарело или неоднозначно, framework предлагает сначала read‑only acquisition.

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

Это не означает, что любой commit должен проходить бюрократический процесс сертификации. Наоборот: consumer validation должна быть целенаправленной на затронутые контракты и failure modes, а не участвующие потребители не требуют новой проверки. Именно здесь для меня сходятся две вещи, которые часто обсуждаются отдельно:

скорость агентской разработки и качество доказательств принятых решений.

Чем больше действий выполняется автоматически, тем меньше нас должен устраивать вывод уровня:

вроде всё зелёное.

Что именно AIRepo считает AI‑ready

Не наличие конкретного файла, количество metadata или отдельный AI layer.
Я бы сформулировал это так.

Репозиторий становится более готовым к human‑AI engineering, когда исполнитель может с приемлемой уверенностью определить:

• что является authoritative state;

• кто им владеет;

• какие производные представления;

• какой у них lifecycle;

• кто реально потребляет изменение;

• какая ревизия рассматривается;

• какое доказательство доказывает результат;

• и где заканчивается его собственное право на действие.

AIRepo формализует эти вопросы через десять semantic owners и набор стабильных rules, но начинать с их изучения я бы не советовал. Framework полезнее проверять от реальной инженерной задачи, а не читать как стандарт сверху вниз.

Что уже проверено, а что пока нет

Здесь я специально хочу оставить границу достаточно жёсткой.

AIRepo 1.0.0 — первый public stable release.

Его pre‑public lineage проходила семантическую проверку, deterministic projection/staleness validation, ограниченную проверку выполнения, проверку на двух независимых потребительских сценариях и независимую оценку квалификации перед публичной сборкой. Это зафиксировано в release manifest и provenance framework.

Для меня это позволяет утверждать, что framework развивался через практическое применение и итеративную проверку, а не только как кабинетная модель. Но это не означает: industry standard, enterprise proven, widely adopted, market validated, guaranteed safe autonomous AI.

Таких доказательств сейчас нет, и я не вижу смысла делать вид, что они есть. Stable release говорит о состоянии самого framework, а не о зрелости рынка вокруг него. Следующий полезный источник доказательств уже независимое применение и критика, в том числе критика самого подхода.

Где я бы вообще не использовал AIRepo

Если репозиторий небольшой, одна команда владеет практически всем, source of truth очевиден, generated state минимален, а change path легко объяснить новому разработчику, то полноценный framework assessment может ничего не добавить.

Если проблема звучит:

Агент пишет код не в нашем стиле.

Я бы сначала использовал AGENTS.md, CLAUDE.md, Copilot instructions или Cursor Rules.

Если проблема:

Агент не должен иметь доступ к записи на проде.

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

Агент сделал разумное изменение, но выбрал неправильную authority.

Или:

У нас три источника, и даже команда не сразу может объяснить, какой из них canonical.

Или:

Доказательство есть, но мы не уверены, какую ревизию оно действительно доказывает.

В этот момент проблема уже не сводится к prompt engineering.

Простейший тест для своего repository

Я опубликовал AIRepo как open‑source framework и сделал отдельный Quick Start. Сам framework и Quick Start доступны в публичном репозитории, но для первого теста framework вообще можно не внедрять.

Возьмите одну задачу из вашего беклога. Не идеальный архитектурный пример, обычную задачу, которую завтра можно отдать coding agent. И попробуйте без устных пояснений команды определить:

• к чему именно agent должен обратиться за authoritative state;

• кто этим состоянием владеет;

• что он имеет право изменить;

• какие потребители будут затронуты;

• и какое доказательство позволит сказать, что изменение действительно завершено.

Если ответы очевидны, то это отлично. Не нужно добавлять «AI‑ready» структуру ради самого значка. Если в какой‑то момент появляется фраза:

Тут вообще‑то надо знать, что…

вот это место я бы и исследовал первым. Потому что возможности coding agents продолжают расти, но более сильный исполнитель не автоматически делает систему исполнения надёжнее. Зачастую наоборот: он просто быстрее действует на основании неоднозначной картины и поэтому вопрос, который мне сейчас кажется интереснее «может ли AI написать этот код?» звучит немного иначе:

«может ли наша среда достаточно надёжно объяснить человеку или AI, какое изменение здесь вообще является правильным?»

Именно на этот вопрос я и пытаюсь ответить с помощью AIRepo.