Устаревшая документация хуже, чем её отсутствие — она отравляет контекст LLM. Агент доверяет тому, что видит. Garbage in — garbage out, только garbage выглядит как аккуратный markdown.

Это вторая часть серии. Первая часть — «Слепое пятно LLM-разработки: контекст за пределами кода».

Проблема: энтропия документации

В первой части я описал workbench — централизованную knowledge base, подключаемую вторым корнем в IDE. Архитектура, реестр, ADR, иерархия правил. Но у любой документации есть фундаментальное свойство: она начинает устаревать с момента написания.

При десятках параллельно развивающихся проектов каждое изменение потенциально делает неактуальным что-то в knowledge base. Стратегический план ссылается на версию сервиса, которая уже трижды обновилась. Реестр проектов показывает статус, изменившийся две недели назад. Агент читает всё это, принимает за актуальное и ориентируется по карте, которая больше не соответствует реальности. Отсюда — ошибки, которых могло бы не быть.

Проблема не в недостатке дисциплины — это вопрос масштаба. Сотни документов, десятки проектов, непрерывный поток изменений. Ручное поддержание актуальности не масштабируется. Нужны два механизма: автоматическое обнаружение устаревания и поведенческие правила, которые не дают ему накапливаться.

В этом проявляется закономерность, выходящая за пределы конкретной проблемы устаревания. Переход к LLM-разработке напоминает пересадку с автомобиля с механической коробки передач на электромобиль с автопилотом высокого уровня автономности. Детали технического процесса — руль, сцепление, газ — перестают быть узким местом. Машина едет быстро и самостоятельно. На первый план выходит другое: куда ехать, зачем и какой дорогой. LLM забирает значительную часть ручной, технической работы — и принципиально повышает значимость методологии: организации процесса, верификации результатов, управления контекстом. Эта статья — о гигиене контекста: как поддерживать knowledge base в состоянии, которому LLM может доверять.

Автоматические проверки

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

Каждая из этих проверок по отдельности тривиальна, ценность — в их систематичности. При первом запуске на моём workbench скрипт обнаружил, что больше трети внутренних ссылок ведут в никуда — наследие миграции документов из разных репозиториев. Это те самые места, где агент пытается перейти по ссылке, не находит документ и либо молча игнорирует контекст, либо галлюцинирует.

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

Пример вывода при первом запуске на реальном workbench:

$ ./tools/validate.sh
[markdown links]
  WARN:  broken link in domains/infra/topology.md -> decisions/adr_007.md
  WARN:  broken link in projects/api/architecture.md -> ../shared/schema.md
  INFO:  42 broken link(s) out of 189 checked

[document freshness — threshold 60d]
  WARN:  stale (87d): projects/data-pipeline/architecture.md
  INFO:  1 document(s) exceed freshness threshold

[project coverage]
  OK:    all projects have workspace files

=== Result ===
  Errors: 0 | Warnings: 43 | Info: 2

Похожий по духу скрипт агрегирует TODO-items из всех markdown-файлов. В документах рассыпано множество незакрытых задач — в планах, бэклогах, иногда в логах сессий. Без агрегации нет единой точки, откуда можно увидеть полную картину: что нужно сделать по деплою, по CI, по конкретному проекту.

Реализация — два bash-скрипта суммарно на ~300 строк, исходники на GitHub.

Жизненный цикл документов

Не все документы стареют одинаково. Стратегический план обновляется еженедельно. Описание протокола — при его изменениях. Post-mortem инцидента — никогда, и это нормально.

Разделение на четыре статуса — active, reference, draft, archived — решает эту задачу для агента. Агент не отличает свежий план от трёхмесячного артефакта, если оба лежат в одной папке без надёжных метаданных. Явный статус и дата в заголовке каждого документа дают агенту четкую информацию.

Архивирование — не удаление. Документ перемещается в подкаталог archive/, где он доступен для контекста, но не смешивается с актуальными материалами. Git history не заменяет этого: в истории документ невидим для агента без целенаправленного поиска, в archive/ — видим, но помечен как устаревший.

Дисциплина в cursor rules

Инструменты обнаруживают проблему, но не решают её. Решает — поведение. В моих глобальных cursor rules (которые действуют во всех workspaces) закреплены три принципа, каждый из которых родился из конкретного класса ошибок.

Первый: после завершения фазы работы агент обновляет связанные документы в workbench — статусы, метрики, бэклоги — и выдаёт список: что осталось, что обнаружено, что требует внимания. Без этого правила агент закончит задачу, а knowledge base останется в прошлом состоянии. Следующая сессия стартует с устаревшими данными — именно тот класс проблемы, с которого начинается эта статья.

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

Третий: планы обновляются при каждом изменении, в той же сессии, а не «потом». Устаревший план — это тот же отравленный контекст, только с виду безобидный.

Ловушки мета-оптимизации

Всё описанное выше — валидация, жизненные циклы, дисциплина сессий — звучит как выстроенный процесс. Но именно здесь начинается самый опасный анти-паттерн solo-разработки с LLM: оптимизировать процесс разработки вместо разработки.

LLM делает автоматизацию дешёвой. Написать скрипт — минуты. Задокументировать процесс — минуты. Соблазн автоматизировать всё — огромный, и именно он убивает продуктивность.

Вот как это выглядит на практике. Месяцы уходят на инфраструктуру для задачи, которая ещё ни разу не была решена вручную: оркестратор микросервисов — а ни одного сервиса в production нет. Или наоборот: десять документов описывают архитектуру фичи, но в коде — ноль. LLM делает планирование настолько дешёвым, что легко убедить себя: «я же работаю — я пишу план». На самом деле это прокрастинация в формате markdown.

Здесь проявляется свойство LLM, которое глубже, чем кажется: он придаёт убедительную форму любому контенту. Недавно на Хабре была статья с формулами, кодом и наукообразной методологией, в основе которой лежала физически абсурдная идея. Текст выглядит настолько профессионально, что люди всерьёз тратят время на аргументированные опровержения в комментариях — потому что с первого взгляда непонятно, нестандартная ли это гипотеза или наукообразно оформленный бред. По сути — новая форма троллинга.

Когда LLM позволяет облечь любую идею в убедительную форму — критерий «выглядит профессионально» перестаёт быть сигналом качества. Это касается и собственной работы: план, написанный с помощью LLM, выглядит как работа. Инфраструктура, спроектированная с помощью LLM, выглядит как прогресс. Отличить деятельность от результата становится сложнее, чем до появления этих инструментов.

Или ещё: невозможность начать работу, пока все предпосылки не выполнены. Все типы конвертированы, все тесты написаны, все файлы декомпозированы — и вот три дня ушли на типизацию вместо того, чтобы выкатить первую версию с тем, что есть. LLM охотно поддерживает эту иллюзию: «конечно, сначала нужно добавить типы, потом тесты, потом рефакторинг…»

Отдельная ловушка — переоценка ROI автоматизации. Десять часов на скрипт, который будет использован пять раз. Формально: (50 минут экономии × 5 использований) / (600 минут инвестиции) = 0.42x. Потрачено больше, чем сэкономлено. Люди систематически завышают ожидаемое число использований и занижают реальную стоимость разработки.

Все эти паттерны объединяет одно: чем дешевле инструменты, тем легче заниматься инструментами вместо работы.

Дистанция от результата

Для ориентации в этом пространстве помогает простая иерархия: насколько далека текущая активность от практического результата.

На одном полюсе — прямой результат: работающий продукт, приносящий измеримую пользу. На шаг дальше — опорные системы, без которых качественный результат невозможен: staging-окружение, мониторинг, CI/CD. Ещё дальше — ускорители разработки: статическая типизация, тесты, cursor rules, сам workbench. Затем — мета-ускорители: локальный LLM-кластер, автоматизация LLM-workflow. И наконец — мета-уровень: рефлексия о самом процессе, переосмысление подхода.

Последний уровень неоднозначен. Большая часть времени, проведённого здесь, — это чистые потери: оптимизация оптимизации, не приносящая измеримого результата. Но именно на этом уровне рождаются концептуальные сдвиги, которые меняют всё остальное. Version control, CI/CD, сам подход test-driven development — всё это когда-то было мета-мета, прежде чем стать нормой. Опасность не в том, чтобы иногда оказываться на этом уровне, а в том, чтобы застрять на нём, перепутав рефлексию с работой.

Ориентир простой: на каждом уровне не более 30% времени уходит на работу следующего, более далёкого от результата уровня. Если больше половины времени уходит на ускорители и мета-ускорители — это тревожный сигнал.

Workbench — это ускоритель. Cursor rules — ускоритель. Эта статья — мета-мета. Возможно, кому-то из читателей она поможет пересмотреть свой подход к LLM-разработке, и тогда это окажется оправданным. Но я отдаю себе отчёт: прямо сейчас она не приближает ни одну задачу в production. Впрочем, делиться наработками — тоже форма ценности: чужой опыт, переведённый в оформленное знание, экономит другим месяцы проб, которые автор уже прошёл.

Зрелость автоматизации

Связанное наблюдение: автоматизация работы с LLM проходит через уровни, и перепрыгивать их — типичная ошибка. Сначала ты ставишь задачу агенту и ревьюишь результат. Когда ревью стабильно проходит без серьёзных правок, а CI ловит регрессии — можно давать агенту больше автономии. И только когда автономный цикл стабилен — есть смысл строить pipeline.

Типичная ошибка: пытаться автоматизировать полный цикл «гипотеза → генерация → деплой» (верхний уровень), когда CI не блокирует merge при сломанных тестах (базовый уровень не пройден). Каждый уровень имеет предпосылки, и без них следующий не работает — он только создаёт иллюзию прогресса.

Что это стоило

Создание workbench: примерно день. Подключение проектов и написание скриптов валидации: ещё день. Ретроспективные ADR по ключевым решениям: около часа. Суммарно — порядка двух дней инвестиций.

Окупаемость — в течение первой недели. Каждая LLM-сессия стартует быстрее на 3-5-10 минут, что при нескольких сессиях в день суммируется в существенную экономию. Но важнее, чем время, — качество: агент принимает решения на основе актуального контекста, а не на основе того, что было актуально два месяца назад.

Вместо заключения

Workbench — не серебряная пуля. Это дисциплина, обёрнутая в структуру папок и несколько bash-скриптов. Агент не станет умнее от того, что рядом лежит документация. Он станет умнее от того, что документация актуальна, структурирована и предсказуема.

Но сама по себе эта дисциплина — ускоритель, не результат. Инвестировать в контекст имеет смысл ровно в той мере, в которой это ускоряет работу, приносящую практический результат. Не больше.

—

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