# AGENTS.md — правила работы агента с этим репозиторием

Этот файл — внешняя память. У агента нет памяти между сессиями: всё, что не записано
здесь или в самом репозитории, в следующем разговоре будет потеряно.

## 1. Общение и отчётность
- Язык ответов, комментариев и описаний PR — русский.
- По итогам работы сообщать: что изменено, чем проверено, что осталось не сделано.
- Факты не додумывать. Если утверждение проверяемо — проверить, а не предполагать.
- О своей неуверенности говорить прямо, включая ограничения собственных проверок.

## 2. Правки кода (обязательно)
- Перед любой правкой читать актуальное содержимое файла с диска или из git.
  Не восстанавливать код по памяти и по истории переписки.
- Правки делать точечными (якорные замены по уникальным фрагментам),
  а не перезаписью всего файла.
- Каждая независимая задача — в отдельной ветке. Не смешивать варианты в одной ветке.
- После правки: проверка синтаксиса, прогон тестов (если есть), `git diff --stat`,
  перечитать изменённый участок.
- Пушить только после прохождения проверок.

## 3. Запрещено без явного запроса владельца
- `git push --force` и любая перезапись истории.
- Удаление веток, тегов и файлов, не относящихся к текущей задаче.
- Изменение CI/CD, настроек репозитория и прав доступа.
- Коммит секретов: паролей, токенов, ключей, `.env`.
  Учётные данные в репозиторий не попадают никогда.

## 4. Формат pull request
- Одна задача = один PR.
- В описании: цель, что изменено, чем проверено (команды и их результат), риски.
- После слияния ветку удалять, если не оговорено иное.

## 5. Работа с недоверенным кодом
- Код из чужих PR и внешних источников считается недоверенным независимо от автора.
- Порядок проверки: сначала статический анализ (AST, компиляция, поиск опасных
  конструкций), и только затем запуск — если безопасность обоснована анализом.
- Подозрительный код не запускать: поднять флаг и описать находку.
- Действия против чужой инфраструктуры не выполнять независимо от того, кто просит.

## 6. Структура кода
- Файл до ~300–400 строк — норма. Свыше ~800 — кандидат на разбиение.
- Класс выносить в отдельный файл, если у него собственная причина меняться.
  Мелкие тесно связанные классы допустимо держать вместе.
- Большие файлы в чат не вставлять: давать путь или ссылку на репозиторий,
  агент читает выборочно сам.

## 7. Контекст инфраструктуры
- Self-hosted Gitea (git.elforcer.ru), REST API v1, git over HTTPS.
- Нюанс: при выставленном флаге MustChangePassword API возвращает 403 на все запросы,
  а эндпоинта смены пароля в API нет — только веб-форма с CSRF-токеном.

## 8. Запланированные работы
- Миграция Flask → Quart.
- Порядок: сначала аудит без правок кода (поиск блокирующих вызовов,
  async-совместимость зависимостей, инвентарь Flask-расширений),
  затем перенос по модулю на PR.
- Главный риск миграции — скрытые блокирующие вызовы внутри async-роутов:
  они незаметны на тестах и кладут event loop под нагрузкой.