sourcebook

La IA puede leer tu código. Pero aún no sabe cómo funciona tu proyecto.

sourcebook captura el conocimiento del proyecto que tu equipo lleva en la cabeza —convenciones, patrones, trampas y dónde van realmente las cosas— y lo convierte en contexto que tu agente de codificación puede utilizar.

npx sourcebook init

Herramientas como Repomix le dan a la IA toda tu base de código. sourcebook le da el conocimiento de tu proyecto.

Por qué

Los agentes de codificación de IA pasan la mayor parte de su ventana de contexto orientándose: leyendo archivos para construir un modelo mental antes de realizar el trabajo real. La mayoría de los archivos de contexto (CLAUDE.md, .cursorrules) son genéricos y se vuelven obsoletos rápidamente.

Las investigaciones demuestran que el contexto generado automáticamente que reitera información obvia en realidad hace que los agentes sean un 2-3% peores. El único contexto que ayuda es la información no descubrible: el conocimiento del proyecto que los agentes no pueden deducir solo leyendo el código.

sourcebook extrae solo lo que los agentes pasan por alto: las convenciones, dependencias ocultas, áreas frágiles y patrones dominantes que viven en las cabezas de tu equipo, no en el código.

Qué encuentra

• Grafo de importaciones + PageRank — clasifica los archivos por importancia estructural, identifica archivos centrales con el mayor radio de impacto.

• Análisis forense del historial de Git — commits revertidos (señales de "no hagas esto"), acoplamiento de cambios (dependencias invisibles), reediciones rápidas (código difícil de implementar correctamente), antipatrones de enfoques abandonados.

• Detección de convenciones — patrones de nomenclatura, estilo de exportación, organización de importaciones, exportaciones de barril (barrel exports), alias de ruta, uso de sugerencias de tipo, estilo de manejo de errores.

• Detección de frameworks — Next.js, Expo, Supabase, Tailwind, Express, TypeScript, Django, FastAPI, Flask, Go (Gin, Echo, Fiber).

• Formato consciente de la degradación del contexto — restricciones críticas al principio, información de referencia en el medio, prompts de acción al final (optimizado para los patrones de atención de los LLM).

• Aplicación inteligente de presupuesto — cuando el contexto excede tu presupuesto de tokens, descarta primero las secciones de baja prioridad (manteniendo siempre las restricciones críticas).

Inicio rápido

# 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

Comandos

Opciones

Soporte de lenguajes

GitHub Action

Actualiza automáticamente los archivos de contexto en cada merge:

# .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

Ejemplo de salida

Ejecutado en cal.com (10,456 archivos):

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

Cómo funciona

sourcebook ejecuta cinco pasadas de análisis, todas deterministas y locales —sin LLM, sin claves API, sin llamadas de red:

1. Análisis estático — detección de framework, comandos de compilación, estructura del proyecto, variables de entorno.

2. Grafo de importaciones — construye un grafo dirigido de todas las importaciones, ejecuta PageRank para encontrar los archivos estructuralmente más importantes.

3. Análisis forense de Git — explora el historial de commits en busca de reversiones, antipatrones, acoplamiento de cambios, puntos críticos de rotación y enfoques abandonados.

4. Inferencia de convenciones — muestrea archivos fuente para detectar patrones de nomenclatura, importación, exportación, manejo de errores y anotación de tipos.

5. Aplicación de presupuesto — si la salida excede tu presupuesto de tokens, descarta inteligentemente las secciones de baja prioridad (primero los hallazgos suplementarios, nunca las restricciones críticas).

Luego aplica un filtro de descubribilidad: por cada hallazgo, pregunta "¿puede un agente deducir esto leyendo el código?". Si la respuesta es sí, lo descarta. Solo la información no descubrible llega a la salida.

La salida está formateada para ser resistente a la degradación del contexto: las restricciones críticas van al principio y al final del archivo (donde los LLM prestan más atención), la información de referencia ligera va en el medio.

Servidor MCP

sourcebook serve inicia un servidor local MCP (Model Context Protocol) que expone inteligencia de base de código en tiempo vivo a cualquier cliente de IA compatible con MCP: Claude Desktop, Cursor y otros.

En lugar de un archivo de contexto estático, tu agente de IA puede consultar la arquitectura de tu proyecto bajo demanda: buscar el radio de impacto antes de editar, verificar convenciones antes de escribir código, extraer el historial de git en busca de antipatrones.

Instalación

Añade sourcebook a la configuración de tu cliente MCP:

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

Claude Code — ejecuta en tu terminal:

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

O añádelo manualmente a ~/.claude/claude_desktop_config.json.

Claude Desktop — añádelo a ~/Library/Application Support/Claude/claude_desktop_config.json.

Cursor — añádelo a .cursor/mcp.json en tu proyecto o a ~/.cursor/mcp.json globalmente.

Otros clientes MCP — cualquier cliente que soporte transporte STDIO funciona con el mismo bloque de configuración anterior.

Reinicia tu cliente después de actualizar la configuración.

Herramientas disponibles

El servidor almacena el escaneo en memoria: las llamadas posteriores a las herramientas son rápidas. Pasa refresh: true a analyze_codebase para forzar un re-escaneo.

Hoja de ruta

• [x] .cursor/rules/sourcebook.mdc + salida heredada .cursorrules

• [x] Salida .github/copilot-instructions.md

• [x] sourcebook update — reanalizar preservando ediciones manuales

• [x] sourcebook diff — mostrar qué cambió (códigos de salida compatibles con CI)

• [x] --budget <tokens> — priorización inteligente basada en PageRank

• [x] Detección de antipatrones a partir de commits revertidos y archivos eliminados

• [x] Soporte para Python (Django, FastAPI, Flask, pytest)

• [x] Soporte para Go (Gin, Echo, Fiber, diseño de módulos)

• [x] GitHub Action para CI

• [x] sourcebook serve — modo servidor MCP

• [ ] Paquetes de conocimiento de frameworks (contribuidos por la comunidad)

• [ ] Análisis AST con Tree-sitter para una detección de convenciones más profunda

• [ ] Panel de control alojado con puntuaciones de calidad de contexto

Base de investigación

Construido sobre hallazgos de:

• Estudio AGENTS.md de ETH Zurich — el contexto obvio generado automáticamente perjudica el rendimiento del agente.

• Autoinvestigación de Karpathy — el contexto curado (program.md) es la palanca número 1 para la eficacia del agente.

• Mapa de repositorio de Aider — PageRank en grafos de importación para la importancia estructural.

• Investigación de Chroma sobre la degradación del contexto — los LLM muestran caídas de precisión del 30%+ para información en el medio del contexto.

Licencia

BSL-1.1 — código disponible, uso gratuito, no puede ofrecerse como servicio alojado. Se convierte a MIT el 25-03-2030. Consulta LICENSE para más detalles.