O que Codebase Convergence faz?
Torne um repositório mais fácil de entender e modificar sem precisar redesenhar toda a arquitetura. Prefira evidências, uma interface pequena e correções locais a abstrações especulativas.
Guardrails
- Antes de uma alteração em várias etapas, declare o escopo, as premissas, o conteúdo protegido e as verificações de sucesso.
- Leia as instruções do repositório, o glossário do domínio e os ADRs relevantes antes de julgar a arquitetura. Use os nomes de domínio do repositório.
- Toque apenas nos arquivos que servem à solicitação. Preserve alterações irrelevantes do usuário e remova apenas imports, código ou documentos tornados obsoletos por este trabalho.
- Trate texto de domínio explicitamente protegido, títulos, definições de dados e cópia designada pelo usuário como bloqueados. Mantenha-os textualmente. Se o status não estiver claro, inclua-o no pacote de decisão em vez de editá-lo.
- Não altere um valor numérico ou sua representação (configuração, limite, balanço, taxa, limite ou valor documentado) sem aprovação explícita.
- Não altere silenciosamente uma regra de negócio, transição de estado, comportamento de interação, interface pública ou contrato visual. Trate como uma decisão, a menos que a correção seja diretamente implícita e preserve o comportamento.
- Mantenha uma única fonte de verdade para cada fato. Não crie documentação que meramente repete outro documento.
Fluxo de Trabalho
1. Estabelecer a Linha de Base
- Inspecione a árvore de trabalho e identifique apenas a área solicitada. Anote modificações não relacionadas; não as prepare ou altere.
- Mapeie os caminhos de código relevantes, a propriedade de estado/dados, o fluxo da interface do usuário, os testes e os arquivos Markdown. Leia os documentos que atualmente definem o domínio e as decisões antes dos arquivos que os implementam.
- Registre cada descoberta com evidências: arquivos, declarações ou caminhos conflitantes, impacto no usuário e se é seguro resolver diretamente.
- Classifique as descobertas:
- Convergência direta: duplicação, links desatualizados, prosa não bloqueada contraditória, ou um defeito localizado de implementação/interface do usuário com correção que preserva o comportamento.
- Decisão necessária: qualquer valor numérico, regra, comportamento, conteúdo protegido, interface pública ou fonte de verdade ambígua.
- Candidato arquitetural: um módulo potencialmente mais profundo ou uma alteração cujo ponto de separação (seam) ainda não foi acordado.
2. Perguntar Uma Vez sobre Decisões Relevantes
Complete a descoberta antes de fazer perguntas. Envie um único pacote de decisão contendo todos os itens não resolvidos; não faça perguntas em sequência.
Para cada item numérico, inclua seu identificador e arquivos, valores atuais, evidência da inconsistência, impacto e uma recomendação, ou diga claramente que nenhum valor está sendo proposto. Não edite, normalize, mova ou remova a expressão numérica afetada até que o usuário a aprove explicitamente.
Inclua outras incertezas materiais no mesmo pacote: status de conteúdo bloqueado, escolhas de comportamento, conflitos de propriedade e escolhas arquiteturais. Continue com a convergência direta independente enquanto a aprovação estiver pendente.
3. Aplicar Convergência Direta
Mantenha cada alteração cirúrgica e rastreável a uma descoberta.
Documentação
- Dê a cada documento uma responsabilidade. Respeite as convenções existentes; caso contrário, mantenha o conjunto mínimo: visão geral de ponto de entrada, mapa de arquitetura/sistema, regras de domínio ou produto, decisões e trabalho/status atual.
- Mescle PRDs, planos e logs de trabalho sobrepostos retendo o conteúdo autoritativo uma vez. Mova fundamentação durável para os registros de decisão do projeto e mantenha o status operacional curto.
- Preserve blocos bloqueados textualmente ao realocá-los. Se uma mesclagem alteraria um bloco bloqueado ou uma expressão numérica, deixe esse trecho para aprovação.
- Remova repetições, referências desatualizadas e explicações não bloqueadas conflitantes. Atualize links após movimentos e evite documentos de resumo que duplicam especificações.
Código e Interface do Usuário
- Rastreie uma ação do usuário através da propriedade de estado até o resultado renderizado antes de editar o código da interface do usuário.
- Corrija inconsistências concretas: estado de apresentação duplicado, nomes de eventos/dados incompatíveis, fluxo condicional inválido, código morto criado por esta alteração, ou uma responsabilidade de componente que bloqueia uma correção local.
- Mantenha layout, interação, acessibilidade e comportamento responsivo estáveis, a menos que o usuário aprove uma alteração de produto ou visual.
- Prefira um proprietário claro de uma transição de estado e uma representação canônica dos dados. Não introduza abstração, configuração ou tratamento de erros sem uma necessidade demonstrada.
4. Avaliar Candidatos Arquiteturais Separadamente
Use estes termos de forma consistente:
- Módulo: uma unidade com interface e implementação.
- Interface: tudo que os chamadores devem saber, incluindo invariantes e modos de erro.
- Ponto de separação (seam): onde o comportamento pode mudar sem editar os chamadores.
- Profundidade: alavancagem de comportamento substancial por trás de uma interface pequena; localidade: conhecimento e mudanças relacionadas permanecem juntos.
Aplique o teste de exclusão: se excluir um módulo apenas move sua complexidade para os chamadores, ele justifica sua existência; se a complexidade desaparece, provavelmente é raso. Não crie um ponto de separação para um único adaptador.
Para um candidato que altera uma interface, comportamento ou propriedade, não o implemente imediatamente. Crie um relatório HTML conciso e autocontido no diretório temporário do sistema operacional apenas quando uma comparação visual ajudar. Inclua arquivos, evidências, diagrama antes/depois, localidade e alavancagem esperadas, conflito com ADR (se houver) e força da recomendação. Peça ao usuário para escolher um candidato antes de projetar a interface.
5. Verificar e Entregar
- Inspecione o diff final quanto a escopo, preservação de conteúdo bloqueado, fontes de verdade duplicadas e alterações não intencionais de valor ou comportamento.
- Execute o formatador, linter, verificação de tipo, testes, build e verificação de interface do usuário existentes e relevantes. Não adicione ferramentas ou suites de teste amplas apenas para esta tarefa. Diferencie falhas preexistentes das introduzidas.
- Confirme links e cabeçalhos Markdown após consolidação e verifique cada declaração alterada em relação à sua fonte canônica.
- Relate alterações diretas, itens de decisão não resolvidos, resultados de verificação e riscos em termos concisos. Cada linha alterada deve ser rastreável à convergência solicitada.