Ruff для команды: конфиг, правила выбора и контроль миграции без поломок стиля

Ruff из тех инструментов, которые быстро становятся “встроенной привычкой” команды. Он работает не как экзотический линтер, а как компилятор для стиля: поднимает сигналы по качеству кода, ловит потенциальные ошибки и помогает держать единообразие. Но в командной среде главная проблема обычно не в том, есть ли Ruff, а в том, как внедрить его без массовых диффов, спорных решений и “сломанных” ожиданий стиля.

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

Что именно делает Ruff и почему это важно для конфигурации

Ruff — это набор правил (линтеров и проверок) и возможность автопочинки части проблем. Его ключевые особенности для команд:

1. Детерминированность. При одинаковой конфигурации Ruff должен давать одинаковый результат. В идеале — без “мелких” отличий между рабочими станциями.
2. Разные уровни строгости. Есть правила, которые почти всегда безопасно включать сразу (стилистические и “простые” ворнинги), и есть те, которые могут менять поведение или затрагивать архитектурные решения.
3. Два типа воздействия:
   • отчёт (diagnostics),
   • автоисправления (--fix), которые применяются только для поддерживаемых правил.

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

Базовая схема конфигурации: ruff.toml как “политика”

Чаще всего команда приходит к одному из двух сценариев:

• Сценарий A — новый репозиторий / небольшой код: можно быстро включить большинство правил и фиксировать диффами.
• Сценарий B — исторический код: нужно “навести порядок” постепенно, иначе CI превратится в генератор шума.

Независимо от сценария логика конфигурации одна:

• определить целевую версию Python,
• ограничить область (файлы/директории),
• выбрать группы правил,
• настроить уровни (select/ignore),
• решить, где и как применять автофиксы,
• стабилизировать миграцию (исключения, пороги, поэтапность).

Минимальный каркас ruff.toml

# ruff.toml
target-version = "py311"

[lint]
# Выбор: какие классы проверок участвуют
select = [
  "E",   # pycodestyle: ошибки по PEP8
  "F",   # pyflakes: потенциальные ошибки
  "I",   # isort: импорт-сортировка
  "N",   # pep8-naming: имена
  # далее добавим группы по мере готовности
]

# Игнор — точечные исключения
ignore = [
  # примеры: для конкретных правил
  # "E501",  # например, если у вас нет лимита по длине строки
]

# Показывать только то, что важно: иначе будет “шум”
# (в Ruff это обычно управляют select/ignore и preview)

Это только каркас. В реальном репозитории почти всегда понадобятся ещё:

• форматирование (или отдельно: formatter),
• исключения по путям,
• настройка логики автоправок,
• политика по “жёсткости” (опасные правила — отдельно).

Как выбрать правила: порядок включения, а не “всё сразу”

Самая распространённая ошибка команд — попытаться включить “все кнопки” и быстро получить “идеальный код”. В итоге:

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

Вместо этого лучше строить лестницу строгости.

Этап 1. Правила, которые почти всегда дают положительный ROI

В начале разумно включать:

• E (pycodestyle): базовая синтаксическая/стилeвая чистота.
• F (pyflakes): вероятные ошибки и неиспользуемые элементы.
• I (isort): упорядочивание импортов — особенно полезно, если у команды разные IDE/линтеры.
• N (pep8-naming): согласованность имен.

Обычно эти правила:

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

Практика внедрения: включайте эти группы в режиме “диагностика”, затем включайте автофиксы для ограниченного набора.

Этап 2. Умеренно строгие правила (нужны согласования)

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

• правила, связанные с переопределениями, сложными конструкциями,
• рекомендации по структуре (например, неявные улучшения),
• некоторые правила из UP / RUF / B (зависит от того, как вы их используете).

Здесь обычно требуются:

• согласование с командой,
• документация “почему так”,
• выборочный ignore для тех случаев, где стиль проекта не совпадает с рекомендацией Ruff.

Этап 3. “Потенциально опасные” правила: аккуратно и точечно

Сюда обычно попадают правила, которые:

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

Их лучше включать:

• либо только в новых модулях,
• либо постепенно по директорам,
• либо как warnings без блокировки merge (в переходный период).

Локализация правил: как не утонуть в разногласиях

Команда почти всегда приходит к ситуации: “в принципе правило хорошее, но в нашем коде оно шумит”.

Есть несколько механизмов:

1. ignore (точечный запрет).
2. per-file-ignores (точечно по файлам/папкам).
3. exclude (вообще не проверять директории).
4. extend-select / extend-ignore (если вы используете “базовый профиль”).

Пример: per-file-ignores для тестов и сэмплов

[lint]
per-file-ignores = { 
  "tests/*" = ["S101"], 
  "scripts/*" = ["S603"]
}

exclude = ["build", "dist", ".venv", ".git"]

Смысл: в тестах часто допустимы “упрощения ради читаемости”, а в скриптах — “прагматичные” решения. Главное — не разбрасываться игнором, иначе появятся “серые зоны”, куда нельзя заглянуть.

Тонкость: избегайте широких игноров “на всё”

Например, игнорировать целую категорию правил для всего репозитория почти всегда означает, что вы:

• не настроили базовый стиль,
• или не выделили корректный этап миграции.

Лучше:

• точечно игнорировать,
• а остальное постепенно довести до соответствия.

Настройка импорта и стабильность: isort как якорь

Импорты — один из самых болезненных источников диффов при миграции линтеров. Поэтому I (isort) обычно стоит включать рано.

Решите, какие правила сортировки “каноничны” для проекта:

• единый стандарт группировки,
• длины строк,
• поведение с “as” и относительными импортами.

Для Ruff это делается в lint.isort.* (точный набор опций зависит от версии Ruff, но логика одна — вы задаёте то, что будет приводиться к единому виду).

Пример:

[lint.isort]
known-first-party = ["my_project"]
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]

Если вы не управляете параметрами isort явно, у команды быстро возникает “конфликт автора”: одни IDE сортируют по одному, другие — по другому. Тогда Ruff становится не мостом к консенсусу, а ещё одним источником разнобоя.

Автопочинка (--fix): что безопасно отдавать в автомат, а что — в ревью

Ключ к безболезненной миграции — выбрать, какие проблемы Ruff может исправлять автоматически, а какие лучше оставить на ручную корректировку.

Типичная политика команды:

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

В Ruff это обычно регулируется тем, какие правила вы “починяете” автоматически. В конфиге можно ограничивать набор автоправок (метод зависит от версии и доступных опций), но общий принцип: делайте --fix в CI по строгому списку, а остальное пусть требует явного PR и ревью.

Рекомендованная тактика миграции

1. Включите диагностику широкого набора правил, но не блокируйте merge на первых итерациях (например, временно снижайте уровень строгости или используйте отдельный “лендер” в CI).
2. Затем сделайте “агрессивный” PR автофиксов только для того, что точно безопасно.
3. После этого включайте блокировку в CI.

Это снижает вероятность “прыжков” стиля между релизами.

Как контролировать миграцию: стратегия против “дифф-цунами”

Когда команда включает Ruff в крупном репозитории, почти всегда появляется два вида проблем:

1. Стартовая волна (исторический код).
2. Дифф-локальная боль (люди не знают, где начинается зона “исправляемого” кода).

Ниже — рабочие стратегии.

Стратегия 1. “Новые PR — чистые, старое — не трогаем сразу”

Смысл: вы не обязаны приводить весь репозиторий к нулю ошибок в первый день.

Что можно сделать практически:

• Настроить Ruff так, чтобы он:
  • проверял новые/изменённые файлы,
  • или использовал временные лимиты.
• Добавить в CI шаг, который фокусируется на diff (например, через ruff совместно с tooling, которое определяет изменённые файлы).

В Ruff есть возможность работать с путями, поэтому вы можете в CI получать список затронутых файлов и запускать Ruff только на них.

Пример логики (не привязано к конкретной CI-платформе):

CHANGED_FILES=$(git diff --name-only origin/main...HEAD | grep -E '\.py$' || true)
if [ -n "$CHANGED_FILES" ]; then
  ruff check $CHANGED_FILES
fi

Это не “магия”, а способ контролировать масштаб.

Стратегия 2. “Собрать волны” в один большой PR (и затем жить дальше)

Иногда проще:

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

Риск — такой PR будет тяжелым для ревью. Но он может быть оправдан, если:

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

Чтобы снизить риск:

• запускайте Ruff фиксами сначала в отдельной ветке,
• фиксите только то, что гарантированно безопасно,
• после первого PR — стабилизируйте конфиг и исключения.

Стратегия 3. “Зоны ответственности” через исключения по директориям

Если репозиторий большой, разумно определить зоны:

• src/ — строгие правила,
• tests/ — мягче или с точечными игнороми,
• scripts/ — допускаем прагматику.

Это отражает реальность: тесты и утилиты часто пишутся быстрее и менее “идеологичны”.

Исключения: минимизируйте “дырки”, но давайте легальные компромиссы

Исключения — неизбежны. Вопрос в том, как сделать их управляемыми.

Подход: исключение + причина

В идеале в комментариях рядом с ignore/per-file-ignores хранится причина. Например:

[lint]
per-file-ignores = {
  "tests/test_*.py" = ["S101"] # assert используется напрямую в тестах
}

Если причина не записана, через полгода выясняется, что “этого уже не было нужно”, но никто не знает почему.

Не смешивайте “не хочу” с “не могу”

Если команда не хочет следовать определённому правилу — лучше:

• отразить это в конфиге (ignore),
• согласовать формат в документации стиля.

Если “не могу” из-за совместимости (например, Python-версия или устаревшая структура) — тоже фиксируйте это явно.

Настройка форматирования: разделение ответственности Ruff и Formatter

В экосистеме Python есть несколько инструментов форматирования (например, Ruff formatter, Black, ruff format и т.п.). Практическая рекомендация для команды:

• определите, кто “главный” по форматированию,
• Ruff используйте как диагностический слой и автофиксы там, где это логично,
• не заставляйте два форматтера спорить друг с другом.

Если вы используете Ruff для форматирования, это должно быть зафиксировано в CI и локальных гайдах. Иначе будет эффект “локально одно, в CI другое”.

CI и локальная разработка: единый сценарий запуска

Конфиг — это только половина. Вторая половина — как команда запускает инструмент.

Рекомендованный набор команд

• проверка:
  codeКопировать

  ruff check .
  

• показ диффа с фиксом (полезно для контроля):
  codeКопировать

  ruff check . --fix --diff
  

• форматирование (если используете):
  codeКопировать

  ruff format .
  

В миграции полезно работать режимом --diff, чтобы люди видели конкретно, что именно изменит автопочинка, и обсуждали это заранее.

Фиксирование версии Ruff

Чтобы избежать “плавающих” правил при обновлении:

• фиксируйте версию Ruff в зависимостях (например, через requirements-dev/pyproject.toml),
• обновляйте Ruff не хаотично, а по плану (раз в спринт/релиз с тестом на дифф).

Иначе команда может неожиданно получить новые диагностики или изменения форматирования.

Пример “реалистичного” ruff.toml для команды (шаблон)

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

target-version = "py311"

[lint]
# Сначала включаем безопасные и выгодные группы
select = ["E", "F", "I", "N"]

# Точечные игноры
ignore = [
  # "E501", # если нет лимита строк
]

# Исключаем мусорные директории и артефакты
exclude = ["build", "dist", ".venv", ".git", ".mypy_cache", ".ruff_cache"]

# Разные правила для разных частей репозитория
per-file-ignores = {
  "tests/*" = ["S101"], # пример: assert в тестах
  "scripts/*" = ["S603"] # пример: прагматичные пути к файлам
}

[lint.isort]
known-first-party = ["my_project"]
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]

Дальше вы постепенно расширяете select и корректируете ignore. Важно делать это не “залипанием в конфиг”, а через контроль PR: после каждого расширения измеряйте, сколько строк/файлов затрагивается и насколько много диффов “старых” областей внезапно подхватилось.

Типичные ошибки команды при внедрении Ruff

1. Включить всё в один коммит
   Это превращает внедрение в спор о стиле, а не в инженерный процесс.

2. Не зафиксировать версию Ruff
   Правила и форматирование могут меняться между релизами инструмента.

3. Игнорить слишком широко
   ignore на уровне репозитория часто скрывает проблемы, а потом правила начинают “не работать”.

4. Смешать несколько инструментов форматирования
   Локально одно, CI другое — и доверие к линтеру падает.

5. Отдать автофиксы без предварительного контроля диффа
   Особенно в историческом коде: можно получить изменения, которые не были согласованы командой.

Как быть уверенным, что “стиль не поломается”

Практический контроль — это не “на глаз”, а несколько простых практик:

• Разделите “первичную миграцию стиля” и “поддержку качества”.
• Используйте ruff check --fix --diff перед применением фиксирующих изменений.
• Введите минимальное правило: любая новая проверка/правило добавляется в PR с описанием ожидаемого эффекта (сколько файлов затронется, какие исключения нужны).
• Ведите список решений: почему правило включено/выключено.

Если в команде нет документированной политики, то конфиг становится живым спором — и тогда Ruff перестаёт быть инструментом качества.

Вывод: Ruff как управляемая политика, а не разовый “линтер ради линтера”

Внедрение Ruff в команде — это управленческая задача: нужно выбрать правила, определить, где они применяются, и сделать миграцию так, чтобы она не ломала разработку диффами и обсуждениями “на пустом месте”. Лучший результат обычно получается не от “максимального select”, а от лестницы строгости: сначала безопасные правила (E, F, I, N), затем — более тонкие группы, и только после этого — сложные/спорные проверки.

Если вам нужно быстрее разложить все аспекты конфигурации и режимов работы Ruff (select/ignore, автофиксы, структура ruff.toml), полезным стартом может стать курс «ruff – для начинающих!». Он поможет системно разобраться в механике инструмента, а дальше уже можно адаптировать конфиг под реальные требования вашего репозитория.

Главное — относитесь к Ruff как к контракту команды. Тогда он будет не источником шума, а механизмом, который удерживает код в одном стиле на протяжении всего жизненного цикла проекта.