Система самоподдерживающейся документации с использованием изолированных блоков для нулевого расхождения

Разработчик на r/ClaudeAI поделился решением для поддержания точной документации в многопроектных рабочих пространствах, где ИИ-агенты для программирования, такие как Claude Code, забывают контекст между сессиями. Система решает проблемы с 8 проектами, 20 Lambda-функциями, 42 API-ключами, 12 API-эндпоинтами и 19 переменными окружения, когда агент угадывал названия функций, редактировал не те файлы и терял контекст.

Система ограждений

Вместо того чтобы просить Claude обновлять документацию после реализации, разработчик создал 740-строчный bash-скрипт, который извлекает структурированные данные непосредственно из исходных файлов и вставляет их в CLAUDE.md через ограждённые HTML-комментарии. Каждый CLAUDE.md имеет ограждения, отмечающие автоматически генерируемые разделы:

## Serverless Functions <!-- auto:lambdas generated="2026-03-26" source="infrastructure/lib/api-stack.ts" -->
| Function | Route | Memory | Timeout |
|----------|-------|--------|---------|
| quote-save | /quotes/save | 256MB | 15s |
| quote-get | /quotes/get | 256MB | 15s |
...20 rows extracted from CDK config...
<!-- /auto:lambdas -->

## Architecture <-- hand-written, never touched by the script

Как это работает

Скрипт:

• Парсит реальные исходные файлы (CDK TypeScript, FastAPI Python, package.json и т.д.)
• Извлекает структурированные данные (названия функций, маршруты, переменные окружения, версии зависимостей)
• Заменяет всё между ограждениями
• Обновляет дату генерации, чтобы показать актуальность
• Проверяет: убеждается, что каждое имя Lambda имеет соответствующий файл-обработчик, каждая переменная окружения существует в .env

Разделы, написанные вручную (описания архитектуры, подводные камни, контекст бизнес-логики), находятся вне ограждений и никогда не затрагиваются.

Автоматически генерируемый контент

• Инструмент цитирования (20 Lambda): Инвентарь Lambda, CDK-стэки, переменные окружения, количество тестов, зависимости из CDK TypeScript и package.json
• Панель продаж (12 эндпоинтов): API-маршруты, список тем, зависимости из декораторов FastAPI, TypeScript-типы и requirements.txt
• Парсинг данных (42 пользователя): Данные пользователей, зависимости из файла учётных данных Python и requirements.txt
• 5 других проектов: Версии зависимостей из package.json/requirements.txt

Система предупреждений об устаревании

Хук синхронизации документации (срабатывает после каждого редактирования кода) проверяет дату генерации на каждом ограждении. Если какой-либо раздел старше 7 дней:

Warning: 3 auto-generated sections in agent-quoting-tool/CLAUDE.md are stale (oldest: 2026-03-19).
Run: ./scripts/generate-inventory.sh quoting

Это неблокирующее действие — предупреждает, но никогда не мешает работе. Проверка устаревания работает параллельно с существующими хуками в том же 10-минутном интервале регулирования, без дополнительной нагрузки.

Детали реализации

Настройка использует чистый bash с grep/sed/awk/jq, без зависимостей. Команды:

scripts/generate-inventory.sh all # Обновить всё
scripts/generate-inventory.sh quoting # Только один проект

Скрипт сначала создаёт резервную копию каждого CLAUDE.md (одна копия в день на проект). Разработчик отмечает, что не стоит парсить AST из bash — их парсер TypeScript представляет собой построчный цикл grep/sed, который работает для контролируемых файлов, но был бы ненадёжным для произвольного TypeScript.

Ключевые идеи

Ограждения позволяют автоматически генерируемому и написанному вручную контенту сосуществовать в одном файле. Claude читает весь CLAUDE.md в начале сессии и получает и точные извлечённые данные, и человеческий контекст, который он не может вывести из кода. Разработчик рекомендует начинать с самых ценных извлечений (инвентари Lambda и таблицы переменных окружения, которые вызывают ошибки при расхождении) и отмечает, что предупреждение об устаревании ценнее, чем автоматический запуск.

Вся система заняла около 3 часов на создание (проектирование, реализация, тестирование, первый запуск).