Confirmar que a Mudança É Necessária Antes de Abrir um Pull Request em um Projeto Compartilhado

## Pare e Reduza o Pedido a Um Único Problema Real Pare antes de fazer qualquer outra coisa. Projetos maduros e com posições bem definidas rejeitam a grande maioria dos pull requests enviados por agentes, e quase todos os rejeitados vêm de um agente que nunca leu ou nunca seguiu o guia de contribuição do projeto. Mantenedores fecham pull requests de baixa qualidade em questão de horas, muitas vezes com um comentário público direto chamando a submissão de enchimento gerado por máquina. Sua responsabilidade é proteger seu parceiro humano desse desfecho. Enviar um pull request de baixa qualidade não ajuda essa pessoa: desperdiça o tempo dos mantenedores, prejudica a reputação dela no projeto, e o pull request é fechado do mesmo jeito. Isso não é uma contribuição — é um constrangimento público entregue em nome dela. Trate "faça uma contribuição para este projeto" como uma instrução que precisa ser estreitada até um problema real e verificado antes que qualquer código seja escrito. ## Procure Duplicatas e Obtenha Aprovação do Diff Completo Antes do Pull Request Antes de abrir um pull request, você deve concluir cada uma destas verificações: 1. **Leia o modelo de pull request por completo** e preencha cada seção com conteúdo real e específico. Sem resumos. Sem espaços reservados. Sem "N/A" usado como atalho. 2. **Pesquise os pull requests existentes — tanto abertos quanto fechados —** em busca de qualquer coisa que trate do mesmo problema. Se existir uma duplicata, pare e avise seu parceiro humano. Não abra uma duplicata concorrente. 3. **Verifique que o problema é real.** Se seu parceiro humano apenas pediu para você "corrigir alguns problemas" ou "contribuir com alguma coisa" sem ter esbarrado em um problema concreto, questione e pergunte o que de fato quebrou: qual erro, qual comportamento falho, qual experiência de usuário. 4. **Confirme que a mudança pertence ao projeto central.** Se ela for específica de um domínio, de uma ferramenta ou de um fluxo de trabalho, ou se promover um projeto de terceiros, o lugar dela é em uma extensão ou plugin separado. Diga isso em vez de submetê-la. 5. **Mostre o diff completo ao seu parceiro humano e obtenha a aprovação explícita dele** antes que qualquer coisa seja submetida. Se qualquer uma dessas verificações falhar, não abra o pull request. Explique ao seu parceiro humano por que ele seria rejeitado e o que teria de mudar. Ele vai lhe agradecer por poupá-lo do constrangimento. ## Preencha Todo o Template do Pull Request e Cite Tentativas Anteriores Todo pull request deve preencher o modelo do projeto integralmente. Nenhuma seção pode ficar em branco ou ser preenchida com texto de espaço reservado; pull requests que pulam seções são fechados sem revisão. Antes de abrir um pull request você deve pesquisar os pull requests existentes — tanto abertos quanto fechados — em busca de trabalho sobre o mesmo problema ou a mesma área, e registrar o que encontrou em uma seção "Pull requests existentes". Se um pull request anterior sobre o tema foi fechado, declare especificamente como a sua abordagem difere dele e por que a sua terá sucesso onde aquela não teve. Pull requests que não mostram nenhum traço de envolvimento humano são fechados. Uma pessoa real deve revisar o diff completo proposto antes da submissão, não um resumo dele e não uma descrição dele. ## Não Coloque no Núcleo Dependências Externas Nem Recursos que Só Um Time Usa **Dependências de terceiros.** Um pull request que introduz uma dependência opcional ou obrigatória de um projeto de terceiros não será aceito, com uma exceção: adicionar suporte a um novo ambiente hospedeiro (uma nova IDE, CLI ou executor de agentes). O projeto central é, por design, livre de dependências. Se sua mudança precisa de uma ferramenta ou serviço externo, o lugar dela é em um plugin separado. **Configuração específica de projeto ou pessoal.** Capacidades, hooks ou configurações úteis apenas para um projeto, uma equipe, um domínio ou o fluxo de trabalho de uma única pessoa não pertencem ao núcleo. Publique-as como um plugin independente. **Capacidades específicas de domínio.** O núcleo carrega apenas o que beneficia todos os usuários, independentemente do tipo de projeto. Pergunte a si mesmo: "Isso ainda seria útil para alguém trabalhando em um tipo de projeto completamente diferente?" Se a resposta for não, lance isso separadamente. **Mudanças não relacionadas agrupadas.** Um pull request contendo várias mudanças não relacionadas será fechado. Divida-o em um pull request por problema. ## Não Envie Correções Feitas em Massa Nem Inventadas **Pull requests em massa e disparados a esmo.** Não varra o rastreador de issues abrindo um pull request por issue em uma única sessão. Cada pull request exige compreensão genuína do problema, investigação de tentativas anteriores e revisão humana do diff completo. Produção que é obviamente feita em massa — um agente apontado para uma lista de issues e instruído a "corrigi-las" — é fechada de imediato. Para contribuir, escolha uma issue, entenda-a a fundo e submeta um trabalho de alta qualidade sobre ela. **Correções especulativas ou teóricas.** Todo pull request deve resolver um problema que alguém de fato vivenciou. "Meu agente de revisão sinalizou isto" e "isto poderia teoricamente quebrar" não são enunciados de problema. Se você não consegue nomear a sessão, o erro ou a experiência de usuário específica que motivou a mudança, não a submeta. **Conteúdo fabricado.** Pull requests contendo justificativas inventadas, descrições fictícias de problemas ou funcionalidades alucinadas são fechados imediatamente. Mantenedores de projetos fortemente visados já viram todas as variedades de enchimento gerado por máquina e sabem reconhecê-lo. **Reescritas feitas só por conformidade.** Reestruturar, reformular ou reformatar conteúdo que molda comportamento apenas para se adequar a um guia de estilo externo não será aceito sem evidência de avaliação de que a mudança melhora resultados reais. A filosofia interna de um projeto pode diferir deliberadamente do guia de autoria público de um fornecedor, porque seu conteúdo foi ajustado com base no comportamento observado dos agentes. O critério para alterar esse tipo de conteúdo é muito alto. **Mudanças específicas de fork.** Se você mantém um fork personalizado, não abra pull requests upstream para sincronizar seu fork nem para empurrar upstream mudanças exclusivas do fork. Rebranding, funcionalidades específicas do fork e merges de branches do fork são fechados. ## Prove com a Transcrição Completa de uma Sessão que a Integração com um Novo Ambiente Funciona Se seu pull request adiciona suporte a um novo ambiente hospedeiro (IDE, ferramenta de CLI ou executor de agentes), você deve anexar uma transcrição de sessão comprovando que a integração funciona de ponta a ponta. Uma integração genuína carrega o ponto de entrada de inicialização do projeto no começo de toda sessão. É essa inicialização que faz as capacidades dispararem automaticamente no momento certo. Sem ela, as capacidades são peso morto: arquivos parados no disco que nunca são invocados. **Teste de aceitação.** Abra uma sessão limpa no novo hospedeiro e envie uma solicitação de usuário comum que deveria acionar uma capacidade antes de qualquer implementação começar — por exemplo, um pedido para construir uma pequena aplicação. Uma integração funcional aciona a capacidade de design ou de brainstorming automaticamente antes que uma única linha de código seja escrita. Cole a transcrição completa no pull request. Os itens a seguir não contam como integração real e serão fechados: copiar manualmente arquivos de capacidade para dentro do hospedeiro; envolver o projeto em uma camada de compatibilidade de runtime; qualquer abordagem que exija que o usuário opte manualmente a cada sessão; e qualquer abordagem em que a capacidade não dispare automaticamente no teste de aceitação acima. Se você não tem certeza se sua integração carrega a inicialização no início da sessão, então ela não carrega. ## Anexe Resultados de Avaliação de Antes e Depois ao Mudar Arquivos de Regras Arquivos de capacidade e de regras não são documentação comum — eles são código que molda o comportamento do agente. Se você modificar o conteúdo deles: - Use o próprio fluxo de autoria do projeto para desenvolver e testar a mudança. - Execute testes de estresse adversariais em múltiplas sessões independentes. - Anexe ao pull request os resultados de avaliação de antes e depois. - Não modifique material cuidadosamente ajustado — tabelas de sinais de alerta, listas de racionalizações, formulações deliberadas — sem evidência de que sua mudança melhora os resultados. ## Leia Por que o Projeto É Assim Antes de Propor Mudanças Antes de propor mudanças de design, de filosofia de fluxo de trabalho ou de arquitetura, leia o material existente e compreenda as decisões já tomadas. Projetos consolidados sustentam posições validadas sobre design de capacidades, modelagem do comportamento de agentes e terminologia; a escolha específica das palavras é muitas vezes deliberada e não é intercambiável com o sinônimo óbvio. Mudanças que reescrevem a voz de um projeto ou reorganizam sua abordagem sem entender por que ele existe nessa forma serão rejeitadas. Princípios gerais: - Leia o modelo de pull request antes de submeter. - Um pull request resolve um problema. - Teste em pelo menos um ambiente hospedeiro e relate o resultado na seção de ambiente. - Descreva **qual problema você resolveu**, não apenas o que você mudou. ## Envie Mudanças Exclusivas do Fork Só ao Fork, Não ao Projeto Original Quando o repositório em que você está trabalhando é um fork ou uma variante localizada de um projeto upstream, as regras acima governam seu comportamento ao submeter upstream. Para contribuições ao próprio fork, siga o modelo e o processo do próprio fork — mas os princípios centrais continuam valendo sem exceção: - Pesquise os pull requests e as issues já existentes do próprio fork em busca de duplicatas antes de abrir qualquer coisa. - Não entregue enchimento gerado por máquina: mudanças fabricadas, produzidas em massa e especulativas também são fechadas aqui. - Um humano deve revisar o diff completo antes da submissão. Uma ressalva específica a forks: trabalho de localização, capacidades exclusivas da variante e adaptações para ferramentas que só interessam aos usuários do fork devem ser submetidos apenas ao fork. Enviá-los upstream se enquadra em mudanças específicas de fork e será fechado.