sourcebook

AI는 당신의 코드를 읽을 수 있습니다. 하지만 여전히 당신의 프로젝트가 어떻게 작동하는지는 모릅니다.

sourcebook은 팀이 머릿속에 가지고 있는 프로젝트 지식(컨벤션, 패턴, 함정, 실제 파일 위치 등)을 캡처하여 코딩 에이전트가 사용할 수 있는 컨텍스트로 변환합니다.

npx sourcebook init

Repomix와 같은 도구는 AI에게 전체 코드베이스를 제공합니다. sourcebook은 AI에게 당신의 프로젝트 지식을 제공합니다.

왜 필요한가

AI 코딩 에이전트는 컨텍스트 윈도우의 대부분을 상황 파악에 소비합니다. 즉, 실제 작업을 시작하기 전에 정신적 모델을 구축하기 위해 파일을 읽는 데 시간을 씁니다. 대부분의 컨텍스트 파일(CLAUDE.md, .cursorrules)은 일반적이며 금방 구식이 됩니다.

연구에 따르면 당연한 정보를 다시 나열하는 자동 생성 컨텍스트는 오히려 에이전트의 성능을 2-3% 저하시킵니다. 도움이 되는 유일한 컨텍스트는 발견하기 어려운 정보입니다. 즉, 에이전트가 코드만 읽어서는 파악할 수 없는 프로젝트 지식입니다.

sourcebook은 에이전트가 계속 놓치는 정보, 즉 코드에는 없지만 팀의 머릿속에만 존재하는 컨벤션, 숨겨진 의존성, 취약한 영역, 지배적인 패턴만을 추출합니다.

탐지 항목

• 임포트 그래프 + PageRank — 구조적 중요도에 따라 파일 순위를 매기고, 영향 범위가 가장 넓은 허브 파일을 식별합니다.

• Git 기록 포렌식 — 되돌린 커밋("이렇게 하지 마시오" 신호), 코드 변경 결합도(보이지 않는 의존성), 잦은 재수정(작성하기 어려웠던 코드), 버려진 접근 방식에서 나타나는 안티 패턴.

• 컨벤션 탐지 — 명명 패턴, export 스타일, import 구성, 배럴(barrel) export, 경로 별칭(path alias), 타입 힌트 사용법, 에러 처리 스타일.

• 프레임워크 탐지 — Next.js, Expo, Supabase, Tailwind, Express, TypeScript, Django, FastAPI, Flask, Go (Gin, Echo, Fiber).

• 컨텍스트 노후화 방지 포맷팅 — 상단에는 중요한 제약 사항, 중간에는 참조 정보, 하단에는 작업 프롬프트를 배치(LLM의 주의 집중 패턴에 최적화).

• 스마트 예산 집행 — 컨텍스트가 토큰 예산을 초과하면 우선순위가 낮은 섹션부터 제거(중요한 제약 사항은 항상 유지).

빠른 시작

# Generate CLAUDE.md + AGENTS.md for your project
npx sourcebook init

# Generate for a specific tool
npx sourcebook init --format claude,agents  # CLAUDE.md + AGENTS.md (default)
npx sourcebook init --format cursor         # .cursor/rules/sourcebook.mdc + .cursorrules
npx sourcebook init --format copilot        # .github/copilot-instructions.md
npx sourcebook init --format agents         # AGENTS.md only
npx sourcebook init --format all            # All of the above

# Re-analyze while preserving your manual edits
npx sourcebook update

# See what changed since last generation (exit code 1 = changes found)
npx sourcebook diff

# Limit output to a token budget (drops low-priority sections first)
npx sourcebook init --budget 1000

명령어

옵션

언어 지원

GitHub Action

모든 병합 시 컨텍스트 파일 자동 업데이트:

# .github/workflows/sourcebook.yml
name: Update context files
on:
  push:
    branches: [main]

jobs:
  sourcebook:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: maroondlabs/sourcebook@main
        with:
          format: all

출력 예시

cal.com (10,456개 파일)에서 실행 시:

sourcebook
Extracting repo truths...

✓ Scanned project structure
  10,456 files, 3 frameworks detected
✓ Extracted 11 findings

  ● Core modules: types.ts imported by 183 files — widest blast radius
  ● Circular deps: bookingScenario.ts ↔ getMockRequestData.ts
  ● Co-change: auth/provider.ts ↔ middleware/session.ts (88% correlation)
  ● Dead code: 1,907 orphan files detected
  ● Conventions: named exports preferred (26:2 ratio)
  ● Barrel exports: 40 index.ts re-export files
  ● Commit style: Conventional Commits (feat/fix/docs)

✓ Wrote CLAUDE.md
✓ Wrote AGENTS.md

작동 원리

sourcebook은 5단계의 분석 과정을 거치며, 모두 결정론적이고 로컬에서 수행됩니다. LLM, API 키, 네트워크 호출이 필요 없습니다:

1. 정적 분석 — 프레임워크 탐지, 빌드 명령어, 프로젝트 구조, 환경 변수.

2. 임포트 그래프 — 모든 임포트의 방향성 그래프를 구축하고 PageRank를 실행하여 구조적으로 가장 중요한 파일을 찾습니다.

3. Git 포렌식 — 커밋 기록에서 되돌리기, 안티 패턴, 코드 변경 결합도, 변경이 잦은 핫스팟, 버려진 접근 방식을 추출합니다.

4. 컨벤션 추론 — 소스 파일을 샘플링하여 명명, import, export, 에러 처리 및 타입 주석 패턴을 탐지합니다.

5. 예산 집행 — 출력이 토큰 예산을 초과하면 우선순위가 낮은 섹션을 지능적으로 제거합니다(보조적인 발견 사항부터 제거, 중요한 제약 사항은 절대 제거 안 함).

그 후 발견 가능성 필터를 적용합니다. 모든 발견 사항에 대해 "에이전트가 코드를 읽어서 스스로 알아낼 수 있는가?"를 묻고, 그렇다면 제거합니다. 발견하기 어려운 정보만 출력에 포함됩니다.

출력물은 컨텍스트 노후화 방지를 위해 포맷팅됩니다. 중요한 제약 사항은 파일의 상단과 하단(LLM이 가장 주의를 기울이는 곳)에 배치하고, 가벼운 참조 정보는 중간에 배치합니다.

MCP 서버

sourcebook serve는 로컬 MCP(Model Context Protocol) 서버를 시작하여 Claude Desktop, Cursor 등 MCP 호환 AI 클라이언트에 실시간 코드베이스 인텔리전스를 노출합니다.

정적인 컨텍스트 파일 대신, AI 에이전트가 필요할 때마다 프로젝트 아키텍처를 쿼리할 수 있습니다. 수정 전 영향 범위를 확인하고, 코드를 작성하기 전 컨벤션을 확인하며, Git 기록에서 안티 패턴을 찾아낼 수 있습니다.

설치

MCP 클라이언트 설정에 sourcebook을 추가하세요:

{
  "mcpServers": {
    "sourcebook": {
      "command": "npx",
      "args": ["-y", "sourcebook", "serve", "--dir", "/path/to/your/project"]
    }
  }
}

Claude Code — 터미널에서 실행:

claude mcp add sourcebook -- npx -y sourcebook serve --dir /path/to/your/project

또는 ~/.claude/claude_desktop_config.json에 수동으로 추가하세요.

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json에 추가하세요.

Cursor — 프로젝트의 .cursor/mcp.json 또는 전역 ~/.cursor/mcp.json에 추가하세요.

기타 MCP 클라이언트 — STDIO 전송을 지원하는 모든 클라이언트는 위와 동일한 설정 블록으로 작동합니다.

설정 업데이트 후 클라이언트를 재시작하세요.

사용 가능한 도구

서버는 스캔 결과를 메모리에 캐시하므로 후속 도구 호출은 빠릅니다. 재스캔을 강제하려면 analyze_codebase에 refresh: true를 전달하세요.

로드맵

• [x] .cursor/rules/sourcebook.mdc + 기존 .cursorrules 출력

• [x] .github/copilot-instructions.md 출력

• [x] sourcebook update — 수동 편집 내용을 유지하며 재분석

• [x] sourcebook diff — 변경 사항 표시 (CI 친화적 종료 코드)

• [x] --budget <tokens> — PageRank 기반 스마트 우선순위 지정

• [x] 되돌린 커밋 및 삭제된 파일로부터 안티 패턴 탐지

• [x] Python 지원 (Django, FastAPI, Flask, pytest)

• [x] Go 지원 (Gin, Echo, Fiber, 모듈 레이아웃)

• [x] CI를 위한 GitHub Action

• [x] sourcebook serve — MCP 서버 모드

• [ ] 프레임워크 지식 팩 (커뮤니티 기여)

• [ ] 더 깊은 컨벤션 탐지를 위한 Tree-sitter AST 파싱

• [ ] 컨텍스트 품질 점수가 포함된 호스팅 대시보드

연구 기반

다음 연구 결과를 바탕으로 구축되었습니다:

• ETH Zurich AGENTS.md 연구 — 자동 생성된 당연한 컨텍스트는 에이전트 성능을 저하시킴

• Karpathy의 autoresearch — 큐레이팅된 컨텍스트(program.md)는 에이전트 효율성을 높이는 가장 중요한 요소

• Aider의 repo-map — 구조적 중요도를 위한 임포트 그래프의 PageRank

• Chroma의 컨텍스트 노후화 연구 — LLM은 컨텍스트 중간 부분의 정보에 대해 30% 이상의 정확도 저하를 보임

라이선스

BSL-1.1 — 소스 공개, 무료 사용 가능, 호스팅 서비스로 제공 불가. 2030년 3월 25일에 MIT 라이선스로 전환됩니다. 자세한 내용은 LICENSE를 참조하세요.