Faça um agente de codificação de IA entregar código sem avisos e relatórios honestos em um repositório com build rígido

## Compile só o módulo alterado ao iterar e valide tudo antes do push Use o wrapper de build versionado no repositório em vez de um toolchain instalado globalmente, para que todo colaborador e agente compile de forma idêntica. Para iteração rápida, compile e teste apenas o módulo que você alterou, em vez do build multi-módulo completo; geralmente existe um perfil "rápido" que pula as verificações de análise estática e uma flag que pula os testes. Esses atalhos servem apenas para ciclos locais. Antes de commitar, você deve rodar uma compilação completa do módulo afetado com as verificações ativadas e confirmar zero warnings — nunca commite com base em um build que pulou as verificações. Antes de dar push, execute a etapa de validação do projeto, que é sensível ao diff: ela classifica a mudança (apenas documentação, módulo único, ou mudança de configuração raiz) e compila somente os módulos afetados junto com seu fechamento de dependências, enquanto uma mudança na configuração raiz do build força uma compilação completa. A validação deixa um marcador de curta duração que o hook de push verifica. Cancele execuções de pipeline substituídas na sua branch antes de dar push para não desperdiçar os runners compartilhados. ## Nunca pule os hooks do Git e escreva mensagens de commit curtas sem assinatura de IA Ative o caminho de hooks do repositório no início de cada sessão de trabalho; sessões podem ser arquivadas e retomadas, então essa não é uma configuração feita uma única vez. Nunca contorne os hooks — nada de flag para pular verificação, nada de bypass de assinatura. Os hooks garantem os cabeçalhos de licença, a ausência de imports não utilizados ou duplicados, e o formato da mensagem de commit. Escreva os assuntos de commit no formato convencional type(scope): description, usando tipos como feat, fix, docs, refactor, test e chore. Mantenha cada mensagem em no máximo duas linhas não vazias, com a primeira linha abaixo de cerca de 100 caracteres. Não adicione linhas de trailer — nada de trailer de co-autor, nada de trailer de sign-off e, acima de tudo, nenhuma assinatura de autoria ou geração por IA de qualquer tipo; o hook de mensagem de commit as rejeita. Correções de bugs vão direto para a branch principal de desenvolvimento; novas funcionalidades usam feature branches. ## Siga o estilo do código ao redor e trate cada aviso como erro Siga o estilo do código ao redor e faça a menor mudança razoável para alcançar o resultado. Todo arquivo-fonte deve carregar o cabeçalho de licença exigido. Prefira composição em vez de herança; use uma construção try-with-resources para todo recurso fechável; retorne um wrapper opcional em vez de null nas APIs públicas; use inferência de tipo local apenas quando o tipo for óbvio pelo contexto; prefira expressões switch e pattern matching em vez de longas cadeias if/else; use tipos sealed e carriers de record imutáveis onde couberem; sempre parametrize generics; anote métodos que sobrescrevem outros; construa strings com um builder dentro de loops; e construa coleções não modificáveis com os helpers de factory padrão. Trate todo warning de compilador, de depreciação e de análise estática como um erro. O build roda com todas as verificações de lint ativadas e falha em imports não utilizados ou duplicados, então zero warnings é exigido para lançar. Não introduza novas anotações de supressão de warning sem um comentário justificando por que uma é inevitável, e nunca apague um comentário de código a menos que você consiga provar que ele está ativamente errado. ## Só quem cria um recurso pode fechá-lo, e nunca ignore os limites de capacidade Os invariantes a seguir bloqueiam o lançamento independentemente do escopo da funcionalidade; violar qualquer um deles bloqueia o release, não importa quão pequena seja a mudança. **Posse (Ownership)** — Somente o criador de um recurso pode liberá-lo, fechá-lo ou desligá-lo. Rastreie a posse explicitamente e, ao aceitar um executor, pool ou conexão fornecido externamente, encapsule-o para que chamadas de ciclo de vida não destruam algo que você não criou. Toda rotina de início precisa de uma rotina de parada simétrica que desfaça todo registro — listeners, handlers, hooks — e todo buffer deve ser liberado em todos os caminhos terminais e de erro. **Completude de caminhos terminais** — Todo caminho de saída (sucesso, falha, cancelamento, timeout, rejeição) deve deixar o sistema em um estado concluído: resolva futures, reinicie flags, libere buffers. Torne o close idempotente com um padrão de compare-and-set ou close-once. Se uma guarda verifica um contador, algum caminho precisa efetivamente incrementar esse contador. **Backpressure** — Nunca ignore sinais de rejeição ou de capacidade. Verifique o valor de retorno de um offer limitado, trate a execução rejeitada e trate escritas parciais. Todo cache e buffer precisa de um limite de tamanho ou de uma política de remoção; uma estrutura sem limite alimentada por entrada externa é um vetor de negação de serviço. ## Valide a entrada em cada fronteira e informe só o que está realmente em execução Esses invariantes também bloqueiam o lançamento independentemente do escopo da funcionalidade. **Segurança de fronteira** — Em toda fronteira (rede, sistema de arquivos, shell, URL, HTTP) valide e codifique antes de interpretar. Decodifique texto somente a partir de mensagens completas e enquadradas, nunca a partir de blocos brutos de transporte. Normalize e valide caminhos do sistema de arquivos — resolva, normalize e depois confirme que o resultado permanece dentro da raiz pretendida, rejeitando segmentos de diretório pai, separadores e segmentos vazios. Use arrays de argumentos para chamadas de shell, codifique em URL as partes dinâmicas de caminho e query, compare tipos de conteúdo sem diferenciar maiúsculas de minúsculas, e retorne um erro de cliente em vez de um erro de servidor para entradas malformadas, capturando falhas de parse na fronteira. **Verdade em tempo de execução** — Anuncie e relate apenas o estado confirmado em tempo de execução, nunca a intenção de configuração ou a mera presença no classpath. Flags de capacidade e endpoints de descoberta devem refletir o que está realmente em execução, e o anúncio de funcionalidades deve ser suprimido quando a inicialização falhar. **Segurança** — Toda superfície mutável ou administrativa exige autenticação e autorização explícitas, com negação por padrão. A verificação de integridade deve falhar de forma fechada (fail closed); qualquer modo fail-open precisa ser explícito e não ser o padrão. Nunca lance padrões inseguros em caminhos de produção — coloque-os atrás de um opt-in explícito com aviso na inicialização — e os exemplos não podem regredir essa postura. **Paridade de modo** — Se uma funcionalidade existe em múltiplos modos de invocação (síncrono, assíncrono, streaming), a semântica deve corresponder: tratamento de erros, eventos de ciclo de vida, observabilidade e comportamento de conclusão. Documente e teste qualquer diferença intencional e, ao adicionar uma funcionalidade em um caminho, verifique-a em todos os caminhos. ## Inclua um teste de regressão para bugs graves e proíba testes vazios Toda correção de bug de alta severidade deve ser lançada com um teste de regressão que reproduza o cenário de falha. Não são permitidos testes placeholder ou no-op nas lanes de CI obrigatórias — um teste que apenas afirma uma verdade trivial é proibido, e cada teste deve verificar o comportamento específico que alega testar. Testes end-to-end devem verificar a funcionalidade em teste, não apenas que um servidor foi iniciado. Se você precisar colocar um teste instável (flaky) em quarentena, ele precisa de um responsável, uma data de expiração e uma issue de rastreamento, e ainda assim deve continuar rodando em uma lane agendada. Os filtros de caminho do workflow devem incluir todo script e local de configuração que afete o comportamento da área sendo alterada, ou o CI vai pular silenciosamente exatamente o código que foi modificado. ## Faça os exemplos chamarem a API real em vez de simulá-la Apps de exemplo e amostra são a primeira coisa que os usuários veem, então precisam ter qualidade de produção, não ser stubs. Use de fato a integração que você alega demonstrar: se um exemplo tem o nome de uma capacidade real, ele precisa chamar essa API real, não simulá-la com um substituto em memória. Se você não conseguir fazer a integração real funcionar, diga isso e peça ajuda em vez de entregar um mock disfarçado — comentários como "em um app real você chamaria isso aqui" são um sinal de alerta de que o exemplo não é o app real. Antes de escrever código de integração contra uma biblioteca de terceiros, leia a API real dela — inspecione os artefatos da dependência e leia as assinaturas públicas — e nunca invente chamadas de método. Prefira a auto-configuração fornecida pela biblioteca em vez de conexão manual. Todo exemplo precisa compilar e vir com um README curto explicando o que ele faz, como executá-lo e o que o código principal demonstra. Não crie um exemplo por variante de backend quando uma única dependência intercambiável é todo o propósito da abstração. ## Confira cada afirmação no código ou no histórico do Git antes de escrevê-la Toda afirmação factual em documentação, entradas de changelog, mensagens de commit e textos voltados ao usuário deve corresponder a algo que realmente existe no código ou no histórico do git. Não invente funcionalidades, nomes de métodos, conjuntos de capacidades, números de métricas ou commits de correção; cada invenção custa credibilidade e precisa ser rastreada e revertida depois. Afirmações numéricas exigem uma fonte — verifique uma contagem contra o código real antes de escrevê-la. Itens de changelog "corrigido" e "adicionado" precisam corresponder a commits reais: procure a mudança no log e mantenha o hash do commit no seu rascunho antes de promovê-lo; se você não conseguir encontrar o commit, a correção não aconteceu. Afirmações sobre a superfície da API exigem ler o código-fonte real primeiro (listas de campos, nomes de métodos). Uma afirmação de que algo foi lançado, conectado ou integrado exige um consumidor real de produção em um caminho alcançado por uma ação do usuário, não apenas uma interface de provedor de serviço ou uma implementação de referência. Quando um fato não pode ser verificado, remova-o ou marque-o explicitamente como não verificado e pergunte antes de publicar. Se você se pegar inventando algo, pare, não commite, relate a afirmação falsa em comparação com a verdade real, e corrija cada cópia dela. ## Não use conflitos entre regras como desculpa nem declare a tarefa pronta no meio Além da honestidade factual, evite a desonestidade comportamental — formulações em que cada frase isolada é defensável, mas o conjunto induz ao erro. Não fabrique um conflito entre duas regras para justificar o caminho mais fácil; quando regras parecem entrar em conflito, a que exige o trabalho mais difícil e mais seguro quase sempre prevalece. Não escolha a dedo qual diretriz citar enquanto existe outra que a contradiz; reconcilie-as abertamente. Não relate um status quando as regras mandam corrigir silenciosamente — se um pipeline compartilhado está quebrado, conserte-o e relate sucesso em vez de narrar a quebra. "Já estava quebrado" ou "não é minha regressão" é uma descrição, não uma desculpa: a responsabilidade por branches compartilhadas se transfere a cada mudança. Não peça permissão para uma ação que as regras já determinam — fazer vale mais que perguntar, então simplesmente execute o trabalho determinado e continue nos itens em aberto até ser redirecionado. Não declare vitória no meio da tarefa; o sinal honesto lista o que ainda falta ao lado do que já foi feito. Quando a brevidade entra em conflito com uma regra de corretude ou segurança, a regra de segurança vence: detalhado-mas-correto vale mais que conciso-mas-inseguro. Quando você perceber um desses padrões em si mesmo, nomeie-o, execute o trabalho que a regra realmente determinava, e lembre-se de que o pedido de desculpas não é o trabalho. ## Guarde decisões e planos na base de conhecimento compartilhada, não só no chat Trate uma base de conhecimento compartilhada como o lar duradouro para resultados estruturados, porque o chat não é duradouro. Consulte-a primeiro em busca de decisões, designs e contexto anteriores antes de iniciar um trabalho estruturado, e registre nela os resultados duradouros em vez de deixá-los apenas em uma conversa. Direcione por tipo de documento: decisões de arquitetura e registros de design, planos em fases, runbooks e procedimentos de plantão, e auditorias, análises e handoffs — cada um tem um destino designado; documentos de referência acompanham o código ao vivo, e specs restritas a um diretório vivem no README daquele diretório. Mantenha identificadores privados ou apenas locais — handles pessoais, nomes de role-play, caminhos específicos de máquina — fora de todo artefato commitado. Use nomes de placeholder neutros em testes e amostras, e um identificador real somente onde ele genuinamente se refere a uma conta pública. Quando o armazenamento duradouro não estiver disponível, use como alternativa um link compartilhável e registre-o para que uma sessão posterior possa arquivá-lo no lugar certo.