CommunityImagemgithub.com

asis-tobe

Explica, em uma única página HTML, como uma alteração (um PR, um branch, uma árvore de trabalho não commitada, um conjunto de PRs em vários repositórios ou uma issue) muda cada camada — dados, payload da API, comportamento do servidor, tela, resultado para o usuário — colocando AS-IS e TO-BE lado a lado e ligando as camadas com uma cadeia causal.

O que é asis-tobe?

Esta skill cria um documento comparativo AS-IS / TO-BE para mudanças em sistemas de software, ajudando revisores e planejadores a entender o impacto completo de uma alteração antes da implantação. Ela organiza a análise em camadas: Dados, Especificação da API, Comportamento, Tela e Impacto no Usuário, comparando cada uma lado a lado e conectando-as com evidências (arquivo:linha ou commit). A skill suporta entradas como PRs, branches, árvores de trabalho não commitadas, bundles de PRs e issues, e funciona com GitHub CLI para obter diffs reais e capturas de tela. O resultado é uma página HTML autossuficiente, sem dependências externas, com um resumo executivo no topo e evidências detalhadas abaixo, seguindo princípios rigorosos de layout e acessibilidade. É particularmente útil para mudanças que afetam múltiplas camadas (servidor, API, app) e para requests em coreano como 'AS-IS TO-BE 정리해줘' ou 'PR 본문에 전후 비교 넣어줘'.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/chordpli/asis-tobe/tree/main

Installed? Explore more Imagem skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Perguntar na sua IA favorita

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

Documentação

AS-IS / TO-BE

Encontre as camadas que uma alteração toca, coloque AS-IS e TO-BE lado a lado para cada uma e ligue as camadas com setas baseadas em evidências: "este campo foi removido, então esta resposta muda, então isto desaparece (ou aparece) nesta tela." Se o código muda mas o que o usuário vê permanece igual, afirmar isso é a conclusão. Não invente mudanças.

<skill> nos comandos abaixo é o diretório base desta skill: a pasta que contém este SKILL.md (~/.claude/skills/asis-tobe para instalação de nível de usuário, <projeto>/.claude/skills/asis-tobe para instalação de nível de projeto). Substitua pelo caminho real antes de executar um comando.

Princípios

  1. Lado a lado. AS-IS à esquerda, TO-BE à direita. Nunca empilhado verticalmente.
  2. Compare artefatos reais. Payloads conforme 「실물 고르는 순서」 abaixo, telas a partir de capturas de tela reais, esquemas a partir de diffs de migração e modelo reais. Sem o artefato real: 「실물 없음: » ("nenhum artefato real: "). Exemplos feitos à mão: 「예시(손으로 만듦)» ("exemplo (feito à mão)").
  3. Desenhe apenas camadas alteradas. Uma camada inalterada recebe 「변경 없음» ("nenhuma alteração") mais uma linha de evidência. Sem tabelas vazias.
  4. Cada seta tem evidência. Um arquivo:linha ou um commit por elo do caminho de impacto. Sem evidência, marque como 「추정:» ("estimativa:").
  5. Diga quem ainda usa a especificação antiga. O que continuar executando código antigo após esta implantação: builds de aplicativos já na loja, abas do navegador ainda abertas na página antiga, outros serviços, outros locais de chamada como uma ferramenta de administração ou um bot. Isso decide a ordem de merge e implantação.
  6. Resumo primeiro. A caixa de resumo no topo sozinha deve apoiar a decisão: uma conclusão de uma frase nas palavras do usuário (sem nomes de campos ou códigos de status), o que muda para o usuário, como é implantado, se pode ser revertido; 3 itens ou menos por grupo. Logo abaixo, três cartões respondem ao que qualquer leitor pergunta em seguida, nomeados pela pergunta e não por um papel: 「정해야 할 것» (o que a mudança decidiu em nome de alguém), 「먼저 볼 곳» (tamanho, os arquivos para abrir primeiro, premissas que o código afirma), 「직접 확인하는 법» (itens de verificação, depois como executar) — regras em references/document.md ("Cartões de Pergunta"). As duas coisas em que uma decisão se baseia, o selo e a reversão, são as coisas mais visíveis na primeira tela. Diga cada fato uma vez: uma frase já na conclusão ou no aviso não é repetida no resumo, nos cartões de pergunta ou em um cenário. Tudo abaixo é evidência. Recolha payloads longos e tabelas exaustivas em <details>; não os delete. Sem introdução, narrativa de progresso ou observações finais.
  7. Layout é conteúdo. Na largura de 420px a página não deve rolar horizontalmente (apenas tabelas podem). Largura do corpo limitada a 880px; apenas tabelas e comparações lado a lado usam largura total. code dentro de tabelas apenas para identificadores; apenas caminhos de arquivos e identificadores são monoespaçados, descrições em coreano nunca. Frases com cerca de 70 caracteres, modificadores cortados. Dois esquemas de cores alternados por um botão acima do título: Padrão Dusk, bege (AS-IS) e azul-ardósia (TO-BE); Bloom, rosa (AS-IS) e menta (TO-BE). Não siga a configuração de modo escuro do sistema. Linhas tracejadas e sólidas sempre acompanham a cor. Destaques de código inline usam --a-mark e --b-mark claros, não as cores escuras de chip. Renderize uma vez em cada esquema e uma vez em 420px.
  8. Termos da indústria, explicados uma vez. Use palavras que desenvolvedores, QA e planejadores entendam imediatamente. No documento em coreano use 레이어, 필드, API 스펙, 호출처, deprecated, breaking change, mock 응답, com uma explicação simples entre parênteses apenas no primeiro uso (ex.: codegen(서버 스펙으로 자동 생성한 타입 파일) — "arquivos de tipo gerados automaticamente a partir da especificação do servidor"). Para jargões internos (「AC」, apelidos de tela inventados), declare o que é no primeiro uso. Glossário: references/terms.md. Se um termo te bloquear, leia lá; não pule a etapa.

Camadas

CamadaO que compararDe onde vem o artefato real
Dados (데이터)Tabelas, campos, tipos, enums, constraints, índices. Um diagrama de entidades apenas das entidades alteradas, e o código do modeloMigrações, esquema ORM (prisma etc.), diff DDL
Especificação da API (API 스펙)Payloads de requisição e resposta, eventos, tipos codegen. Adições, remoções, alterações de tipo, alterações semânticas por campoDiff OpenAPI, DTOs de resposta, fixtures de teste
Comportamento (동작)O resultado que o servidor e o cliente produzem para a mesma entradaDiff de asserções de teste, código de transição de estado
Tela (화면)Duas capturas da tela no mesmo estadoFerramenta de captura de tela do projeto (references/adapters.md, 「프로젝트 어댑터」)
Impacto no usuário (사용자 영향)O que os usuários podem agora fazer ou não fazer mais, números que mudam. Inclui estados intermediários causados pela ordem de implantaçãoCritérios de aceitação da Issue, a soma das camadas acima, tabela de compatibilidade

Listas de verificação por camada e armadilhas comuns: references/layers.md.

Escolhendo o artefato real (실물 고르는 순서, API spec)

Fixture de teste do servidor > Exemplo OpenAPI > Chamada real registrada > Resposta mock do cliente. Pegue o primeiro que existir completo. Se uma fonte superior for apenas parcial (uma fixture construída a partir de variáveis, ou testes que constroem a requisição inline e verificam campo por campo) e você registrou uma chamada real, mostre a fonte superior no painel e a chamada registrada como texto completo, cada uma rotulada com sua fonte. Uma chamada registrada carrega valores que diferem em cada execução (ids, timestamps); compare tais payloads com code_diff.py --mask id,time e diga isso na linha da fonte, para que um novo id não seja contado como campo alterado. Um mock do cliente (ex.: uma resposta falsa para capturas de tela) não é o artefato real do servidor. Escreva o caminho da fonte escolhida sob o payload. Se a fixture for construída a partir de variáveis sem um JSON completo, transcreva-a a partir dos valores esperados do teste, rotule-a como 「예시(테스트 기대값에서 옮김)» ("exemplo (transcrito das expectativas do teste)"), e use … onde for encurtado. Não preencha campos ausentes dos valores esperados; deixe-os como …. Se você pegou emprestado um valor de outro lugar (uma resposta mock, etc.), anote a fonte ao lado desse campo.

Procedimento

1. Defina o escopo

  • Entrada via PR: obtenha o diff pelo número do PR (gh pr diff <n> -R <repo>). Um caminho ou branch sozinho dá um PR empilhado com main como base e mistura mudanças de outras pessoas.
  • Entrada via Issue: encontre os PRs em cada repo (gh pr list -R <repo> --search <chave> --state all). Dois ou mais repositórios vão em um documento.
  • Sem PR: git diff <base>...HEAD na árvore de trabalho, com <base> o ponto de bifurcação, calculado a partir da raiz do repositório (main local está desatualizado e mistura centenas de arquivos):
    git fetch origin main
    git merge-base origin/main HEAD
    
    Se o diff incluir arquivos não relacionados à issue, a base está errada. Recalcule antes de dividir em camadas.
  • Sem remoto: pule o fetch e use a base que o usuário nomear, senão o commit a partir do qual o trabalho começou (git merge-base main HEAD, ou HEAD para trabalho não commitado).
  • Árvore de trabalho não commitada: AS-IS é HEAD, TO-BE é a árvore de trabalho. git diff HEAD perde novos arquivos, então também leia git ls-files --others --exclude-standard. Onde um sha de HEAD for solicitado, escreva 「커밋 전» ("não commitado"). Não faça commit, stash ou checkout para fazer a comparação.
  • Sem PR ou issue: o alvo é nomeado pelo que é (「 작업 트리 변경」, 「 브랜치」). A tabela de implantação recebe uma linha por unidade que é implantada (um branch, 「작업 트리 커밋」) com a célula do PR nomeando-o; a chave da issue é descartada, não inventada.
  • Por repositório, escreva uma linha <repositorio> <sha base curto> → <sha branch curto>. Use-o literalmente no relatório. No documento, PRs e shas vão uma vez no cartão de resumo na tabela de ordem de implantação e na tabela base (references/document.md), não no cabeçalho.

2. Atribua arquivos alterados às camadas

Cada arquivo vai para uma ou mais camadas; se não estiver claro, abra-o. Arquivos de teste não são atribuídos; eles são evidência para a camada de Comportamento (동작). Esta tabela decide quais seções de camada o documento recebe; é material de trabalho e não é impressa no documento.

3. Primeiro decida se a tela realmente muda

Mesmo que o código da tela tenha mudado, pergunte antes de capturar: o branch alterado é alcançável com os dados atuais? Escolha um valor do qual o branch depende e descubra se o servidor realmente o produz.

# Exemplo: removeu o branch onde o app mostrava um selo 「품절» (“sold out”) quando stockState === 'SOLD_OUT'
git -C <repositorio servidor> grep -n "SOLD_OUT" -- <arquivos fonte>      # o servidor coloca este valor em uma resposta em algum lugar?
git -C <repositorio app> grep -n "stockState" -- <tipos gerados>          # valores que o tipo gerado permite

Nenhum código do servidor definindo o valor (apenas definições de tipo ou enum) significa inalcançável, mesmo que o tipo gerado o permita. Registre o arquivo:linha como a evidência para 「변경 없음」.

Se apenas o lugar que calcula um valor se move (ex.: o ERROR do servidor agora é calculado pelo app como lastError), coloque ambas as fórmulas lado a lado com seus arquivo:linha. Mesmo valor para a mesma entrada: mesma tela. Diferente: encontre uma entrada que produza um valor diferente e capture esse estado.

  • Alcançável: capture na etapa 4.
  • Inalcançável: a camada de Tela recebe 「현재 데이터로는 변경 없음: <motivo e evidência>» ("nenhuma alteração com os dados atuais: <motivo e evidência>"). Registre o estado desaparecido sob 「실물 없음」 e mostre sua aparência antiga através das strings de teste cujas asserções verificavam aquele estado. Se confirmação for necessária, capture um cenário representativo e mostre igualdade com md5.
  • Incerto: capture.

4. Colete artefatos reais por camada

  • Dados: três partes, nesta ordem.
    1. Diagrama de entidades, aberto. Apenas as entidades alteradas e as diretamente ligadas, 6 ou menos por lado. Escreva-as como JSON e deixe o script desenhar ambos os lados como SVG inline: python3 -I <skill>/scripts/erd.py <spec.json> (o formato da especificação está no cabeçalho do script). Nunca desenhe o SVG manualmente e nunca carregue uma biblioteca de diagramas; a página é autossuficiente. O script marca campos e entidades adicionados, removidos e alterados comparando os dois lados, então escreva cada lado como realmente é naquele commit.
    2. Código do modelo, recolhido (<details>): o modelo como o código o mantém (struct, classe, esquema ORM) na base e agora. Diff de uma linha por modelo de python3 -I <skill>/scripts/code_diff.py <ASIS.txt> <TOBE.txt> --label "<nome (caminho)>" --start-a <linha> --start-b <linha>; um modelo novo ou removido usa /dev/null para o lado faltante. O script calcula as linhas alteradas e exibe ambas as visualizações (나란히 lado a lado, 합쳐서 unificado) para o leitor alternar; nunca marque linhas manualmente.
    3. Tabela de campos, recolhida: o que o diagrama deixa de fora (valores padrão, constraints, índices, tratamento de linhas existentes). Um único campo alterado sem relação envolvida não precisa de diagrama: uma linha na tabela de campos, mostrada aberta. Se AS-IS não tinha esquema armazenado (em memória, um arquivo), forneça apenas tobe ao script com asis_note dizendo onde os dados viviam (arquivo:linha); o código do modelo é então a evidência AS-IS, então deixe esse <details> aberto. A migração que cria as primeiras tabelas é TO-BE. Se isso limpa após uma migração já implantada, 「이미 반영()» ("já aplicado ()") é o primeiro elo do caminho de impacto.
  • Especificação da API: o payload antes e depois como um diff de linha de scripts/code_diff.py (mesmo script que o código do modelo; uma chamada por payload, --context 3 para longos, --mask id,time para chamadas registradas). Abaixo, 필드 | AS-IS | TO-BE | 시맨틱 변경 (campo | AS-IS | TO-BE | alteração semântica). Uma alteração apenas de nome ou tipo funde ambas as células em uma linha: <code class="old">start_time</code> → <code class="new">starts_at</code>. Locais de chamada:
    • git grep <campo> em cada repositório, a partir da raiz do repositório (um subdiretório torna os caminhos relativos e retorna 0 resultados).
    • Também na versão lançada: git grep -n <campo> <sha>. Seu resultado decide a ordem de merge e implantação e o selo. Leia references/adapters.md ("Encontrando a versão lançada") antes de fazer isso. Obrigações: apenas um sha da lista de builds é confirmado, outros são 「추정:»; se as fontes discordarem, grep em cada sha e conte qualquer resultado como 「배포된 앱이 읽는다» ("o app lançado lê"); nunca escolha apenas pelo nome da tag (tags podem pertencer a outro implantável no mesmo repo). Fallback leve quando a lista de builds falha (ex.: sem login no serviço de build): shas da issue ou notas de versão, senão um limite inferior 「추정:».
    • Saída do codegen não é um local de chamada; ela é regenerada a partir da especificação do servidor. Anote separadamente 「다시 뽑으면 무엇이 바뀌나» ("o que muda se regenerado").
    • Também git grep o campo removido nas respostas mock do cliente e fixtures de teste. Se permanecer, a verificação de tipo pode quebrar uma vez que o codegen seja regenerado após o servidor ser implantado. Liste esses arquivos como o último passo de implantação (「codegen 재생성과 fixture 정리」, "regenerar codegen e limpar fixtures").
  • Comportamento: 입력·상태 | AS-IS | TO-BE | 근거(테스트 이름) (entrada/estado | AS-IS | TO-BE | evidência (nome do teste)).
  • Tela: leia references/screens.md ("Capturar") antes de capturar. Mesmo cenário, dados, um idioma e tamanho em ambos os lados, em uma árvore de trabalho temporária (base para AS-IS, branch para TO-BE) ou, para trabalho não commitado ou um repositório que você não pode tocar, em duas cópias fora do repositório; instala e captura em segundo plano, md5 comparado, então, uma vez que a etapa 10 tenha remensurado o que precisa, pare os servidores e remova a árvore de trabalho temporária ou cópias (mantenha-as se o usuário quiser a execução reproduzível); nunca as comite. Sem ferramenta de captura mock, execute o servidor real de cada versão em sua própria porta e capture isso. Comandos de captura por projeto: references/adapters.md. Pule a captura apenas quando a plataforma não puder ser capturada (ex.: nativa) ou a etapa 3 descobriu que o branch é inalcançável; então 「실물 없음: » mais strings de asserção de teste. Se incerto, capture.

4b. Preencha o trilho de cenário

Leia references/scenario-rail.md antes de preencher 「시나리오별 전후」. Nomes de células para outros domínios: references/domains.md.

EsqueletoWeb/aplicativoModelo de dadosServidor (comportamento)
Linha 1 …………
Linha 2 …………

5. Construa o caminho de impacto (evidência em setas)

O caminho de impacto é uma sequência de setas onde cada seta mostra como uma mudança em uma camada causa uma mudança na próxima. Cada seta tem evidência (arquivo:linha ou commit). Não invista tempo em uma visualização elaborada: uma lista simples com marcadores é suficiente. Se uma camada não mudar, a seta para a próxima camada diz "nenhuma mudança" com evidência. Se a mudança em uma camada é causada por uma mudança em outra, a seta é bidirecional.

6. Determine a ordem de implantação

Tabela de implantação: Passo | O que implantar | Pré-requisitos | Risco de reversão | Impacto se falhar | Responsável (passo, o que implantar, pré-requisitos, risco de reversão, impacto se falhar, responsável). A ordem de implantação decide o que vai primeiro e o que vai depois. Se a mudança pode ser revertida, marque como "reversível" - "sim". Se não, "não".

7. Escreva o resumo

O resumo é uma caixa no topo do documento. Contém:

  • Conclusão: uma frase no idioma do usuário (sem nomes de campos ou códigos de status).
  • O que muda para o usuário: no máximo 3 itens.
  • Como é implantado: no máximo 3 itens.
  • Pode ser revertido: sim/não.
  • Selo: breaking-change ou non-breaking, com evidência.

8. Crie o documento

O documento é uma única página HTML que contém tudo: o resumo, as camadas com comparações lado a lado, o caminho de impacto, a ordem de implantação e as evidências. A página deve ser autossuficiente (sem dependências externas). Deve ser legível em 420px de largura e não deve ter barras de rolagem horizontais. Use o layout e cores especificados nos princípios.

9. Revise

Verifique:

  • Cada camada tem evidência real? Se não, marcada como 「추정:»?
  • O resumo está em linguagem de usuário?
  • O layout funciona em 420px?
  • As cores estão corretas?
  • Não há informações duplicadas?
  • O caminho de impacto tem evidência para cada seta?

10. Entregue

  • Salve a página HTML no diretório de saída.
  • Informe o usuário onde o arquivo foi salvo.
  • Se o usuário pediu uma comparação em particular, explique como interpretá-la.

Scripts

scripts/erd.py

Gera um diagrama de entidades como SVG inline a partir de um arquivo JSON de especificação. Consulte o cabeçalho do script para o formato da especificação.

scripts/code_diff.py

Gera um diff lado a lado e unificado para duas versões de um arquivo de código. Use --label para nomear o diff, --start-a e --start-b para números de linha iniciais, --context para linhas de contexto, --mask para mascarar campos (ex.: id,time) durante a comparação.

Referências

Habilidades Relacionadas