Проектирование AGENTS.md и модульных правил: как запретить ИИ ломать слои

Даже самая продвинутая модель при первом знакомстве с репозиторием не знает ваших негласных договорённостей: где должны открываться транзакции, какой контейнер внедрения зависимостей используется и почему в папке endpoints/ запрещено импортировать SQLAlchemy-сессию. Файл AGENTS.md решает эту проблему, превращаясь в исполняемую конституцию проекта.

1. Почему обычного README недостаточно

Классический README.md пишется для человека и обычно рассказывает, как запустить Docker-контейнер и настроить переменные окружения. Для ИИ-агента эта информация вторична. Ему нужны топология директорий, направления разрешённых импортов и жёсткие инварианты, нарушение которых считается критической ошибкой.

2. Анатомия эффективного файла правил

На практике лучше всего работает трёхуровневая иерархия документации в каталоге .agents/:

• Обзор стека и версий библиотек: таблица с точными версиями (например, Python 3.12+, SQLAlchemy 2.0 async, Dishka, Pydantic v2), чтобы агент не генерировал устаревший синтаксис v1;
• Карта ссылок на профильные правила (rules/): отдельные компактные файлы для правил базы данных, UI-слоя и чистой архитектуры;
• Золотые правила (Непреложные запреты): 5–7 конкретных пунктов с примерами того, что делать категорически нельзя.

3. Эталонный фрагмент правил Clean Architecture + Dishka

Ниже приведён проверенный шаблон блока архитектурных ограничений, который мы используем в учебных проектах Трека 02:

# Правила разделения слоёв (Clean Architecture & CQRS)

## 1. Границы ответственности
- `src/delivery/` (FastAPI роутеры, Telegram диалоги): только валидация входных DTO,
  вызов одного UseCase из DI-контейнера и форматирование ответа.
- `src/application/use_cases/`: оркестрация бизнес-сценария, управление транзакцией
  `async with self.uow:` и публикация доменных событий.
- `src/infrastructure/database/dao/`: атомарные параметризованные запросы к БД.

## 2. Строгие запреты
1. ЗАПРЕЩЕНО импортировать модели SQLAlchemy или DAO напрямую в `src/delivery/`.
2. ЗАПРЕЩЕНО использовать блокирующие вызовы (`requests`, `time.sleep`, синхронный IO).
3. Каждый новый DAO или UseCase ОБЯЗАН быть зарегистрирован в провайдере Dishka
   в `src/infrastructure/di/providers/` с корректным Scope (`Scope.REQUEST`).

4. Три главные ошибки при поддержке AGENTS.md

1. Слишком большой объём корневого файла: если AGENTS.md превышает 300 строк, модель начинает пропускать правила из середины документа. Дробите его на тематические модули.
2. Противоречия с реальным кодом: если в правилах написано одно, а в соседнем легаси-файле сделано иначе, агент скопирует паттерн из кода. Помечайте устаревшие модули явно.
3. Отсутствие автоматической проверки: любое правило из AGENTS.md по возможности должно дублироваться проверкой в ruff, mypy или кастомном тесте архитектуры.

Читайте также в инженерном блоге