wingbox

Grafo de código para grandes repositórios e monorepos. Use-o, antes de grep ou ler arquivos, quando a pergunta é o que uma alteração quebrará (raio de explosão, análise de impacto), quem usa um arquivo, função, tipo ou pacote, onde uma funcionalidade é implementada, quais arquivos ler primeiro, ou como módulos e pacotes dependem uns dos outros; antes de um refatoramento, uma alteração entre pacotes ou qualquer edição não trivial; e ao explorar uma base de código desconhecida. Constrói e consulta pesquisa de código ciente de arquitetura, grafos de dependência, fluxos de chamada, limites de módulos e violações de arquitetura para Python, TypeScript, TSX, Rust, C#, Java, Go, Ruby, Ruby on Rails, PHP, Laravel, Blade, Livewire, Eloquent, Dart e Flutter.

O que é wingbox?

Wingbox é uma ferramenta de descoberta de arquitetura de código que constrói e consulta um grafo de código em S-expression, permitindo que desenvolvedores e agentes de IA naveguem em bases de código grandes e monorepos sem ler arquivos cegamente. Em vez de usar grep ou leitura de arquivos como primeira ação, o wingbox recomenda consultar primeiro o grafo de código para entender a estrutura do projeto, dependências, fluxos de chamada e limites de módulos. A ferramenta suporta múltiplas linguagens de programação (Python, TypeScript, Rust, C#, Java, Go, Ruby, PHP, Dart/Flutter e frameworks como Laravel e Ruby on Rails) e é especialmente útil antes de refatorações, alterações entre pacotes, análise de impacto (raio de explosão) e exploração de bases de código desconhecidas. O wingbox é integrado a assistentes de IA como Claude Code e Codex através de comandos como `/wingbox`, hooks de pré-pesquisa e pós-edição, e pode ser instalado globalmente ou por projeto. Seu fluxo de trabalho principal é consultar o grafo antes de ler arquivos fonte, usando comandos como `analyze`, `impact`, `usages` e `boundary` para obter contexto completo sobre módulos, dependências e violações de arquitetura.

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

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Wingbox -- Descoberta de Arquitetura por Grafo de Código

Consulte .wingbox/index.sexp para descobrir módulos, limites e dependências antes de ler arquivos fonte. Nunca leia código cegamente -- consulte o grafo primeiro.

/wingbox

Quando o usuário digitar /wingbox (no Codex $wingbox), faça isso antes de qualquer outra coisa:

  • /wingbox sem argumento: encontre o grafo (.wingbox/index.sexp na raiz do projeto; todo comando wingbox o encontra também de uma subpasta). Construa-o com wingbox build . quando estiver ausente ou desatualizado. O grafo está desatualizado quando um arquivo do projeto foi modificado após o arquivo do grafo; esta verificação encontra um:

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

    Uma reconstrução apenas reanalisa os arquivos cujo conteúdo mudou. Em seguida, leia .wingbox/REPORT.md e dê ao usuário suas "Descobertas principais", os módulos com mais dependências e por onde começar a ler, e diga que o mapa é .wingbox/map.html (wingbox open o mostra em um navegador, offline).

  • /wingbox <arquivo>: execute wingbox impact <arquivo> 2 e resuma o que depende do arquivo e quais arquivos ler primeiro.

  • /wingbox <comando> ...: execute wingbox <comando> ... (por exemplo /wingbox quick "upload de arquivo", /wingbox analyze src/billing/invoice).

Executando os comandos

Quando o comando wingbox estiver instalado (command -v wingbox), execute wingbox <comando> ... para cada consulta abaixo e wingbox build CAMINHO para construir; eles recebem os mesmos argumentos que os scripts. Uma habilidade instalada por wingbox install não tem pasta scripts/ e sempre usa o comando.

ComandoPropósito
`wingbox install [--global--project] [--assistant NOME ...] [--dry-run]`
`wingbox uninstall [--global--project] [--assistant NOME ...]`
wingbox open [CAMINHO]Abre .wingbox/map.html do projeto no navegador (imprime seu caminho quando não há navegador)
wingbox update [--check] [--dry-run]Atualiza com pipx, uv ou pip, então atualiza as habilidades, blocos e hooks instalados; avisa sobre arquivos deixados por uma versão anterior (.code_graph*, wingbox-out/)
wingbox hook pre-searchO hook PreToolUse do Claude Code; lê a entrada do hook no stdin; atualiza o grafo antes de lê-lo
wingbox hook dirtyO hook PostToolUse do Claude Code em Editar e Escrever: marca o arquivo alterado para que o grafo seja atualizado antes de seu próximo uso

Cada um destes imprime fatos como texto; adicione --sexp para expressões-S.

Scripts

Esta habilidade inclui scripts Python. Resolva as raízes da habilidade e do alvo antes de executá-los para que o projeto escaneado seja sempre explícito:

  • scripts/code_graph_search.py -- consulta o grafo de código
  • scripts/build_code_graph.py -- gera o grafo de código a partir do código fonte
  • scripts/build_infra_topology.py -- extrai fatos de topologia de Kustomize, Helm e Terraform
  • scripts/git_descendants.py -- encontra todos os commits descendentes de HEAD (ou de uma referência dada)

Nunca use cópias locais destes scripts no projeto -- elas podem estar desatualizadas e gerar JSON em vez de sexp.

Pré-requisito

Localize o grafo de código. Se ausente, construa-o:

ls .wingbox/index.sexp 2>/dev/null
SKILL_ROOT="$(pwd -P)"
TARGET_ROOT="$(cd /caminho/absoluto/para/o/projeto && 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

A indexação Python não tem dependência de parser externa. Para outras linguagens detectadas, a primeira construção falha antes da publicação quando um parser está ausente ou tem a versão errada e imprime o comando exato por linguagem para executar, 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"

Instale apenas os arquivos de requisitos nomeados pelo construtor e execute-o novamente. requirements.txt é reservado para a dependência de topologia de infraestrutura.

Fluxo de Trabalho Obrigatório: Consulte Antes do Código

Para trabalho de código não trivial, execute uma consulta ao grafo de código antes de rg, find, sed, cat, nl, abrir diretórios ou ler arquivos fonte. A habilidade só ajuda quando usada como primeiro passo de escopo, não como confirmação após o código já ter sido inspecionado.

Primeira passagem rápida quando a tarefa tem uma palavra-chave clara:

python3 scripts/code_graph_search.py quick "palavra-chave"

quick procura pelo primeiro módulo correspondente e imediatamente executa analyze. Use-o para obter arquivos de limite, dependências, dependências reversas, camadas e violações em uma única etapa. Se quick retornar o módulo errado ou nenhum resultado, use o fluxo explícito search -> analyze abaixo.

Passo 1 -- Encontre o ID do módulo:

python3 scripts/code_graph_search.py search "palavra-chave"
python3 scripts/code_graph_search.py entity NomeDaEntidade

Use search ou entity para localizar o ID do módulo. IDs de módulo são caminhos relativos completos como billing-service/src/modules/invoice/invoice.service, não códigos curtos como bs34. O grafo de código pode conter IDs curtos de mapa de caminho internamente, mas eles são resolvidos automaticamente -- sempre passe strings semelhantes a caminhos legíveis por humanos. NÃO adivinhe ou invente IDs de módulo -- sempre confirme com search primeiro.

Passo 2 -- Analise o módulo (faça isso IMEDIATAMENTE, não opcionalmente):

python3 scripts/code_graph_search.py analyze <id-do-modulo>

analyze é o comando PRINCIPAL. Ele retorna o contexto completo: arquivos de limite, dependências, dependências reversas, camada de arquitetura e violações. Sempre execute-o antes de ler qualquer fonte.

Passo 3 -- Leia apenas os arquivos de limite listados na saída do analyze.

Passo 4 -- NÃO leia diretórios inteiros. Se o limite mostrar 2-3 arquivos relevantes, leia apenas esses arquivos. Ignore todo o resto no diretório.

Referência de Comandos

ComandoPropósitoExemplo
search "<padrão>"Pesquisa literal segura ou com .* no grafosearch "operative.*service"
analyze <id> [--all]Análise completa do módulo (comando PRINCIPAL); nomeia no máximo 200 dependentes a menos que --all; termina com o (advice ...) que diz respeito ao móduloanalyze drive/modules/drive/drive_schema
quick <palavra-chave>Pesquisa + analisa a primeira correspondência (atalho)quick operatives
boundary <id>Arquivos a ler para uma alteraçãoboundary operatives.service
boundary <id> --files-onlyApenas caminhos de arquivo (compacto)boundary operatives.service --files-only
entity <Nome> [--positions]Encontra definições + os módulos que as usam; --positions: cada uso com linha e colunaentity DrivePath --positions
usages <símbolo> [--sexp] [--all]Cada uso de um símbolo (Nome, <arquivo>::Nome, <arquivo>::Classe.método) através de reexportações e aliases, por arquivo, linha:col e tipo (import, re-export, call, type, extends, reference; unresolved-call para uma chamada de método cujo tipo do receptor não está à vista); no máximo 200 a menos que --all; um nome definido em vários arquivos lista os candidatosusages src/billing/invoice.ts::Invoice
deps <id> [profundidade]Árvore de dependências de saídadeps operatives.service 3
rdeps <id> [profundidade]Raio de explosão (quem depende disso)rdeps drive_schema 2
`impact <arquivoid> [profundidade] --sexp [--all]`Raio de explosão de um arquivo: dependentes pela profundidade mais curta + arquivos a ler primeiro; lista no máximo 200 a menos que --all, contagens são sempre completas; termina com o conselho que diz respeito ao arquivo
flow <id> <fn>Rastreia fluxo de chamada/dadosflow drive_api fetchFiles
module <id>Módulo único com arestasmodule operatives.controller
wingbox init [CAMINHO] [--force] [--sexp] [--synonyms]Divide o repositório em partes, julga o estilo de arquitetura de cada uma (com pontuação, evidência e fontes) e escreve .wingbox/config.yaml (mantido a menos que --force); --synonyms também mapeia nomes de pastas através dos vetores de palavras embutidos; em uma pasta vazia --language L --style S --yes [--scaffold] inicia um novo projeto (sem eles imprime as opções e sai com código 2)wingbox init --sexp
wingbox advice [--sexp] [--learned] / `wingbox advice acceptreject [--reason TEXTO]`Abre recomendações da última construção (mover, consertar-violação, pasta-faltante) sem as rejeitadas ou ignoradas por muito tempo; registra uma decisão em .wingbox/decisions.sexp
wingbox align [PARTE] [--to ESTILO] [--learn] [--sexp]Lacunas de cada parte contra seu estilo (arquivos colocados, regras seguidas, pastas não colocadas, regras quebradas); --to contra outro estilo; --learn escreve pastas aprendidas e uma linha de base para que apenas novas violações sejam relatadaswingbox align --sexp
wingbox place "<o que>" [--part PARTE] [--sexp]Camada e pasta para novo código pelas regras de colocação do estilo da parte (:new quando a pasta ainda não existe) e o que pode importarwingbox place "repositório para faturas" --sexp
wingbox compare [--sexp]Partes de um monorepo por linguagem: estilo, camadas, diferenças (camadas faltantes, um nome de pasta significando outra camada, um estilo diferente da maioria) e conselho para a parte que se desviawingbox compare --sexp
wingbox learn --agent [PARTE] [--sexp] / wingbox learn --apply [ARQUIVO]/wingbox learn: execute wingbox learn --agent, leia os arquivos que ele nomeia, responda apenas em seu formato ((layer <parte> <pasta> <camada> :because "..."), (unknown ...), no máximo um (style ...)), passe a resposta para wingbox learn --apply, mostre o resultado; em erros, corrija as linhas nomeadas e envie a resposta inteira novamente. Quando o código não decidir uma pasta, pergunte ao usuário no chat e responda com :because "operator: <as palavras deles>"; nunca adivinhe. Para alterar .wingbox/config.yaml, siga as instruções no topo delewingbox learn --agent
`boundaries [idall]`Verifica as regras de limite de cada parte (ou regras que a parte declara); cada linha nomeia :part, :style e :rule; importações apenas de tipo e camadas adivinhadas são relatadas separadamente; então quais arquivos fazem o que sua camada pode não permitir (capability-violation: SQL fora de repositórios, HTTP de saída fora da infraestrutura, o framework no domínio, com :line e :evidence) e as verificações de padrão do estilo (pattern-violation). boundaries-ok apenas quando cada parte foi verificada; uma parte cujas regras declaradas não foram lidas, ou sem um estilo determinado, é boundaries-not-checked com boundaries-partial em vez de ok. Status de saída: 2 não verificado (regras declaradas não lidas), 1 violações, 0 caso contrário - nunca relate aprovação na saída 2
`invariants [idall]`Verifica violações de convenção de nomenclatura
layersMostra todos os módulos por camada, com a parte, estilo e regra que definiram cada camadalayers
find_function <nome>Encontra definições de funções/métodosfind_function createOrder
find_type <nome>Encontra definições de tipos/classes/módulos/interfaces/enumsfind_type DriveDbCommitResponse
find_callchain <src> <tgt> [profundidade]Rastreia caminho de chamada entre funçõesfind_callchain createOrder processPayment
find_callers <fn> [profundidade]Quem chama esta funçãofind_callers handleRequest 3
find_calls <fn> [profundidade]O que esta função chamafind_calls createOrder 2
grep_functions <padrão>Pesquisa corpos de função no código fontegrep_functions "validate.*input"
diff_functions [ref]Funções alteradas no git diffdiff_functions HEAD~3
query '<sexp>'Consulta Scheme combinávelquery '(count (boundary "X"))'
replREPL Scheme interativarepl
wingbox mcp [--root DIR]Executa estes comandos como ferramentas de um servidor MCP no stdio (build, impact, usages, analyze, quick, boundary, deps, ...) para clientes MCPclaude mcp add wingbox -- wingbox mcp

impact aceita um caminho de arquivo comum. Sem --sexp ele imprime texto legível para pessoas; agentes passam --sexp para obter os mesmos fatos na forma compacta de expressão-S, que é o formato que todo outro comando usa.

Referência Rápida: Consultas rg

Quando você precisar de consultas rápidas e direcionadas sem invocar o script Python, consulte o grafo de código diretamente com rg. O construtor escreve o grafo em .wingbox/index.sexp:

# Todos os fatos sobre um módulo
rg 'drive/modules/drive_db/api ' .wingbox/index.sexp

# Quem importa um módulo
rg 'imports .* drive/modules/commons/result' .wingbox/index.sexp

# O que um módulo importa
rg 'imports drive/modules/drive_db/api' .wingbox/index.sexp

# Todas as referências a uma entidade
rg 'DriveDbCommitResponse' .wingbox/index.sexp

# Todas as classes em um repositório
rg '^\(cls drive/' .wingbox/index.sexp

# Arestas de fluxo de dados
rg 'data-flow' .wingbox/index.sexp

# Módulos Python carregados por um nome lido de um arquivo de configuração
rg 'registry-wires' .wingbox/index.sexp

Estes one-liners são úteis para verificações rápidas. Para saída estruturada e análise completa, use os comandos do script Python.

Notação de Saída

Toda saída são fatos em expressão-S, um por linha. Veja references/sexp-notation.md para o formato completo.

Padrões-chave:

(boundary <mod> :lang py :file <caminho> :purpose "<desc>")
(boundary-dep <mod> <dep> :lang ts :file <caminho> :relation imports)
(boundary-rdep <mod> <rdep> :lang tsx :file <caminho> :relation imports)
(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
(entity-def cls <mod> <Nome> <linha> :lang py :file <caminho>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<motivo>")
(result <modulo-ou-caminho>)
(result-count 42)

Valores :lang: py = Python (snake_case), ts = TypeScript (camelCase), tsx = TSX (PascalCase), rs = Rust, cs = C#, java = Java, go = Go, rb = Ruby, php = PHP, dart = Dart. O construtor detecta essas linguagens automaticamente.

Notas Adicionais

  • Cache e Desempenho: O grafo é armazenado em .wingbox/index.sexp. Uma vez construído, consultas são rápidas porque operam sobre o grafo pré-indexado. A reconstrução apenas reanalisa arquivos modificados.
  • Integração com Claude Code: A habilidade adiciona hooks pre-search e post-tool-use que mantêm o grafo atualizado automaticamente durante a sessão.
  • Monorepos: Wingbox trata cada parte de um monorepo separadamente, permitindo análise de dependências entre partes e verificação de regras de arquitetura por parte.
  • Fluxo de Trabalho Típico para Agentes: 1) Execute /wingbox para garantir que o grafo exista e esteja atualizado. 2) Use quick ou search + analyze para obter contexto sobre o módulo relevante. 3) Leia apenas os arquivos listados em boundary. 4) Execute impact antes de fazer alterações para entender o raio de explosão.

Licença

Wingbox é distribuído sob a licença MIT. Veja o arquivo LICENSE para detalhes.

Habilidades Relacionadas