Кэш знаний
Антипаттерн кэша знаний
Ты извлёк из кодовой базы архитектурные знания с помощью агента: аккуратные диаграммы, полную документацию API, подробные связи компонентов. Ты сохраняешь их в ARCHITECTURE.md и коммитишь. Теперь у тебя проблема инвалидации кэша: код меняется (всегда), документация — нет (обычно), а будущие агенты находят и то и другое при исследовании кода. Диаграмма ниже показывает расхождение.
Как только ты коммитишь извлечённые знания, каждое изменение кода требует обновления документации, о котором ты забудешь. Исходный код — твой единственный источник истины: инструменты исследования кода (ChunkHound, семантический поиск, Explore) каждый раз динамически извлекают архитектурные знания, свежие и точные. Различие такое: знания о том, КАК всё устроено (детали реализации, потоки данных, связи компонентов), дублируют код — исследование кода восстанавливает их по требованию. Знания о том, ПОЧЕМУ всё так устроено (отвергнутые альтернативы, бизнес-обоснования, обязательные нормативные требования), в коде не выразить. Коммить ПОЧЕМУ в виде записей о решениях: коротких документов, фиксирующих, что решено, почему и какие альтернативы отклонены. Оставь КАК инструментам исследования кода.
Главные выводы
- Избегай антипаттерна кэша знаний — инструменты исследования кода каждый раз динамически извлекают архитектурные знания из исходников. Сохранение извлечённых знаний в файлы .md создаёт ненужные кэши, которые устаревают. Коммить ПОЧЕМУ в виде записей о решениях; оставь КАК исследованию кода.