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:
-
/wingboxsin argumento: encuentra el grafo (.wingbox/index.sexpen la raíz del proyecto; cada comandowingboxlo encuentra también desde una subcarpeta). Constrúyelo conwingbox 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 -quitUna reconstrucción re-analiza solo los archivos cuyo contenido cambió. Luego lee
.wingbox/REPORT.mdy 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 openlo muestra en un navegador, sin conexión). -
/wingbox <archivo>: ejecutawingbox impact <archivo> 2y resume qué depende del archivo y qué archivos leer primero. -
/wingbox <comando> ...: ejecutawingbox <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.
| Comando | Propó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-search | El hook PreToolUse de Claude Code; lee la entrada del hook en stdin; refresca el grafo antes de leerlo |
wingbox hook dirty | El 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ódigoscripts/build_code_graph.py-- genera el grafo de código desde el código fuentescripts/build_infra_topology.py-- extrae hechos de topología de Kustomize, Helm y Terraformscripts/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
| Comando | Propósito | Ejemplo |
|---|---|---|
search "<patrón>" | Búsqueda literal segura / con .* en el grafo | search "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ódulo | analyze drive/modules/drive/drive_schema |
quick <palabra clave> | Buscar + analizar la primera coincidencia (atajo) | quick operatives |
boundary <id> | Archivos a leer para un cambio | boundary operatives.service |
boundary <id> --files-only | Solo 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 columna | entity 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 candidatos | usages src/billing/invoice.ts::Invoice |
deps <id> [profundidad] | Árbol de dependencias salientes | deps operatives.service 3 |
rdeps <id> [profundidad] | Radio de explosión (quién depende de esto) | rdeps drive_schema 2 |
| `impact <archivo | id> [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/datos | flow drive_api fetchFiles |
module <id> | Módulo único con aristas | module 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 accept | reject [--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 violaciones | wingbox 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 importar | wingbox 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ía | wingbox 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 superior | wingbox learn --agent |
| `boundaries [id | all]` | 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 [id | all]` | Verificar violaciones de convenciones de nomenclatura |
layers | Mostrar todos los módulos por capa, con la parte, el estilo y la regla que establecieron cada capa | layers |
find_function <nombre> | Encontrar definiciones de funciones/métodos | find_function createOrder |
find_type <nombre> | Encontrar definiciones de tipos/clases/módulos/interfaces/enumeraciones | find_type DriveDbCommitResponse |
find_callchain <src> <tgt> [profundidad] | Trazar ruta de llamada entre funciones | find_callchain createOrder processPayment |
find_callers <fn> [profundidad] | Quién llama a esta función | find_callers handleRequest 3 |
find_calls <fn> [profundidad] | Qué llama esta función | find_calls createOrder 2 |
grep_functions <patrón> | Buscar cuerpos de funciones en el código fuente | grep_functions "validate.*input" |
diff_functions [ref] | Funciones cambiadas en diff de git | diff_functions HEAD~3 |
query '<sexp>' | Consulta Scheme componible | query '(count (boundary "X"))' |
repl | REPL de Scheme interactivo | repl |
wingbox mcp [--root DIR] | Ejecutar estos comandos como herramientas de un servidor MCP en stdio (build, impact, usages, analyze, quick, boundary, deps, ...) para clientes MCP | claude 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]