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
- Lado a lado. AS-IS à esquerda, TO-BE à direita. Nunca empilhado verticalmente.
- 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)").
- Desenhe apenas camadas alteradas. Uma camada inalterada recebe 「변경 없음» ("nenhuma alteração") mais uma linha de evidência. Sem tabelas vazias.
- Cada seta tem evidência. Um
arquivo:linhaou um commit por elo do caminho de impacto. Sem evidência, marque como 「추정:» ("estimativa:"). - 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.
- 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. - 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.
codedentro 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-marke--b-markclaros, não as cores escuras de chip. Renderize uma vez em cada esquema e uma vez em 420px. - 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
| Camada | O que comparar | De 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 modelo | Migraçõ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 campo | Diff OpenAPI, DTOs de resposta, fixtures de teste |
| Comportamento (동작) | O resultado que o servidor e o cliente produzem para a mesma entrada | Diff de asserções de teste, código de transição de estado |
| Tela (화면) | Duas capturas da tela no mesmo estado | Ferramenta 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ção | Crité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>...HEADna á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):
Se o diff incluir arquivos não relacionados à issue, a base está errada. Recalcule antes de dividir em camadas.git fetch origin main git merge-base origin/main HEAD - 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, ouHEADpara trabalho não commitado). - Árvore de trabalho não commitada: AS-IS é
HEAD, TO-BE é a árvore de trabalho.git diff HEADperde novos arquivos, então também leiagit 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.
- 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. - 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 depython3 -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/nullpara 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. - 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
tobeao script comasis_notedizendo 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.
- 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:
- 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 3para longos,--mask id,timepara 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 grepo 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.
| Esqueleto | Web/aplicativo | Modelo de dados | Servidor (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-changeounon-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
- references/document.md: Regras de layout do documento, incluindo cartões de pergunta.
- references/adapters.md: Adaptadores de projeto para captura de tela e localização de versão lançada.
- references/layers.md: Listas de verificação por camada e armadilhas comuns.
- references/terms.md: Glossário de termos.
- references/screens.md: Instruções de captura de tela.
- references/scenario-rail.md: Instruções para preencher o trilho de cenário.
- references/domains.md: Nomes de células para outros domínios.