Beadloom

Read this in other languages: English

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

🔎 Посмотреть, что получается: интерактивный граф архитектуры Beadloom — щелчок по узлу открывает его карточку и радиус влияния. Страница собрана из графа этого репозитория командой beadloom docs site, а не нарисована руками.

Платформы: Linux проверяется на каждом прогоне CI. На macOS проект разрабатывают, но CI его там не запускает  |  Python: от 3.10 до 3.13

---

Почему промптов и CLAUDE.md уже недостаточно

Чат-бот, отвечающий на вопросы, и агент, которому поручают что-то несложное: сгенерировать функцию, собрать табличку, разобрать лог. Это давно никого не удивляет. Базовый уровень.

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

Вместе с автономностью растёт не только скорость. Растёт и вероятность, что агент поймёт задачу не так, как её задумывали. Попросили починить упавший тест — он удалил тест, и сборка позеленела. Попросили довести покрытие до восьмидесяти процентов — написал тесты, которые вызывают код и ничего не проверяют. Формально задача выполнена. У этого есть название: несоответствие целей, misalignment.

Есть случай неприятнее. Агент выглядит согласным с правилами, но о части сделанного умалчивает, а часть проверок обходит. Это называют скрытым стратегическим поведением, scheming. Такие сценарии уже изучают в лабораториях. В повседневной работе мы такое пропускаем. Сначала пропускаем, потом разводим руками и говорим, что модель поглупела.

Когда агентов несколько, добавляется то, чего у одного не бывает. Двое правят один файл в одном дереве, и первый считает работу законченной, не увидев, что рядом её уже переделали. Проверка при этом проходит зелёной, потому что проверять ей стало нечего.

Поэтому надеяться, что агент вспомнит и правильно применит написанное в промпте, AGENTS.md или CLAUDE.md, больше нельзя. В короткой сессии это ещё работает. В длинной контекст растёт, правила в нём тонут и слабеют как раз тогда, когда становятся нужны.

Нужен инженерный контур: явные границы задачи и полномочий, архитектурный контекст, изолированная параллельная работа, исполнимые проверки, доказательства сделанного и честная запись того, что проверить не удалось.

Beadloom — попытка встроить такой контур прямо в репозиторий.

«Проверка прошла» и «проверять было нечего» — это разное

У большинства инструментов два ответа: прошло или не прошло. Третий они показать не умеют, а он самый опасный: проверять было нечего, а написано «прошло».

Так бывает чаще, чем кажется. В пути правила опечатка, и оно не совпало ни с одним файлом. Документ есть в графе, а с диска его удалили. Репозиторий только что склонировали, и проверке свежести не с чем сравнивать. Гард (guard) настроен верно, но никуда не подключён и ни разу не сработал.

Честный ответ тут один: «это я не проверил». Обычный ответ — зелёный.

Beadloom пишет, чего он не сделал. Вот выдержки из настоящих прогонов, длинные строки перенесены:

[PASS] docs-audit: 20 mention(s) fresh; 4/9 declared fact(s) verified, NOT VERIFIED:
       cli_command_count, edge_count, language_count, nodes_with_framework, test_count
[SKIP] scope-check: skipped — the branch 'master' names no work item among the planning
       documents, so there are no declared axes to judge against
[SKIP] readme-pair: skipped — no document pair is declared; add a `document_pairs:` block
       of `source:`/`follower:` entries to .beadloom/config.yml
Rule 'domain-needs-parent' cannot fire: its `for` kind 'domain' matches none of the 1 nodes
in the graph. It is counted as evaluated but checks nothing

У гарда шесть исходов вместо двух:

• pass — проверил и претензий нет;
• warn — есть на что посмотреть, но работу это не останавливает;
• block — правило нарушено, правка не проходит;
• skip — проверять было нечего, и это не выдаётся за успех;
• error — гард отказывается толковать то, что ему дали. Тоже не проходит;
• unresolved — гард не смог проверить сам себя. Его код не импортируется, настройки не читаются.

Про unresolved стоит сказать отдельно. Если сломанный гард запрещает всё подряд, он запрещает и ту правку, которая его чинит. Получается ловушка, из которой агент не выберется сам. Поэтому здесь Beadloom предупреждает, а не блокирует.

Что именно каждая проверка отказывается утверждать, разобрано ниже.

Чего Beadloom не делает

Он ничего не знает про саму модель. Честен ли агент, о чём он умалчивает, вёл бы он себя иначе без наблюдения — на эти вопросы Beadloom не отвечает. Это свойства модели, и с ними работают в другом месте.

Он не заменяет изоляцию среды, хранение секретов, разграничение доступа и ревью человеком. Если у агента есть выход в сеть и боевые ключи, это вопрос инфраструктуры, а не рабочего процесса.

Beadloom обещает меньше, зато обещанное можно проверить. Он ограничивает, куда может дотянуться правка. Показывает, что она задевает. Разводит агентов по разным файлам. И не называет проверку пройденной, если проверять было нечего.

Что закрыто, а что нет

Beadloom складывается из нескольких слоёв, каждый из которых в отрасли называют «as code». Ниже — что из этого закрыто, чем именно, и где проходит граница.

Слой		Чем закрыт
Architecture as code	да	граф в YAML под версией, lint над ним, impact, раскладка графа по файлам
Policy as code	да	гарды как данные, правила области задачи, шесть вердиктов и коды возврата
Documentation as code	да	пары «документ ↔ код», проверка свежести против HEAD, тех-писатель на pull request
Context as code	да	ctx, prime, why, объявленная типизированная поверхность
Coordination as code	да	waves, rooms, clean-room, выдача номеров через исключительное создание файла
Assurance as code	да	guard --liveness, scope-check, mutation, явные «не проверено» в каждом отчёте
Agentic workflow as code	да	flow.yml, роли, адаптеры, config-check над ними
Security & privacy as code	частично	запись срабатываний хранит имя команды и файлы, но не командную строку
Runtime agent governance	частично	контур инструментов и правок в репозитории, но не полноценный слой авторизации действий
Model alignment	нет	Beadloom не судит о целях и честности модели
Frontier-AI safety	не цель	не заменяет оценку моделей, песочницы и пороги допустимых возможностей

Три нижние строки — не заготовка на будущее. Это граница проекта, и она проведена сознательно.

Правило становится командой

Beadloom держит правила в архитектурном графе. Граф — это описание вашей системы, которое лежит в репозитории обычным YAML: какие в ней есть части, как они связаны, что чему можно. Важно в нём одно свойство: по графу можно запустить команду.

Правило лежит в графе. По графу есть команда. Команда возвращает код. Код возврата не забывается — ни агентом, ни человеком, ни в CI.

Все проверки сходятся в один Gate. Вот его вывод на этом репозитории при выпуске версии 7.0.0, 29 сентября 2026 года. Длинные строки перенесены, пропущенный текст отмечен знаком «…»:

Beadloom CI gate

  [PASS] reindex: up to date
  [PASS] lint: 0 error(s), 73 warning(s), 10 crossings suppressed by an exemption,
         architecture-layers judged 371 of 379 live depends_on edge(s)
  [PASS] sync-check: 519 pair(s) fresh
  [PASS] docs-audit: 20 mention(s) fresh; 4/9 declared fact(s) verified, NOT VERIFIED:
         cli_command_count, edge_count, language_count, nodes_with_framework, test_count
  [WARN] docs-quality: 292 document(s) read; … NO CHECK READS: PLAN, SUMMARY; …
  [PASS] issue-log: 277 entr(ies) uniquely numbered; … PARTLY CHECKED: 235 of 277 …
  [PASS] readme-pair: 1 pair(s) held, 118 block(s) compared, 0 finding(s); …
  [WARN] doc-spaces: to_be 229, as_is 124, working 65; …
  [PASS] scope-check: 0 path(s) outside the axes BDL-075 declares (…); 3 judged, …
  [PASS] config-check: no blocking drift; 1 artifact(s) reported (warn)
  [PASS] doctor: 13 check(s): 0 error(s), 240 warning(s), 4 info
  …
PASS — gate clean
Room: Darwin arm64 · CPython 3.13.7 · 10 cores · extras … · locale utf-8
  23 of 23 declared room(s) not entered by this run: …
Not run by this gate:
  the test suite — `uv run pytest --cov=beadloom …` (.github/workflows/ci.yml: tests)
  the style linter — `uv run ruff check src/ tests/` (.github/workflows/ci.yml: tests)
  the type checker — `uv run mypy src/` (.github/workflows/ci.yml: tests)
…

Смотреть здесь стоит не на PASS, а на то, что рядом. Каждый шаг называет, сколько он проверил и чего не смотрел. Проверка, которой нечего было проверить, не выглядит как успешная — этому посвящён отдельный раздел, и это главное отличие Beadloom от набора линтеров.

Последние строки говорят то же о самом Gate. Он называет машину, на которой шёл прогон, окружения из CI, в которых прогона не было, и проверки, которые он не запускал вовсе: тесты, линтер и проверку типов. Зелёный вердикт относится к этой машине и к тем проверкам, которые Gate запустил, а не к проекту целиком.

Один Gate стоит в трёх местах: в pre-push-хуке, в CI и в руках агента. Неважно, каким провайдером агентов вы пользуетесь: Beadloom универсален и не является частью ни одного из них. Claude Code, Cursor, редактор с MCP, задача в CI, человек за клавиатурой — все упираются в один и тот же beadloom ci.

Часть правил в команду не превратишь: они так и остаются текстом, который агент читает. Этот текст Beadloom старается не раздувать. Правила вашего проекта живут отдельным слоем в .beadloom/flow/, поставляемое ядро — отдельно, и обновление меняет только ядро.

Откуда Gate знает, что правильно

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

Вопрос	Откуда ответ
Где реализован этот класс?	видно в коде
Что импортирует этот модуль?	видно в коде
А можно ли ему это импортировать?	только если вы это записали
Этот документ всё ещё описывает текущий код?	вы записали, какой документ какой код описывает, дальше Beadloom сверяет
Кто ещё пользуется контрактом, который мы собираемся удалить?	записано в соседнем репозитории
Эта зависимость уже построена или пока только запланирована?	только если вы это записали

Первые два вопроса закроет любой хороший индексатор. Остальные не закроет никакой, и дело не в его качестве: ответа просто нет в исходниках.

Записывается это один раз — в тот самый граф. Внутри он устроен просто: узлы (сервисы, домены, фичи, компоненты) и рёбра между ними (part_of, uses, depends_on). Поднять граф можно из уже написанного кода командой beadloom init --bootstrap, дальше вычитать и вести руками.

При переиндексации Beadloom сливает в одну базу SQLite три источника: сам граф, документацию, привязанную к его узлам, и код, разобранный через tree-sitter ради символов. После этого граф можно спрашивать: beadloom ctx <узел> отдаёт по нему всё сразу, beadloom why <узел> показывает, что сломается, если его тронуть.

Что стоит на графе

Граф сам по себе — просто данные. Полезным его делает то, что на нём построено.

• Единый Gate и проверки по шагам. Все проверки за одним кодом возврата. А beadloom guard проверяет один шаг процесса отдельно и выносит один из шести вердиктов, описанных выше.
• Агентный процесс разработки — настраиваемый и не зависящий от инструмента. Пять ролей: explore, dev, test, review и tech-writer. Адаптеры для Claude Code и Cursor равноправны.
• Контекст по запросу — людям и агентам одинаково. ctx отдаёт код, документацию и действующие правила по узлу. why считает радиус влияния. prime укладывает обзор проекта в пакет меньше двух тысяч токенов. search ищет полнотекстом по узлам и документации.
• Архитектура как код. Границы и правила в YAML, которые проверяет beadloom lint и блокирует Gate.
• Тесты на графе. У каждого узла видно, какие тесты к нему относятся. Правила следят за самим набором тестов, а мутационное тестирование показывает, заметят ли тесты ошибку.
• Spec-Driven: сначала спецификация, потом код. Три пространства документов: TO-BE — что вы собираетесь построить, AS-IS — что построено, WORKING — рабочие записи по ходу задачи. Последние от проверки свежести освобождены намеренно: заметка о прогрессе описывает ход работы, а не код. beadloom docs spaces показывает все три и находит задачи, где работа закончена, а обещанный документ так и не появился.
• Федерация между репозиториями. Общий ландшафт из графов отдельных сервисов и сверка каждого контракта с обеими сторонами.
• Портал документации. beadloom docs site собирает сайт на VitePress: интерактивные графы, дашборд метрик и документация с отметкой свежести.
• Панель в терминале. beadloom tui — три экрана в консоли: дашборд, обозреватель графа и состояние документации. Работает, если Beadloom установлен с дополнением tui.

Первые пять минут

uv tool install beadloom        # рекомендуется
pipx install beadloom           # альтернатива
uv tool install "beadloom[languages,tui]"   # ещё восемь языков и панель в терминале

beadloom init --bootstrap          # поднять граф из уже написанного кода
vi .beadloom/_graph/services.yml   # вычитать: поправить домены, переименовать узлы, добавить связи
beadloom reindex                   # построить индекс
beadloom ci                        # прогнать все проверки разом

beadloom init сверяет граф, который только что записал, с правилами, записанными рядом. Если скелет нарушает одно из них, init называет правило и узел и завершается с кодом 1, а не с кодом 0 и разбирательством на первом же beadloom ci. Скелет в любом случае остаётся на диске.

Дальше стоит посмотреть три вещи: beadloom ctx <узел> — что инструмент знает о куске системы, beadloom prime — ровно то, что увидит агент, beadloom docs site — как это выглядит на портале.

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

У Beadloom высокий порог входа

Граф надо поднять, вычитать и дальше вести. Правила — написать. Gate — встроить в CI. На проекте из десяти файлов или на разовой задаче эта работа не окупится: вы и так всё помните, а агенту хватит того, что он прочитает сам.

Отдача начинается в двух случаях. Первый — когда над репозиторием одновременно работают хотя бы два агента: почти всё, что здесь есть, отвечает на вопросы, которых при одном агенте не возникает. Второй — когда система перестаёт помещаться в голову. Когда её пишут годами, когда через неё прошло несколько составов команды, когда сервисов больше одного и они лежат в разных репозиториях. Тогда знание уходит вместе с людьми, документация расходится с кодом незаметно, а контракт ломается в чужом репозитории и всплывает в проде. Чем дольше живёт система и чем больше в ней движущихся частей, тем быстрее окупается настройка.

Кому это обычно нужно:

• Тем, кто запускает агентов пачками. Чтобы работа нескольких агентов сразу оставалась предсказуемой. beadloom waves считает, какие задачи можно вести параллельно, а какие придётся сериализовать, и называет причину для каждой пары, которую пришлось сериализовать. Каждый агент получает свой контекст и свои границы, а результат любого из них проходит через один и тот же Gate. Подробности — в руководстве по параллельным волнам.
• Тимлидам и архитекторам. Чтобы архитектура была явной, версионируемой и переживала смену команды.
• Platform- и DevEx-инженерам. Чтобы в CI стояли работающие проверки актуальности документации и границ, а у агентов был структурный контекст через MCP.
• Разработчикам. Чтобы не тратить первый час каждой задачи на восстановление картины.

---

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

Самые опасные баги прячутся между сервисами. Туда не достают ни компилятор, ни тесты одного репозитория, а специализированные проверки заточены под один протокол.

Событие уходит в очередь, единственного слушателя которой переименовали в соседнем репозитории. У брокера нет ни схемы, ни реестра, чтобы это заметить. Сервис собран против зависимости, которую объявили в плане и не построили. Эндпоинт поддерживают, хотя его последний потребитель давно удалён.

Beadloom сводит контракты всех видов — сообщения AMQP, GraphQL, объявленные межсервисные зависимости — в один граф ландшафта и сверяет обе стороны каждого:

beadloom export --out service-a.json          # в каждом репозитории сервиса
beadloom federate service-*.json              # на хабе

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

Вердикт учитывает жизненный цикл: planned ещё не обязан существовать и ложную тревогу не поднимает, а deprecated, который всё ещё используют, это явный долг. Хаб собирает либо один продукт, либо ландшафт компании из нескольких — продукты без общих контрактов не шумят друг про друга. В каждом артефакте есть SHA коммита и время, поэтому видно, насколько устарел экспорт каждого сервиса. Если данных нет, хаб пишет «неизвестно» и SHA не выдумывает.

Что уже готово: AMQP и GraphQL с проверкой ломающих изменений, федерация вне зависимости от языка и продукта, гейт в CI через federate --fail-on. Проверено от начала до конца: расхождение со статусом BREAKING поймано до релиза. Пока нет: REST/OpenAPI и gRPC. Хаб работает на собранных артефактах, без размещённого сервиса.

Когда проверить не удалось, Beadloom так и пишет

Проверка документации отвечает «всё свежо». Звучит хорошо, но за этим ответом может стоять два очень разных факта. Либо документация действительно совпадает с кодом. Либо проверять было нечего, и вам об этом не сказали.

Второе случается чаще, чем кажется. Документ упомянут в графе, а с диска его кто-то удалил. В правиле опечатка в пути, поэтому оно не подходит ни к одному файлу. В CI свежая копия репозитория, и сравнивать пока не с чем. Раньше Beadloom на всё это отвечал одинаково: «всё свежо».

Дальше «связка» — это документ и код, который он описывает: Beadloom знает, какой файл какой документ объясняет, и следит, чтобы они не разъезжались.

Что произошло	Что говорит Beadloom
Документ объявлен в графе, но на диске его нет	missing. sync-check завершается с кодом 2, а Gate не проходит и завершается с кодом 1. Удалить документ — не способ закрыть вопрос
Сравнивать не с чем: репозиторий только что склонировали	unverified. Такая связка считается отдельно и в число свежих не попадает. Gate показывает WARN и код возврата не меняет: с кодом всё в порядке, ответить не может сама проверка
Правило не подходит ни к одному файлу или узлу	предупреждение rule_liveness. В итоговой строке сказано, сколько правил из запущенных не смогли проверить ничего
У временного исключения из правил вышел срок	предупреждение, и на каждом запуске печатается, сколько нарушений это исключение прячет. Само исключение продолжает действовать: сборка не должна краснеть оттого, что сменилась дата
В README есть число, которое аудит ни разу не сверил	docs audit пишет, сколько заявленных фактов он подтвердил из скольких, называет остальные и перечисляет документы, которые вообще не открывал
Работа по задаче закончена, а обещанный по ней документ так и не появился	это показывает docs spaces. Для остальных проверок такой узел выглядит чистым: устаревать нечему, когда документа нет вовсе
Документация помечена в конфиге как временная и от проверки свежести освобождена	число освобождённых связок и причина печатаются рядом с числом свежих, чтобы освобождение нельзя было спутать с проверкой
Перевод документа разошёлся с оригиналом: в одном есть абзац, которого нет в другом	readme-pair сравнивает пары из блока document_pairs: по структуре: заголовки, абзацы, списки, таблицы и блоки кода. Сам текст он не сравнивает. Если ни одна пара не объявлена, шаг пишет, что пропущен, а не что прошёл

Отдельно про то, откуда Beadloom знает, что документ устарел. Он смотрит в git, а не в собственный индекс.

Это важно, потому что раньше был простой способ получить зелёный отчёт: удалить локальную базу .beadloom/beadloom.db. Она в .gitignore, живёт на одной машине, и в CI её нет. Beadloom пересобирал её с нуля, принимал текущее состояние кода за точку отсчёта и объявлял всю документацию свежей. Теперь каждая связка помнит, с каким коммитом её сверяли, и сравнивается с HEAD. Удаление базы больше ничего не даёт.

Агентный процесс разработки

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

# .beadloom/flow.yml
tools:        [claude, cursor]   # адаптеры для одного или обоих
architecture: [ddd]              # ddd | fsd (ровно один)
stack:        [python]           # python, fastapi, javascript, typescript, vuejs
quality:      [clean-code, tdd]
language:     en                 # язык документов процесса

beadloom setup-agentic-flow собирает из этого протоколы пяти ролей, slash-команды и CLAUDE.md, а config-check следит, чтобы собранное не разошлось с графом. Правила вашего проекта лежат отдельным слоем в .beadloom/flow/ и переживают обновление: оно меняет ядро под ними. Отменить правило ядра можно только декларацией с причиной и сроком, а по истечении срока о ней сообщит config-check. Подробности в руководстве по проектным оверлеям.

Процесс локальный в первую очередь и проходит через тот же Gate. На pull request запускается ИИ tech-writer: он чинит устаревшую документацию прямо в ветке, на уровне символов — документ переписывается, только если изменился символ, на который он ссылается. Настоящий контроль остаётся за CI, а правка агента это предложение, которое проверяет и мерджит человек.

Архитектура как код

Границы вы пишете в YAML, а beadloom lint их проверяет:

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

  - name: tui-no-direct-infra             # TUI не лезет в базу напрямую
    forbid_import:
      from: "src/beadloom/tui/**"
      to:   "beadloom/infrastructure/**"

Правило объявляет ровно один из 15 ключей: require, deny, forbid, layers, forbid_cycles, forbid_import, check, unregistered_feature_candidate, module_coverage, scenario_coverage, doc_area_coherence, summary_facts, test_binding, test_import_boundary и scenario_binding. Полный справочник — в docs/architecture.md.

Правило, которое не может ни с чем совпасть, сообщает об этом само: матчер, не выбирающий ни одного узла, опечатка в шаблоне пути, исключение, которое ничего не подавляет. В итоговой строке lint появляется их число, поэтому объявленное количество правил не может обещать больше, чем проверено.

Свой тезис Beadloom применяет и к себе: lint module-coverage поднят до error, поэтому каждый модуль исходников обязан быть узлом графа или явным исключением, а новый неотслеживаемый модуль проваливает beadloom ci.

Анализ импортов работает для Python сразу после установки. Для TypeScript/JavaScript, Go, Rust, Kotlin, Java, Swift, C/C++ и Objective-C нужно дополнение languages: uv tool install "beadloom[languages]".

Тесты привязаны к графу

Агент из начала этого README довёл покрытие до восьмидесяти процентов тестами, которые ничего не проверяют. Покрытие этого не видит: оно показывает только, что строка выполнилась. Beadloom смотрит на тесты с трёх сторон.

Что считается тестом, записано один раз в роли test: одно поведение на тест, подготовка, одно действие и проверка его результата. Эти требования одинаковы для любого стека.

Тестовый файл относится к узлу графа одним из трёх способов: его путь повторяет путь проверяемого кода, он лежит рядом с этим кодом, или узел сам перечисляет свои тесты в ключе tests:. Больше Beadloom ничего не угадывает. Файл, который не привязался ни одним способом, считается отдельно, и каждый отчёт о тестах называет число таких файлов: любой из них может проверять узел, у которого на первый взгляд тестов нет. Тесты узла показывает beadloom ctx <узел>. За самим набором тестов следят три правила:

• test_binding — относится ли каждый тестовый файл к узлу и есть ли тест у каждого узла выбранного вида;
• test_import_boundary — не импортирует ли тест то, что правило ему запрещает;
• scenario_binding — лежит ли приёмочный сценарий в папке своего узла.

Каждое правило на каждом запуске пишет, какую часть набора оно проверило.

Заметит ли тест ошибку, показывает мутационное тестирование: в код вносят мелкие искажения и смотрят, упадёт ли хоть один тест. Программу для этого выбирает проект, а beadloom mutation считает оценку по тому, что она записала. С флагом --changed-since main команда называет, что нужно проверить для этой правки: изменённые функции в объявленной области, их узлы и привязанные к ним тесты. С флагом --sample-of она читает результат как случайную выборку и печатает доверительный интервал. Порог считается не пройденным, только если ниже него лежит весь интервал. В этом репозитории так проверяется каждый pull request, а раз в неделю — случайная выборка из всей объявленной области.

Подробности — в руководстве по тестированию.

---

Команды

Команда	Что делает
init --bootstrap	Поднять граф из структуры кода
reindex	Перестроить индекс из графа, документации и кода
ctx REF_ID	Пакет контекста по узлу (Markdown или --json)
why REF_ID	Что зависит от узла и что сломается при его изменении
search QUERY	Полнотекстовый поиск по узлам и документации
lint	Проверить правила архитектуры (--strict для CI)
sync-check	Свежесть документации относительно кода
ci	Единый Gate: все проверки за одним кодом возврата
impact TARGET	Кто ещё пишет туда же, кто вызывает этот код и сколько в нём ветвлений. TARGET — путь или имя символа
scope-check	Остался ли коммит внутри осей, объявленных его задачей
waves --parent BEAD	Какие задачи можно вести одновременно — выводится из трекера, а не пишется руками
clean-room BEAD	Комната из HEAD и названных вами файлов, чтобы вердикт агента был о его собственной работе
guard --liveness	Какие гарды есть и к чему каждый из них на самом деле подключён
export / federate	Выгрузить граф и собрать ландшафт из нескольких сервисов
docs site	Собрать портал на VitePress

Полный справочник — docs/services/cli.md: там все команды со всеми флагами, включая axes, typed-surface, bd-calls, issue-number, rooms, mutation, review-brief, version-surface, docs spaces, snapshot, status --debt-report и настройку хуков через install-hooks.

MCP, конфигурация, Beads

beadloom mcp-serve даёт агентам 18 инструментов: четырнадцать читают и пишут граф, четыре ведут агентный процесс. Работает с Claude Code, Cursor, Windsurf, Cline и любым MCP-совместимым инструментом. Каталог целиком — в docs/services/mcp.md.

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

Всё, что Beadloom про вас знает, лежит в .beadloom/ в корне репозитория: config.yml (где искать код и тесты, языки, пары документов и настройки проверок), flow.yml (декларация агентного процесса), flow/ (ваш слой процесса), _graph/*.yml (граф и правила, под версионным контролем), AGENTS.md (соглашения для агентов). База beadloom.db генерируется и в git не нужна.

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

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

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

Windows не проверен. На нём в этом проекте никогда ничего не запускалось. Ветку CI windows-latest собрали и отозвали, потому что она становилась критическим путём конвейера. Подробности — в разделе Windows: unverified by decision в SPEC по guard-ам процесса.

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

Документ	Описание
architecture.md	Дизайн системы и обзор компонентов
getting-started.md	Руководство по быстрому старту
Мультиагентная разработка	Как устроен агентный процесс Beadloom
Исполняемые приёмочные сценарии	Gherkin как источник истины и что сообщает scenario-coverage
Параллельные волны	Что гарантирует волна параллельных агентов и что здесь не проверяется ничем
Виды документов	Обязательные разделы и пять проверок стандарта письма
Тестирование	Где живёт тест, как он привязывается к узлу графа, что о наборе тестов сообщает lint и как читать мутационную оценку
CI Setup	Интеграция с GitHub Actions / GitLab CI
VitePress Site	Публикация базы знаний на VitePress
Домены	Context Oracle · Graph · Doc Sync · Onboarding · Infrastructure
Сервисы	CLI Reference · MCP Server · TUI Dashboard

Разработка

uv sync --extra all             # зависимости и инструменты разработки, как в CI
uv run pytest                   # тесты
uv run ruff check src/ tests/   # линтер
uv run mypy src/                # проверка типов (строгий режим)

Лицензия

MIT