SpiderBrain: слой понимания для вашего репозитория

Репозиторий говорит ИИ-агенту, что представляет собой код. Но он никогда не говорит ему, что важно, чего достигает изменение, или почему что-то было построено именно так. Поэтому каждый агент заново выводит структуру с нуля, в каждой сессии, и немного ошибается.

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

• Веб-сайт: https://spiderbrain.ai

• Бенчмарк детерминизма: https://contextbenchmark.com

Используйте это в одну строку

Когда репозиторий содержит папку .spiderbrain/, укажите на нее читателю:

npx spiderbrain mcp --root .

Рабочая директория MCP-клиента обычно не является вашим репозиторием, поэтому передавайте репозиторий явно с помощью --root <path>, --root=<path> или переменной окружения SPIDERBRAIN_ROOT. Без этого сервер обслуживает рабочую директорию и сообщает, что слой понимания не найден, что является неверным ответом, а не ошибкой.

Это запускает MCP-сервер, к которому может обращаться ваш агент для кодинга (Claude Code, Cursor или любой MCP-клиент). Инструменты: sb_blast, sb_impact, sb_path, sb_keystones, sb_map, sb_ask. Без аккаунта, без установки SpiderBrain, без конфигурации. Реальная стенограмма сессии находится в examples/agent-session.md.

Предпочитаете терминал:

npx spiderbrain blast src/server/health.ts   # what a change here reaches
npx spiderbrain impact                        # what YOUR CURRENT DIFF reaches
npx spiderbrain keystones                     # the load-bearing files
npx spiderbrain map src/auth/session.ts       # what a file is + touches
npx spiderbrain path src/a.ts src/b.ts        # how one file reaches another
npx spiderbrain verify --allow-stale          # folder untampered? see note below

Почему --allow-stale для зафиксированного мозга. verify проверяет две вещи: что structure.ndjson по-прежнему соответствует записанному отпечатку, и что мозг был оценен на текущем HEAD. Фиксация папки сама по себе является коммитом, поэтому мозг, зафиксированный в репозитории, всегда отстает как минимум на один коммит, и вторая проверка никогда не может пройти на свежем клоне. --allow-stale сохраняет строгую проверку целостности и допускает только это. Уберите флаг, когда вы строите мозг в CI на том коммите, который тестируете, где актуальность реальна.

Related MCP server: mcp-codebase-intelligence

Агенты — граждане первого класса

Каждая команда принимает --json и выдает один машиночитаемый объект, а коды выхода являются частью контракта: 0 — ок, 1 — проверка не пройдена, 2 — использование, 3 — нет понимания. CI может на них опираться:

npx spiderbrain impact --fail-over 200   # fail a PR whose blast exceeds 200 files
npx spiderbrain verify                   # fail a build whose folder is stale or edited (drop --allow-stale to require currency)

Готовые рабочие процессы — комментарий о радиусе поражения PR и шлюз свежести — находятся в examples/.

Нет папки? Резервный реестр

Когда репозиторий не содержит папки .spiderbrain/, читатель проверяет публичный реестр SpiderBrain на наличие неофициального мозга того же репозитория (сопоставленного по удаленному origin, четко помеченного, проверенного по отпечатку). Зафиксированная папка всегда имеет приоритет, если она присутствует; сопровождающие могут опубликовать официальную с помощью npx spiderbrain create.

Этот репозиторий ест свой собственный корм

Этот репозиторий содержит собственную зафиксированную папку .spiderbrain/, полученную из его реального графа импорта (node scripts/build-own-brain.mjs, регенерируется детерминированно, проверяется в CI). Клонируйте его и спросите о нем самом:

npx spiderbrain keystones      # read/src/core.mjs is the load-bearing file
npx spiderbrain verify --allow-stale   # the committed fingerprint matches the bytes

Дайте вашему репозиторию понимание

export SPIDERBRAIN_API_KEY=sb_live_...     # https://spiderbrain.ai/dashboard?tab=keys
npx spiderbrain create

Загружает ваш оцененный мозг и записывает свободную от исходного кода папку .spiderbrain/ плюс блок AGENTS.md. Зафиксируйте оба, и каждый агент, который позже коснется репозитория, прочитает их.

Офлайн против облака

• Офлайн (бесплатно, детерминированно, из зафиксированных байтов): структура, зависимости, радиус поражения, ключевые узлы. Один и тот же репозиторий, один и тот же вопрос, один и тот же ответ, байт в байт.

• Облако (установите SPIDERBRAIN_API_KEY): почему за файлом (записанное решение и его обоснование), всегда свежие оценки и семантический поиск. Получите ключ на https://spiderbrain.ai/dashboard?tab=keys.

export SPIDERBRAIN_API_KEY=sb_live_...
npx spiderbrain why src/billing/charge.ts

Что находится в папке

Зафиксированная папка .spiderbrain/ свободна от исходного кода: пути к файлам, структура и радиус поражения, выводимый из ребер. Никогда ваш исходный код. Никогда веса оценки. Ее точное содержимое и гарантии детерминизма задокументированы в SPEC.md.

Каждая папка несет отпечаток в своем manifest.json; читатель пересчитывает его при загрузке, поэтому вручную отредактированная или поврежденная папка помечается, и карта, к которой вы обращаетесь, — это карта, которая была опубликована.

Этот репозиторий (три MIT-пакета + спецификация)

• spiderbrain/ — spiderbrain, одна команда. Тонкий диспетчер над двумя ниже.

• read/ — @spiderbrain/read, потребление: загрузчик папок, обход радиуса поражения, CLI, MCP-сервер, облачный клиент. Ноль зависимостей.

• create/ — @spiderbrain/create, производство: загрузка вашего оцененного мозга и запись набора понимания + AGENTS.md.

• SPEC.md — публичный формат папки .spiderbrain/.

Каждый scoped-пакет устанавливается независимо: заданию CI, которое только публикует понимание, нужен только @spiderbrain/create; конфигурации MCP, которая только читает, указывает на @spiderbrain/read. spiderbrain — это то, что вы вводите, когда просто хотите получить результат.

Движок, который оценивает мозг (парсинг и модель оценки), является проприетарным и принадлежит SpiderBrain. Что здесь открыто, так это формат, читатель и клиент-производитель, поэтому любой может прочитать или записать опубликованный слой понимания или создать инструмент, который это делает.

Лицензия

MIT. См. LICENSE.