Вы добавили AGENTS.md, настроили Cursor Rules и запустили coding agent в репозиторий. Тесты прошли, код выглядит чисто — но через неделю выясняется, что внешний SDK использует не тот контракт, который изменил агент. Проблема не в генерации кода, а в том, что репозиторий содержит противоречивые сигналы о владении и статусе артефактов.

AI-агенты принимают решения на основе структуры репозитория, и если она неоднозначна, даже идеально написанный код может сломать продакшен. Разберём, как проверить репозиторий на готовность к AI-разработке и исправить критические проблемы до того, как агент начнёт вносить изменения.

Почему AGENTS.md и инструкции не решают проблему

Документация для агентов — необходимый, но недостаточный шаг. Инструкции в AGENTS.md, Cursor Rules или CLAUDE.md объясняют агенту, как работать с кодом, но не отвечают на ключевые вопросы:

• Какой файл является источником истины для API-контракта?
• Кто активный потребитель этого контракта?
• Является ли документация производной или самостоятельным артефактом?
• Можно ли доверять CI-проверке для конкретного изменения?

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

7 проверок репозитория на готовность к AI-агентам

1. Authority: кто владеет решением?

Проблема: Агент видит два файла с описанием API — docs/architecture/api.md и contracts/api.yaml. Оба выглядят актуальными, но только один является источником истины (canonical source). Без явного указания агент выберет неверный файл.

Как проверить:

• Найдите все артефакты, описывающие одно и то же (API, схемы, конфиги).
• Проверьте, есть ли явное указание на владение в:
• README или AGENTS.md (contracts/api.yaml is the source of truth for API contracts).
• Комментариях в коде (// Generated from contracts/api.yaml, do not edit manually).
• CI-скриптах (например, генерация SDK из конкретного файла).
• Если указания нет — добавьте его в AGENTS.md и в сам артефакт.

Пример: ```markdown <!-- AGENTS.md -->

API Contracts

```

• Source of truth: contracts/api.yaml (OpenAPI 3.1).
• Derived artifacts:
• docs/architecture/api.md (human-readable docs, generated via make docs).
• src/api/schema.ts (TypeScript types, generated via make generate).
• Active consumers:
• External SDK (generated from contracts/api.yaml).
• Frontend (uses src/api/schema.ts).

2. Ownership: где canonical state?

Проблема: Агент обновляет документацию, но не знает, что она генерируется из другого файла. Изменения теряются при следующей сборке.

Как проверить:

• Определите, какие артефакты являются источниками (source), а какие — производными (derived).
• Для производных артефактов добавьте:
• Комментарий с указанием на источник (// Generated from contracts/api.yaml. Do not edit.).
• CI-скрипт, который перегенерирует артефакт при изменении источника.

Пример CI-проверки (GitHub Actions): ```yaml

.github/workflows/check-api-consistency.yml

name: Check API consistency on: [push, pull_request]

jobs: check: runs-on: ubuntu-latest steps:

run: | make generate-docs # Генерирует docs/architecture/api.md из contracts/api.yaml if ! git diff --quiet docs/architecture/api.md; then echo "::error::Docs are out of sync with API contract. Run 'make generate-docs'." exit 1 fi ```

• uses: actions/checkout@v4
• name: Verify docs are in sync with contract

3. Lifecycle: активен ли артефакт?

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

Как проверить:

• Пометьте артефакты статусами:
• active (используется сейчас).
• historical (сохранён для совместимости, не изменять).
• deprecated (устарел, будет удалён).
• transitional (временный, например, миграционные скрипты).
• Добавьте статус в имя файла или в комментарий.

Пример: ```markdown <!-- contracts/api_v1.yaml -->

DEPRECATED: Use api_v2.yaml. Kept for backward compatibility until 2026-12-31.

Do not modify.

```

4. Provenance: откуда взялся артефакт?

Проблема: Агент не знает, что файл сгенерирован из другого репозитория или стороннего инструмента. Пытается изменить его напрямую.

Как проверить:

• Для сгенерированных артефактов добавьте:
• Комментарий с указанием на источник (// Generated by protobuf. Source: github.com/org/proto-repo).
• CI-скрипт, который проверяет, что артефакт не изменён вручную.

Пример: ```python

src/generated/models.py

Generated by protobuf v3.20.1 from github.com/org/proto-repo/models.proto.

Do not edit manually. Regenerate via make generate-models.

```

5. Compatibility: кто зависит от артефакта?

Проблема: Агент изменяет API-контракт, но не знает, что его использует внешний SDK. Изменение ломает интеграцию.

Как проверить:

• Составьте список активных потребителей для каждого ключевого артефакта (API, схемы, конфиги).
• Добавьте список в AGENTS.md или в комментарий к артефакту.
• Настройте CI-проверку на совместимость (например, запуск тестов внешнего SDK при изменении контракта).

Пример: ```markdown <!-- AGENTS.md -->

External Dependencies

```

• contracts/api.yaml:
• External SDK (generated via make generate-sdk).
• Frontend (uses TypeScript types from src/api/schema.ts).
• Monitoring (uses OpenAPI spec for health checks).

6. Validation: что доказывает корректность?

Проблема: Агент считает задачу выполненной, потому что прошли тесты, но тесты не проверяют критические аспекты (например, совместимость с внешним SDK).

Как проверить:

• Для каждого артефакта определите, что действительно доказывает его корректность.
• Добавьте CI-проверки, которые покрывают эти аспекты.

Пример: ```yaml

.github/workflows/validate-api.yml

name: Validate API changes on: pull_request: paths:

• 'contracts/api.yaml'
• 'src/api/**'

jobs: validate: runs-on: ubuntu-latest steps:

run: make test-api

run: | make generate-sdk cd external-sdk && npm test ```

• uses: actions/checkout@v4
• name: Run API tests
• name: Verify external SDK compatibility

7. Mutation boundary: кто имеет право изменять?

Проблема: Агент изменяет файл, который должен обновляться только через определённый процесс (например, миграционные скрипты).

Как проверить:

• Определите, какие артефакты можно изменять напрямую, а какие — только через CI или специальные команды.
• Добавьте ограничения в AGENTS.md и CI.

Пример: ```markdown <!-- AGENTS.md -->

Mutation Rules

```

• contracts/api.yaml: Can be modified directly, but changes must pass:
• make test-api (API tests).
• make generate-sdk (SDK generation).
• External SDK tests (see .github/workflows/validate-api.yml).
• src/migrations/:
• Do not modify manually. Use make generate-migration to create new migrations.
• All changes must pass make test-migrations.

Где это ломается

1. Противоречивые сигналы: Если в репозитории есть два артефакта с одинаковым статусом (например, два "источника истины" для API), агент выберет неверный. Решение — явное указание на владение в AGENTS.md и CI-проверки.
2. Сгенерированные артефакты: Агент может изменить файл, который перезаписывается при сборке. Решение — пометки в коде и CI-проверки на ручные изменения.
3. Устаревшие артефакты: Агент тратит время на изменение deprecated-файлов. Решение — явные статусы (DEPRECATED, HISTORICAL) и удаление из индекса агентов.
4. Внешние зависимости: Агент не знает, что изменение контракта ломает внешний SDK. Решение — список потребителей в AGENTS.md и CI-проверки на совместимость.

Что попробовать дальше

1. AIRepo: Фреймворк для организации репозиториев с явными границами владения и статусов. Поддерживает проверки на authority, lifecycle и provenance. GitHub.
2. GitHub Repository Rules: Настройте правила для защиты ключевых файлов от прямых изменений (например, contracts/api.yaml можно изменять только через PR с определёнными проверками).
3. Dependabot для внутренних зависимостей: Настройте Dependabot для отслеживания изменений во внутренних контрактах (например, если contracts/api.yaml используется в другом репозитории).
4. Семантическое версионирование для артефактов: Используйте теги v1, v2 для контрактов и схем, чтобы агенты могли определить, какие версии активны.

Источники

• Habr AI: AIRepo: как проверить, готов ли ваш репозиторий к работе с AI-агентами