1. Фіксаємо назви файлів, рефакторинг та оптимізація під Python, підключаємо Ruff та uv

Повне одночасне переписування Selenium-проєкту на Playwright створює надто великий ризик. Практичний порядок інший: спочатку переносити тести, які вже падають або є flaky, потім — короткі ізольовані сценарії, а далі рухатися функціональними зрізами.

Старі й нові інструменти можуть тимчасово співіснувати в одному репозиторії. Окремі pytest suites і CI-команди дозволяють запускати Selenium та Playwright незалежно, тому міграцію можна виконувати без зупинки розвитку наявного набору тестів.

Початкова проблема — файли названо з великої літери, хоча Python-конвенція вимагає snake_case і нижнього регістру для модулів. Просте ручне перейменування не гарантує, що динамічні імпорти та всі usages буде знайдено, тому спочатку потрібен аналіз повного графа використання.

AI-агент отримує вузьку технічну задачу: знайти невідповідні PEP 8 назви, скласти план і виконати перейменування разом з оновленням імпортів. Для збереження Git-історії файлів використовується git mv. Після окремої завершеної задачі варто починати нову AI-сесію, щоб старий контекст не впливав на наступний етап.

Prompt має описувати конкретні ознаки, які треба знайти: змішані absolute/relative imports, відсутні type hints, невикористаний код, naming conventions, кеші Python. Рольова фраза на кшталт «працюй як інженер із десятьма роками досвіду» не замінює технічних критеріїв.

Згенерований план обов’язково перечитується. У прикладі корисними знахідками є відсутній тип Page, зайві імпорти, непослідовні приватні поля та незаігнорований __pycache__, але частина запропонованих змін є спірною або зайвою. Спочатку важливо отримати корисний робочий тест; узгодженість структури виправляється окремим контрольованим рефакторингом.

Для великої міграції план доцільно зберегти в окремому Markdown-файлі й виконувати по одному пункту в нових сесіях. Це зменшує ризик, що модель втратить початкові обмеження у довгому контексті або спробує змінити забагато файлів за один раз.

Стабільні правила проєкту — структура, команди, naming, бібліотеки та перевірки — корисно тримати у спільному інструкційному файлі на кшталт AGENTS.md. Тимчасовий migration plan можна не комітити, якщо він потрібен лише для локальної роботи.

Після автоматичного рефакторингу переглядається кожен змінений файл. Демонстрація виявляє як нормальні зміни — типи, constants, імпорти — так і небажане видалення файлів та помилку у fixture, яка створила некоректний стан сторінки.

AI-агент запускає найменший тест, але сам факт запуску не доводить коректність усієї зміни: треба прочитати failure, перевірити fixture lifecycle і повторити сценарій. Результат оформлюється в окремій гілці та коміті, а не змішується з наступною міграцією інструментів.

IDE inspections залежать від локальних налаштувань кожного інженера. Ruff переносить правила у репозиторій: перевіряє naming, невикористані імпорти, частину потенційних помилок і може форматувати код значно швидше за традиційний набір Python-інструментів.

У PyCharm вмикається інтеграція Ruff, а в Actions on Save — reformat та optimize imports. Налаштування зберігаються в ruff.toml або секції pyproject.toml; версія Python у конфігурації має відповідати реальному runtime проєкту.

[project]
name = "example-tests"
version = "0.1.0"
requires-python = ">=3.12"

[tool.ruff]
target-version = "py312"

[tool.ruff.lint]
select = ["E4", "E7", "E9", "F", "I", "N"]

Замість ручної послідовності створення venv, активації та pip install -r requirements.txt проєкт переходить на uv sync. Залежності й метадані описуються у pyproject.toml, а uv.lock фіксує точні версії, включно з транзитивними залежностями.

Для застосунку або тестового проєкту lock-файл варто комітити: це відтворює однаковий dependency graph локально та в CI й зменшує ризик конфліктів, коли різні бібліотеки вимагають несумісні версії спільної залежності.

Після міграції тест запускається через команду uv run ... з консолі, бо це ближче до майбутнього CI-запуску, ніж Run Configuration IDE. Треба перевірити, що виконався потрібний тест і що очікуване падіння справді належить тестовій логіці, а не відсутній залежності чи неправильному шляху.

Фінальний крок — створити короткий README з мінімальною версією Python, установкою, командами запуску, структурою та правилами внесення змін. Commit message перевіряється вручну: він має називати реальну міграцію на uv і підключення Ruff, а не перелічувати випадкові деталі diff.