derive-instead-of-transcribing
Tudo o que é copiado à mão de outro arquivo está correto exatamente uma vez. Se dá para gerar, gere — e quebre o build quando a cópia envelhecer.
Conferida por quem revisou e leu o cartão, não reivindicada pelo próprio arquivo. Um cartão que o agente destila durante uma execução que consumiu conteúdo não confiável nasce contaminado e fica retido para revisão antes de alguma vez ser recuperado.
Quando ele vem à mente
- documentando uma lista de comandos
- copiando valores entre projetos
- mantendo dois arquivos em sincronia
- escrevendo uma página de referência
Evite e Verifique são onde costuma estar o valor. Faça é a seção que todo mundo escreve.
O corpo do cartão acima é uma tradução. O original em inglês é o que a CLI importa, o que o agente lê em execução e o que o hash abaixo atesta.
Gatilho
Dois lugares no seu sistema guardam a mesma informação: uma config e sua documentação, um schema e os tipos do cliente, uma paleta e o site que a usa, uma lista de comandos e uma página de referência.
Não se aplica quando a segunda cópia é deliberadamente diferente — um guia de primeiros passos com curadoria não é uma cópia desatualizada da referência, é prosa com um trabalho diferente.
Faça
- Escolha qual dos dois é a fonte. Normalmente é aquele que o programa de fato lê em tempo de execução.
- Gere o outro, fazendo commit do arquivo gerado para que os diffs sejam revisáveis.
- Adicione um passo de CI que regenera e falha se a cópia commitada divergir, com o comando exato a rodar na mensagem de erro.
- Carimbe o arquivo gerado com a versão ou o commit a partir do qual foi gerado, para que quem lê saiba o que ele descreve.
Evite
Manter a cópia sincronizada de memória. Isso funciona enquanto uma única pessoa carrega os dois arquivos na cabeça, e para de funcionar na primeira semana em que outra pessoa mexer em um deles.
Evite também a versão pela metade: gerar o arquivo mas não colocar um gate nele. Um artefato que é às vezes regenerado é pior que um escrito à mão, porque carrega a autoridade de ser gerado ao mesmo tempo em que fica igualmente desatualizado.
E evite gerar prosa. Material de referência se gera bem; explicação não, e uma página de descrições de campo expandidas mecanicamente é uma página que ninguém lê.
Verifique
Mude a fonte, não regenere, e faça push. O CI precisa ficar vermelho e dizer o que rodar.
Depois leia o arquivo gerado procurando a coisa que você mudou e confirme que ela está lá — o gate prova que o arquivo está atualizado, não que o gerador capturou o campo que importa para você.
Risco
Um artefato gerado que ninguém consegue ler frustra o propósito; se a saída só faz sentido para uma máquina, ela precisa de uma camada de renderização, que é mais código para manter.
Também há um custo de acoplamento. O consumidor agora depende do formato do produtor, e um refactor de um lado quebra o build do outro. Esse costuma ser o objetivo — mas significa que o gate precisa ser fácil de satisfazer, ou alguém vai desativá-lo durante um refactor sem relação e vai esquecer de reativá-lo.
Como usar
O cartão é dado. Clone o repositório e importe pelo caminho — o que chega pela rede é tratado como contaminado e fica retido para aprovação, que é o comportamento desejável e a razão de não haver um instalador de uma linha aqui.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/derive-instead-of-transcribing/SKILL.mdIntegridade
SHA-256 do arquivo como publicado. Quem importa pode conferir que o que recebeu é o que esta página mostrou.
8b9a25705790b36bd8b04294161cac342e63b667c0e6a6e36240d981687f35f9