# Ваш репозиторий обманывает AI-агентов: как это исправить до продакшена
Каноническая страница: https://plainews.ru/posts/podgotovit-repozitorij-k-ai-agentam
Опубликовано: 2026-08-18T07:01:09.615Z

Ваш репозиторий выглядит готовым к AI-разработке? Проверьте 7 ключевых аспектов владения, жизненного цикла и совместимости, чтобы избежать критических ошибок в продакшене.
Вы добавили 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-агентами