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

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

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

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

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

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

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

Простой скрипт валидации, запускаемый вручную или в CI, проверяет три аспекта:

• Целостность внутренних ссылок — не ведут ли они в никуда.
• Свежесть ключевых документов — по дате последнего обновления (порог — 60 дней).
• Покрытие — есть ли у всех проектов workspace-файл, через который агент получает доступ к документации.

При первом запуске скрипт выявил, что более трети внутренних ссылок — битые. Это наследие миграций из разных репозиториев. В таких местах агент либо игнорирует контекст, либо галлюцинирует.

Проверка свежести не требует переписывания документа — достаточно ревизии: проверить версии, статусы, зависимости, обновить дату. Это занимает минуты, но возвращает документу доверие.

Другой скрипт агрегирует TODO-задачи из всех markdown-файлов. Без агрегации нет единой точки для отслеживания задач по деплою, CI или проектам. Реализация — два bash-скрипта на ~300 строк, исходники доступны на GitHub.

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

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

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

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

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

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

• Обновление документации после завершения фазы — агент обновляет статусы, метрики, бэклоги и выдаёт список оставшихся задач. Без этого знания остаются в прошлом, и следующая сессия стартует с устаревшим контекстом.
• Формирование continuation prompt — при приближении к лимиту контекста агент не останавливается, а передаёт: что сделано, текущее состояние, следующие шаги. Новая сессия продолжает с места остановки.
• Обновление планов в той же сессии — при любом изменении. Устаревший план — это отравленный контекст, даже если он выглядит аккуратно.

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

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

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

Примеры:

• Месяцы уходят на оркестратор микросервисов, хотя ни одного сервиса ещё нет в production.
• Десять документов описывают архитектуру фичи, но в коде — ноль.
• Три дня уходят на типизацию, вместо того чтобы выкатить первую версию.

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

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

Чем дешевле инструменты, тем легче заниматься ими вместо работы.

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

Ориентир — иерархия близости к практическому результату:

• Результат — работающий продукт, приносящий пользу.
• Опорные системы — staging, мониторинг, CI/CD.
• Ускорители — типизация, тесты, cursor rules, workbench.
• Мета-ускорители — локальный LLM-кластер, автоматизация workflow.
• Мета-уровень — рефлексия, переосмысление подхода.

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

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

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

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

Автоматизация с LLM проходит уровни, и перепрыгивать их — ошибка:

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

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

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

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

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

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

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

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

Устаревшая документация хуже, чем её отсутствие — она отравляет контекст 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:

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