SpiderBrain: 저장소를 위한 이해 계층

저장소는 AI 에이전트에게 코드가 무엇인지만 알려줍니다. 무엇이 중요한지, 변경 사항이 어디에 영향을 미치는지, 왜 그렇게 구축되었는지는 절대 알려주지 않습니다. 그래서 모든 에이전트는 매 세션마다 구조를 처음부터 다시 유추해야 하고, 조금씩 틀리기 마련입니다.

SpiderBrain은 저장소에 커밋된 소스 프리(source-free) 이해 계층을 제공합니다. 즉, 구조, 의존성, 블래스트 레이더스(blast radius)에 대한 결정론적 맵으로, 어떤 AI 코딩 에이전트도 별도 설정 없이 읽을 수 있습니다. 이 저장소는 그 계층의 오픈 소스(MIT 라이선스) 부분, 즉 리더(reader)와 포맷 사양입니다.

• 웹사이트: https://spiderbrain.ai

• 결정론 벤치마크: https://contextbenchmark.com

한 줄로 사용하기

저장소에 .spiderbrain/ 폴더가 있으면 리더가 그 폴더를 가리키게 하세요:

npx spiderbrain mcp --root .

MCP 클라이언트의 작업 디렉터리는 보통 저장소가 아니므로 --root <path>, --root=<path> 또는 SPIDERBRAIN_ROOT 환경 변수로 저장소를 명시적으로 전달하세요. 그렇지 않으면 서버는 작업 디렉터리를 제공하고 이해 계층을 찾을 수 없다고 보고하는데, 이는 오류가 아니라 잘못된 답변입니다.

그러면 코딩 에이전트(Claude Code, Cursor 또는 모든 MCP 클라이언트)가 쿼리할 수 있는 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로 공식 브레인을 게시할 수 있습니다.

이 저장소는 스스로를 사용합니다

이 저장소는 실제 가져오기 그래프(node scripts/build-own-brain.mjs, 결정론적으로 재생성, CI에서 검증)에서 파생된 자체 커밋 .spiderbrain/ 폴더를 포함합니다. 복제해서 스스로에 대해 물어보세요:

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 블록을 작성합니다. 둘 다 커밋하면 나중에 저장소를 건드리는 모든 에이전트가 이를 읽습니다.

오프라인 vs 클라우드

• 오프라인 (무료, 결정론적, 커밋된 바이트에서 파생): 구조, 의존성, 블래스트 레이더스, 키스톤. 같은 저장소, 같은 질문, 같은 답변이 바이트 단위로 동일합니다.

• 클라우드 (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 패키지 3개 + 스펙)

• spiderbrain/ — spiderbrain, 단일 명령어. 아래 두 개를 얇게 감싸는 디스패처입니다.

• read/ — @spiderbrain/read, 소비: 폴더 로더, 블래스트 레이더스 순회, CLI, MCP 서버, 클라우드 클라이언트. 의존성이 없습니다.

• create/ — @spiderbrain/create, 생성: 점수화된 브레인을 가져와 이해 집합 + AGENTS.md를 작성합니다.

• SPEC.md — .spiderbrain/ 공개 폴더 형식.

각 범위 패키지는 독립적으로 설치할 수 있습니다. 이해를 게시만 하는 CI 작업은 @spiderbrain/create만 있으면 되고, 읽기만 하는 MCP 구성은 @spiderbrain/read를 가리키면 됩니다. spiderbrain은 그냥 실행만 하면 되는 경우에 입력하는 명령어입니다.

브레인을 점수화하는 엔진(파싱 및 점수 모델)은 독점이며 SpiderBrain에 있습니다. 여기서 공개하는 것은 형식, 리더, 생성 클라이언트이므로 누구나 게시된 이해 계층을 읽거나 쓰거나, 그렇게 하는 도구를 만들 수 있습니다.

라이선스

MIT. LICENSE를 참조하세요.