chimera-write-the-check-before-the-code
Um critério escrito depois da implementação descreve a implementação. Escreva a checagem que falha primeiro, veja-a falhar, e só então construa.
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
- prestes a implementar uma feature
- definindo o que é pronto
- escrevendo o teste depois do código
- tarefa sem critério de aceite
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 implementar algo cujo "pronto" ainda não é observável — uma feature, uma correção de bug, um refactor que afirma preservar comportamento. Morde mais forte quando o autor e o único revisor são o mesmo processo: um agente trabalhando sozinho, ou um commit solitário que ninguém mais vai ler.
Não se aplica a um spike. Exploração cujo propósito é descobrir o que sequer é possível ainda não tem critério de aceitação, e inventar um logo de cara só te ancora na primeira ideia. Escreva a checagem quando o spike terminar e o trabalho de verdade começar.
Este card é sobre a checagem que ainda não existe. O irmão dele,
chimera-prove-the-test-discriminates, é sobre uma checagem que já existe e pode estar vazia — você
recorre àquele depois de uma correção, para mostrar que o teste falha sem ela. Mesmo instinto, pontas
opostas do trabalho.
Faça
- Antes de tocar na implementação, escreva o critério como algo que pode falhar: um teste, uma asserção, um comando cujo código de saída se inverte, uma consulta com uma linha esperada. Prosa não é checagem — "o endpoint deveria ficar mais rápido" não é; "p95 abaixo de 200 ms no conjunto de fixtures, medido pelo comando de bench existente" é.
- Diga de onde vem a observação. Da máquina, não da sua leitura do diff.
- Rode a checagem agora, contra o código sem modificações. Ela precisa falhar. Se passar, ou o comportamento já existe — e nesse caso pare, não há nada a construir — ou a checagem não testa o que você pensa.
- Leia a mensagem de falha. Ela precisa falhar pelo motivo pretendido, não por um erro de import, uma fixture ausente, ou um erro de digitação no nome do teste. Um vermelho vindo da causa errada é um verde disfarçado.
- Entregue a checagem antes da implementação, no seu próprio commit. Depois que a implementação existe, a checagem fica editável para se ajustar a ela, e ela será ajustada.
- Implemente. Pronto é quando a checagem passa — não quando o código parece terminado.
Evite
Escrever a asserção depois, a partir da saída:
normalize(" Foo ") # -> "foo"
# test transcribed from that observation
assert normalize(" Foo ") == "foo"
Essa asserção não tem como falhar contra o código do qual foi copiada. Ela registra comportamento em
vez de requisito, então continua verde através de todo bug sobre o qual a implementação for
internamente consistente. Se o requisito era normalização NFKC e você entregou strip().lower(),
este teste concorda com você para sempre.
Evite também o critério que é uma reformulação da mudança — "pronto quando a função for adicionada", "pronto quando a migration rodar". Ambos são satisfeitos por um corpo vazio.
Verifique
Duas perguntas binárias, ambas respondíveis a partir do repositório:
- Você viu a checagem falhar antes de a implementação existir? Se não há um momento em que ela esteve vermelha, você não tem evidência de que ela consegue ficar vermelha.
- A checagem continuaria correta se a feature tivesse sido construída de um jeito completamente diferente? Uma checagem que nomeia detalhes internos — uma chamada privada, uma linha de log, uma string SQL exata — está presa à sua solução em vez de ao requisito, e vai travar o próximo refactor sem pegar nada.
Concretamente: o git log mostra a checagem entrando junto ou antes da implementação, e reverter
apenas o commit da implementação deixa a suíte vermelha.
Risco
Um requisito que você ainda não entende não pode ser preso por uma checagem escrita primeiro. Você vai escrever uma asserção precisa sobre a coisa errada e então implementar de acordo com ela — pior do que não ter checagem nenhuma, porque isso lava um mal-entendido e o transforma numa suíte verde em que um revisor vai confiar. Quando o critério é genuinamente desconhecido, isso é sinal de ir perguntar, uma pergunta por vez, não de chutar em forma de teste.
Há também um custo simples. Para a correção de um erro de digitação ou uma edição de documentação, escrever a checagem primeiro é cerimônia sem ninguém para pagá-la. O card se paga quando o comportamento é importante o bastante para que alguém se machuque com um "pronto" errado.
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-write-the-check-before-the-code/SKILL.mdIntegridade
SHA-256 do arquivo como publicado. Quem importa pode conferir que o que recebeu é o que esta página mostrou.
95d0a1b750e25af7651e85d26106a91f02f563ab1a1422edc4133d16942b67d7