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:
-
/wingboxsem argumento: encontre o grafo (.wingbox/index.sexpna raiz do projeto; todo comandowingboxo encontra também de uma subpasta). Construa-o comwingbox 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 -quitUma reconstrução apenas reanalisa os arquivos cujo conteúdo mudou. Em seguida, leia
.wingbox/REPORT.mde 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 openo mostra em um navegador, offline). -
/wingbox <arquivo>: executewingbox impact <arquivo> 2e resuma o que depende do arquivo e quais arquivos ler primeiro. -
/wingbox <comando> ...: executewingbox <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.
| Comando | Propó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-search | O hook PreToolUse do Claude Code; lê a entrada do hook no stdin; atualiza o grafo antes de lê-lo |
wingbox hook dirty | O 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ódigoscripts/build_code_graph.py-- gera o grafo de código a partir do código fontescripts/build_infra_topology.py-- extrai fatos de topologia de Kustomize, Helm e Terraformscripts/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
| Comando | Propósito | Exemplo |
|---|---|---|
search "<padrão>" | Pesquisa literal segura ou com .* no grafo | search "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ódulo | analyze 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ção | boundary operatives.service |
boundary <id> --files-only | Apenas 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 coluna | entity 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 candidatos | usages src/billing/invoice.ts::Invoice |
deps <id> [profundidade] | Árvore de dependências de saída | deps operatives.service 3 |
rdeps <id> [profundidade] | Raio de explosão (quem depende disso) | rdeps drive_schema 2 |
| `impact <arquivo | id> [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/dados | flow drive_api fetchFiles |
module <id> | Módulo único com arestas | module 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 accept | reject [--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 relatadas | wingbox 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 importar | wingbox 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 desvia | wingbox 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 dele | wingbox learn --agent |
| `boundaries [id | all]` | 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 [id | all]` | Verifica violações de convenção de nomenclatura |
layers | Mostra todos os módulos por camada, com a parte, estilo e regra que definiram cada camada | layers |
find_function <nome> | Encontra definições de funções/métodos | find_function createOrder |
find_type <nome> | Encontra definições de tipos/classes/módulos/interfaces/enums | find_type DriveDbCommitResponse |
find_callchain <src> <tgt> [profundidade] | Rastreia caminho de chamada entre funções | find_callchain createOrder processPayment |
find_callers <fn> [profundidade] | Quem chama esta função | find_callers handleRequest 3 |
find_calls <fn> [profundidade] | O que esta função chama | find_calls createOrder 2 |
grep_functions <padrão> | Pesquisa corpos de função no código fonte | grep_functions "validate.*input" |
diff_functions [ref] | Funções alteradas no git diff | diff_functions HEAD~3 |
query '<sexp>' | Consulta Scheme combinável | query '(count (boundary "X"))' |
repl | REPL Scheme interativa | repl |
wingbox mcp [--root DIR] | Executa estes comandos como ferramentas de um servidor MCP no stdio (build, impact, usages, analyze, quick, boundary, deps, ...) para clientes MCP | claude 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-searchepost-tool-useque 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
/wingboxpara garantir que o grafo exista e esteja atualizado. 2) Usequickousearch+analyzepara obter contexto sobre o módulo relevante. 3) Leia apenas os arquivos listados emboundary. 4) Executeimpactantes 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.