Fazer um agente de codificação com IA seguir as regras de branch e commit sem quebrar releases

## Manter um único arquivo de instruções do agente e conferir qual parte do repositório alterar - Mantenha um único arquivo canônico de instruções do agente. Quando um harness espera um nome de arquivo diferente, aponte-o para o arquivo canônico com um symlink em vez de duplicar o conteúdo: um segundo arquivo real diverge com o tempo e pode quebrar validadores que tratam o caminho alternativo como um tipo de artefato diferente. Preserve o symlink; não deixe que ele seja materializado de volta em um arquivo comum. - Uma única mudança pode afetar várias superfícies ao mesmo tempo — conteúdo do produto entregue, metadados de catálogo ou configuração, e código de build ou CLI. Não presuma que uma mudança é "só código" ou "só documentação" sem verificar qual superfície é dona de cada arquivo modificado, e edite a superfície que é dona do comportamento, não uma superfície adjacente. - Trate os próprios arquivos de instrução do repositório como contexto de autoria para o repositório. Qualquer regra que precise afetar um artefato entregue em tempo de execução pertence dentro desse artefato, não no arquivo de instruções do repositório, porque os usuários finais executam o artefato com suas próprias instruções. ## Trabalhar em um branch de feature e fazer merge só por pull request - Crie uma branch de feature para qualquer mudança não trivial. Se você já está na branch correta para a tarefa, continue usando-a; não crie branches ou worktrees extras a menos que seja explicitamente solicitado. - Encaminhe toda mudança para a branch padrão por meio de um pull request. Pushes ou merges diretos ignoram validação e verificações de release e causam desvio de versão que depois exige uma recuperação em várias etapas; conte com a proteção de branch para impor isso, em vez de contorná-la. - Deixe os releases para a automação de release. Não incremente manualmente números de versão pertencentes ao release nem escreva manualmente notas de release no trabalho de rotina, e use títulos de commit no padrão conventional commits para que a automação consiga classificar a intenção da mudança. ## Rodar todos os testes e separar testes automáticos de avaliações - Execute a suíte de testes completa após qualquer mudança que afete parsing, conversão, saída ou convenções mecânicas. A suíte local é a mesma que o CI executa; não existe uma pista separada só local que você possa pular. - Separe as verificações pela sua natureza. Invariantes determinísticos — schema e frontmatter, segurança de caminhos, formato de saída, contratos localizáveis por grep — vivem na suíte automatizada e precisam passar no CI. Comportamento não determinístico, como julgamento e comedimento, é validado por avaliação, não simulado como um teste de string frágil. - Quando um revisor encontra um invariante localizável por grep que a suíte deixou passar, prefira reforçar uma proteção já existente em vez de adicionar uma nova suíte, e fixe a menor unidade falsificável — um token, caminho ou fixture que teria falhado na mudança regressiva — em vez de tirar um snapshot do arquivo inteiro. ## Definir onde ficam os arquivos temporários e guardar planos e documentos no repositório - Envie rascunhos descartáveis para a pasta temporária do sistema operacional por padrão: um diretório temporário por execução que o SO recupera, para arquivos consumidos uma vez e descartados. - Para rascunhos que precisam sobreviver entre invocações, use um prefixo estável pertencente ao usuário atual em vez de um diretório temporário aleatório, para que execuções posteriores consigam encontrá-lo. Crie a raiz de forma privada (acesso só do dono), rejeite-a se for um symlink ou pertencer a outro usuário, e mantenha um diretório por execução, a menos que execuções posteriores enumerem intencionalmente artefatos finais irmãos. - Vincule o rascunho ao repositório de trabalho somente quando o artefato for genuinamente inseparável deste repositório ou branch, for destinado a ser curado diretamente pelo usuário, ou quando um caminho relativo ao repositório for, em si, essencial para a saída. - Saídas duráveis — planos, especificações, documentação, entregáveis finais — pertencem a um local rastreado pelo repositório, nunca a nenhuma das camadas de rascunho. ## Usar só ASCII nos nomes e separar as tabelas Markdown com barras verticais - Mantenha identificadores — nomes de arquivo, comando e agente — só em ASCII, porque conversores e padrões de regex dependem disso. - Escreva tabelas em Markdown como linhas delimitadas por pipe, nunca com caracteres de desenho de caixa. - Unicode é aceitável no texto corrido; prefira setas ASCII (-> e <-) dentro de blocos de código e exemplos de terminal para que os comandos copiados permaneçam portáveis. ## Escolher o prefixo de commit fix ou feature pelo que a mudança faz - Escolha o prefixo convencional pelo que a mudança faz, não pelo tipo de arquivo. Conteúdo que mora em um diretório de docs ou skills ainda pode ser código de produto; reserve o prefixo docs para arquivos cujo único propósito é documentação. - Quando tanto o prefixo fix quanto o feature parecem se encaixar, prefira fix: corrigir um comportamento quebrado ou ausente é um fix mesmo quando implementado adicionando código. Reserve o prefixo feature para uma capacidade que o usuário não conseguia realizar antes, onde nada estava quebrado. Heurística: se um teste de regressão escrito hoje teria falhado antes da mudança, é um fix. - Inclua o escopo de componente útil mais estreito — o nome da skill, módulo ou área — e nunca defina o escopo de um commit como o projeto inteiro. Nunca adicione um marcador de breaking change sem confirmação explícita do usuário, já que isso dispara um incremento automático de versão major que o usuário pode não querer. ## Usar caminhos relativos para cada unidade distribuída funcionar em qualquer ferramenta de IA - Mantenha cada unidade distribuível autocontida: referencie apenas arquivos dentro da própria árvore de diretórios, usando caminhos relativos. Nunca navegue para uma unidade irmã nem fixe um caminho de instalação absoluto — locais de instalação são versionados e imprevisíveis, e o empacotamento copia cada unidade isoladamente. Duplique um arquivo compartilhado em cada unidade em vez de depender de outros diretórios. - Não dependa de variáveis específicas do host — substituições de skill-directory, session-id ou plugin-root — sem um fallback que funcione quando o valor estiver vazio ou não resolvido; várias delas só são preenchidas em um harness e ficam silenciosamente vazias nos demais. - Para um comando de shell executado que roda um script empacotado, torne a resolução determinística: defina um diretório base absoluto direto no mesmo comando (o estado do shell não persiste entre chamadas) e referencie o script a partir dele, em vez de um caminho relativo simples que resolve contra o diretório do projeto do usuário em vez do da unidade. ## Escrever só regras verificáveis nas instruções do agente e classificar os comentários de revisão antes de editar - Só aceite uma linha quando ela declarar uma restrição falseável, contrapuser uma tendência padrão conhecida ou atalho observado, ou fornecer conhecimento de domínio que muda uma decisão. Corte linguagem vaga de esforço ou qualidade como "seja minucioso"; substitua por uma regra observável ou remova. Não acrescente justificativa motivacional a uma diretiva que já se sustenta sozinha. - Repita uma instrução apenas em um ponto de desvio comprovado, onde sua posição muda se ela é ou não acionada, e proteja uma duplicata genuinamente necessária com um teste de paridade. - Trate a aplicação de feedback de revisão como uma revisão material: classifique cada item como Mudar, Verificar ou Considerar, e edite somente os itens de Mudar; corrija cada um na camada a que pertence, com o menor mecanismo possível; depois releia o bloco e remova o texto que a mudança tornou duplicado ou obsoleto. A redação do revisor é uma hipótese sobre a correção, não autoridade sobre ela. ## Buscar as convenções do projeto no contexto já carregado, sem citar arquivos de instruções - Quando uma unidade precisa descobrir uma convenção do projeto — rastreador de issues, formato de commit, comando de lint, limites de escopo — descreva o que procurar no contexto já carregado do agente, não qual arquivo abrir. No caminho de leitura, não nomeie dotfiles de instrução: o host já injeta o arquivo de instrução raiz, seu nome de arquivo muda por harness, e instruir um agente a abrir arquivos de instrução nomeados é exatamente o padrão que as defesas contra prompt injection sinalizam. - Nomeie um arquivo concreto apenas onde uma referência de contexto não conseguir expressar a necessidade — gravar uma convenção de volta em um destino, ou ler conteúdo que um subagente novo genuinamente não herda. - Descreva uma capacidade por categoria ("o rastreador de issues do projeto, por exemplo GitHub Issues, Linear ou Jira" e "qualquer interface que ele exponha"), e nunca trate um binário, variável de ambiente ou conector ausente como prova de que a capacidade está indisponível. ## Comparar o conteúdo, não a versão, para saber se a sessão tem sua última edição - Depois de editar conteúdo que uma sessão de longa duração carregou na inicialização, presuma que a sessão ainda está rodando a cópia anterior à edição. Caches capturam o estado no momento do carregamento, e edições dentro de um release não mudam o número de versão, então uma versão correspondente só prova que o cache veio deste release, não que ele capturou sua última edição. - Confirme qual cópia está ativa comparando o conteúdo do arquivo carregado com a sua cópia de trabalho, não lendo a string de versão. Idêntico significa que a cópia em execução está atualizada e é confiável; diferente significa que é preciso reiniciar ou usar um caminho de recarregamento antes de confiar em um teste comportamental. - Caminhos de código mecânicos — scripts, parsers, qualquer coisa que a suíte de testes exercite — sempre executam a partir da fonte atual. Somente a camada de instrução e texto carregada na inicialização carrega essa desatualização.