Rain Lag

Невидимый список дел в кодовой базе: как превратить TODO в настоящий роадмап

Ваша кодовая база полна скрытой работы в виде комментариев TODO и FIXME. Узнайте, как превратить эти невидимые заметки в видимый, приоритизированный роадмап с помощью автоматизации, трекера задач и командных процессов.

Невидимый список дел в вашей кодовой базе: как превратить TODO в настоящий роадмап

Большинство инженерных команд сидят на тихом бэклоге, который почти никто не признаёт: это TODO, FIXME и комментарии в духе «потом бы это улучшить», разбросанные по всей кодовой базе.

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

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

Проблема: невидимая работа, спрятанная в комментариях

Инлайн‑комментарии вроде // TODO: optimize this или # FIXME: handle nulls properly — это по сути управление проектом, только сделанное плохим способом.

Почему это проблема:

  • Они невидимы за пределами файла: пока никто не открыл конкретный файл, эта работа не существует ни в одном планирующем инструменте.
  • У них нет приоритета: «TODO: log errors» и «TODO: rewrite payment flow» выглядят одинаково, хотя влияние у них радикально разное.
  • У них нет владельца: в комментариях почти никогда не указано, кто и когда должен это сделать.
  • Их нельзя измерить: нельзя отслеживать прогресс по TODO, которых вы не видите, — техдолг тихо накапливается.

При этом сами комментарии ценны. В них попадает:

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

Цель не в том, чтобы запретить комментарии TODO/FIXME. Цель — системно поднять их до статуса полноценных задач.

Шаг 1. Сделать невидимый роадмап видимым

Первый шаг — осознанность: относитесь к комментариям как к данным.

1.1. Просканируйте кодовую базу на TODO/FIXME

Начните с простого поиска по репозиториям:

  • Используйте поиск по коду (например, GitHub, GitLab, Sourcegraph, ripgrep), чтобы найти:
    • TODO
    • FIXME
    • XXX или HACK (если ваша команда их использует)
  • Запустите поиск по всем репозиториям, чтобы увидеть скрытую работу во всей организации.

Уже это может открыть глаза:

  • Сколько TODO у вас вообще есть?
  • Где они концентрируются (сервисы, модули, языки)?
  • Есть ли явно опасные с точки зрения безопасности или надёжности комментарии?

1.2. Разбейте находки на категории

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

  • Баги и корректность работы: FIXME: off-by-one when month changes
  • Технический долг и рефакторинг: TODO: extract this into a separate service
  • Производительность и масштабируемость: TODO: avoid full table scan
  • Безопасность и соответствие требованиям: TODO: sanitize user input here
  • Разработческое удобство (DX): TODO: improve error messages
  • Продуктовые и фичевые идеи: TODO: support bulk operations

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

Шаг 2. Автоматически превращайте комментарии в задачи

Ручная конвертация каждого TODO в тикет — скучно и нереалистично. Вместо этого автоматизируйте поток «комментарий → роадмап».

2.1. Используйте CI или GitHub Actions для извлечения TODO

Вы можете настроить автопроцесс, который:

  1. Периодически сканирует кодовую базу на TODO/FIXME (например, каждую ночь) или при изменениях в main.
  2. Парсит комментарии и метаданные (файл, строка, автор, временная метка, контекст).
  3. Создаёт или обновляет задачи в вашем трекере (GitHub Issues, Jira, Linear и т.д.).

Минимум ваш скрипт или Action должны собирать:

  • Текст комментария
  • Путь к файлу и номер строки
  • Имя репозитория
  • Хэш коммита (чтобы можно было перейти к историческому контексту)

Пример комментария TODO в формате, удобном для парсинга автоматикой:

// TODO[security][P1]: Validate JWT audience claim before using it

Из него можно создать задачу с заголовком: «Validate JWT audience claim before use», с лейблами security, priority:high и ссылкой на исходный файл.

2.2. Не допускайте дублей задач

Чтобы не заспамить трекер:

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

Так ваш трекер задач остаётся единственным источником правды, а кодовый комментарий — локальным контекстом.

Шаг 3. Сделайте TODO полноправными участниками процесса

Когда TODO и FIXME превращаются в задачи, они перестают быть фоновым шумом и становятся управляемой работой.

3.1. Назначайте, оценивайте и приоритизируйте

Теперь, когда у каждого TODO/FIXME есть задача, вы можете:

  • Назначить владельца: больше никаких «кто‑нибудь когда‑нибудь это поправит».
  • Добавить контекст: прикрепить связанные инциденты, PR или документацию.
  • Оценить влияние: безопасность, UX‑косметика или производительность.
  • Приоритизировать на одном борде вместе с фичами.

Команды могут осознанно решать:

  • Какие TODO брать в каждый спринт
  • Какие критичные FIXME закрыть перед крупным релизом
  • Какой техдолг логично убирать «в попутку» вместе с доработкой фич

3.2. Встройте это в CI/CD

Можно пойти дальше и связать управление TODO/FIXME с пайплайном:

  • Падать или выдавать предупреждение на определённые теги: например, блокировать merge, если вносятся новые комментарии FIXME[security].
  • Закладывать бюджет на техдолг: отслеживать, какая доля ёмкости спринта уходит на задачи, появившиеся из комментариев.
  • Отслеживать динамику: мониторить количество открытых TODO/FIXME‑задач во времени как метрику здоровья.

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

Шаг 4. Регулярный триаж, чтобы выделять сигнал среди шума

Не каждый TODO достоин того, чтобы жить в трекере вечно. Часть из них устарела, сформулирована расплывчато или уже неактуальна.

4.1. Задайте ритм триажа

Добавьте регулярный ритуал, например:

  • Ежемесячный разбор TODO/FIXME внутри команды
  • Ежеквартальный кросс‑репо аудит для рисков по безопасности и надёжности

На таких сессиях команда:

  • Закрывает устаревшие задачи, где код уже изменился
  • Уточняет расплывчатые комментарии и перезаписывает их как понятные, исполнимые тикеты
  • Пересматривает приоритеты с учётом текущего роадмапа и инцидентов
  • Группирует связанные элементы в более крупные эпики по рефакторингу или улучшениям

4.2. Связывайте это с инцидентами и баг‑репортами

Всякий раз, когда вы проводите разбор инцидента (post‑incident review):

  • Ищите TODO/FIXME в затронутых областях кода
  • Линкуйте связанные задачи из комментариев к инциденту
  • Поднимайте приоритет у TODO, которые явно повлияли на инцидент или могут предотвратить похожие сбои

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

Шаг 5. Организационная видимость через кросс‑репо поиск

По мере роста кодовой базы по сервисам и репозиториям TODO и FIXME начинают сигнализировать о системных проблемах.

Используйте кросс‑репо поиск по коду, чтобы отвечать на вопросы:

  • Сколько TODO, связанных с безопасностью, существует во всех сервисах?
  • Какие репозитории больше всего насыщены комментариями FIXME?
  • Есть ли TODO про одну и ту же проблему, разбросанные по нескольким сервисам (например, обработка ошибок, feature flags, auth‑флоу)?

Имея видимость на уровне всей организации, вы можете:

  • Выявлять «горячие точки» техдолга и рисков
  • Обосновывать крупные рефакторинги или инвестиции в платформу
  • Замечать паттерны, которые не видны на уровне одного репозитория

Комбинируйте это с автоматизацией: кросс‑репо поиск подпитывает кросс‑репо создание задач, а вы получаете портфельный взгляд на скрытую работу.

Практичные соглашения, чтобы всё это работало

Чтобы масштабировать поток «комментарий → роадмап», введите лёгкие соглашения:

  1. Структурированный формат TODO

    • Пример: // TODO[area][priority]: понятное, исполнимое описание
    • Области: security, perf, ux, refactor, infra и т.п.

  2. Ссылка на задачу, если она уже есть

    • // TODO: see ISSUE-1234 for full context
    • Автоматизация может такие комментарии пропускать (задача уже существует).

  3. Правила, когда уместно писать TODO

    • Использовать TODO/FIXME только для работы, которую вы реально планируете сделать.
    • Для чисто спекулятивных идей лучше использовать документацию или продуктовый бэклог.

  4. Проверки в pull request‑ах

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

Эти простые привычки сильно повышают ценность работы, которая рождается из комментариев.

Польза: зачем относиться к TODO как к реальной работе

Когда вы начинаете считать TODO и FIXME полноправной работой, вы получаете накопительный эффект:

  • Более быстрый и осознанный возврат техдолга
    Долг перестаёт быть туманом — он превращается в бэклог с владельцами и приоритетами.
  • Меньше регрессий и сюрпризов в проде
    Важные FIXME больше не живут забытыми в тёмных уголках кода.
  • Постепенное улучшение качества кода
    TODO закрываются в рамках планирования, а не только во время «недель уборки».
  • Лучшее соответствие кода и роадмапа
    Работа, которую инженеры видят в коде, совпадает с тем, что они видят на борде.
  • Организационная видимость рисков
    Лидеры понимают, где сконцентрированы риски по безопасности, производительности и надёжности.

Главное — вы переходите от реактивного управления долгом («когда‑нибудь надо будет это почистить») к проактивному, измеримому подходу.

Вывод: превратите шёпот в коде в настоящий план

Ваша кодовая база уже содержит набросок карты: где больно, где хрупко и где можно сделать лучше. Эта карта спрятана в крошечных, легко игнорируемых комментариях: TODO, FIXME, HACK.

Вместо того чтобы давать этим заметкам медленно сгнить:

  1. Поднимите их на поверхность с помощью кросс‑репо поиска.
  2. Автоматизируйте перенос в задачи через CI или GitHub Actions.
  3. Сделайте их полноправными элементами планирования, владения и приоритизации.
  4. Регулярно пересматривайте и триажируйте, чтобы сохранять высокий сигнал.

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

Невидимый список дел в кодовой базе: как превратить TODO в настоящий роадмап | Rain Lag