Устаревшая документация хуже, чем её отсутствие — она отравляет контекст 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 меняет мышление разработчика, и почему это может быть опаснее, чем ошибки в генерации кода.
Автор: VsBirdEye
