Unship

Visão Geral

Unship é um fluxo de trabalho local para comparar alternativas de UI geradas por IA na aplicação real, em vez de aceitar uma versão gerada por vez. Ele adiciona variantes temporárias no nível do código-fonte, exibe um seletor de navegador local e, em seguida, remove as opções não utilizadas após a escolha do usuário.

Esta habilidade é para iteração de frontend com agentes de codificação. Não se trata de testes A/B em produção, análise, sinalização de recursos ou um serviço de experimentação hospedado.

Quando Usar Esta Habilidade

• Use quando o usuário quiser comparar múltiplas alternativas de UI, layout, texto, estado, fluxo ou sistema de design.
• Use quando um agente de codificação deve criar várias opções temporárias no código-fonte real e deixar o usuário julgá-las no aplicativo local em execução.
• Use quando o usuário escolher uma opção visível e quiser que o código temporário perdedor seja removido antes do envio.

Não Use Esta Habilidade Quando

• O usuário precisa de experimentos em produção, divisão de tráfego, análise ou sinalização de recursos.
• O aplicativo não pode renderizar com segurança variantes ocultas inativas devido a IDs ativos duplicados, scripts globais, gatilhos de análise, armadilhas de foco, ações destrutivas ou efeitos colaterais de reprodução automática.
• O usuário não autorizou edições de código-fonte local.

Como Funciona

1. Instalar ou Reutilizar Unship

Prefira o binário local do projeto quando ele existir:

./node_modules/.bin/unship doctor --json --no-update-check

Caso contrário, instale uma versão CLI revisada e exata no projeto e, em seguida, execute o binário local:

npm install --save-dev @unship/cli@<reviewed-version>
./node_modules/.bin/unship doctor --json --no-update-check

Se a configuração for necessária para o seletor local, execute:

./node_modules/.bin/unship setup --json

Aplique patch apenas no menor ponto de montagem de desenvolvimento necessário para carregar o seletor na visualização local.

2. Criar Variantes Temporárias

Inspecione a página, componente, rota ou artefato renderizado relevante. Adicione a menor comparação no nível do código-fonte que permita ao usuário julgar opções reais em contexto.

Use a marcação Unship:

<section data-unship-pick="Hero">
  <div data-unship-option="Current">...</div>
  <div data-unship-option="Proof-led" hidden>...</div>
  <div data-unship-option="Visual" hidden>...</div>
</section>

Mantenha os rótulos das opções curtos e visíveis. Prefira 2-4 alternativas significativas, a menos que o usuário tenha solicitado uma contagem específica.

3. Verificar Prontidão da Comparação

Antes de entregar ao usuário, verifique se:

• o grupo data-unship-pick esperado existe;
• os rótulos de opção esperados existem;
• as opções são filhas diretas do grupo;
• exatamente uma opção está visível inicialmente;
• opções inativas ocultas permanecem ocultas.

4. Deixe o Usuário Escolher

Informe ao usuário o rótulo do grupo, os rótulos das opções, o status da configuração e quaisquer dicas detectadas do servidor de visualização local. O usuário escolhe nomeando um rótulo de opção visível no chat.

5. Limpar Após a Seleção

Quando o usuário escolher um vencedor, mantenha o código-fonte real dessa opção e remova as opções perdedoras para esse grupo. Remova os atributos temporários data-unship-* do código-fonte resolvido.

Para limpeza final antes do envio, remova todos os artefatos Unship e execute:

./node_modules/.bin/unship check --json

Não declare a limpeza como completa até que a verificação relate que está limpo.

Melhores Práticas

• Mantenha o trabalho do Unship local e temporário.
• Preserve a linguagem de design existente do aplicativo, a menos que o usuário solicite explicitamente uma direção diferente.
• Evite refatorações não relacionadas enquanto as variantes forem temporárias.
• Não coloque abas personalizadas, preferências de aplicativo ou alternadores permanentes na UI do produto para comparações do Unship.
• Mantenha as opções inativas seguras: evite IDs ativos duplicados, envie controles, scripts globais, gatilhos de análise, armadilhas de foco, efeitos colaterais destrutivos e provedores com estado.

Limitações

• O Unship não decide qual variante vence; o humano escolhe.
• O Unship não substitui a revisão de design, QA de navegador, verificações de acessibilidade ou validação de lançamento de produção.
• O Unship não se destina a tráfego de produção, análise remota ou experimentos de produto persistentes.

Notas de Segurança e Proteção

• Execute comandos apenas em um projeto local que o usuário autorizou você a modificar.
• Não execute npx @unship/cli@latest ou qualquer CLI remota não fixada em fluxos de trabalho de agente automatizados. Fixe e revise a versão do pacote primeiro, depois execute o binário local do projeto.
• Trate as variantes geradas como código temporário que deve ser limpo antes do lançamento.
• Antes da limpeza destrutiva, confirme o rótulo da opção selecionada quando a escolha do usuário for ambígua.

…