CommunityProgramación y desarrollogithub.com

wingbox

Grafo de código para repositorios grandes y monorepos. Úsalo, antes de grep o leer archivos, cuando la pregunta sea qué romperá un cambio (radio de explosión, análisis de impacto), quién usa un archivo, función, tipo o paquete, dónde está implementada una característica, qué archivos leer primero, o cómo dependen los módulos y paquetes entre sí; antes de una refactorización, un cambio entre paquetes o cualquier edición no trivial; y al explorar un código base desconocido. Construye y consulta búsqueda de código con conocimiento de la arquitectura, grafos de dependencias, flujos de llamadas, límites de módulos y violaciones de arquitectura para Python, TypeScript, TSX, Rust, C#, Java, Go, Ruby, Ruby on Rails, PHP, Laravel, Blade, Livewire, Eloquent, Dart y Flutter.

¿Qué es wingbox?

Wingbox es una habilidad para agentes de IA (como Claude Code, Cursor, Codex) que construye un grafo de código local y completo de la arquitectura de un proyecto, permitiendo consultas avanzadas sobre dependencias, impacto de cambios y estructura de módulos antes de leer el código fuente. Es especialmente útil en repositorios grandes y monorepos para realizar análisis de radio de explosión (blast radius), encontrar quién usa un archivo o función, determinar qué archivos leer primero, y detectar violaciones de arquitectura. Soporta múltiples lenguajes (Python, TypeScript, Rust, C#, Java, Go, Ruby, PHP, Dart, Flutter, etc.) y se integra directamente en el flujo de trabajo del agente a través de comandos como `/wingbox` y consultas sexp. El agente debe construir el grafo si no existe y siempre ejecutar consultas de análisis antes de leer archivos o usar grep, siguiendo un flujo estricto: buscar el módulo, analizarlo, leer solo los archivos límite y no directorios completos.

Compatible con✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/aileron-tech/wingbox/tree/HEAD

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Wingbox -- Descubrimiento de Arquitectura de Grafos de Código

Consulta .wingbox/index.sexp para descubrir módulos, límites y dependencias antes de leer archivos fuente. Nunca leas código a ciegas: consulta el grafo primero.

/wingbox

Cuando el usuario escribe /wingbox (en Codex $wingbox), haz esto antes que cualquier otra cosa:

  • /wingbox sin argumento: encuentra el grafo (.wingbox/index.sexp en la raíz del proyecto; cada comando wingbox lo encuentra también desde una subcarpeta). Constrúyelo con wingbox build . cuando falte o esté desactualizado. El grafo está desactualizado cuando un archivo del proyecto se modificó después del archivo del grafo; esta comprobación lo encuentra:

    G=.wingbox/index.sexp
    [ ! -f "$G" ] || find . -type f -newer "$G" -not -path './.git/*' \
      -not -path './.wingbox/*' -not -path '*/node_modules/*' -print -quit
    

    Una reconstrucción re-analiza solo los archivos cuyo contenido cambió. Luego lee .wingbox/REPORT.md y dale al usuario sus "Hallazgos clave", los módulos más dependidos y por dónde empezar a leer, y dime que el mapa es .wingbox/map.html (wingbox open lo muestra en un navegador, sin conexión).

  • /wingbox <archivo>: ejecuta wingbox impact <archivo> 2 y resume qué depende del archivo y qué archivos leer primero.

  • /wingbox <comando> ...: ejecuta wingbox <comando> ... (por ejemplo /wingbox quick "carga de archivos", /wingbox analyze src/billing/invoice).

Ejecución de los comandos

Cuando el comando wingbox está instalado (command -v wingbox), ejecuta wingbox <comando> ... para cada consulta a continuación y wingbox build RUTA para construir; toman los mismos argumentos que los scripts. Una habilidad instalada por wingbox install no tiene carpeta scripts/ y siempre usa el comando.

ComandoPropósito
`wingbox install [--global--project] [--assistant NOMBRE ...] [--dry-run]`
`wingbox uninstall [--global--project] [--assistant NOMBRE ...]`
wingbox open [RUTA]Abre .wingbox/map.html del proyecto en el navegador (imprime su ruta cuando no hay navegador)
wingbox update [--check] [--dry-run]Actualiza con pipx, uv o pip, luego refresca las habilidades instaladas, bloques y hooks; advierte sobre archivos que dejó una versión anterior (.code_graph*, wingbox-out/)
wingbox hook pre-searchEl hook PreToolUse de Claude Code; lee la entrada del hook en stdin; refresca el grafo antes de leerlo
wingbox hook dirtyEl hook PostToolUse de Claude Code en Editar y Escribir: marca el archivo modificado para que el grafo se refresque antes de su próximo uso

Cada uno de estos imprime hechos como texto; agrega --sexp para S-expresiones.

Scripts

Esta habilidad incluye scripts de Python. Resuelve las raíces de la habilidad y del objetivo antes de ejecutarlos para que el proyecto escaneado sea siempre explícito:

  • scripts/code_graph_search.py -- consulta el grafo de código
  • scripts/build_code_graph.py -- genera el grafo de código desde el código fuente
  • scripts/build_infra_topology.py -- extrae hechos de topología de Kustomize, Helm y Terraform
  • scripts/git_descendants.py -- encuentra todas las confirmaciones descendientes de HEAD (o de una referencia dada)

Nunca uses copias locales del proyecto de estos scripts -- pueden estar desactualizados y generar JSON en lugar de sexp.

Prerrequisito

Localiza el grafo de código. Si está ausente, constrúyelo:

ls .wingbox/index.sexp 2>/dev/null
SKILL_ROOT="$(pwd -P)"
TARGET_ROOT="$(cd /ruta/absoluta/al/proyecto && pwd -P)"
python3 "$SKILL_ROOT/scripts/build_code_graph.py" --root "$TARGET_ROOT"
python3 "$SKILL_ROOT/scripts/build_code_graph.py" --root "$TARGET_ROOT" --full

La indexación de Python no tiene dependencia externa de analizador sintáctico. Para otros lenguajes detectados, la primera compilación falla antes de la publicación cuando falta un analizador o tiene la versión incorrecta e imprime el comando exacto por lenguaje para ejecutar, como:

python3 -m pip install -r "$SKILL_ROOT/requirements/typescript.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/csharp.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/ruby.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/php.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/dart.txt"

Instala solo los archivos de requisitos nombrados por el constructor, luego vuelve a ejecutarlo. requirements.txt está reservado para la dependencia de topología de infraestructura.

Flujo de Trabajo Obligatorio: Consulta Antes del Código

Para trabajo de código no trivial, ejecuta una consulta al grafo de código antes de rg, find, sed, cat, nl, abrir directorios o leer archivos fuente. La habilidad solo ayuda cuando se usa como primer paso de alcance, no como confirmación después de que el código ya ha sido inspeccionado.

Primer paso rápido cuando la tarea tiene una palabra clave clara:

python3 scripts/code_graph_search.py quick "palabra clave"

quick busca el primer módulo que coincide e inmediatamente ejecuta analyze. Úsalo para obtener archivos límite, dependencias, dependencias inversas, capas y violaciones en un solo paso. Si quick devuelve el módulo incorrecto o no encuentra coincidencias, usa el flujo explícito search -> analyze a continuación.

Paso 1 -- Encuentra el ID del módulo:

python3 scripts/code_graph_search.py search "palabra clave"
python3 scripts/code_graph_search.py entity NombreEntidad

Usa search o entity para localizar el ID del módulo. Los IDs de módulo son rutas relativas completas como billing-service/src/modules/invoice/invoice.service, no códigos cortos como bs34. El grafo de código puede contener IDs de mapas de ruta cortos internamente, pero se resuelven automáticamente -- siempre pasa cadenas legibles similares a rutas. NO adivines ni inventes IDs de módulo -- siempre confirma con search primero.

Paso 2 -- Analiza el módulo (haz esto INMEDIATAMENTE, no de forma opcional):

python3 scripts/code_graph_search.py analyze <id-del-módulo>

analyze es el comando PRINCIPAL. Devuelve el contexto completo: archivos límite, dependencias, dependencias inversas, capa de arquitectura y violaciones. Ejecútalo siempre antes de leer cualquier código fuente.

Paso 3 -- Lee solo los archivos límite listados en la salida de analyze.

Paso 4 -- NO leas directorios completos. Si el límite muestra 2-3 archivos relevantes, lee solo esos archivos. Ignora todo lo demás en el directorio.

Referencia de Comandos

ComandoPropósitoEjemplo
search "<patrón>"Búsqueda literal segura / con .* en el grafosearch "operative.*service"
analyze <id> [--all]Análisis completo del módulo (comando PRINCIPAL); nombra como máximo 200 dependientes a menos que se use --all; termina con el (advice ...) que concierne al móduloanalyze drive/modules/drive/drive_schema
quick <palabra clave>Buscar + analizar la primera coincidencia (atajo)quick operatives
boundary <id>Archivos a leer para un cambioboundary operatives.service
boundary <id> --files-onlySolo rutas de archivos (compacto)boundary operatives.service --files-only
entity <Nombre> [--positions]Encontrar definiciones + los módulos que las usan; --positions: cada uso con línea y columnaentity DrivePath --positions
usages <símbolo> [--sexp] [--all]Cada uso de un símbolo (Nombre, <archivo>::Nombre, <archivo>::Clase.método) a través de reexportaciones y alias, por archivo, linea:col y tipo (importación, reexportación, llamada, tipo, extensión, referencia; unresolved-call para una llamada a método cuyo tipo receptor no está a la vista); como máximo 200 a menos que --all; un nombre definido en varios archivos lista los candidatosusages src/billing/invoice.ts::Invoice
deps <id> [profundidad]Árbol de dependencias salientesdeps operatives.service 3
rdeps <id> [profundidad]Radio de explosión (quién depende de esto)rdeps drive_schema 2
`impact <archivoid> [profundidad] --sexp [--all]`Radio de explosión de un archivo: dependientes por profundidad más corta + archivos a leer primero; lista como máximo 200 a menos que --all, los recuentos son siempre completos; termina con el consejo que concierne al archivo
flow <id> <fn>Trazar flujo de llamadas/datosflow drive_api fetchFiles
module <id>Módulo único con aristasmodule operatives.controller
wingbox init [RUTA] [--force] [--sexp] [--synonyms]Dividir el repositorio en partes, juzgar el estilo de arquitectura de cada una (con puntuación, evidencia y fuentes) y escribir .wingbox/config.yaml (se conserva a menos que se use --force); --synonyms también mapea nombres de carpetas a través de los vectores de palabras integrados; en una carpeta vacía --language L --style S --yes [--scaffold] inicia un nuevo proyecto (sin ellos imprime las opciones y sale con código 2)wingbox init --sexp
wingbox advice [--sexp] [--learned] / `wingbox advice acceptreject [--reason TEXTO]`Abrir recomendaciones de la última compilación (mover, corregir-violación, carpeta-faltante) sin las rechazadas o ignoradas por mucho tiempo; registrar una decisión en .wingbox/decisions.sexp
wingbox align [PARTE] [--to ESTILO] [--learn] [--sexp]Brechas de cada parte contra su estilo (archivos colocados, reglas seguidas, carpetas no colocadas, reglas rotas); --to contra otro estilo; --learn escribe carpetas aprendidas y una línea base para que solo se reporten nuevas violacioneswingbox align --sexp
wingbox place "<qué>" [--part PARTE] [--sexp]Capa y carpeta para código nuevo según las reglas de colocación del estilo de la parte (:new cuando la carpeta aún no existe) y qué puede importarwingbox place "repositorio para facturas" --sexp
wingbox compare [--sexp]Partes de un monorepo por lenguaje: estilo, capas, diferencias (capas faltantes, un nombre de carpeta que significa otra capa, un estilo diferente a la mayoría) y consejo para la parte que se desvíawingbox compare --sexp
wingbox learn --agent [PARTE] [--sexp] / wingbox learn --apply [ARCHIVO]/wingbox learn: ejecuta wingbox learn --agent, lee los archivos que nombra, responde solo en su formato ((layer <parte> <carpeta> <capa> :because "..."), (unknown ...), como máximo un (style ...)), canaliza la respuesta a wingbox learn --apply, muestra el resultado; en errores corrige las líneas nombradas y envía la respuesta completa de nuevo. Cuando el código no decide una carpeta, pregunta al usuario en el chat y responde con :because "operator: <sus palabras>"; nunca adivines. Para cambiar .wingbox/config.yaml, sigue las instrucciones en su parte superiorwingbox learn --agent
`boundaries [idall]`Verificar las reglas de límite de cada estilo de parte (o de las reglas que la parte declara); cada línea nombra :part, :style y :rule; las importaciones de solo tipo y las capas adivinadas se reportan por separado; luego qué archivos hacen lo que su capa quizás no (capability-violation: SQL fuera de los repositorios, HTTP saliente fuera de la infraestructura, el framework en el dominio, con :line y :evidence) y las comprobaciones de patrón del estilo (pattern-violation). boundaries-ok solo cuando cada parte fue verificada; una parte cuyas reglas declaradas no se leyeron, o sin un estilo determinado, es boundaries-not-checked con boundaries-partial en lugar de ok. Código de salida: 2 no verificado (reglas declaradas no leídas), 1 violaciones, 0 en caso contrario - nunca reportar un pase en código de salida 2
`invariants [idall]`Verificar violaciones de convenciones de nomenclatura
layersMostrar todos los módulos por capa, con la parte, el estilo y la regla que establecieron cada capalayers
find_function <nombre>Encontrar definiciones de funciones/métodosfind_function createOrder
find_type <nombre>Encontrar definiciones de tipos/clases/módulos/interfaces/enumeracionesfind_type DriveDbCommitResponse
find_callchain <src> <tgt> [profundidad]Trazar ruta de llamada entre funcionesfind_callchain createOrder processPayment
find_callers <fn> [profundidad]Quién llama a esta funciónfind_callers handleRequest 3
find_calls <fn> [profundidad]Qué llama esta funciónfind_calls createOrder 2
grep_functions <patrón>Buscar cuerpos de funciones en el código fuentegrep_functions "validate.*input"
diff_functions [ref]Funciones cambiadas en diff de gitdiff_functions HEAD~3
query '<sexp>'Consulta Scheme componiblequery '(count (boundary "X"))'
replREPL de Scheme interactivorepl
wingbox mcp [--root DIR]Ejecutar estos comandos como herramientas de un servidor MCP en stdio (build, impact, usages, analyze, quick, boundary, deps, ...) para clientes MCPclaude mcp add wingbox -- wingbox mcp

impact acepta una ruta de archivo ordinaria. Sin --sexp imprime texto legible para personas; los agentes pasan --sexp para obtener los mismos hechos en la forma compacta de S-expresión, que es el formato que usan todos los demás comandos.

Referencia Rápida: Consultas rg

Cuando necesites búsquedas rápidas y específicas sin invocar el script de Python, consulta el grafo de código directamente con rg. El constructor escribe el grafo en .wingbox/index.sexp:

# Todos los hechos sobre un módulo
rg 'drive/modules/drive_db/api ' .wingbox/index.sexp

# Quién importa un módulo
rg 'imports .* drive/modules/commons/result' .wingbox/index.sexp

# Qué importa un módulo
rg 'imports drive/modules/drive_db/api' .wingbox/index.sexp

# Todas las referencias a una entidad
rg 'DriveDbCommitResponse' .wingbox/index.sexp

# Todas las clases en un repositorio
rg '^\(cls drive/' .wingbox/index.sexp

# Aristas de flujo de datos
rg 'data-flow' .wingbox/index.sexp

# Módulos de Python cargados por un nombre leído de un archivo de configuración
rg 'registry-wires' .wingbox/index.sexp

Estos one-liners son útiles para comprobaciones rápidas. Para salida estructurada y análisis completo, usa los comandos del script de Python.

Notación de Salida

Toda la salida son hechos en S-expresión, uno por línea. Consulta references/sexp-notation.md para el formato completo.

Patrones clave:

(boundary <mod> :lang py :file <ruta> :purpose "<desc>")
(boundary-dep <mod> <dep> :lang ts :file <ruta> :relation imports)
(boundary-rdep <mod> <rdep> :lang tsx :file <ruta> :relation imports)
(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
(entity-def cls <mod> <Nombre> <línea> :lang py :file <ruta>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<razón>")
(result <módulo-o-ruta>)
(result-count 42)

Valores de :lang: py = Python (snake_case), ts = TypeScript (camelCase), tsx = TSX (PascalCase)

…

[truncado para traducción]

Skills relacionados