Como digo a um agente de IA o que significa «concluído»?

Escreva o que «concluído» significa na própria tarefa, como lista markdown, antes de o agente começar. No Done é o campo acceptance_criteria da tarefa: uma linha por condição verificável, escrita como «- [ ] os testes passam na ponta do branch». O agente lê-a primeiro, marca cada linha com check_criterion à medida que a cumpre de facto e depois pede a conclusão. Marcar todas as caixas não fecha a tarefa: continua a aprovar uma pessoa.

Por que uma boa descrição da tarefa não chega?

Uma descrição diz ao agente o que fazer. Não diz como é um resultado terminado, por isso é o agente que o decide, e um agente deixado a decidir costuma parar na primeira saída plausível. Os critérios de aceitação são a outra metade: a meta verificável contra a qual o resultado é julgado, não mais instruções. As descrições das ferramentas do Done traçam essa linha e pedem ao agente que confira o trabalho com essa meta antes de propor a conclusão.

Como é um critério que um agente consegue usar?

• Verificável por outra pessoa: «os testes passam na ponta do branch», «a página carrega em menos de 200 ms», «o resumo lista todas as faturas em atraso». «Parece bom» não é uma condição.
• Uma linha por condição, para que cada uma possa ser marcada à parte e uma tarefa a meio se leia como 2/4 e não como nada.
• Escreva como lista de tarefas markdown, com linhas que começam por «- [ ] ». Uma lista com marcadores simples ou um parágrafo fica guardada, mas para o Done é prosa: a tarefa não reporta critérios e o agente não tem nada para marcar.
• Ponha o como em notes_for_agent ou na descrição e deixe nos critérios só o quê. Misturar os dois faz a meta mudar com as instruções.

Como é que o agente reporta o progresso face aos critérios?

Chama get_task, que devolve os critérios com met, total e o índice (a partir de zero) de cada item, e depois check_criterion com o id da tarefa e esse índice, à medida que cumpre cada linha. Com done:false desmarca-se uma, e marcar uma caixa já marcada não altera nada. Cada mudança real deixa uma linha no histórico da tarefa, como «met 'tests pass' (2/4 criteria met)», de modo que vê como o trabalho avançou sem comentários contínuos no fio. Só se pode marcar em tarefas da faixa do próprio agente.

Marcar todos os critérios conclui a tarefa?

Não, e é de propósito. check_criterion é um relatório de progresso; a resposta só avisa o agente de que todos os critérios estão cumpridos e de que pode propor a conclusão. Fechar é outro ato. Uma tarefa que não é agent_ok passa a pending_approval com propose_completion e espera por si; só numa tarefa agent_ok o agente pode chamar complete_task por conta própria. A lista torna a afirmação do agente mais fácil de verificar, e a porta de aprovação impede que essa afirmação seja definitiva.

O agente pode reescrever os seus próprios critérios?

Pode editar o campo com update_task, e é por isso que não deve confiar numa lista toda marcada sem mais. Na tarefa de uma pessoa pode usar propose_edit, que lhe mostra a alteração como diff atual contra proposto, a aceitar ou descartar campo a campo. Na revisão, get_evidence devolve o progresso dos critérios com cada recibo, entregável e rasto de execução, mais o histórico de edições e agent_edits_since_human, o número de edições do agente desde que uma pessoa tocou na tarefa pela última vez. Se não for zero, leia os critérios antes de confiar nas marcas: critérios reescritos depois de o trabalho começar não são a meta combinada.