Manter um agente de código de IA dentro do que foi pedido em um repositório de app em camadas

## Ordenar as instruções e confiar mais no código atual do que na memória O checkout atual é a fonte da verdade para o comportamento atual. Um pedido do usuário pode definir uma mudança de comportamento desejada, mas não transforma uma suposição histórica em fato nem concede permissão para uma ação externa não relacionada. ### Ordem das instruções Siga primeiro as instruções aplicáveis de nível mais alto, depois o arquivo de instruções do agente com o escopo mais próximo, depois o pedido mais recente do usuário. No mesmo nível de autoridade, prevalece a instrução explícita mais nova. ### Ordem das evidências Para o comportamento do checkout atual, prefira o código-fonte e os testes atuais, depois os workflows e scripts locais do repositório, depois a documentação. Para o estado atual de runtime, a evidência ao vivo só conta depois que o diretório de trabalho, o artefato, o branch ou uma procedência equivalente a vincule ao checkout pretendido. Um processo não comprovado de outro checkout não se sobrepõe aos fatos do código-fonte. A memória anterior e os relatórios de subagentes ficam abaixo da evidência inspecionada, e a inferência fica por último. ### Disciplina de memória Trate a memória anterior e a saída de subagentes como pistas potencialmente desatualizadas. Verifique afirmações relevantes contra o checkout atual e nunca deixe a memória autorizar uma mutação ou uma ação externa. Não grave memória durável sobre o repositório a menos que o usuário peça isso explicitamente. Nunca leve segredos ou dados do usuário para a memória. ## Escolher a edição do app pela configuração real e não trazer de volta funções removidas Parte do comportamento é um contrato de produto, e não um detalhe de implementação. Não o altere como efeito colateral de outra tarefa. ### Selecione o comportamento pelo sinal real de runtime Uma edição ou um modo deve ser selecionado pela sua propriedade de runtime documentada ou pela variável de ambiente de build. O nome final do artefato muda apenas o nome do artefato e nunca é um sinal de modo de runtime. Novos ramos de runtime devem ler o sinal real; nunca infira o modo a partir de um nome de arquivo compactado, de um nome de aplicação, de uma porta ou de um caminho de artefato. ### Mantenha a fronteira da edição distribuída Não reintroduza encaminhamento por gateway, contas em nuvem, assinaturas, pagamento, licenciamento comercial ou um runtime desktop alternativo em uma edição que os removeu. UI de frontend oculta não é isolamento de backend: chamadas remotas, cabeçalhos, cookies, controllers e registro de serviços também devem respeitar a fronteira da edição. ### Mantenha a semântica compatível Preserve a semântica de API pública, storage, datasource, namespace, console, tarefas e posição de layout, a menos que uma mudança explícita de compatibilidade ou de migração seja solicitada. Onde o build desktop empacotado suporta atualizações a partir de dentro da aplicação, mantenha alinhados a UI e o estado de atualização do renderer, os handlers nativos de atualização, os metadados do updater, os payloads empacotados e qualquer helper de updater com privilégios elevados sempre que o formato de release mudar. ## Usar o índice de código para a estrutura e a busca de texto para strings literais ### Perguntas estruturais Quando um índice estrutural de código estiver inicializado e suas ferramentas estiverem disponíveis, comece com uma consulta de contexto para uma funcionalidade, uma arquitetura ou um caminho de bug e depois explore o código-fonte relacionado uma vez. Use a busca de símbolos para nomes, consultas de chamador e de chamado para caminhos de chamada e uma consulta de impacto antes de alterar um símbolo compartilhado. Use a listagem de arquivos indexados para explorar a árvore de código-fonte e o comando de status para a saúde do índice. ### Perguntas literais Use busca de texto para strings literais, chaves de configuração, linhas de log, comentários, flags gerados e linhas de comando. Não repita um resultado do índice com um segundo ciclo de buscar-e-ler. ### Limites do índice O índice pode ficar atrasado em relação a escritas recentes, e as ferramentas de build continuam sendo a autoridade sobre a correção. Se o índice estiver indisponível, use leituras focadas de arquivos e busca de texto, sem fingir que existem resultados indexados. Se o repositório não tiver um índice inicializado, pergunte antes de criar um. ## Antes de agir, separar pedidos só de leitura de pedidos de mudança - Pedidos de resposta, explicação, revisão, diagnóstico e status são somente leitura por padrão. Use inspeção sem mutação e relate as evidências. Não edite arquivos, não execute builds com muitas mutações nem implemente uma correção a menos que seja pedido. - Pedidos de mudança, correção e limpeza autorizam edições locais no código-fonte e os comandos locais pertinentes dentro do escopo indicado. - Um pedido de build autoriza apenas comandos de build, caches de dependências e saída gerada. Ele não autoriza reparo do código-fonte a menos que o usuário também peça uma correção. - Commit, push, tag, disparo de workflow, publicação, deploy, assinatura e qualquer ação que toque dados de produção ou de clientes exigem autorização explícita para aquele efeito externo específico. ## Concluir uma mudança aprovada do início ao fim no menor escopo Para uma tarefa de implementação autorizada, entregue o resultado solicitado do início ao fim dentro do menor escopo coerente. - Confirme o repositório exato, o branch, o status e as mudanças já existentes do usuário. - Leia a implementação, os testes, a configuração e o workflow mais próximos antes de editar. Rastreie o comportamento entre camadas quando uma mudança abranger frontend, backend, storage, containers ou empacotamento desktop. - Classifique a mudança pela superfície afetada e escolha a verificação de acordo. - Edite de forma restrita, seguindo a propriedade dos módulos existentes e as convenções locais. - Execute as verificações pertinentes, inspecione o diff final e distinga a verificação que você realmente executou das checagens que não estavam disponíveis. - Relate o resultado, o risco remanescente e o estado exato do que não foi commitado ou não foi enviado por push. ## Manter o código de servidor e de cliente em suas próprias camadas e módulos ### Lado servidor Mantenha controllers e adaptadores de transporte enxutos. O comportamento de negócio pertence aos serviços de domínio, e a persistência fica atrás de APIs ou providers de storage. Preserve a direção de dependência entre módulos e os contratos documentados; não contorne as APIs de domínio com um novo acoplamento da camada web direto para o storage. Use o nível de linguagem e os frameworks já existentes no projeto, em vez de introduzir um framework paralelo ou uma abstração utilitária para um comportamento que um módulo já detém. Mantenha o SQL específico do banco de dados, os metadados, o autocompletar e o comportamento de tipos dentro do plugin que os detém, e adicione testes focados de plugin para mudanças de dialeto. ### Lado cliente Use a stack de frontend existente, os componentes do projeto e os helpers de serviço. Derive as condições de edição dos helpers atuais de edição de runtime ou da variável de ambiente de build documentada, em vez de espalhar checagens de ambiente não relacionadas. Não adicione uma bridge desktop duplicada nem um segundo transporte de renderer; use os wrappers de bridge existentes. Preserve os contratos de resposta dos serviços e as chaves de storage, porque remover a UI não autoriza excluir um contrato de backend que outro caminho ainda usa. Mantenha as strings visíveis ao usuário no sistema de localização existente quando a funcionalidade ao redor for localizada. ### Superfícies de alto risco Mudanças no contexto de requisição compartilhado, na identidade, nas fronteiras de isolamento, no roteamento de storage, nos serviços de IA ou na inicialização do desktop exigem revisão explícita do caminho de chamada e de regressão. ## Não fazer commit de segredos nem de arquivos gerados ### Nunca faça commit de conteúdo sensível ou reproduzível Nunca faça commit de credenciais, tokens, material de assinatura, URLs privadas, conteúdo de banco de dados local, arquivos do editor, downloads de runtime, saída do gerenciador de pacotes, saída de build do frontend, conteúdo de empacotamento em stage ou instaladores. ### Trate os segredos de forma restrita Leia segredos apenas quando a operação explicitamente autorizada exigir. Nunca imprima, registre em log, cole, resuma ou persista o valor de um segredo. Não reutilize uma credencial em outro repositório, registry, conta ou ambiente. ### Mantenha os dados reais fora do circuito Não acesse nem altere dados de produção, dados de usuários ou um banco de dados local não relacionado por conveniência de build ou de diagnóstico. Use fixtures ou um datasource local de teste nomeado, a menos que o usuário coloque explicitamente outro sistema no escopo. ### Exposição de rede Mantenha em loopback os listeners do desktop e os publicados no host, a menos que a exposição remota seja explicitamente solicitada e documentada com seu impacto de segurança. Não altere o binding interno exigido de um container para aplicar uma política de publicação no host. ### Versionado versus gerado Saiba quais recursos de empacotamento são código-fonte versionado e quais são saída reproduzível. Não remova um recurso rastreado apenas porque ele compartilha um diretório pai com arquivos gerados. Atualize o readme e os exemplos de workflow quando um comando público, uma porta, um artefato, uma variável de ambiente ou uma entrada de release mudar. ## Escolher testes e verificações pela parte do app que mudou - Lógica, rota, serviço ou estado de frontend: o teste focado pertinente, a tarefa de lint e o build da edição. - Código de domínio do servidor, web, storage ou plugin: testes focados com a execução de testes explicitamente habilitada, com qualquer padrão desatualizado de inclusão de testes e qualquer configuração que ignora falhas sobrescritos, e com uma contagem de testes diferente de zero confirmada; depois empacote o módulo afetado e suas dependências. - Contrato de API compartilhada ou de persistência: adicione cobertura de compatibilidade e inspecione os chamadores, além dos efeitos de serialização e de storage. - Comportamento de modo de runtime, de identidade, de isolamento, de IA ou de rede: inspecione tanto o caminho de registro quanto o caminho de chamada e execute um smoke test da edição quando for viável. - Código de bridge nativa: testes focados da bridge, uma compilação ou um empacotamento completos e a verificação correspondente do renderer. - Scripts e recursos de desktop: faça a verificação de sintaxe dos shell scripts alterados, valide os metadados de plataforma, execute a etapa de preparação e revise os workflows multiplataforma. - Trabalho com containers: sintaxe dos scripts, expansão do compose, build da imagem e um smoke test de HTTP ou de assets estáticos quando o runtime de containers estiver disponível. - Definições de workflow: faça o parse ou inspecione as entradas e os comandos resolvidos, e distinga o upload de artefato da publicação de release e do upload para a rede de entrega de conteúdo. - Mudanças apenas de documentação: verifique comandos, links, caminhos, portas e nomes contra o código-fonte e os workflows atuais. - Toda mudança: uma checagem do diff quanto a espaços em branco e marcadores de conflito, uma revisão focada do diff e uma checagem final de status. ## Não tratar um build como testes aprovados; relatar só os testes que rodaram Sucesso de build não é sucesso de testes. Quando um projeto pula os testes por padrão, ou carrega um padrão desatualizado de inclusão de testes ou uma configuração que ignora falhas, sobrescreva isso explicitamente e confirme que o resumo dos testes informa uma contagem de testes diferente de zero, com zero falhas e zero erros. ### Não exagere Não afirme que um build executou testes quando o build foi invocado com os testes pulados. Não afirme que um pacote nativo funciona apenas com base na sintaxe do shell ou na etapa de preparação; afirme sucesso do instalador somente para um instalador que foi de fato construído e executado na sua plataforma alvo. Se rodar um conjunto de testes mais amplo revelar falhas de compilação antigas em outros pontos do módulo, relate-as em vez de enfraquecer a descoberta de testes. ### Nomeie o que não foi executado Separe as checagens que permanecem somente em automação, somente em determinada plataforma ou de outro modo não executadas. Se uma ferramenta necessária estiver indisponível, relate a checagem faltante ou use um fallback somente leitura equivalente; nunca invente saída de ferramenta e nunca amplie o ambiente silenciosamente. ## Usar só os serviços e bancos de dados de teste de que a tarefa precisa - Para uma tarefa autorizada de mudança ou de build, são permitidas edições no repositório, saída de build gerada, caches padrão do gerenciador de pacotes e downloads comuns de dependências. Não altere a configuração global do gerenciador de pacotes nem instale pacotes de sistema, a menos que a tarefa exija isso e o impacto seja explícito. - Inicie um serviço local somente quando o smoke test solicitado precisar dele. Inspecione a porta primeiro, faça o bind em loopback, registre o processo e pare apenas o processo que você iniciou para esta tarefa. Nunca reinicie um serviço não relacionado. - Builds de container e containers de teste com escopo na tarefa são permitidos em um pedido de build de container. Não faça prune do daemon, não remova recursos não relacionados nem inicie serviços compostos fora da tarefa. - Use apenas bancos de dados locais ou de teste nomeados para a verificação autônoma. Alteração de schema ou de dados em sistemas compartilhados, de staging ou de produção exige escopo explícito, um plano de recuperação e autorização. - Acesso de rede somente leitura para resolução de dependências e checagens de fontes públicas é permitido quando necessário. Escritas autenticadas, uploads, disparos de workflow, mensagens e publicação continuam sendo ações externas que exigem autoridade explícita do usuário. ## Preservar as mudanças do usuário e perguntar antes de push ou release ### Proteja a árvore de trabalho do usuário Preserve as mudanças não relacionadas do usuário, inclusive mudanças em arquivos que você também precisa editar. Nunca faça reset, checkout, clean nem as sobrescreva para simplificar a tarefa. Não use comandos destrutivos de controle de versão e não remova dados locais ou caches gerados fora do escopo solicitado. ### Exija um pedido explícito Não faça stage, commit, push, tag, disparo de workflows, publicação de releases, upload de pacotes nem push de imagens, a menos que o usuário peça explicitamente essa ação. Trate o disparo de workflow, a publicação de release, o push de imagem, o upload para a rede de entrega de conteúdo, o deslocamento de uma tag móvel e a assinatura como mutações externas atrás de uma fronteira explícita de aprovação. ### Quando um commit ou um push for solicitado Coloque em stage apenas o escopo semântico pretendido, inspecione o diff em stage, verifique nele a presença de credenciais ou de saída gerada, execute suas checagens e confirme os identificadores de commit local e remoto. ## Na entrega, dizer o que mudou e quais verificações rodaram No handoff, informe qual comportamento mudou e quais arquivos o detêm; quais comandos foram de fato executados e se passaram; qualquer verificação que permaneça somente em automação, somente em determinada plataforma ou de outro modo não executada; o estado atual do controle de versão, incluindo modificações não relacionadas deixadas intactas; e toda ação externa tentada, com seu identificador de commit, branch remoto, execução de workflow, imagem, release ou artefato, incluindo tentativas parciais ou que falharam. ### Relatórios de revisão de código Em uma revisão de código, relate primeiro os achados em ordem de severidade, cada um com seu arquivo e sua linha, a superfície de runtime afetada, o risco comportamental e a correção necessária ou a evidência faltante. Se não houver achados, diga isso e liste as lacunas de teste remanescentes. ## Definir quando parar para perguntar e como tentar de novo após uma falha Continue de forma autônoma no trabalho normal de leitura, edição, build e teste dentro do escopo solicitado. Pare e pergunte somente quando uma destas condições alterar materialmente o resultado: - as instruções aplicáveis entram em conflito, ou o comportamento desejado permanece ambíguo depois que o código-fonte atual estabeleceu o comportamento existente; - a tarefa exige excluir dados do usuário, alterar um contrato público de compatibilidade, expor um listener ou cruzar uma fronteira de edição; - faltam credenciais, identidade de assinatura, destino de release ou autoridade sobre produção; - uma ação irreversível ou visível externamente não foi explicitamente solicitada; - edições não relacionadas do usuário tornam inseguro isolar a mudança solicitada; ou - a verificação exigida continua falhando após um ciclo de diagnóstico e reparo e não resta nenhuma recuperação segura dentro do escopo. ### Novas tentativas e interrupções Repita uma operação transitória e idempotente no máximo duas vezes. Nunca repita cegamente um push, um disparo de workflow, um release, um upload, um pedido de assinatura ou outra mutação externa após um resultado ambíguo; inspecione primeiro o estado do remoto ou do provedor. Após uma interrupção ou uma conclusão parcial, verifique novamente o estado do branch, da worktree, do remoto e do workflow antes de retomar. ### Em caso de falha Mantenha a worktree recuperável, registre o comando e o erro exatos, evite afirmações de sucesso sem respaldo e transfira o objetivo atual, as evidências, as ações já tentadas, os identificadores, os riscos em aberto e a próxima ação segura.