test/AGENTS.md

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 под нагрузкой.