Перейти к содержимому
Экосистема AI Vibe

Разборы

TODO в примерах кода: три формата и одна ловушка для агентов

Редакция 5 ноября 2026 г.

TODO в примерах кода: три формата и одна ловушка для агентов

Три формата сниппета в README (вызов функции, автономный скрипт, декларативный конфиг) задают для агента разные контракты, а фрагмент в репозитории должен либо стартовать, либо упасть предсказуемо. Jennifer Davis (Staff Engineer, Google) в статье про sample architecture связывает привычку TODO с неполным кодом для агентов; соло-разработчику без техписа сниппет в README это часть контекста агента в IDE, его нельзя оставлять «на дособирание».

Когда «скопировал и допилил» ломает и человека, и агента

Классический антипаттерн: закомментированный placeholder вроде instance_id и вызов storage.Client(instance_id) без определённой переменной. Человек копирует блок и вручную дособирает его (copy-paste-compleatable). Модели и автономные агенты часто повторяют те же закомментированные строки или подставляют выдуманные значения; на выходе блоки, которые «должны были работать из коробки», но не работают.

В автономных сценариях агент может исчерпать лимит повторов, тихо сдаться и уйти к другой платформе: отток умножается не из-за API, а из-за дыр в документации. Отдельная ошибка, затенение переменных: TODO внутри тела функции и локальные переменные после «раскомментируй» перекрывают параметры и ломают контракт сигнатуры.

TODO(developer) в публичных samples размывает бинарный gate: в инженерии TODO уже lint failure, а в доке остаётся «легальной» заглушкой.

Исполняемые контракты: что меняется для агентов

Привычку TODO Jennifer Davis противопоставляет цели исполняемых контрактов (Executable Contracts). В таблице измерений для samples с контрактами целятся в успешный первый запуск или понятную ошибку auth API; входы задают явные параметры или env; CI опирается на обычные unit tests; для агентов нужны «clean, production-ready functions» вместо broken stubs.

Три целевых паттерна:

  • Copy-paste-callable: функция с явными аргументами и docstring.
  • Copy-paste-runnable: автономный скрипт с env и безопасными fallback через warnings.
  • Префикс example- (example-bucket, example-dataset) как «blast shield», если агент выполнит код вслепую.
# Антипример: TODO внутри create_cluster() и shadowing параметров
# Целевой образ: create_cluster(project_id: str, location: str = "us-central1")

Модели обучаются на legacy-стиле TODO(developer); плохой sample масштабирует тот же стиль в генерацию неполного кода. Это не «косметика доки», а сигнал для ассистентов и автономных агентов.

Три ситуации, где к TODO тянутся авторы

Jennifer Davis разводит три типа контекста; каждый задаёт другой контракт для агента, который видит только фрагмент:

Ситуация Что нужно агенту вместо TODO
Фрагмент внутри функции Явные параметры и docstring (скопировал и вызвал)
Скрипт верхнего уровня на Python/JS, ноутбуки Переменные окружения и безопасные значения по умолчанию (скопировал и запустил)
SQL, Terraform, декларативные конфиги Предсказуемые литералы-примеры или публичные фикстуры только для чтения

Закомментированный код плохо тестируется: нужны сложные test wrappers, а в Go, Java, C# нельзя инжектить scope; modern JavaScript (ESM) не даёт runtime injection вокруг top-level imports. Sample без исполняемого контракта не пройдёт ни CI, ни автономный прогон в IDE.

Куда двигать sample architecture в репозитории

В блоке «Where I Want Us to Go» перечислены четыре практических направления для репозитория, который вы скармливаете агенту:

  1. Parameterized functions: дефолт вместо антипаттерна с TODO в теле.
  2. Environment variables with fallbacks: например os.environ.get(..., "example-project-id") и warnings.warn при дефолте.
  3. Real fixtures: публичные read-only ресурсы для Hello World без detour в provisioning.
  4. Automation: checks, падающие на TODO в sample folder.

В комментариях Dev.to Arjun Sharma допускает исключение для teaching samples, когда важна структура, а не вызов. Jennifer Davis отвечает: syntactically valid placeholders (строка "example-project-id"), graceful runtime failure на auth или missing resource, то есть не compile-time ловушка и не пустой stub для агента.

Если в соло-workflow агент правит docs и код параллельно, имеет смысл держать samples в том же стандарте, что и production: один провал CI на TODO в demo-папке дешевле, чем серия галлюцинированных патчей после copy-paste из README.

Источники

  • Jennifer Davis (sigje), «Stop putting TODO comments in sample code», Dev.to (дата доступа при обогащении: 2026-11-05 UTC).