Imported from Ilyawysy/ICAOMS (AGENTS.md). Install upstream with npx skills add Ilyawysy/ICAOMS. Copyright stays with the author.

ICAOMS: правила работы агентов

Назначение

Этот файл задаёт единый процесс для агентов, работающих над ICAOMS. Источником продуктового контекста является docs/PROJECT_CONTEXT.md, а согласованные решения фиксируются в docs/DECISIONS.md.

До подтверждения владельцем решения со статусом TBD нельзя молча превращать в архитектурные или продуктовые допущения.

Роли

Оркестратор

• ведёт диалог с владельцем проекта;
• хранит целостный контекст и границы текущего этапа;
• назначает агентам только ограниченные задачи;
• сводит результаты планировщика, исполнителя и проверяющего;
• не начинает следующий этап без прохождения его gate.

Ведущий планировщик / архитектор

• предпочтительная модель: самая сильная доступная;
• уточняет требования, доменную модель, зависимости и ADR;
• формулирует критерии приёмки до реализации;
• проверяет, что задача является вертикальным, проверяемым инкрементом;
• не принимает собственную реализацию.

Исполнитель

• предпочтительная модель: более экономичная инженерная модель;
• реализует только утверждённую ограниченную задачу;
• не меняет архитектуру, публичные контракты и границы MVP молча;
• добавляет тесты соразмерно риску;
• сообщает о расхождениях между планом и кодовой базой.

Независимый проверяющий

• предпочтительная модель: более экономичная модель;
• сначала проводит ревью, затем отдельно предлагает исправления;
• проверяет критерии приёмки, права доступа, миграции, аудит и тесты;
• для юридически значимой логики проверяет негативные сценарии;
• не считает успешную демонстрацию заменой автоматическим тестам.

Рабочий цикл

1. Оркестратор формулирует ограниченный вертикальный инкремент.
2. Планировщик уточняет зависимости, риски и критерии приёмки.
3. Владелец подтверждает существенные продуктовые или архитектурные решения.
4. Исполнитель реализует утверждённый объём.
5. Проверяющий независимо анализирует diff и запускает проверки.
6. Исполнитель устраняет подтверждённые замечания.
7. Оркестратор сверяет результат с критериями и обновляет контекст.

При четырёх доступных слотах рекомендуется одновременно держать:

• оркестратора;
• ведущего планировщика;
• одного исполнителя;
• одного независимого проверяющего.

Специализации frontend, backend, AI и QA назначаются под конкретный инкремент, а не закрепляются навсегда за отдельными агентами.

Неприкосновенные инварианты

• ИИ не пишет непосредственно в подтверждённое состояние договора.
• Каждый критичный извлечённый факт имеет проверяемый источник.
• Расчёт сроков, авторизация, переходы состояний и аудит детерминированы.
• Исходный файл неизменяем; новая версия является новой сущностью.
• Дополнительное соглашение не стирает прежние условия.
• Фильтрация доступа выполняется до поиска и передачи контекста модели.
• Изменяющее действие помощника требует предпросмотра и подтверждения.
• Повтор фоновой задачи не должен создавать дубликаты результата.

Правила изменений

• Сначала искать и соблюдать локальные инструкции в затрагиваемой области.
• Не редактировать пользовательские изменения вне текущей задачи.
• Для схемы БД использовать миграции; не изменять production-схему вручную.
• Для новых API сначала зафиксировать контракт и ошибки.
• Для AI/OCR использовать адаптеры провайдеров и моки в автоматических тестах.
• Не помещать документы, персональные данные, ключи и секреты в репозиторий или обычные application logs.
• Каждая задача завершается кратким отчётом: что изменено, что проверено, известные ограничения и следующий gate.