Как превратить хаос вашего кода и документации в управляемый граф знаний за 1 день: кейс Graphify

Я — Denis Shokhirev, архитектор агентных AI-систем из Фрайбурга. В DennisCraft AI Studio я внедряю и сопровождаю автономные multi-agent системы для B2B DACH-клиентов. Мой стек: Claude, Supabase, n8n, Doppler, self-hosted Postgres. Два месяца назад пришлось экстренно чинить цепочку, когда документация, архитектурные диаграммы и код перестали совпадать — из-за этого агент ошибочно трижды запросил устаревший API-метод в проде.

Почему хаос в коде и знаниях — не абстракция, а угроза SLA

В реальности у большинства инженеров кодовая база и документация живут раздельной жизнью. Каждый релиз — новый слой хаоса. Даже если есть Swagger, Confluence, README, в критический момент никто не знает, какой endpoint реально деплоится. В одной из интеграций у меня обнаружилось 6 конфликтующих описаний одного и того же метода: в .py, в OpenAPI, в Notion и устаревшем PDF. Один агент, оперируя на этих данных, уронил критичный процесс на стороне клиента.

Согласно ACM Queue, 2004, 40% production-bugs связаны с устаревшей или неполной документацией. Даже спустя 20 лет ситуация не изменилась: LLM-агенты, интеграции, автоматизированные пайплайны только ускоряют накопление разнородных знаний и ошибок.

Граф знаний как антивирус хаоса: что я делаю

Что такое управляемый граф знаний

Граф знаний — это не модный термин, а практичная структура: узлы (entities) — функции, классы, API, бизнес-правила. Рёбра — связи: «вызывает», «документирует», «обновляет», «ссылается». Такой граф можно запрашивать: «Какие endpoints реально задеплоены и где они описаны?»

Почему 1 день — реально

Сложные решения типа Neo4j или облачных managed-graph не нужны. Я строю граф на Supabase Postgres, используя pgvector для embedding-сходства и обычные таблицы для хранения связей. В качестве ETL — n8n (для вытаскивания кода, docstrings, markdown), Claude Code для структурирования, semgrep для статического анализа.

import openai
import psycopg2

def extract_functions(file_path):
    with open(file_path) as f:
        code = f.read()
    # semgrep для поиска функций
    # ... (здесь можно использовать subprocess)
    return functions_list

def insert_to_pg(functions):
    conn = psycopg2.connect(dbname="graphify", ...)
    with conn.cursor() as cur:
        for func in functions:
            cur.execute(
                "INSERT INTO nodes (type, name, source) VALUES (%s, %s, %s)",
                ('function', func['name'], func['file'])
            )
    conn.commit()

Пошаговый pipeline: как я строю граф знаний

1. Извлечение артефактов

• Кодовые файлы: парсинг через semgrep + AST
• Документация: вытаскиваю markdown и docstrings с помощью n8n
• API-описания: OpenAPI, если есть; иначе парсинг ручками

2. Нормализация и унификация

Claude Code API приводит всё к единому формату: тип, имя, описание, связи. Для сложных случаев — кастомный промпт, чтобы извлекать бизнес-логику из "человеческих" описаний.

3. Загрузка в граф

В Supabase (Postgres) таблицы: nodes (id, type, name, source, embedding), edges (from_id, to_id, relation). Для embedding — pgvector и модель из OpenAI cookbook.

curl -X POST 'https://api.openai.com/v1/embeddings' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"input": "get_user_profile", "model": "text-embedding-ada-002"}'

4. Запросы и аудит

Теперь можно за 5 секунд узнать: где задекларирован endpoint, где реально реализован, кто последний менял. Любой агент — или человек — может по API делать быстрые запросы к структуре знаний.

def find_conflicts(pg_conn):
    # Находим endpoints, описанные в доке, но не реализованные в коде
    with pg_conn.cursor() as cur:
        cur.execute("""
            SELECT d.name FROM nodes d
            LEFT JOIN nodes c ON d.name = c.name AND c.type='function'
            WHERE d.type='doc' AND c.id IS NULL
        """)
        return cur.fetchall()

Сравнение подходов: старые методы vs граф

FAQ

Как быстро поднять граф знаний?

Минимальный MVP — за 1 рабочий день, если кодовая база не превышает 1000 файлов. Достаточно Supabase, n8n, semgrep и одного Claude API-ключа.

Это не усложнит пайплайн?

Нет — наоборот, граф становится центральной точкой правды. Любой новый агент или интеграция сразу подключаются к актуальной структуре.

Как поддерживать актуальность?

n8n запускает обновление при каждом push в main. Появляется новый код/док — граф обновляется автоматически.

Безопасно ли хранить граф в облаке?

Я храню только метаданные, без исходного кода. Для чувствительных данных — отдельный self-hosted Postgres, никаких внешних API.

Можно ли масштабировать под microservices?

Да — схема легко расширяется: каждый сервис — отдельный подграф, связи между сервисами задаются через edges.

У вас сейчас документация и код расходятся хотя бы на одном критичном сервисе? Сколько production-ошибок это уже стоило? Напишите, как у вас решено с аудитом знаний — через граф или по-старинке? Я бесплатно провожу 30-мин аудит стека для DACH-команд, внедряющих AI в регулируемых рынках. Пишите в LinkedIn или @ger_dennis_ai.