CovD831/fluxo-de-trabalho-para-rearquitetura

Fluxo de Trabalho para Rearquitetura

Use esta skill para transformar um redesign de arquitetura em um pacote de desenvolvimento pronto para entrega. O resultado não é meramente um diagrama: é um contrato delimitado para o que será construído, como migrará, como será testado e o que permanece sem suporte. Trate a rearquitetura como um programa de migração contínua. Cada pacote é um incremento de entrega revisável, não uma promessa de especificar ou implementar todo o sistema futuro.

Princípios operacionais

1. Separe autoridade de intenção. Leia o código atual, testes, autoridade de arquitetura e instruções do repositório primeiro. Marque documentos de redesign como alvo, plano ou evidência; nunca os apresente como comportamento atual.
2. Nomeie coisas existentes. Mapeie cada módulo proposto para classes, contratos, registros, armazenamentos ou pontos de entrada atuais. Não oculte conteúdo existente atrás de substantivos inventados.
3. Torne a propriedade explícita. Declare o que cada fronteira possui e não deve possuir, quem escreve fatos duráveis, quem autoriza mutações e quem é dono da recuperação.
4. Mereça abstrações a partir de consumidores reais. Admita uma nova abstração apenas quando um consumidor real remove uma dependência nomeada, unifica um registro real ou torna um invariante aplicável. Uma abstração genérica normalmente precisa de dois consumidores; uma fronteira de segurança estreita pode ser admitida para um.
5. Comece com uma fatia vertical real. Preserve um fixture legado e adicione um fixture de fronteira-alvo para o mesmo cenário. Um gráfico sintético pode testar mecânicas, mas não pode provar a arquitetura.
6. Congele contratos antes da substituição. Defina entradas, saídas, autorização, identidade, idempotência, falha, persistência, recuperação e compatibilidade antes de remover uma dependência concreta.
7. Trate desempenho como evidência, não justificativa. Preserve autoridade, compatibilidade durável e recuperação primeiro; depois meça cargas de trabalho equivalentes em relação ao caminho atual.
8. Mantenha documentos sustentáveis. Dê a cada afirmação um proprietário canônico, mantenha o status atual/alvo/histórico visível e vincule à política em vez de copiá-la entre documentos.
9. Planeje para entrega sucessiva. Cada incremento declara entregáveis, adiamentos, seu próximo gatilho de avanço e evidência de promoção necessária.

Fluxo de trabalho e carregamento de módulos

Nível 1 (L1) significa fronteiras do sistema, Nível 2 (L2) significa contratos estáveis de módulo/fronteira e Nível 3 (L3) significa detalhes de implementação específicos da tarefa. Mapeie os rótulos existentes de um projeto para esses significados, em vez de introduzir uma segunda taxonomia.

Dimensionamento correto primeiro. Leia references/deliverable-matrix.md e selecione o menor pacote que torna a próxima decisão revisável. As fases abaixo são o caminho completo, não uma lista de verificação obrigatória para cada solicitação. Carregue as outras referências apenas quando sua fase ou preocupação correspondente estiver ativa.

Cada pacote ou incremento de migração deve declarar um horizonte de entrega. A matriz de entregáveis possui o esquema, redução de design, adiamentos e condições de avanço.

Fase 0 — Resolver autoridade e linha de base

• Leia instruções do repositório, README, orientação de desenvolvimento e autoridade de arquitetura se existirem.
• Pesquise registros de orientação, documentação, lançamento, migração, tarefa e handoff antes de concluir que nenhum programa de rearquitetura anterior existe.
• Para cada programa ativo relevante para a solicitação, leia seu registro de incremento mais recente, decisões de revisão, adiamentos não resolvidos, afirmações L1/L2 abertas, ADRs e próxima tarefa registrada antes de definir novo escopo.
• Verifique o gatilho de avanço anterior e a evidência de promoção. Se algum não for atendido, ou uma descoberta bloqueadora permanecer em aberto, apresente o estado e as opções ao usuário antes de continuar. Se o usuário autorizar uma exceção, registre o motivo, aprovador e escopo afetado no registro do incremento atual.
• Identifique a hierarquia de origem e a revisão de linha de base exata. Inspecione pontos de entrada atuais, proprietários de estado/dados, persistência, testes, exemplos e registros de extensão quando presentes.
• Registre o que está implementado, o que é intenção alvo e o que é desconhecido.
• Antes de reivindicar acoplamento reduzido, crie um inventário reproduzível de dependências ou registros: um comando/script executável novamente, saída ou relatório verificado, e o mesmo método reutilizado para comparação antes/depois.

Siga o livro de tarefas, sistema de issues e formato de handoff existentes do repositório. Não exija uma ferramenta de colaboração específica, e não use o histórico da conversa como autoridade de arquitetura.

Fase 1 — Posicionamento e escopo

Registre:

• o que o sistema é e quem constrói sobre ele;
• o problema causado pelo acoplamento ou crescimento atuais;
• a fronteira de implantação do primeiro estágio;
• não-objetivos e capacidades adiadas;
• vantagens delimitadas e a linha de base de comparação para cada afirmação.

Ao mesmo tempo, estabeleça um orçamento de complexidade. Carregue references/document-and-complexity-gates.md para o orçamento, regras de propriedade de documento e condições de parada. Prefira reivindicações delimitadas em vez de palavras como "mais modular" ou "mais escalável."

Portões de decisão do usuário

Não infira intenção de produto a partir de código ou diagramas. Quando a evidência do repositório não puder responder a uma questão material sobre escopo, propriedade, implantação, compatibilidade, segurança, critérios de sucesso ou ordem de migração, pause e pergunte ao usuário. Agrupe escolhas relacionadas, mostre fatos observados e trade-offs, e recomende um padrão conservador quando justificado.

Use references/user-decision-gates.md para as perguntas específicas do estágio e locais de registro duráveis. Se o usuário delegar explicitamente uma escolha material, selecione a opção recomendada ou mais bem suportada reversível, registre a delegação e suposições, e continue. Torne suposições reversíveis não materiais explícitas em vez de bloquear o progresso.

Fase 2 — Arquitetura alvo de Nível 1

Defina subsistemas principais ou planos de coordenação, autoridades de estado/dados e escritores únicos, propriedade de identidade, direção de dependência, ponto de entrada da aplicação, fronteira de processo/implantação e formas de comunicação controladas.

L1 é necessário e explícito para o alvo no escopo antes da direção de implementação. Não precisa descrever todo módulo futuro, mas não pode deixar ambiguidade sobre propriedade, direção de dependência ou escopo de implantação. Nomeie questões L1 não resolvidas com um proprietário e portão de decisão.

Carregue references/architecture-contracts.md para regras de diagrama L1 e os esquemas L2/L3/interface usados em fases posteriores.

Fase 3 — Mapeamento atual-para-alvo

Para cada ponto quente atual, classifique a primeira ação como reter, expor, adaptar, dividir, consolidar, depreciar ou remover. Registre proprietário atual, proprietário alvo, caminho de comunicação/persistência preservado e portão de remoção. Mantenha o horizonte de entrega como o proprietário canônico de adiamentos detalhados.

Não crie um documento apenas porque um tópico é interessante. Encontre o proprietário canônico primeiro; crie um novo documento apenas quando propriedade, status, público-alvo ou ciclo de vida for materialmente diferente.

Fase 4 — Contratos de módulo de Nível 2

Crie um contrato L2 por módulo estável ou fronteira entre módulos. Cubra responsabilidade e não responsabilidade, componentes atuais, serviços fornecidos/necessários, autoridade gravável, chamadas/visibilidade de dados permitidas, ciclo de vida/falha, compatibilidade e decisões adiadas para implementação.

L2 pode permanecer incompleto no primeiro pacote. Marque afirmações significativas como estabelecidas, condicionais ou abertas. Cada escolha aberta precisa de um experimento delimitado, limiar de evidência ou portão de implementação que possa resolvê-la; não invente precisão por aparência.

Use as regras L2 e de forma de interação em references/architecture-contracts.md. Use as verificações de navegação e proprietário canônico em references/document-and-complexity-gates.md quando o pacote contiver vários documentos.

Fase 5 — MVP e contrato local de tarefa

Escolha o menor loop fechado real que exercite a fronteira pretendida. Uma fatia de leitura/fechamento de ciclo de vida pode preceder uma fatia de primeira fronteira de escrita. Preserve rótulos MVP locais apenas quando emparelhados com um nome descritivo, e declare exatamente o que a fatia prova e não prova.

Antes de codificar uma tarefa de implementação delimitada, congele apenas o contrato L3 consumido por essa tarefa. Ele permanece candidato até que a tarefa de implementação adote ou registre revisões nele. Não crie documentos L3 para módulos não selecionados. Use a lista de verificação L3 e de interface em references/architecture-contracts.md.

Fase 6 — Revisão adversarial e steelman bidirecional

Execute uma passagem adversarial que tenta quebrar propriedade, recuperação, compatibilidade, migração e reivindicações de evidência, seguida por um steelman que declara o valor mais forte e fronteiras deliberadamente conservadoras. Prefira um revisor independente que não escreveu o pacote; caso contrário, use um novo contexto e divulgue a limitação.

Use references/adversarial-review.md para tempo de revisão, perguntas e o livro de reconciliação único. Consuma cada descoberta imediatamente. Uma descoberta bloqueadora mantém o portão fechado até que o risco seja resolvido ou explicitamente rebaixado/aceito como uma exceção pelo usuário ou por um revisor independente; rejeitá-la ou adiá-la sozinho não abre o portão.

Fase 7 — Migração, verificação e promoção

Defina migração em estágios com camadas de compatibilidade, condições de aborto, portões de remoção, fronteiras de reversão/reinício, fixtures legado/alvo e evidência equivalente. Promova texto alvo para arquitetura atual apenas após a implementação, evidência de compatibilidade e atualizações de autoridade do repositório serem mescladas juntos.

Ao final de cada incremento, escolha um resultado: continuar, executar um experimento nomeado, revisar o alvo/contrato, ou parar e preservar o caminho atual. O próximo incremento começa apenas quando seu gatilho e evidência de promoção forem satisfeitos. Carregue references/migration-and-promotion.md para evidências detalhadas, experimentos e regras de ADR.

Fase 8 — Handoff e publicação

Antes da publicação:

• valide metadados, links, catálogos e verificações de conformidade/regressão relevantes;
• inspecione o diff completo para arquivos não relacionados ou alegações de implementação não suportadas;
• atualize o registro de mudança/handoff existente do projeto;
• torne o registro do incremento descobrível a partir de uma entrada de orientação ou catálogo;
• declare a próxima tarefa exata e proprietário.

Não crie um PR ou envie uma branch a menos que o usuário autorize essa mutação externa. Quando autorizado, descreva o pacote como design/documentação alvo a menos que o comportamento em tempo de execução tenha realmente mudado.

Preocupações opcionais

Plugins, coexistência de versões, isolamento de processo, substituição a quente e descarregamento dinâmico não são requisitos de arquitetura padrão. Carregue references/optional-concerns.md apenas quando o design solicitado realmente ativar uma dessas preocupações.

Roteamento de módulos

Necessidade	Carregar
Selecionar o menor conjunto de artefatos e horizonte de entrega	deliverable-matrix.md
Perguntar ou registrar uma decisão material do usuário	user-decision-gates.md
Definir L1/L2/L3 ou uma interface voltada para implementação	architecture-contracts.md
Controlar crescimento de documento, complexidade ou superdimensionamento	document-and-complexity-gates.md
Executar revisão adversarial e steelman	adversarial-review.md
Planejar migração, experimentos, ADRs ou promoção	migration-and-promotion.md
Projetar plugins, isolamento ou coexistência de versões	optional-concerns.md

Não carregue todos os módulos por padrão. A fase ativa e o entregável solicitado determinam quais referências são necessárias.

Não fazer

• Não reescreva toda a base de código antes de provar uma fatia real.
• Não transforme todo arquivo/classe em um plugin.
• Não crie proprietários de estado duplicados, agendadores, armazenamentos, barramentos ou autoridades de ciclo de vida sem uma decisão de alvo explícita e modelo de falha.
• Não oculte responsabilidades mistas atrás de um wrapper de passagem renomeado.
• Não reivindique desacoplamento baseado apenas em uma contagem de dependências mais baixa.
• Não use uma demonstração sintética como condição primária de saída do MVP.
• Não deixe que a limpeza de extensão implique conclusão ou destruição de domínio.
• Não trate notas de tarefa, pontuações de benchmark ou prosa gerada como autoridade de arquitetura atual.