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» перечислены четыре практических направления для репозитория, который вы скармливаете агенту:
- Parameterized functions: дефолт вместо антипаттерна с
TODOв теле. - Environment variables with fallbacks: например
os.environ.get(..., "example-project-id")иwarnings.warnпри дефолте. - Real fixtures: публичные read-only ресурсы для Hello World без detour в provisioning.
- 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).