Beadloom

Read this in other languages: English

Beadloom — это источник правды о вашем коде: его архитектуре, контрактах и документации.

Он следит, чтобы всё это не расходилось с кодом, и подсвечивает то, что устарело. В основе лежит запрашиваемый граф, выведенный из самого кода, а поверх него строятся инструменты — межсервисная федерация, проверки целостности, агентный процесс разработки и многое другое. А единый Gate не пропускает в main ни нарушения архитектурных границ и правил, ни код с устаревшей или отсутствующей документацией, ни сломанные контракты — одинаково для людей и для агентов.

Это один бесплатный инструмент под лицензией MIT, без облака: один CLI и один файл SQLite. Граф живёт в Git рядом с кодом, поэтому знание об устройстве системы переживает смену команды, а не уходит вместе с людьми.

📖 Портал документации: zoologov.github.io/beadloom — интерактивная архитектура, дашборд метрик и актуальная документация.

Платформы: macOS, Linux, Windows  |  Python: 3.10+

---

В основе — граф

Всё, что делает Beadloom, опирается на одну структуру данных: архитектурный граф вашей системы. Граф поднимается из самого кода (beadloom init --bootstrap), живёт в Git как YAML и при каждой переиндексации сверяется с реальными исходниками. К нему можно обращаться с запросами, и на один и тот же вопрос он всегда отвечает одинаково — это обычные данные, которые можно проверять и версионировать.

Граф держат честным три составляющие:

1. Context Oracle — обход графа отдаёт по любому узлу детерминированный пакет контекста меньше чем за 20 мс: код, документация и действующие правила.
2. Doc Sync Engine — знает, какая документация какой код описывает, и ловит расхождение на каждом коммите. Исключает ситуации «в спецификации одно, в коде другое».
3. Architecture Rules — границы и правила в YAML, которые проверяет beadloom lint. Граница соблюдается при сборке, а не «на ревью, если кто-то заметит».

Для ИИ-агента те же три составляющие собираются в один пакет меньше 2K токенов командой beadloom prime — вместо привычного цикла «grep, чтение, догадка». Через MCP агент получает тот же контекст и те же правила для участка, над которым работает, поэтому держится внутри ваших архитектурных границ по умолчанию.

	Семантический поиск (IDE)	Beadloom
Отвечает на	«Где этот класс?»	«Что это за функционал и как он вписан?»
Метод	Эмбеддинги и ранжирование моделью	Явный граф и обход
Результат	Вероятностный	Детерминированный
Документация	Не следит за свежестью	Ловит устаревшую на каждом коммите
Границы	Не проверяет	Соблюдает, блокирует нарушения
Знание	Умирает вместе с сессией	Живёт в Git, переживает смену команды

Поверх графа — инструменты

На том же графе Beadloom строит инструменты, которые работают с системой целиком:

• Межсервисная федерация. Графы отдельных репозиториев объединяются в общий ландшафт, где Beadloom сверяет, что каждый сервис обещает отдавать, против того, что его потребители на самом деле используют.
• Настраиваемый, не зависящий от инструмента агентный процесс. beadloom setup-agentic-flow собирает многоагентный процесс (dev → test → review → tech-writer) и пишет адаптеры для Claude Code и Cursor на равных.
• Опубликованная база знаний. beadloom docs site собирает портал (VitePress) — дашборд метрик, интерактивная архитектура, карта ландшафта и документация с отметкой актуальности.

Единый Gate

Проверки документации, границ и контрактов сходятся в один Gate. beadloom ci прогоняет полный набор — reindex, lint --strict, sync-check, config-check, doctor и необязательный гейт ландшафта — и работает в трёх местах: в pre-push-хуке локально, как обязательная проверка в CI и в руках агента.

Поэтому правило простое и одинаковое для всех. В main не попадёт ни код, нарушающий архитектурные границы и правила, ни код с устаревшей или отсутствующей документацией, ни сломанный контракт между сервисами — будь автором человек или ИИ-агент. beadloom install-hooks ставит pre-push-хук, который блокирует push при красном Gate (обойти можно документированным git push --no-verify), а тот же beadloom ci остаётся обязательной проверкой в CI. Контроль один, и он детерминированный.

Какие проблемы решает

Архитектура, которую вы задумали, и код, который есть на самом деле, со временем расходятся — а следить за этим расхождением некому. Внутри репозитория тихо устаревает документация и размываются архитектурные границы. Между сервисами так же тихо ломаются контракты: переименованный слушатель очереди, объявленная в плане, но не построенная зависимость, эндпоинт без единого потребителя. Каждая специализированная проверка закрывает свой протокол, но за ландшафт целиком не отвечает никто — поэтому разрыв всплывает в проде, в другом сервисе, а не там, где было изменение.

Beadloom делает это расхождение видимым и проверяемым: документацию и границы — внутри каждого репозитория, контракты — между сервисами. ИИ-агент умеет читать ваш код, но не знает о задуманной вами архитектуре и о состоянии контрактов вне репозитория — а именно эту часть сложно получить как-то иначе.

Федерация: сверка контрактов между сервисами

Самые опасные баги прячутся между сервисами — там, где компилятор и тесты одного репозитория не достают, а специализированные проверки заточены под один протокол. Событие уходит в очередь, единственного слушателя которой переименовали в соседнем репозитории, — у брокера нет ни схемы, ни реестра, чтобы это заметить. Один сервис собран против зависимости, которую объявили в плане, но так и не построили. Эндпоинт продолжают поддерживать, хотя его последний потребитель давно удалён. Beadloom сводит контракты всех видов — сообщения AMQP, GraphQL, объявленные межсервисные зависимости — в один граф ландшафта и сверяет обе стороны каждого, причём с оглядкой на жизненный цикл: planned ещё не обязан существовать и не поднимает ложную тревогу, а deprecated, который всё ещё используют, — это явный долг. Не схема одного протокола, а карта замысла всего ландшафта против того, что построено на самом деле.

Каждый сервис выгружает свой граф детерминированным артефактом с привязкой к коммиту. Хаб собирает их в единый ландшафт и сверяет контракты:

# В каждом репозитории сервиса — детерминированный артефакт с привязкой к коммиту:
beadloom export --out service-a.json

# На хабе — собрать ландшафт и сверить контракты:
beadloom federate service-a.json service-b.json service-c.json

• Ссылки между репозиториями. Ребро графа может указывать на узел в другом сервисе как @<репозиторий>:<ref_id> (например, consumes @backend:WebAPI). Локальные ссылки остаются локальными. Ошибочную ссылку Beadloom показывает, а не отбрасывает молча.

• Контракты поверх AMQP и GraphQL. Контракты — это самостоятельные сущности с ключом, не зависящим от языка: AMQP как amqp:<брокер>/<routing>:<тип сообщения>, GraphQL как graphql:<схема>. Клиент на TypeScript и бэкенд совпадают по имени контракта.

• План и факт по каждому контракту. Каждый контракт получает вердикт:

  Вердикт	Что значит
  CONFIRMED	Поставщик и потребитель на месте и совместимы.
  BREAKING	Потребитель использует имя, которого больше нет в текущей GraphQL-схеме поставщика. Поймано до релиза — это проверка по факту наличия, а не сравнение версий.
  ORPHANED_CONSUMER	Что-то потребляет контракт, который никто не производит.
  UNDECLARED_PRODUCER	Что-то производит контракт, который никто не потребляет.
  EXTERNAL	Помечено как «есть, но не наше» (например, нативный мост) — без ложных тревог.
  DRIFT	Объявленная активной зависимость между репозиториями, цель которой не находится.

• С учётом жизненного цикла. У каждого узла и ребра есть статус — active, planned, deprecated, dead или external. Запланированный, но ещё не построенный контракт читается как ожидаемый, а не как сбой. А deprecated, который всё ещё используется, помечается кандидатом на удаление.

• Масштаб продукта и компании. federate собирает либо один продукт (его бэкенд, фронтенд, инфраструктуру, интеграции), либо целый ландшафт компании из нескольких продуктов. Продукты без общих контрактов не создают друг про друга лишний шум, а контракт между продуктами появляется только там, где интеграция реальна.

• Актуальность. В каждом артефакте есть SHA коммита и время, поэтому хаб показывает, насколько устарел экспорт контрактов каждого сервиса. Если данных нет, он честно пишет «неизвестно», а не выдумывает SHA.

Что уже готово. Контракты AMQP и GraphQL с проверкой ломающих изменений по факту наличия, федерация, которой неважны язык и продукт, и контроль в CI — граф контрактов можно гейтить через federate --fail-on и единый beadloom ci (обкатано на собственном CI Beadloom). Проверено на реальном ландшафте от начала до конца: реальное GraphQL-расхождение со статусом BREAKING поймано до релиза, а отдельный продукт на архитектуре FSD прошёл круг export/federate без потерь. Ландшафт рисуется визуальной картой на опубликованном портале VitePress. Пока нет: контрактов REST/OpenAPI и gRPC — это в планах. Хаб работает на собранных артефактах по документированной схеме, без размещённого сервиса.

Агентный процесс разработки — настраиваемый, не зависящий от инструмента

Тот же граф, что отвечает на prime и ctx, питает и упакованный многоагентный процесс разработки. Что представляет собой проект, вы описываете один раз — в .beadloom/flow.yml:

tools:        [claude, cursor]   # сгенерировать адаптеры для одного или обоих
architecture: [ddd]              # ddd | fsd (ровно один)
stack:        [python]           # python, fastapi, javascript, typescript, vuejs
quality:      [clean-code, tdd]

beadloom setup-agentic-flow собирает каждую роль (dev, test, review, tech-writer) из CORE-протокола, оверлея архитектуры и оверлеев стека и пишет набор адаптеров под каждый инструмент — .claude/agents/* для Claude Code, .cursor/agents/* для Cursor — на равных. config-check побайтово сверяет каждый сгенерированный адаптер с его сборкой, поэтому процесс никогда не разойдётся с графом незаметно.

Процесс локальный в первую очередь и проходит через тот же Gate. Запускаемый на pull request оркестратор ИИ tech-writer (поставляется в составе пакета, python -m beadloom.ai_agents.ai_techwriter) чинит устаревшую документацию прямо в ветке pull request — на уровне символов. Символ — это именованная сущность кода: функция, класс, метод или константа (их извлекает tree-sitter при разборе исходников). Документ переписывается, только если реально изменился символ, на который он ссылается, а не при любой правке в файле. У оркестратора ограниченная параллельность и классификация вердиктов, поэтому мёртвый раннер или исчерпанная квота не замораживают мерж. CI остаётся настоящим контролем, а правка агента — это предложение, которое проверяет и мерджит человек.

Поскольку один и тот же процесс работает на Claude Code и Cursor, а архитектура и стек задаются конфигурацией, а не написанным вручную текстом, процесс внедряется без переписывания под каждый проект.

Beadloom управляет собой сам

Beadloom применяет собственный тезис к своему же коду — теневого кода нет. Lint module-coverage повышен до severity: error: каждый модуль исходников — это либо отслеживаемый узел графа (feature со SPEC.md или component с DOC.md), либо запись в небольшом видимом списке исключений, поэтому новый неотслеживаемый модуль проваливает beadloom ci. Внутренние строительные блоки получают полноценный вид узла component (инфраструктурный аналог feature), и даже оркестратор ИИ tech-writer живёт в отслеживаемом графом домене ai_agents. Тезис architecture-as-code здесь не декларируется, а соблюдается.

Кому это нужно

• Тимлиды и архитекторы — сделать архитектуру явной, версионируемой и переживающей смену команды, а границы — соблюдаемыми в CI.
• Platform- и DevEx-инженеры — дать CI работающие проверки актуальности документации и границ, а агентам — структурный контекст из коробки через MCP.
• Разработчики — перестать тратить первый час каждой задачи на то, чтобы понять или вспомнить, как всё устроено: beadloom ctx <фича> или портал VitePress ответят за минуты.
• Те, кто работает с ИИ — чтобы агенты работали внутри архитектуры, а не ломали её.

Установка

uv tool install beadloom        # рекомендуется
pipx install beadloom           # альтернатива

Быстрый старт

# 1. Просканировать код и сгенерировать первичный граф архитектуры
#    (в работе: точность дорабатывается на реальных проектах)
beadloom init --bootstrap

# 2. Просмотреть сгенерированный граф (поправить домены, переименовать узлы, добавить связи)
vi .beadloom/_graph/services.yml

# 3. Построить индекс и начать пользоваться
beadloom reindex
beadloom ctx search        # получить контекст по фиче
beadloom sync-check        # актуальна ли документация?
beadloom lint              # соблюдены ли правила архитектуры?

# 4. Настроить контекст для ИИ-агентов
beadloom setup-rules       # создать файлы-адаптеры для IDE
beadloom prime             # посмотреть ровно то, что увидит агент

Первичная документация для старта не нужна — Beadloom поднимает базовый скелет из одной только структуры кода. Дальше его можно доработать и наполнить вручную или любым ИИ-агентом (см. beadloom docs polish), а Beadloom будет следить за актуальностью.

Architecture as Code

Beadloom не просто описывает архитектуру — он её защищает. Правила границ вы пишете в YAML, проверяете командой beadloom lint и блокируете нарушения в CI. Для примера, правила этого проекта:

version: 3

tags:
  layer-service: [cli, mcp-server, tui]
  layer-domain: [context-oracle, doc-sync, graph, onboarding]
  layer-infra: [infrastructure]

rules:
  - name: domain-needs-parent
    description: "Каждый домен должен быть part_of сервиса beadloom"
    require:
      for: { kind: domain }
      has_edge_to: { ref_id: beadloom }
      edge_kind: part_of

  - name: no-domain-depends-on-service
    description: "Домены не должны зависеть от сервисов"
    deny:
      from: { kind: domain }
      to: { kind: service }
      unless_edge: [part_of]

  # Соблюдать направление слоёв (сервисы → домены → инфраструктура)
  - name: architecture-layers
    severity: warn
    layers:
      - { name: services, tag: layer-service }
      - { name: domains, tag: layer-domain }
      - { name: infrastructure, tag: layer-infra }
    enforce: top-down

  # Не пускать TUI напрямую в слой базы данных
  - name: tui-no-direct-infra
    forbid_import:
      from: "src/beadloom/tui/**"
      to: "src/beadloom/infrastructure/**"

  # Предупреждать, когда узел разрастается
  - name: domain-size-limit
    severity: warn
    check:
      for: { kind: domain }
      max_symbols: 200      # слишком много кода в одном узле

Доступно семь типов правил: require, deny, forbid, layers, forbid_cycles, forbid_import и check.

beadloom lint                 # читаемый вывод в терминале
beadloom lint --strict        # код возврата 1 при нарушениях (для CI)
beadloom lint --format json   # машиночитаемый вывод

Когда агент запрашивает контекст по узлу, в ответ попадают и правила, которые к нему применяются, поэтому он соблюдает границы по умолчанию, а не случайно. Анализ импортов работает для Python, TypeScript/JavaScript, Go, Rust, Kotlin, Java, Swift, C/C++ и Objective-C.

Ключевые возможности

• Граф контрактов между сервисами — export в каждом репозитории, federate объединяет два и более сервиса в один ландшафт с вердиктами по каждому контракту (CONFIRMED / BREAKING / ORPHANED_CONSUMER / UNDECLARED_PRODUCER / EXTERNAL) поверх AMQP и GraphQL, плюс отметка актуальности по каждому сервису. Масштаб продукта и компании.
• Единый Gate — beadloom ci прогоняет reindex → lint → sync-check → config-check → doctor → необязательный гейт ландшафта за одним кодом возврата. Поставляется готовым GitHub Action и pre-push-хуком.
• Context Oracle — детерминированный обход графа, компактный JSON-пакет меньше чем за 20 мс.
• Doc Sync Engine — отслеживает связь кода и документации, ловит устаревшее, встраивается в git-хуки.
• Контекст для агента — beadloom prime (меньше 2K токенов), setup-rules для IDE-адаптеров, MCP-сервер с 18 инструментами и config-check, который держит файлы агента в согласии с графом.
• Агентный процесс разработки — setup-agentic-flow собирает настраиваемый, не зависящий от инструмента многоагентный процесс (Claude Code и Cursor; DDD/FSD и оверлеи стека) из .beadloom/flow.yml, с контролем через pre-push Gate и запускаемый на pull request ИИ tech-writer.
• Без теневого кода — lint module-coverage (error) требует, чтобы каждый модуль исходников был узлом графа или явным исключением, а вид узла component отслеживает внутренние строительные блоки наряду с узлами feature.
• Полнотекстовый поиск — FTS5 по узлам, документации и символам кода.
• Анализ влияния — beadloom why показывает, что зависит от узла и что сломается при его изменении.
• Старт от кода — поднять граф из одной структуры кода, без документации.
• Снимки и долг — snapshot сравнивает архитектуру во времени, а status --debt-report сводит lint, синхронность и сложность в одну оценку 0–100 с гейтом в CI.
• Диаграммы C4 — автогенерация Context / Container / Component в Mermaid и PlantUML.
• Опубликованный сайт — beadloom docs site собирает базу знаний на VitePress (дашборд, интерактивная архитектура, карта ландшафта, актуальная документация).
• Локально и без зависимостей — один CLI и один файл SQLite. Без Docker и без облака.

Как это устроено

Beadloom держит граф архитектуры в YAML под .beadloom/_graph/ — узлы (фичи, сервисы, домены, сущности), соединённые рёбрами (part_of, uses, depends_on и так далее). Переиндексация сливает три источника в одну базу SQLite:

1. YAML графа — узлы и рёбра, описывающие архитектуру.
2. Документация — Markdown, привязанный к узлам графа и разбитый на куски для поиска.
3. Код — исходники, разобранные через tree-sitter ради символов и аннотаций # beadloom:domain=....

Запросите контекст узла — и Context Oracle обойдёт граф в ширину, соберёт нужный подграф, документацию, символы кода и вернёт компактный пакет данных.

Команды CLI

Команда	Описание
init --bootstrap	Просканировать код и сгенерировать начальный граф архитектуры
init --import DIR	Импортировать и классифицировать существующую документацию
reindex	Перестроить индекс SQLite из графа, документации и кода
ctx REF_ID	Получить пакет контекста (Markdown или --json)
graph [REF_ID]	Показать граф архитектуры (Mermaid или JSON)
search QUERY	Полнотекстовый поиск по узлам, документации и символам кода
status	Статистика индекса, покрытие документацией и отчёт о долге
doctor	Проверить граф архитектуры
sync-check	Проверить синхронность документации и кода
sync-update REF_ID	Просмотреть и обновить устаревшую документацию
why REF_ID	Анализ влияния — от чего зависит и что зависит от него
lint	Проверить код по правилам архитектуры (--strict, --format rich/json/porcelain/github)
ci	Единый Gate: reindex → lint → sync-check → config-check → doctor → необязательный гейт ландшафта
config-check	Проверить (или --fix), что сгенерированные файлы агента совпадают с графом
export	Выгрузить граф детерминированным артефактом для федерации
federate	Собрать два и более артефакта в один ландшафт. Флаг --fail-on включает гейт в CI
docs generate	Сгенерировать заготовки документации из графа
docs polish	Выдать структурные данные для обогащения документации с помощью ИИ
docs site	Собрать сайт VitePress (дашборд, архитектура, карта ландшафта, проверенная документация)
docs audit	Найти устаревшие факты в обзорной документации (README, руководства)
diff	Показать изменения графа с момента git-ref
snapshot	Сохранять и сравнивать снимки архитектуры
link REF_ID [URL]	Управлять ссылками на внешние трекеры у узлов
prime	Выдать компактный контекст проекта для ИИ-агентов
active-sync	Сверить таблицу статусов бидов в ACTIVE.md каждого эпика с трекером (bd)
setup-rules	Создать файлы-адаптеры для IDE (.cursorrules, .windsurfrules, .clinerules)
setup-mcp	Настроить MCP-сервер для ИИ-агентов
setup-agentic-flow	Собрать и записать адаптеры ролей многоагентного процесса из .beadloom/flow.yml (--tool/--architecture/--stack)
mcp-serve	Запустить MCP-сервер (транспорт stdio)
tui / ui	Интерактивная панель в терминале (нужен beadloom[tui])
watch	Автопереиндексация при изменении файлов (нужен beadloom[watch])
install-hooks	Установить pre-commit-хук и pre-push Beadloom Gate (полный beadloom ci)

Инструменты MCP

beadloom mcp-serve даёт ИИ-агентам 18 инструментов: 14 инструментов чтения и записи графа — prime, get_context, get_graph, list_nodes, sync_check, get_status, update_node, mark_synced, search, generate_docs, why, diff, lint, get_debt_report — плюс четыре процессных инструмента, которые ведут агентный процесс: task_init, bead_context, checkpoint, complete_bead. Работает с Claude Code, Cursor, Windsurf, Cline и любым MCP-совместимым инструментом. Подключение:

{
  "mcpServers": {
    "beadloom": { "command": "beadloom", "args": ["mcp-serve"] }
  }
}

Конфигурация

Всё лежит тут: .beadloom/ в корне репозитория:

• config.yml — пути сканирования, языки, настройки синхронизации.
• flow.yml — декларация агентного процесса: tools (claude/cursor), architecture (ddd/fsd), оверлеи stack и quality (читается командой setup-agentic-flow).
• _graph/*.yml — граф архитектуры (под версионным контролем).
• _graph/rules.yml — правила границ.
• AGENTS.md — соглашения и каталог MCP-инструментов для агентов.
• beadloom.db — индекс SQLite (генерируется автоматически, добавьте в .gitignore).

Связать код с узлом графа можно однострочной аннотацией:

# beadloom:domain=doc-sync
def check_freshness(db: sqlite3.Connection, ref_id: str) -> SyncStatus:
    ...

Документация

Документ	Описание
architecture.md	Дизайн системы и обзор компонентов
getting-started.md	Руководство по быстрому старту
Мультиагентная разработка	Как устроен агентный процесс Beadloom
CI Setup	Интеграция с GitHub Actions / GitLab CI
VitePress Site	Публикация базы знаний на VitePress
Домены	Context Oracle · Graph · Doc Sync · Onboarding · Infrastructure
Сервисы	CLI Reference · MCP Server · TUI Dashboard

Интеграция с Beads

Beadloom — архитектурный контекст для beads.

Beadloom дополняет Beads: агенты-исполнители вызывают get_context(feature_id) по MCP и получают готовый пакет вместо поиска по коду с нуля. Интеграция необязательна — Beadloom прекрасно работает сам по себе.

Разработка

uv sync --dev              # установка с dev-зависимостями
uv run pytest              # запуск тестов
uv run ruff check src/     # линтер
uv run mypy                # проверка типов (строгий режим)

Лицензия

MIT