chimera-ground-it-in-the-source
Pegue a assinatura na versão instalada, não na memória — uma API plausível é indistinguível de uma real até rodar.
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
- chamando uma biblioteca que não escrevi
- como se chama esse parâmetro
- a API mudou entre versões
- escrevendo para um framework de cabeça
- AttributeError num método que deveria existir
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
Você está prestes a escrever uma chamada para a biblioteca, o framework ou a CLI de outra pessoa: um nome de método, um argumento nomeado, uma chave de config, o formato de um valor de retorno, uma flag. Isso vale de forma mais aguda quando a lembrança parece confiante, porque a confiança é produzida do mesmo jeito, exista a API ou não.
Não se aplica aos builtins da própria linguagem que você exercita o tempo todo, e não é uma instrução
para buscar documentação antes de escrever dict.get. A linha divisória é se estar errado seria pego
imediatamente pela próxima coisa que você rodar.
Faça
- Pegue a versão que está de fato instalada, não a que você lembra de ter lido:
uv pip show <pkg>, oupython -c "import pkg; print(pkg.__version__)". - Leia a coisa instalada.
python -c "import inspect, pkg; print(inspect.signature(pkg.fn))", ou abra o arquivo dentro desite-packages, ou rode--helpno binário que está no PATH. Esta é a autoridade, porque é o código que vai executar. - Quando você usar um post de blog, um README na web, ou a sua própria lembrança, trate isso como hipótese e confirme contra o passo 2. Sites de documentação descrevem a última release; o seu lockfile pode não estar preso nela.
- Exercite a chamada uma vez num trecho descartável e imprima o valor de retorno real antes de
escrever código que indexa a sua suposição sobre ele. Formatos aninhados —
["choices"][0]["message"]— são onde a memória é menos confiável e menos propensa a falhar de forma ruidosa. - Deixe a evidência ao lado do código: a versão, e a assinatura ou a saída de help que você leu. Um comentário ou o corpo do PR bastam, e isso conta ao próximo leitor contra o que o código foi escrito.
Evite
Escrever texto com cara de API. A falha não é um erro de digitação — um erro de digitação levanta exceção na hora e é corrigido em segundos. É um nome que obedece a cada uma das convenções de nomenclatura da biblioteca e não existe:
Um caso real deste repositório, e o formato é o ponto — o chute não era absurdo, era razoável:
from chimera.core.checkpoint import WorkspaceGuard, diff_snapshots # ImportError
# Where it actually is. One grep, before writing the line, would have found it.
from chimera.core.checkpoint import WorkspaceGuard
from chimera.evolution.diff_gate import diff_snapshots
O custo não foi a exceção — um ImportError é barulhento e barato. É que o mesmo chute confiante
sobre um comportamento falha em silêncio, e você só descobre quando o número que ele produziu se
revela errado.
Evite também se ancorar na versão errada. Ler a documentação atual de um pacote preso duas versões major atrás produz código que está correto a respeito de uma biblioteca que você não está rodando — e a mensagem de erro, quando vier, aponta para a sua chamada, não para o descompasso.
E evite aceitar um type checker passando como ancoragem quando o pacote não distribui stubs. Contra
uma dependência sem tipos, Any engole todo atributo que você inventar; a checagem reporta sucesso
porque não tinha nada a checar.
Verifique
Para cada chamada não óbvia no diff, você consegue apontar onde a viu — uma assinatura que imprimiu,
uma linha em site-packages, um --help que rodou? Se a resposta honesta para alguma delas for
"parecia certo", aquela chamada não está verificada, e dizer isso custa uma frase.
A checagem mais forte é executável: rode o trecho do passo 4 contra a versão instalada e cole a saída dele. Um import que resolve e uma chamada que retorna o formato que você esperava são dois fatos diferentes; o segundo é aquele do qual você depende.
Risco
Aplicado a tudo, isso transforma código de rotina em pesquisa e atrasa o trabalho sem ganho nenhum. Gaste isso na chamada desconhecida, na chamada sensível a versão, e no formato de retorno aninhado — não nas cem linhas ao redor delas.
O risco mais sutil é se ancorar literalmente demais. O código-fonte instalado vai alegremente te
mostrar _internal_helper, que existe, funciona hoje, e não é promessa de ninguém. O código-fonte
diz o que está lá; a documentação diz o que é suportado. Quando os dois discordam, prefira a
superfície documentada, e se você conscientemente for além dela, diga isso no comentário em vez de
deixar o próximo leitor supor que aquilo era sancionado.
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/chimera-ground-it-in-the-source/SKILL.mdIntegridade
SHA-256 do arquivo como publicado. Quem importa pode conferir que o que recebeu é o que esta página mostrou.
9a51bb6b117c736dba1de11a166efed09ad200134e153ad553f4701302025398