На Hacker News развернулось обсуждение, которое знакомо каждому инженеру, присоединившемуся к стартапу на стадии роста: как сделать legacy-код, написанный «на коленке» (vibe-coded), читаемым не только для человека, но и для AI-агентов? Автор поста — первый инженер в двухлетнем стартапе, который унаследовал MVP, созданный CTO в Lovable. Сейчас команда расширяется, и встаёт вопрос: как AI-агенты не будут «ломать» код при каждой правке?
Проблема: три кита legacy-хаоса
Автор выделяет три ключевые проблемы, знакомые многим:
— Дублирование бизнес-логики. Отсутствие единого источника истины (single source of truth) и плохое разделение ответственности.
— «Зомби-таблицы» и колонки. Схема базы данных разрослась, многие сущности выглядят рабочими, но на деле не используются или содержат устаревшие данные.
— Неявные зависимости. Изменение в одном месте требует каскада правок в других, но отследить это можно только вручную. Это классическая проблема высокой связанности (high change coupling).
Решение: не рефакторинг, а база знаний
Вместо тотального рефакторинга (который может занять месяцы), автор предлагает более прагматичный путь: документировать код и хранить эту документацию как структурированную базу знаний для AI-агентов. Основная идея — дать агентам контекст: известные пробелы, ограничения, принятые решения, бизнес-логику и карту зависимостей.
Автор ссылается на статью от Meta, которая описывает схожий подход. Суть в том, чтобы AI-агент не просто видел код, но и понимал, «почему это написано так», и «где ещё нужно поменять, если я трону это поле».
Как это может работать на практике
— Индексация графа кода. Инструменты вроде codebase graph indexer позволяют построить карту зависимостей между файлами, функциями и таблицами.
— Создание «knowledge base». В эту базу попадают не только комментарии из кода, но и явно прописанные бизнес-правила, известные баги и контекст принятия решений.
— Подача контекста AI-агенту. При генерации кода или рефакторинге агент получает не только фрагмент кода, но и сопутствующую документацию.
Ограничения и риски
— База знаний должна быть живой. Если документация не обновляется синхронно с кодом, она станет дезинформацией.
— Не заменяет рефакторинг. Документирование хаоса не устраняет хаос. Это временная мера для ускорения работы AI-агентов.
— Затраты на создание. Первоначальная работа по документированию может быть сопоставима с небольшим рефакторингом.
Один из комментаторов на HN (PaulHoule) отмечает, что проблема схожа с очисткой кода для человека: если код выдаёт бессмысленные ошибки, AI тоже не сможет с ним работать. В его примере с TypeScript-проектом ушло два дня на то, чтобы просто разобраться в ошибках вместе с AI.
Итог
Подход с созданием базы знаний для AI-агентов — это прагматичный компромисс между скоростью и надёжностью. Он не лечит корень проблемы (плохой код), но позволяет AI-агентам работать осмысленно, не плодя новые баги. Для стартапов, где время дороже идеального кода, это может быть оптимальным первым шагом.
Источники
— Оригинальное обсуждение на Hacker News: https://news.ycombinator.com/item?id=49698073
— Статья Meta по теме (упомянута автором): ссылка не приведена в исходном материале, но рекомендуется найти по ключевым словам «Meta codebase knowledge base AI agents».