Mantenha documentos de habilidades de IA em um só lugar e escreva-os para a IA consultar

## Edite apenas o arquivo-fonte e regenere as cópias com o gerador Identifique o documento canônico da habilidade e trate integrações geradas, manifestos e projeções específicas de plataforma como artefatos derivados. Edite a fonte e suas referências e, em seguida, regenere os derivados com o gerador do repositório. Nunca edite manualmente saídas controladas pela integração contínua. Mantenha nela um modo de verificação que regenere na memória ou em uma área temporária e falhe quando os derivados confirmados no repositório divergirem da fonte. Quando a mesma habilidade for distribuída por várias plataformas, compartilhe o conteúdo em vez de manter bifurcações. Registre qual arquivo é responsável pelo conteúdo, pelos metadados e pelos valores de versão para que os colaboradores não criem fontes concorrentes. Mantenha a instalação e o uso pelo usuário final fora das instruções para colaboradores. A documentação para colaboradores deve explicar manutenção, validação, testes e comportamento dos lançamentos sem duplicar o guia do produto. ## Deixe as decisões no documento principal e os detalhes em arquivos de referência Use o documento principal da habilidade como ponto de entrada da recuperação e carregue referências detalhadas somente quando necessário. Distribua o conteúdo assim: - estruturas de decisão e padrões frequentes no documento de entrada; - guias detalhados, modelos e exemplos ampliados nos arquivos de referência; - cenários de referência e registros de justificativa na documentação de testes; - instalação e uso na documentação voltada ao usuário; - detalhes do processo de colaboração no guia de contribuição. Use links relativos estáveis entre o documento de entrada e as referências adjacentes. Preserve as âncoras de referência de nível superior usadas pelas tabelas de roteamento, mesmo ao reestruturar subseções de níveis inferiores. Aplique um teste de posicionamento: se um item determinar qual caminho escolher, mantenha-o próximo ao ponto de entrada; se explicar em profundidade como executar um caminho já escolhido, mova-o para uma referência. ## Escreva instruções curtas e diretas, com as tabelas de decisão primeiro Otimize o conteúdo para um agente que classifica a intenção, seleciona uma ramificação e executa, não para um leitor que percorre o guia do início ao fim. Quando várias abordagens forem válidas, coloque uma tabela de decisão compacta antes do procedimento operacional. Organize cada seção assim: 1. tabela de decisão; 2. procedimento padrão; 3. alternativas; 4. regras concisas e armadilhas. Use o modo imperativo e expresse um único fato por item. Converta estruturas de aconselhamento como “você deve considerar”, “observe que” ou “tenha em mente” em ações diretas. Para distinções pouco óbvias, prefira regras afirmativas e negativas breves. Cada tabela, exemplo e bloco de código deve acrescentar um fato ainda não declarado. Quando o procedimento já transmitir a instrução, remova diferenças de antes e depois, justificativas repetidas, apartes didáticos e exemplos incluídos apenas para dar aparência de completude. Limite a justificativa a uma única frase de abertura. Defina um objetivo de tokens para cada subseção e divida ou compacte as que o excederem sem remover critérios de decisão, ações obrigatórias, restrições ou exceções. ## Verifique a estrutura do documento e teste o comportamento da IA após mudanças Adapte a validação ao artefato. Habilidades voltadas à documentação podem não precisar de compilação, mas ainda exigem verificações estruturais automatizadas e testes manuais de comportamento. Automatize verificações dos campos de frontmatter obrigatórios, regras de nomenclatura, limites de linhas ou tokens, links internos, sincronização de artefatos gerados e regras de lint específicas do repositório. Trate metas flexíveis de tamanho como avisos e restrições rígidas de integridade como falhas. Para uma alteração de conteúdo: 1. edite a habilidade canônica ou uma referência; 2. execute a validação estrutural local; 3. recarregue a habilidade no ambiente anfitrião; 4. execute consultas realistas de usuários que percorram a ramificação alterada; 5. compare o comportamento com os cenários de referência para identificar regressões. Exija no pull request evidências de antes e depois para os cenários afetados. Para alterações substanciais na arquitetura da informação, obtenha uma revisão independente focada na estrutura de recuperação, na compactação e nas ramificações de decisão ausentes. ## Exija verificações nos pull requests e deixe a versão para o lançamento automático Proteja a ramificação principal: exija pull requests, verificações de validação e um título convencional válido. Se as alterações forem integradas por merge com squash e o título do pull request se tornar o commit de lançamento, valide esse título, pois ele determina o versionamento. Associe tipos convencionais de alteração a incrementos de versão, incluindo um sinal explícito de alteração principal. Faça com que o fluxo de lançamento atualize o histórico de alterações, os metadados da versão canônica, os manifestos de plataforma e os artefatos gerados em uma única alteração de lançamento. Nunca edite manualmente números de versão sincronizados. Mantenha uma única fonte canônica para a versão e deixe que a esteira de lançamento a propague antes de criar a tag. Antes de integrar, confirme: - as saídas geradas correspondem à fonte canônica; - as tabelas de decisão vêm antes dos procedimentos com ramificações; - estruturas introdutórias e exemplos redundantes foram removidos; - as âncoras usadas para roteamento permanecem estáveis; - os cenários de referência alterados incluem evidências; - as verificações obrigatórias de validação e de título foram aprovadas.