AI-агент Manus проходит тесты, но ломает SDK: почему инструкции не решают проблему

Эту категорию ошибок описал автор открытого фреймворка AIRepo, опубликованного под лицензией Apache-2.0 (версия 1.0.0). Его наблюдение выросло из практики: ни один из популярных механизмов инструкций для ИИ-агентов, будь то AGENTS.md у OpenAI Codex, Cursor Rules, CLAUDE.md у Claude Code или инструкции GitHub Copilot, не решает проблему семантической неопределённости репозитория. Они объясняют агенту, как работать, но не отвечают на вопрос, чему доверять.

Почему ИИ-агент ошибается на ровном месте?

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

• docs/architecture/api.md выглядит актуальным, его регулярно обновляют вместе с кодом
• contracts/api.yaml тоже живой, в Git-истории видны свежие правки

Нигде явно не указано, что api.yaml является каноническим контрактом (canonical contract, единственный файл, из которого генерируется внешний SDK). Агент читает документацию, меняет реализацию, обновляет api.md, добавляет тесты. Все тесты проходят.

Через некоторое время выясняется: внешний SDK генерируется именно из api.yaml. Новое поле работает на сервере, но отсутствует в контракте, который использует потребитель. Код правильный, тесты настоящие, агент ничего не выдумал. Он просто принял решение на основании правдоподобной, но неполной картины.

Почему инструкции не спасают?

Очевидный ответ: «добавьте строку contracts/api.yaml is the source of truth». Для небольшого репозитория это работает. Но по мере роста системы вопрос перестаёт быть про одну строку.

Что происходит, когда:

• дорожная карта (roadmap) живёт в Jira
• часть состояния релиза хранится в Git
• архитектурные решения описаны в ADR (Architecture Decision Records, журнал решений по архитектуре)
• сведения о совместимости лежат в манифестах
• документация генерируется из нескольких источников
• часть старых артефактов всё ещё нужна одному потребителю

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

Автор фреймворка AIRepo выделяет три разные задачи, которые часто смешивают в одном файле:

• Инструкции (instructions): как агент должен работать, какие команды запускать, какие конвенции соблюдать
• Семантика репозитория (repository semantics): чему можно доверять, кто чем владеет, что актуальное, что историческое, что сгенерированное, какой потребитель зависит от конкретного файла
• Политики и права (runtime/policy): что агент вообще имеет право делать

Если два артефакта выглядят одинаково авторитетными и репозиторий не позволяет уверенно определить, какой из них владеет решением, ещё одна инструкция лечит симптом, а не причину.

Что понадобится

• Доступ к репозиторию проекта с правами на редактирование структуры и документации
• Любой ИИ-агент для кода: Manus, Codex, Claude Code, Cursor или GitHub Copilot
• Текстовый редактор или IDE
• 30 минут на первичную разметку для небольшого репозитория

Пошаговая инструкция

1. Определите «источники истины» для каждого типа артефактов. Пройдитесь по репозиторию и для каждого файла, который описывает API, схему, конфигурацию или контракт, зафиксируйте: он canonical (из него генерируются зависимости) или descriptive (описывает, но не владеет)?

2. Запишите владельцев артефактов. Для каждого canonical-файла укажите, кто или что является его потребителем (consumer). Например:

# contracts/api.yaml
role: canonical-contract
consumers:
  - external-sdk-generator
  - partner-integration-tests

1. Разделите инструкции, семантику и политики. Не сваливайте всё в один файл. Инструкции по стилю кода пусть остаются в AGENTS.md или аналоге. Информацию о владении артефактами вынесите отдельно.

2. Добавьте явную связь между артефактами. Если api.md описывает то, что определено в api.yaml, укажите это прямо:

# docs/architecture/api.md
derived-from: contracts/api.yaml
role: descriptive
note: do not treat as source of truth for SDK generation

1. Проверьте на практике. Дайте ИИ-агенту задачу, которая требует выбора между двумя файлами. Посмотрите, какой он выберет. Если ошибётся, значит, разметка недостаточно явная.

2. Настройте CI-проверку согласованности. Когда владение определено, можно написать валидатор: изменился canonical-контракт, проверь, что зависимые артефакты тоже обновлены. Без определённого владения такой валидатор невозможен.

Что делать с этим прямо сейчас, по ролям

Автору на Дзене или копирайтеру. Если вы используете ИИ-агента для генерации контента из нескольких источников (черновики, ТЗ, стайлгайд), явно укажите, какой документ главный. Это тот же принцип: агент не угадает, что стайлгайд важнее старого черновика, если вы не скажете это прямо в промпте (prompt, текстовая инструкция для ИИ).

Маркетологу. Если в вашей команде ИИ-агент работает с лендингами, письмами и документацией продукта, определите, что является «источником истины» по описанию фич. Иначе агент возьмёт формулировку из устаревшего PDF вместо актуальной карточки в таск-трекере.

Предпринимателю и разработчику. Фреймворк AIRepo (версия 1.0.0, лицензия Apache-2.0) открыт и не привязан к конкретному провайдеру ИИ. Его можно применить к любому репозиторию. Из доступных в РФ инструментов для агентной работы с кодом: пока выбор ограничен, но принцип разметки владения работает с любым агентом, включая локальные решения.

Главный вывод простой: прежде чем давать ИИ-агенту задачу, убедитесь, что ваш репозиторий (или набор документов) однозначно отвечает на вопрос «кто здесь главный», иначе агент ответит на него сам, и вам может не понравиться результат.