Удалите магические константы из кода, сгенерированного ИИ (безопасно)

Почему магические константы создают проблемы в коде, сгенерированном ИИ

Магические константы — это значения, разбросанные по коду без имени или объяснения. Они выглядят как жестко закодированные числа (например 7 или 10000), вставленные URL (например https://api.example.com) или строки, которые тихо контролируют поведение (например beta, admin или enabled). Когда вы видите их позже, нельзя понять, зачем это значение существует и что сломается при его изменении.

Прототипы, сгенерированные ИИ, усугубляют ситуацию: код часто создаётся маленькими, отдельными фрагментами. Одна компонента получает один таймаут, другая — другой, третья вставляет URL с чуть другим путём. Приложение достаточно работоспособно для демо, но одно и то же правило оказывается реализовано в нескольких местах с мелкими различиями.

Поэтому удаление магических констант может показаться рискованным. Простая задача вроде «увеличить лимит загрузки с 10МБ до 25МБ» превращается в охоту по контроллерам, UI-компонентам, хелперам валидации и фоновых задачам. Пропустили одно место — и вы выпускаете баг, который проявится только в продакшене.

Симптомы обычно видны быстро:

• Несогласованное поведение между страницами (на одном экране разрешено 25МБ, на другом блокируется на 10МБ)
• Исправления, которые срабатывают в одном потоке, но не в другом
• Тесты, которые сложно писать, потому что правила разбросаны
• Хотфиксы, создающие новые крайние случаи по мере дрейфа значений
• Запутанные тикеты поддержки ("иногда работает") без понятной закономерности

Реалистичный пример: в потоке логина у вас захардкожен "https://api.example.com" в одном месте, другой файл использует "https://api.example.com/", а третий указывает на "https://staging-api.example.com", оставшийся от предыдущего эксперимента. Вы поменяли одно место — аутентификация всё равно падает у некоторых пользователей, и вы начинаете охоту за призраками.

Это одна из самых распространённых проблем, которые мы видим в сломанных AI-созданных приложениях в FixMyMess. Самый быстрый путь к безопасным изменениям — сделать важные значения скучными: одно имя, одно место, один источник правды.

Что считается магической константой (а что — нет)

Магическая константа — это любое значение, запечённое в коде, смысл которого не очевиден, и изменение которого позже требует поиска по файлам и догадок, что ещё затронется. В AI-сгенерированных прототипах риск увеличивается, потому что одинаковые значения часто повторяются в разных файлах.

Что такое магическая константа?

Обычно это магические числа, магические строки и захардкоженные URL. Это часто «важные дефолты», которые тихо управляют поведением.

Частые примеры:

• Таймауты вроде 3000 или 30 (миллисекунды или секунды?)
• Размеры пагинации вроде 10, 20, 50
• Число попыток вроде 3 или 5
• Базовые URL API вроде https://api.example.com/v1
• Переключатели фич, спрятанные в строках вроде enableNewCheckout = true

Проблема не в том, что такие значения существуют. Проблема в том, что код не объясняет, что они означают. Через шесть недель 3000 выглядит как догадка, а не осознанное решение.

Почему «одно быстрое правка» оборачивается проблемой

В AI-сгенерированных прототипах одна и та же константа часто копируется по компонентам, роутам и хелперам. Вы меняете её в одном месте, тесты проходят, и затем другой экран ломается, потому что он использовал чуть другую копию.

Скрытые дубликаты особенно коварны: timeout = 3000 в одном файле, timeout = 3500 в другом и timeoutMs = 3000 где-то ещё. Это может быть намеренной разницей, а может быть случайным дрейфом. В любом случае теперь поведение зависит от того, какой путь проходит пользователь.

Что НЕ считается магической константой?

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

Хорошие не-магические примеры:

• 0 или 1 как простой счётчик в цикле
• 404 при возврате HTTP-статуса в обработчике
• Небольшой отступ в UI, явно локальный для одного компонента

Полезное правило: если изменение значения должно быть осознанным продуктовым решением (лимиты, URL, ретраи, переключатели), оно должно иметь имя и одно место.

Простой способ найти и приоритизировать, что фиксить

Сложность не в самом изменении. Сложность — выбрать, с чего начать, чтобы не создать новых багов.

Начните с быстрого инвентаря. Используйте поиск редактора, чтобы найти повторяющиеся значения: тот же URL, тот же таймаут, те же 10 или 1000, ту же строку статуса. Если значение встречается в 5+ местах, это сильный кандидат. Если только в 2 местах, но относится к деньгам или логину — тоже кандидат.

Фокусируйтесь на риске, а не на совершенстве. Константы, которые больше всего вредят, — это те, которые могут сломать продакшен или создать проблемы с безопасностью при ошибке.

Быстрое правило для триажа

Разделите найденное на «починить сейчас» и «починить позже». В «починить сейчас» обычно попадает:

• Аутентификация и идентификация: OAuth-URL, callback-URL, время жизни токена, настройки cookie
• Платежи и вебхуки: эндпойнты провайдеров, имена секретов для подписей, задержки при повторных попытках
• Лимиты и квоты: максимум запросов, максимальный размер загрузки, размеры пагинации
• Таймауты и ретраи: таймауты API, интервалы фоновых задач
• Внешние базовые URL: всё, что указывает на staging, localhost или личный сервер

Затем выберите один элемент и создайте единый источник правды, прежде чем трогать кучу файлов. AI-сгенерированный код часто содержит одно и то же значение в слегка разных формах, и быстрые правки превращаются в недоделанные рефакторы.

Назовите так, чтобы любой понял

Используйте имена, которые объясняют намерение. Избегайте CONST_1 или DEFAULT_VALUE. Предпочитайте AUTH_TOKEN_TTL_SECONDS или PAYMENTS_WEBHOOK_BASE_URL. Указывайте единицы измерения в имени (секунды vs миллисекунды), чтобы никто не угадывал.

Пример: если вы находите три разных Stripe webhook URL и два различающихся таймаута — создайте PAYMENTS_WEBHOOK_URL и PAYMENTS_API_TIMEOUT_MS в одном месте. Затем обновляйте места вызова по одному и проверяйте поведение.

Если вы унаследовали сломанный прототип от инструментов вроде Bolt, v0, Cursor, Lovable или Replit, это часто первый шаг очистки, который мы делаем в FixMyMess: централизуем рискованные значения, а затем продолжаем исправления поверх стабильной базы.

Пошагово: централизуем лимиты, URL и таймауты

Цель проста: поместить «изменяющиеся вещи» в одно место с понятными именами, чтобы обновлять их можно было без охоты по репозиторию.

Практический подход

Относитесь к этому как к серии маленьких безопасных правок, а не как к большому ребилду.

1. Выберите очевидное место для конфигурации. Создайте модуль (файл), который будет импортировать всё приложение, например config или settings.

2. Добавьте понятные имена и дефолты. Предпочитайте имена, объясняющие назначение, а не тип: API_BASE_URL, REQUEST_TIMEOUT_MS, MAX_UPLOAD_MB, PASSWORD_MIN_LENGTH. Используйте безопасные значения по умолчанию, чтобы локальный запуск не сломался.

3. Меняйте литералы постепенно. Выберите одну папку или фичу, замените литералы на конфиг-значения, закоммитьте и двигайтесь дальше. Маленькие шаги проще ревьюить и откатить.

4. Делайте лёгкую проверку после каждого шага. Запустите приложение и пройдитесь по затронутым экранам (логин, загрузка, оформление заказа). Если есть тесты — прогоните их. Цель — быстрый фидбек.

5. Держите коммиты сфокусированными. Один коммит для «централизовать таймауты», другой для «централизовать API URL». Так проще заметить ошибки (секунды vs миллисекунды).

Маленький пример, предотвращающий будущие баги

Допустим, ваше приложение вызывает https://api.example.com в пяти файлах, и в каждом месте используется разный таймаут: 2000, 5000, 15_000. После централизования вы задаёте API_BASE_URL и REQUEST_TIMEOUT_MS один раз. В следующий раз, когда нужно переключиться на staging или увеличить таймаут под нагрузку, вы меняете одно место, а не пять.

Где хранить конфиг: env vars, config-файлы и дефолты

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

Что в env vars, а что — в кодовых дефолтах

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

Практическое разделение:

• Переменные окружения: ключи API, секреты аутентификации, URL баз данных, приватные эндпойнты, секреты вебхуков
• Конфигурационные файлы (в репозитории): небезопасные настройки вроде доступности фич, публичных URL, значений пагинации, счётчиков ретраев
• Дефолты в коде: запасные значения, которые позволяют приложению работать при отсутствии настройки (никогда не для секретов)

Если значение может сломать продакшен или раскрыть данные — предпочитайте env vars. Если это просто разумный дефолт (например PAGE_SIZE=20) — кодовый дефолт подойдёт.

Как не попадать в ловушки между локальным, staging и продакшеном

Многие AI-прототипы случайно захардкожены под «одно окружение», в котором их тестировали. Вместо этого сделайте конфигурацию чувствительной к окружению: локально используйте локальные shell-переменные (или .env для разработки), staging — свои настройки деплоя, продакшен — защищённые секреты.

Держите правила предсказуемыми:

• Те же ключи конфигурации везде (меняются только значения)
• Быстрый фейл при отсутствии обязательных секретов в staging/production
• Дефолты только для неопасных значений

Например, можно разрешать локально дефолт REQUEST_TIMEOUT_MS=8000, но требовать DATABASE_URL и JWT_SECRET перед стартом в staging или production.

Не смешивайте загрузку конфигурации с логикой приложения

Распространённая ошибка — читать process.env... по всему коду. Это превращает конфигурацию в скрытую логику приложения.

Лучше загрузить и валидировать конфиг один раз при старте (в одном модуле), а затем передавать конфиг туда, где он нужен.

Переключатели фич, которые не превращаются в хаос

Флаги функций — это простые вкл/выкл, позволяющие выпускать код, не показывая его всем пользователям сразу. В AI-коде переключатели часто появляются как случайные булевы переменные по всему коду, что является ещё одним видом магических констант.

Хороший флаг отвечает на один вопрос простым языком: «Должны ли пользователи видеть X?» При рискованных релизах это удобно — новую регистрацию можно включить для небольшой доли пользователей или скрыть новую страницу цен до утверждения. Главное — чтобы переключатель можно было перевернуть без правки множества файлов.

Именование и структура, которые остаются читабельными

Выберите постоянный стиль именования и придерживайтесь его. Описательные имена лучше коротких. enableNewSignupFlow понятнее, чем flag2 — во время хотфикса любой поймёт, что делает переключатель.

Держите все флаги в одном месте (модуль конфигурации или файл настроек). Если значение должно меняться по окружениям, пробросьте его через переменную окружения, но всё равно экспортируйте через один объект конфигурации, чтобы остальной код не заботился, откуда оно пришло.

Несколько правил против размножения флагов:

• Предпочитайте имена enableX или useX, которые соответствуют поведению, видимому пользователю
• Один флаг на функцию, не по файлу
• Добавляйте срок жизни или заметку об удалении для временных флагов
• По умолчанию выключайте рискованные изменения

Кто может переключать флаги

Флаги могут нанести вред, если ими может поменять кто угодно. Решите, кто и как может менять их, и как изменения ревьюятся.

Пример: в AI-приложении новая страница оформления заказа за флагом. Заинтересованный просит выключить её после всплеска тикетов. Если флаг централизован, вы перевернёте одно значение и будете уверены, что не пропустили скрытую копию булева.

Реалистичный пример: одно изменение — одно место

Представьте стартап, который быстро выпустил AI-сгенерированный прототип. Для демо он работал, но код повторяет одни и те же значения: API URL, таймауты, лимиты и переключатель "нового оформления".

До: маленькое изменение — много рискованных правок

Вам нужно переключиться с staging API на продакшен. Вы ищете https://api-staging... и находите его в шести файлах: frontend fetch-вызовы, клиент на бэкенде, обработчик вебхуков и фоновая задача. Вы меняете все места, деплоите, а позже обнаруживаете файл, который всё ещё указывает на staging. Половина приложения тихо читает старые данные.

После этого при реальной нагрузке нужно поднять лимит запросов с 10 до 50 в минуту, а таймаут с 2с до 8с. Эти числа разбросаны, и в одном месте используются миллисекунды, в другом — секунды. Простая правка превращается в игру в угадайку.

В конце концов ошибки всплывают в новой фиче. AI-код добавил ENABLE_NEW_CHECKOUT = true в двух разных модулях. Вы выключили один — пользователи всё ещё видят сломанный путь, потому что другой флаг остался true.

Вот как часто выглядит такой беспорядок:

// auth.js
const API_BASE_URL = "https://api-staging.example.com";

// orders.js
fetch("https://api-staging.example.com/orders", { timeout: 2000 });

// worker.js
const TIMEOUT_MS = 2000;
const RATE_LIMIT = 10;

// checkout.js
const ENABLE_NEW_CHECKOUT = true;

После: одно обновление конфигурации

После централизования остальная часть приложения импортирует значения из одного модуля конфигурации (и использует переменные окружения там, где это уместно).

// config.js
export const config = {
  apiBaseUrl: process.env.API_BASE_URL ?? "https://api.example.com",
  timeoutMs: Number(process.env.TIMEOUT_MS ?? 8000),
  rateLimitPerMin: Number(process.env.RATE_LIMIT ?? 50),
  features: {
    newCheckout: process.env.FEATURE_NEW_CHECKOUT === "true",
  },
};

// orders.js
fetch(`${config.apiBaseUrl}/orders`, { timeout: config.timeoutMs });

Теперь «сменить базовый URL API» — значит обновить одну переменную окружения, а не править половину кодовой базы. «Поднять таймаут» — поменять одно число с одной единицей измерения. «Отключить новую фичу» — перевернуть один флаг и быстро реагировать при проблемах.

Распространённые ошибки и ловушки

Цель — безопасность: меньше рискованных правок, меньше сюрпризов, удобнее вносить изменения позже. Большинство проблем возникает, когда рефактор выглядит аккуратно, но поведение тихо меняется.

Частая оплошность — переименовать константу и не обновить все импорты и использования. Это часто встречается в AI-проектах, где одно и то же значение продублировано под слегка разными именами. Приложение продолжает собираться, но поведение становится разрозненным.

Несколько конфиг-файлов — ещё одна ловушка. Началось с «один для сервера, один для клиента», а выросло в три-четыре файла, которые расходятся. Когда значение меняется, часть команды обновляет файл A и забывает файл B.

Также надо остерегаться «полезных» fallback-значений, которые тихо перекрывают переменные окружения. Дефолты — это нормально, но только когда они очевидны и безопасны. Если код делает «использовать ENV, если есть, иначе этот захардкоженный production URL», вы можете выпустить билд, который будет говорить с неверным бекендом.

Ошибки, которые чаще всего бьют сильнее всего:

• Переименование констант без обновления всех импортов/использований, что оставляет разное поведение
• Создание нескольких источников конфигурации (разные файлы, разные паттерны), которые со временем расходятся
• Жёстко заданные значения по умолчанию, которые тихо побеждают переменные окружения, особенно в production-билдах
• Обращение с секретами как с обычными константами (ключи API в файлах констант или закоммиченные .env)
• Слишком ранняя избыточная абстракция с уровнями конфигурации, которые никто не понимает во время инцидента

Если вы унаследовали AI-прототип и не уверены, не изменилось ли поведение после рефактора, именно это FixMyMess проверяет в аудитах: скрытые дубликаты, небезопасные дефолты и смешение секретов с константами.

Быстрый чеклист перед релизом рефактора

После централизования констант приложение может выглядеть чище, но всё ещё скрывать рискованные пробелы. Используйте этот быстрый чек перед мёрджем.

Проверка конфигурации

Сделайте тест «одного изменения». Возьмите значение, которое вы ожидаете менять позже (например базовый API-URL), поменяйте его в одном месте и подтвердите, что приложение использует новое значение повсеместно. Если вам всё ещё приходится искать по файлам — вы не централизовали по-настоящему.

Также убедитесь, что секреты не смешаны с обычными настройками. Конфиг может содержать безопасные дефолты, но всё чувствительное (ключи API, пароли баз данных, JWT-секреты) должно приходить только из переменных окружения. Если секрет в репозитории — он рано или поздно протечёт.

Короткий предполётный чеклист:

• Поменяли ключевую настройку (API base URL, webhook URL или CDN host) в одном месте и подтвердили, что всё приложение следует за изменением.
• Поискали оставшиеся литералы, которые нужно было назвать (таймауты вроде 30000, лимиты вроде 50, числа ретраев вроде 3).
• Убедились, что лимиты и таймауты имеют понятные имена и короткий комментарий (что это защищает и почему именно такое число).
• Проверили, что у фичевых флагов есть владелец, безопасный дефолт и план удаления для временных переключателей.
• Провели smoke-тест: войти, пройти основные экраны и вызвать хотя бы один путь ошибки (неверный пароль, отсутствующая запись, оффлайн).

Финальная проверка во время smoke-теста

Во время smoke-теста взгляните на логи или консоль. Если вы видите отсутствующую переменную окружения, неожиданный fallback-URL или переключатель по умолчанию в неправильную сторону — исправьте до деплоя.

Если вы унаследовали хрупкий AI-прототип и не уверены, где ещё может быть захардкоженное или небезопасное значение, FixMyMess (fixmymess.ai) может начать с бесплатного аудита кода, чтобы указать рискованные константы, раскрытые секреты и паттерны конфигурации, которые часто ломаются в продакшене.

Что делать дальше: поддерживать чистоту по мере роста приложения

Главная победа — не дать магическим константам вернуться. Малые команды быстро двигаются, и «ещё одно захардкоженное число» — это путь к разбросанным рискованным правкам.

Практический следующий шаг — короткий спринт по очистке, сфокусированный на константах, которые реально вам мешают. Не пытайтесь всё исправить. Выберите 10–20 значений, которые часто меняются или могут сломать продакшен при ошибке (таймауты, лимиты запросов, базовые URL, пороги цен, размеры загрузок), централизуйте их и выкладывайте маленькими порциями.

Внедрите одно простое правило для команды: новые важные значения должны иметь имя и место. Если значение явно не один раз (например индекс цикла), оно должно жить в модуле конфигурации или в файле констант.

Если ваш кодовая база сгенерирована AI и кажется хрупкой, экспертный аудит перед глубокими рефакторами может сэкономить много времени. Такие проекты часто скрывают рискованные константы вместе с более серьёзными проблемами: раскрытыми секретами, поломанными потоками аутентификации или небезопасными запросами к базе данных.