Alterar uma ferramenta de automação de dispositivos e conferir em aparelhos reais

## Classificar o pedido e ler só o código que será alterado Primeiro, classifique a solicitação. Uma revisão, triagem ou pergunta apenas informativa é somente leitura, a menos que edições ou execução sejam solicitadas explicitamente. Uma solicitação de mudança de código autoriza uma implementação mínima e as verificações exigidas para a área afetada. Declare as suposições e defina um sucesso observável antes de editar. Leia o vocabulário duradouro do domínio, as decisões de arquitetura aplicáveis e a configuração ou o contrato responsável. Não leia todo o repositório por padrão. Comece com uma busca delimitada: - Localize o símbolo, comando, sinalizador ou erro com uma busca de texto rápida. - Leia o módulo responsável, um auxiliar compartilhado e um chamador ou adaptador subsequente. - Em um arquivo grande, encontre o tipo ou a função relevante antes de abrir um intervalo delimitado. - Siga imports e testes para fora apenas quando as evidências exigirem. Mantenha a mudança dentro de uma única família de comandos, ponto de integração da plataforma ou grupo de módulos, a menos que a tarefa atravesse fronteiras explicitamente. Não examine duas implementações de plataforma só porque ambas existem. Se for necessário ampliar o escopo, pare e confirme a nova fronteira. Decida o impacto sobre documentação, ajuda, esquema e skill antes de programar. Prefira referências duradouras à fonte da verdade em vez de inventários de arquivos que ficam desatualizados. ## Reunir o nome e as opções de cada comando num único registro Dê a cada comando um descritor canônico responsável por sua identidade, capacidades, política de timeout, política de lote e projeções públicas. Mantenha o roteamento do daemon ou serviço em um registro de rotas, as garantias dos caminhos de interação em uma matriz tipada e os nomes dos comandos em um único catálogo. Não recrie conjuntos de strings nos handlers. Mantenha os roteadores de nível superior enxutos e dedicados apenas à orquestração. Encaminhe para a família de handlers responsável; não acumule lógica de comandos no ponto de entrada. As decisões de capacidade pertencem à fonte da verdade sobre capacidades, não a condicionais espalhadas. Faça cada opção pública atravessar somente as camadas que a compreendem: 1. Defina o sinalizador público e a gramática. 2. Adicione-o aos metadados e ao esquema do comando responsável. 3. Analise-o como entrada do comando. 4. Projete-o em uma solicitação de serviço somente se a execução em runtime precisar dele. 5. Estenda clientes tipados e normalizadores somente quando essas interfaces o expuserem. 6. Passe-o pelo despacho e pelos módulos de plataforma somente depois que o contrato público comprovar que ele pertence a essas camadas. 7. Classifique cada opção pública no modelo de progresso da arquitetura ou de cobertura. Centralize a análise, a correspondência e a resolução de seletores, além da avaliação de predicados. Uma ação direcionada a elementos deve aceitar seletores estáveis ou referências gravadas, preservar sua cadeia de seletores e apresentar divergências de reprodução como sugestão, em vez de reescrever silenciosamente o estado do usuário. ## Conferir se os caminhos rápidos e de cache agem como o principal Pressuponha que as garantias se enfraquecem nas fronteiras dos caminhos. Ao adicionar um caminho rápido, delegado, de cache ou específico de plataforma, classifique cada célula afetada de comando e caminho antes de afirmar que há paridade. Uma entrada de registro não é uma prova semântica. Leia a implementação e verifique se ela satisfaz a definição da garantia. Um fallback que delega somente após um erro não comprova a paridade do caminho de sucesso; o caminho rápido pode aceitar uma entrada que o caminho compartilhado rejeitaria. Antes de medir um experimento, prove que cada braço pode ser executado. Duas execuções aprovadas não significam nada quando a ramificação alterada nunca foi acionada. Registre o caminho, o backend, o código de motivo e outras evidências tipadas necessárias para mostrar qual implementação tratou a solicitação. Use sinais estruturados em vez de analisar mensagens voltadas a pessoas. Faça ramificações com base em códigos de motivo, detalhes tipados e valores explícitos de timeout; não copie detecção por texto de erro. Trate qualquer correspondência inevitável de mensagem como uma dívida documentada no local da decisão. Componha avisos por meio do construtor compartilhado de respostas, em vez de sobrescrever avisos anteriores. Armazene metadados de toda a resposta uma única vez, em vez de repetir bytes para cada nó ou item. Antes de preservar um campo de compatibilidade, determine se ele já foi lançado. Uma superfície não lançada pode ser removida diretamente; uma superfície lançada exige migração e tratamento de compatibilidade. ## Manter arquivos pequenos e testes com a mesma estrutura do código Use `unknown` somente em fronteiras de confiança, como entrada analisada, payloads de runtime, erros capturados e E/S genérica. Valide uma vez e então restrinja a um tipo de domínio ou parser específico, em vez de propagar a incerteza por auxiliares internos e formatadores. Prefira verificações de completude no nível de tipos quando a linguagem puder tornar impossíveis os casos ausentes. Mantenha declarações legíveis por máquina junto ao código que descrevem: células de registro ao lado dos pontos de aplicação, manifestos de cobertura ao lado dos testes de contrato e comentários de decisão na ramificação que justificam. Mantenha cada módulo responsável por uma única pergunta. Como limite prático, busque cerca de 300 linhas para arquivos de implementação; depois de 500, melhore a localidade antes de adicionar comportamento; acima de 1,000, trate o arquivo como dívida de arquitetura, a menos que seja dado gerado ou snapshot de fixture. Nomeie os arquivos de acordo com o conceito de domínio ao qual respondem. Use arquivos de agregação de exports somente nos limites de pacote; arquivos internos desse tipo adicionam saltos de navegação. Extraia um módulo profundo quando isso melhorar a responsabilidade conceitual, não apenas para reduzir a contagem de linhas. Reproduza a topologia do código-fonte nos testes. Quando um módulo-fonte for dividido, divida os testes na mesma mudança. Coloque fixtures reutilizáveis em um módulo irmão nomeado, em vez de duplicar grandes objetos inline. Não adicione exports de produção apenas para facilitar o teste de um detalhe privado. Antes de finalizar, enxugue o código alterado e o diretamente adjacente: remova ramificações obsoletas, testes redundantes, imports não utilizados, fixtures desatualizadas e duplicação tornada desnecessária pela mudança. Evite limpezas não relacionadas. ## Fechar as sessões de dispositivo e separar logs e diagnósticos Encaminhe a execução de processos pela abstração compartilhada de processos. Quando faltar uma capacidade, estenda essa abstração, em vez de importar primitivas de processo de baixo nível por todo o código. Trate cada sessão de dispositivo aberta manualmente como um recurso. Registre o nome da sessão, a plataforma, o identificador do dispositivo e o diretório de estado; em seguida, feche-a com os mesmos valores antes de concluir, mesmo após um experimento malsucedido. Interrompa somente os processos obsoletos exatos que pertençam à execução de verificação; nunca encerre grupos amplos de processos por suposição. Mantenha distintos os logs da aplicação, a saída do runner e os diagnósticos da solicitação. Um único backend deve ser responsável pela captura dos logs da aplicação. Armazene os diagnósticos da solicitação sob a sessão resolvida e o identificador da solicitação; reserve os logs de nível superior do daemon para o ciclo de vida e para falhas anteriores à resolução da sessão. Centralize escopos de diagnóstico, temporizadores, emissão de eventos, mascaramento e construção de caminhos de artefatos. Não construa caminhos de log manualmente nem adicione arquivos ad hoc quando o serviço de diagnóstico for responsável por esses dados. Normalize falhas voltadas ao usuário em um payload estável com código, mensagem concisa, dica de recuperação, identificador de diagnóstico, caminho do log e detalhes tipados. Preserve esses campos ao encapsular erros. Informe o que falhou, o motivo quando conhecido e a próxima ação de recuperação. Trate sondagens opcionais, verificações de cache e pré-verificações como melhor esforço, a menos que o contrato do recurso as torne obrigatórias. Dê a elas um timeout menor que o da operação exigida e recorra ao caminho estabelecido quando falharem ou retornarem uma estrutura inutilizável. ## Escolher os testes conforme o que mudou Comece pelo planejador de verificações afetadas do repositório, quando disponível. Ele deve derivar testes focados e controles restantes a partir de metadados canônicos, não de uma lista escrita à mão. Mapeie as verificações para a superfície alterada: - Toda mudança em código-fonte tipado exige verificação de tipos e formatação. - A configuração da toolchain ou do compilador exige o controle de ferramentas e a geração de declarações. - Mudanças em serviços ou handlers compartilhados exigem o pacote de testes unitários focado. - Mudanças no formato da resposta ou na fronteira do provedor exigem integração com provedores e verificações de cobertura. - Mudanças no runner nativo exigem reconstruir o artefato de teste nativo. - Comportamento multiplataforma exige a suíte de integração multiplataforma. - Trabalho apenas de documentação só exige testes de runtime quando um contrato mais específico assim determinar. Não execute testes de integração amplos por padrão quando evidências focadas forem suficientes. Por outro lado, não declare pronta uma mudança voltada ao dispositivo com base apenas em testes unitários. Mantenha os testes comportamentais. Não teste o que os tipos estáticos já comprovam. Testes unitários não devem esperar em tempo real; injete um orçamento de tempo, derive a cadência dele ou verifique se o orçamento foi conectado corretamente. Quando um controle de aplicação encontrar um sinalizador não classificado, uma célula de garantia ausente, um cenário sem cobertura, um desvio da construção de resposta ou uma lacuna de paridade de regras, classifique ou cubra o novo comportamento. Nunca suprima o controle nem adicione uma entrada inexplicada à lista de permissão. ## Refazer o build antes de conferir em aparelhos reais ou simuladores Antes da verificação manual, reconstrua todos os artefatos que o runtime realmente consome, reinicie os serviços que não fazem recarga dinâmica e invalide ou substitua qualquer runner adotado que possa continuar servindo um binário nativo antigo. Um teste contra saída desatualizada é um falso negativo, não evidência do produto. Comprove qual backend tratou a execução. Capture um snapshot ou uma resposta de status legível por máquina e verifique o identificador do backend e a versão do auxiliar em relação ao pacote atual. Um fallback silencioso só é evidência válida quando o comportamento de fallback é o recurso em teste. Use dispositivos, simuladores ou emuladores diferentes para worktrees simultâneas, pois o estado isolado do daemon não isola alvos físicos. Siga o guia de configuração do próprio aplicativo de teste; um aplicativo instalado não basta, a menos que as verificações de build, servidor de desenvolvimento e superfície comprovem que a versão pretendida está em execução. Classifique o ruído do ambiente antes de depurar o código do produto. Reproduza falhas de contenção isoladamente e na base inalterada sob a mesma carga. Um conjunto variável de falhas que passa isoladamente provavelmente indica contenção; uma falha estável no caminho alterado é uma evidência mais forte de regressão. Se um sandbox impedir um listener local, uma ponte de dispositivo ou uma ferramenta nativa necessária, execute novamente pelo caminho elevado aprovado, em vez de diagnosticar a recusa do sandbox como bug do produto. Se a verificação ao vivo continuar bloqueada, informe o dispositivo, a permissão, o comando ou o serviço exato necessário e mantenha o risco residual. ## Revisar o caminho real do comando e relatar com resultados do aparelho Faça a revisão em relação à issue motivadora e às decisões de arquitetura aceitas, não apenas ao diff. Rastreie a rota de produção desde a superfície do comando, passando pelo roteamento da solicitação, até o backend da plataforma. Um teste que ignore o roteador ou simule a junção crítica não comprova o comportamento entregue. Para cada teste de regressão essencial, identifique a implementação antiga, a exclusão ou a reversão que deveria fazê-lo falhar. Se o teste continuar aprovado após o retorno do bug, ele é vazio e precisa ser fortalecido. Separe a refatoração pretendida de mudanças de comportamento ocultas no formato de saída, propagação de avisos, detalhes de erros, caminhos de artefatos, níveis de nova tentativa e fallbacks. Verifique mudanças irmãs e a ordem das ramificações quando a implementação depender de outra mudança. Coloque a publicação externa ou o push atrás de uma única cadeia de sucesso, para que não possam ser executados após uma falha de formatação, tipos, lint ou testes. Mantenha commits e pull requests com escopo definido, use o estilo de título convencional do projeto e abra uma revisão pronta por padrão somente quando o trabalho estiver concluído. Resuma o comportamento visível ao usuário, a validação relevante, as evidências do dispositivo ao vivo e as contrapartidas reais. Não chame a CI de aprovada com base em uma execução unitária local e não declare uma mudança de plataforma pronta para merge sem evidência ao vivo atual. Informe o impacto sobre documentação ou ajuda, o escopo alterado, qualquer caminho não verificado e o bloqueador exato. Antes da entrega, feche todas as sessões e contabilize todos os recursos abertos durante a verificação. Informe qualquer sessão, processo, diretório de estado ou artefato que não pôde ser limpo.