DotMDComo rever uma especificação escrita por IA:uma lista antes de o agente construir.
Um agente de IA escreve em um minuto uma especificação segura e arrumada. É esse o perigo: lê-se bem mesmo quando está errada. Esta lista mostra o que procurar antes de dizer ao agente para começar a construir.
macOS 14 ou posterior. Ler é grátis; editar e rever são um pagamento único.
Resposta rápida
Reveja uma especificação escrita por IA como reveria uma pull request: verifique se resolve o problema certo e depois procure o que falta. Passe por âmbito e não-objetivos, casos-limite, dados e migrações, testes e reversão, e deixe um comentário em cada passagem que queira alterar antes de o agente escrever código.
- [ ] Scope matches what I asked for
- [ ] Non-goals are listed
- [ ] Edge cases and errors are covered
- [ ] Data and migrations are explicit
- [ ] Tests prove each requirement
- [ ] There is a rollback·
Porque é que as especificações de IA pedem outro tipo de revisão
Uma pessoa que redige uma especificação tende a deixar lacunas onde tem dúvidas. Um modelo escreve texto fluente sobre tudo, incluindo as partes que adivinhou. Assim, os sinais habituais de uma especificação fraca, redação vaga e buracos óbvios, não aparecem, e os problemas ficam escondidos em frases seguras. Reveja procurando as coisas sobre as quais um bom autor teria perguntado.
A lista de verificação
-
Âmbito: resolve o que pediu?
Compare o primeiro parágrafo com o seu pedido. Procure um problema diferente resolvido em vez do seu e funcionalidades que ninguém pediu.
-
Não-objetivos: o que não vai fazer?
Uma especificação sem não-objetivos não tem limites. Junte os extras que não quer.
-
Pressupostos: o que adivinhou?
Procure "presumivelmente", "provavelmente" e tudo o que seja afirmado como facto sobre código ou dados que possa não ter lido. Peça-lhe que cite os ficheiros.
-
Casos-limite: o que acontece quando algo corre mal?
Entrada vazia, entrada muito grande, sem permissão, sem rede, dois utilizadores ao mesmo tempo, a mesma ação duas vezes.
-
Dados: o que é guardado, alterado ou apagado?
Campos, formatos, quem os pode ler e o que acontece aos registos existentes.
-
Migrações: como passam os dados antigos?
Uma alteração de esquema precisa de uma ordem de passos, de um plano para uma falha a meio e de uma forma de a executar duas vezes em segurança.
-
Interfaces: que mais é afetado?
APIs, ecrãs, tarefas, código de outras equipas. Tudo o que a especificação altera mas não lista será uma surpresa mais tarde.
-
Segurança e privacidade: quem pode fazer o quê?
Novas permissões, novos dados a sair do sistema, segredos nos registos.
-
Testes: como vai saber que funciona?
Cada requisito deve corresponder a uma verificação. Se um requisito não pode ser testado, reescreva-o.
-
Lançamento e reversão: como se desfaz?
Uma flag, um lançamento faseado, uma forma de voltar atrás. "Corrigimos para a frente" não é um plano.
-
Questões em aberto: quem as decide?
Uma especificação honesta lista o que não sabe. Se não houver nenhuma, desconfie.
Um comentário que funciona
Um comentário vago recebe uma reescrita vaga. Um bom comentário de revisão aponta para uma só passagem, diz o que está errado e o que quer em vez disso:
> The export runs when the user taps Export.
Missing: what happens with a 2 GB file? Add a limit (R4) and an
error message, and say whether the export can be cancelled.Mantenha os comentários separados do texto da especificação para o ficheiro ficar limpo, e agrupe-os: leia a especificação toda uma vez e depois comente, para o agente reescrever uma vez e não dez.
O ciclo de revisão
-
Leia-a primeiro de ponta a ponta
Antes de comentar, certifique-se de que percebeu todo o plano.
-
Comente as passagens exatas
Um problema por comentário.
-
Deixe o agente rever
Ele corrige cada comentário e produz uma nova versão.
-
Verifique o que mudou, não o documento inteiro
Leia as diferenças. Uma correção pode estragar algo que estava bem.
-
Aprove só quando a lista estiver limpa
Depois deixe-o construir, de acordo com os requisitos numerados.
A mesma lista serve quando um agente revê a especificação de outro. Peça ao revisor que responda a cada item com uma citação da especificação.
Fazê-lo no DotMD
Pode fazer tudo isto na própria página. No DotMD seleciona a passagem e escreve um comentário sobre ela; os comentários ficam no DotMD, não no ficheiro. O agente corrige-os e envia o documento de novo, e rever as alterações mostra o texto antigo a vermelho e o novo a verde para as poder aceitar uma a uma. A configuração está descrita em rever especificações de IA. A leitura é gratuita; veja os preços das revisões.
Erros comuns
- Rever o estilo, e não a substância. Uma especificação arrumada também pode estar errada.
- Aprovar porque é longa. Extensão não é cobertura.
- Saltar os não-objetivos e a reversão, as duas secções que os modelos mais vezes deixam pobres.
- Corrigir o código em vez da especificação. Se o plano está errado, corrija-o primeiro.
- Sem segunda leitura. Depois de o agente rever, verifique o diff.
Perguntas sobre rever especificações escritas por IA
Como reviso uma especificação escrita por IA?
Verifique se resolve o problema certo e depois procure o que falta: não-objetivos, casos-limite, dados e migrações, testes e reversão. Comente cada passagem e peça ao agente que reveja antes de escrever código.
O que deve incluir uma lista de verificação para rever especificações?
Âmbito, não-objetivos, pressupostos, casos-limite, dados, migrações, interfaces, segurança, testes, lançamento e reversão, e questões em aberto.
Um agente de IA pode rever a especificação de outro agente?
Sim. Dê ao revisor a lista e peça-lhe que responda a cada item com uma citação da especificação. É sempre você a decidir o que aceitar.
Porque não ler simplesmente o código?
Nessa altura as decisões já foram tomadas e é caro mudá-las. Um pressuposto errado é mais barato de corrigir na especificação.