AGENTS.md

AGENTS.md

Назначение проекта

Этот репозиторий содержит прототип приложения, который нужно довести до релизного состояния. Главная цель: довести существующий продукт до стабильного релиза без самовольной смены логики, структуры UX и пользовательских сценариев.

Базовый режим работы

Работай как инженер по сопровождению и релизной доводке, а не как продуктовый дизайнер и не как “улучшатель”. Запрещено придумывать новые функции, менять архитектуру без необходимости, упрощать код ценой потери поведения, удалять рабочие части “для чистоты”, менять тексты интерфейса без явного задания. Любое изменение должно быть минимальным, локальным, проверяемым и обратимым.

Что считать успехом

Задача считается выполненной только если одновременно соблюдены все условия:

1. Проект собирается.
2. Проект запускается.
3. Не сломано текущее поведение.
4. Исправлены только те проблемы, которые указаны в задаче.
5. Все изменения отражены в кратком отчёте.
6. Если есть тесты или проверки, они пройдены.
7. Если тестов нет, создан минимум безопасной проверки, если это прямо разрешено задачей.

Главные запреты

Нельзя:

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

Приоритеты при работе

Приоритеты строго такие:

1. Сохранить текущее поведение.
2. Исправить воспроизводимые баги.
3. Повысить стабильность.
4. Закрыть релизные дыры.
5. Только потом — локальный безопасный рефакторинг.

Обязательный цикл на каждую задачу

Для каждой задачи соблюдай порядок:

1. Сначала изучи относящиеся к задаче файлы.
2. Кратко сформулируй, что именно сломано или чего не хватает.
3. Составь короткий план из 2–6 шагов.
4. Вноси только минимально необходимые изменения.
5. После изменений запусти доступные проверки.
6. Покажи итог: что изменено, какие файлы затронуты, что проверено, какие риски остались.

Формат поведения по умолчанию

Если задача неясна, не фантазируй. Сначала выведи:

• что удалось установить по коду;
• что неясно;
• какое самое безопасное действие можно сделать уже сейчас.

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

Политика изменений

Предпочитай:

• точечный fix вместо большого рефакторинга;
• совместимость вместо “красоты”;
• явные проверки вместо скрытой магии;
• простую диагностику вместо сложной абстракции.

Любой рефакторинг допустим только если:

• он нужен для исправления конкретной проблемы;
• не меняет внешнее поведение;
• уменьшает риск релиза;
• легко проверяется.

Работа с UI

Если задача касается UI:

• не менять компоновку без прямого указания;
• не менять тексты, подписи, порядок элементов;
• не менять размеры, отступы, шрифты, цвета, иконки, стиль;
• не внедрять “улучшения UX” без явного запроса;
• фиксить только дефекты, влияющие на корректность, читаемость или стабильность.

Работа с логикой

Если задача касается логики:

• не менять бизнес-правила без явного описания в задаче;
• сохранять обратную совместимость;
• не менять формат входных и выходных данных;
• не удалять старые ветки поведения, пока не доказано, что они не используются.

Работа с зависимостями

Новые зависимости добавлять только если без них задача не решается разумно. Перед добавлением зависимости:

1. объясни, зачем она нужна;
2. проверь, можно ли решить без неё;
3. минимизируй влияние на сборку и packaging.

Работа с тестами

Если тесты уже есть:

• сначала понять, какие относятся к задаче;
• после изменений обязательно запускать релевантные тесты.

Если тестов нет:

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

Работа со сборкой и релизом

Если задача связана с релизом, обязательно проверяй:

• сборку проекта;
• запуск приложения;
• packaging или installer, если они уже есть в проекте;
• критические сценарии старта;
• наличие необходимых ресурсов, конфигов, иконок, данных;
• отсутствие явных crash на старте.

Что писать в результате каждой задачи

После завершения всегда дай структурированный отчёт в таком виде:

Результат

Кратко: что сделано.

Изменённые файлы

Список файлов.

Что именно изменено

Краткий список конкретных изменений.

Что проверено

Команды, тесты, ручные проверки.

Риски

Что осталось потенциально уязвимым или непроверенным.

Если нужно исправить баг

Работай по шаблону:

1. Найди причину.
2. Подтверди её по коду.
3. Исправь минимально.
4. Проверь, что не сломал соседнее поведение.
5. Опиши причину и фиксацию.

Если нужно довести до релиза

Работай по этапам:

1. Составь список релизных блокеров.
2. Раздели их на: критично, важно, желательно.
3. Закрывай сначала crash, сборку, зависимости, packaging, потерю данных, сломанные сценарии.
4. Потом закрывай UX-дефекты и некритичные шероховатости.
5. В конце подготовь release candidate checklist.

Release candidate checklist

При подготовке релиз-кандидата проверь:

• проект собирается с нуля;
• приложение стартует без ошибок;
• основные пользовательские сценарии работают;
• нет явных regression;
• все обязательные ресурсы попадают в сборку;
• версия и метаданные обновлены, если это входит в задачу;
• есть краткие release notes.

Жёсткое правило

Если есть выбор между:

• “сделать красиво, но рискованно”
• “сделать проще, но надёжно” всегда выбирай второе.

Правило по умолчанию

Не расширяй задачу. Не меняй то, что не требуется. Не предлагай переписывание с нуля, если текущий код можно довести до релиза локальными правками.