Atualizar e ampliar instruções de IA feitas de um só original para várias ferramentas de IA

## Descobrir qual parte cuida de algo antes de alterar Trate o repositório como um conjunto de camadas com responsáveis definidos, não como uma coleção dispersa de arquivos. Antes de editar, identifique qual camada é responsável pelo comportamento solicitado: - as instruções-fonte definem operações reutilizáveis voltadas aos usuários; - as referências compartilhadas definem contratos e esquemas transversais; - os scripts auxiliares implementam processos repetíveis; - os adaptadores convertem instruções canônicas em pacotes específicos de cada plataforma; - as distribuições geradas contêm resultados que podem ser recriados; - os hooks aplicam as regras do repositório e dos resultados; - a arquitetura e os manuais operacionais explicam como as camadas interagem; - os arquivos de dependências e de instalação definem o ambiente de execução compatível. Use a camada de fontes canônicas como autoridade. As distribuições geradas comprovam que a compilação funciona, mas não são fontes independentes da verdade. Gere-as novamente pelo fluxo de compilação documentado em vez de editá-las diretamente. Localize o menor arquivo autoritativo que controla o comportamento solicitado e, em seguida, identifique todos os documentos, esquemas, testes e artefatos gerados que dependem dele e precisam permanecer sincronizados. ## Ter um só original e gerar a versão de cada ferramenta com um conversor Mantenha as instruções reutilizáveis em um único formato de origem neutro em relação à plataforma. Deixe que os adaptadores executem o empacotamento e a conversão de sintaxe exigidos por cada ambiente compatível. Um adaptador pode: - copiar uma fonte compatível sem alterações semânticas; - gerar um pacote de recurso nativo para cada operação; - montar um mecanismo compartilhado com vários pontos de entrada; - criar um pacote de plataforma com instruções de entrada e recursos auxiliares; - gerar um despachante e uma tabela de roteamento a partir dos metadados da fonte. Os adaptadores devem preservar o comportamento e as restrições originais. Quando o ambiente de destino usar ferramentas diferentes, converta nomes de ferramentas específicos da plataforma em ações neutras. Gere os metadados de roteamento com base na descrição canônica em vez de manter um segundo catálogo escrito manualmente. Ao adicionar uma operação, edite sua fonte canônica uma única vez. Use uma exclusão explícita de plataforma somente quando a operação não puder funcionar nela. Recompile todos os adaptadores afetados e examine seus resultados para detectar desvios semânticos. ## Marcar cada nota salva com as fontes e o grau de certeza Toda operação que grave artefatos de conhecimento deve seguir o contrato de gravação canônico do repositório. Projete os artefatos para permitir recuperação e raciocínio futuros confiáveis, não apenas para oferecer legibilidade humana imediata. Exija que cada artefato contenha: - um preâmbulo curto que explique sua finalidade a um futuro leitor de IA; - metadados estruturados, como tipo de artefato, data, etiquetas e um sinalizador `AI-first` explícito; - links internos estáveis para pessoas, projetos, ideias e decisões mencionados; - marcadores de atualidade para afirmações que possam ficar desatualizadas; - URLs das fontes preservadas literalmente junto às afirmações externas; - rótulos de confiança que distingam fatos declarados, evidências fortes, evidências moderadas e especulação. Não remova metadados, links, procedência nem sinais de confiança para fazer um artefato parecer mais organizado. Se uma operação introduzir um novo tipo de artefato, amplie o esquema compartilhado antes de produzi-lo. ## Usar regras de escrita que as checagens automáticas possam confirmar Use convenções que os formatadores e hooks possam verificar de forma consistente: - escreva os títulos Markdown com capitalização de frase; - não use emojis decorativos nas fontes de instruções; - use pontuação ASCII em vez de substituições tipográficas, a menos que um símbolo não ASCII tenha significado próprio; - use valores de etiqueta em minúsculas e coloque entre aspas as sequências ambíguas de metadados; - siga a versão da linguagem, o formatador, o limite de comprimento de linha e o gerenciador de dependências configurados; - use assuntos de commit no imperativo e aplique a política de atribuição do repositório. Trate o formatador canônico e os hooks de validação como a autoridade final para o estilo mecânico. Não os ignore nem preserve manualmente uma formatação que eles rejeitem. Mantenha as convenções restritas o suficiente para que possam ser aplicadas automaticamente. Quando uma regra não puder ser verificada de forma mecânica, documente as evidências de revisão necessárias para confirmá-la. ## Ao adicionar uma tarefa nova, atualizar manuais e listas junto Use esta sequência ao adicionar uma nova operação: 1. Crie a fonte canônica de instruções com metadados de roteamento e orientações operacionais completas. 2. Adicione um auxiliar na área de scripts designada somente quando houver necessidade de lógica executável. 3. Faça referência ao contrato de gravação compartilhado em todos os caminhos capazes de criar ou modificar um artefato. 4. Amplie o esquema compartilhado de metadados antes de introduzir um novo tipo de artefato. 5. Atualize o manual operacional, o inventário de recursos, as notas de arquitetura e o catálogo público de comandos. 6. Registre a alteração na seção de mudanças ainda não publicadas. 7. Execute a compilação dos adaptadores e examine os resultados de todas as plataformas afetadas. Não duplique uma operação nas árvores de plataforma geradas. Uma alteração sincronizada atualiza em conjunto a fonte, as referências reguladoras, os testes e a documentação, para que compilações posteriores não possam apagá-la nem contradizê-la. ## Testar separadamente as instruções e o processo que gera as versões Teste separadamente o comportamento da fonte e o processo de geração. Use um espaço de trabalho de teste isolado ou uma cópia de trabalho local vinculada em vez de um repositório de conhecimento ativo. Para validar o comportamento: - execute a operação alterada com dados de teste representativos; - examine os artefatos resultantes; - verifique os metadados, links, procedência, rótulos de confiança e outros campos obrigatórios do contrato de gravação; - confirme que os fatos desconhecidos continuem explicitamente marcados como desconhecidos. Para validar o processo: - execute o conjunto de testes de fumaça do repositório por meio do executor de pacotes configurado; - verifique os locais dos resultados dos adaptadores e o roteamento gerado; - teste as interfaces dos scripts auxiliares e os resultados legíveis por máquina; - atualize a asserção correspondente na mesma alteração quando o layout dos resultados for modificado intencionalmente. Execute primeiro o teste relevante mais restrito e depois o conjunto de testes de fumaça afetado. As verificações manuais de comportamento complementam os testes automatizados; não os substituem. ## Publicar uma nova versão só depois das checagens e com permissão Publique somente quando a integração contínua estiver aprovada e o contrato de gravação orientado a máquinas continuar sendo cumprido. Use uma sequência de publicação controlada: 1. Mova as entradas de mudanças ainda não publicadas para baixo de um título de versão com data. 2. Atualize a versão no arquivo principal do pacote e em todos os arquivos espelhados de manifesto ou citação. 3. Execute verificações de divergência que comparem todas as declarações de versão. 4. Recompile as distribuições geradas e execute os testes afetados. 5. Confirme a função de publicação e a política de branches antes de criar etiquetas ou fazer push. 6. Publique as notas da versão usando a entrada aprovada do histórico de alterações. Proteja as branches padrão compartilhadas. Os colaboradores devem usar o caminho de revisão exigido. Um responsável pela manutenção pode publicar diretamente somente quando a política do repositório conceder explicitamente essa autoridade e as mesmas etapas de verificação tiverem sido aprovadas. ## Não inventar fatos que faltam nem editar à mão os arquivos gerados Nunca enfraqueça o contrato de recuperação do sistema por motivos estéticos. Não retire os preâmbulos nem os metadados obrigatórios, não reescreva artefatos orientados a máquinas apenas para que pareçam mais humanos e não adicione elementos decorativos proibidos pelas convenções das fontes. Não invente taxas, datas, propriedade, relacionamentos nem outros fatos ausentes. Marque valores desconhecidos com `TBD` ou com o marcador explícito equivalente adotado pelo repositório. Nunca edite um resultado gerado quando ele for controlado por um gerador. Não ignore hooks, não publique por uma branch não autorizada e não alegue sucesso com base apenas na inspeção da fonte. Antes de informar a conclusão: - examine toda a diferença pretendida para detectar alterações não relacionadas; - confirme que as fontes canônicas e os resultados gerados estejam de acordo; - execute o formatador, os hooks, os testes e a compilação dos adaptadores pertinentes; - verifique esquemas, manuais, catálogos e entradas do histórico de alterações que devam ser sincronizados; - registre todas as validações manuais e qualquer verificação que não tenha sido executada; - confirme que a ação final de publicação correspondeu à função autorizada. Informe o comportamento alterado, as evidências de verificação, as limitações restantes e qualquer decisão ainda necessária.