TASK_SPEC que dá para verificar

"Faça uma calculadora para dividir a conta do restaurante". Parece um pedido simples, até começarmos a destrinchar os detalhes. A conta é dividida igualmente ou cada pessoa paga pelos próprios pratos? A gorjeta já está incluída? O que mostrar quando o total não puder ser dividido igualmente?

Vamos definir a tarefa junto com o Claude Code: o(a) senhor(a) explica o que precisa e escolhe as soluções, o agente as registra em um arquivo, e o(a) senhor(a) confere o que ficou escrito. Começaremos com um pedido curto e, aos poucos, chegaremos a um TASK_SPEC que sirva de base para o trabalho.

"Faça direito" não é uma tarefa

Imagine: o(a) senhor(a) queria apenas dividir a conta rapidinho, mas o agente acrescentou cadastro e histórico de restaurantes. Para guardar as contas, precisou de um servidor. A ideia era abrir um único arquivo no navegador; agora é preciso descobrir como executar tudo e remover o que não foi pedido. Cada acréscimo parece útil por si só, mas o resultado já está longe do que o(a) senhor(a) tinha em mente.

Ao trabalhar com código, o que ficou implícito pode virar alterações reais nos arquivos. A sequência costuma ser esta:

O diagrama mostra como uma decisão em aberto vira trabalho extra. O agente pode fazer uma pergunta, mas é melhor perceber a dúvida antes de qualquer alteração. A primeira formulação já pode indicar o rumo e os limites:

Ainda está vago:
Faça uma calculadora para dividir a conta do restaurante.

Mais específico:
Uma única página: informamos o total da conta e o número de pessoas,
e vemos quanto cabe a cada uma. A divisão é igual.
Sem contas de usuário, histórico de contas ou divisão por prato.

O segundo pedido ainda não responde a tudo. Mas já descarta vários produtos diferentes que poderiam surgir a partir do primeiro. Daqui em diante, o agente ajuda a encontrar o que falta e a registrar as suas decisões.

A tarefa em um arquivo

TASK_SPEC é o registro das condições de uma tarefa: qual resultado é esperado, onde o trabalho termina e como verificá-lo. Em geral, ele é salvo em um arquivo Markdown chamado TASK_SPEC.md, junto do projeto. Esse nome não corresponde a um formato especial nem a um comando específico. As condições também podem ser passadas em uma mensagem, mas é mais fácil reler e atualizar um arquivo.

Não é preciso escrever o TASK_SPEC à mão. É mais prático montá-lo com o agente e conferir como ele registrou as decisões. A tarefa pode ser descrita com palavras comuns; depois, basta responder às perguntas e pedir ajustes na formulação. O agente mantém o arquivo, e o(a) senhor(a) confere o sentido.

1. o(a) senhor(a) descreve o que quer obter e discute os pontos que ainda não estão claros;
2. o agente sugere opções, e o(a) senhor(a) escolhe a mais adequada;
3. o agente registra a decisão no TASK_SPEC e mostra o trecho acrescentado ou alterado;
4. o(a) senhor(a) lê esse trecho no arquivo: o sentido foi preservado, não surgiram condições extras e nada contradiz o que já estava escrito. Se algo não estiver certo, pede a correção e confere de novo.

Depois de cada decisão, basta conferir as linhas afetadas e as condições relacionadas. Antes da implementação, releia o arquivo inteiro: cada registro pode parecer correto isoladamente e, em conjunto, exigir coisas incompatíveis. A mensagem "atualizei a especificação" não mostra o que de fato foi parar no documento.

A diferença em relação ao CLAUDE.md está na finalidade. "Todos os textos da interface do projeto ficam em português" é uma regra geral do projeto. "Nesta tarefa, vamos acrescentar o cálculo da gorjeta" é uma condição específica do trabalho. A primeira cabe no CLAUDE.md; a segunda, no TASK_SPEC.

O tamanho do documento depende da tarefa. Para corrigir um erro de digitação em uma página pronta, basta uma especificação como esta:

Na página de divisão da conta, corrija o texto do botão:
"Calcularr" → "Calcular". Não altere mais nada.
Confira se o novo texto aparece e se o botão continua calculando.

Esse é um TASK_SPEC curto, às vezes chamado de tiny spec. Quase não há o que discutir nesse caso. Já uma calculadora nova pode ter vários comportamentos possíveis, então duas linhas não bastam. Vale registrar as decisões que afetam o resultado; a quantidade de títulos, por si só, não garante nada.

Comece pelo resultado

Imagine que o projeto ainda não existe. Um grupo de amigos quer abrir uma página no navegador, informar o valor da conta e descobrir quanto cada pessoa deve pagar. Vamos pedir ao agente que crie um rascunho:

Crie um TASK_SPEC.md para uma página de divisão da conta.
O projeto ainda não existe. Informamos o valor da conta e o número de pessoas;
após clicar em "Calcular", vemos a parte de cada uma.
O resultado deve ser um index.html que abre no navegador sem instalação.
Registre as condições acordadas e marque o que for desconhecido como dúvida.
Mostre o texto registrado. Ainda não escreva o código da página.

Este é um exemplo didático do primeiro trecho do arquivo:

## CONTEXTO
Um grupo em um restaurante quer dividir a conta rapidamente.
O projeto ainda não existe e a pasta de trabalho está vazia.

## COMPORTAMENTO DESEJADO
O usuário informa o valor da conta e o número de pessoas.
Ao clicar em "Calcular", vê quanto cabe a cada participante.
Resultado do trabalho: uma página index.html
que abre no navegador sem instalação.

Abra o TASK_SPEC.md no editor e confira se o registro corresponde ao pedido: os dois campos, a ação e o resultado para cada participante estão lá. Se o agente acrescentou campo para nomes ou cadastro obrigatório, são condições que ninguém aprovou. Peça para removê-las do arquivo e confira a correção.

Agora sabemos quem usa a página e o que recebe. Também demos nome ao artefato, ou seja, ao resultado concreto do trabalho do agente: o arquivo da página. Em outra tarefa, poderia ser uma análise de um erro ou um plano de alterações sem código. Vale dizer isso claramente.

Observe que ainda não escolhemos funções de JavaScript nem dissemos como armazenar os participantes. Essas decisões fazem parte da implementação. Na especificação, o mais importante é definir o que a pessoa verá: entrada, ação e resultado.

Onde a tarefa termina

Agora vamos definir até onde vai a primeira versão. Peça ao agente que registre os limites acordados e mostre o bloco atualizado:

## SCOPE
Uma página: informar o valor e o número de pessoas,
dividir o total igualmente e mostrar a parte de cada uma.

## NON-GOALS
Sem contas de usuário ou histórico de contas: não precisamos guardar dados.
Sem divisão por prato: na primeira versão, a divisão é igual.
Limite da implementação: um único arquivo HTML com estilos e script
embutidos, sem servidor nem bibliotecas externas.
A página deve abrir com um clique duplo.

Nesse trecho, não basta conferir se as exclusões estão listadas: a divisão igual precisa continuar dentro do escopo, e a divisão por prato deve ficar de fora. Se o agente trocar uma pela outra, corrija o documento antes de trabalhar na página.

Scope descreve o escopo do trabalho. É possível defini-lo a partir da tela e do cenário, como fizemos aqui. Caminhos exatos ajudam quando já são conhecidos, mas não é preciso começar com uma lista de arquivos. Ao alterar um projeto existente, se ainda não estiver claro onde fica a página, peça ao Claude Code que a encontre sem fazer mudanças e explique por que escolheu aquele arquivo. Depois, inclua o caminho na especificação. O que ainda não se sabe pode ficar em aberto; não invente.

Non-goals são os itens excluídos de propósito. "Sem histórico de contas" deixa o limite mais claro do que "não faça nada extra". Uma justificativa curta também ajuda: daqui a uma semana, ficará claro que a possibilidade de guardar dados foi considerada e descartada.

As restrições de implementação respondem a outra pergunta: quais soluções são aceitáveis? Contas de usuário são um recurso desnecessário; um servidor é uma forma de construir a solução que excluímos aqui. Em um documento curto, é possível manter essas condições no mesmo bloco, desde que as restrições sejam identificadas com clareza.

Os limites precisam permitir que o resultado seja alcançado. Se mais tarde forem necessárias contas compartilhadas com histórico em vários dispositivos, a exigência de "um único arquivo HTML local" terá de ser revista. Não dá para exigir um recurso novo e manter ao mesmo tempo uma restrição que o torna impossível.

O centavo que ficou faltando

Até aqui, tudo parece bem definido. Vamos testar a especificação antes de escrever código: três pessoas, uma conta de 1000. Quanto cada uma vai pagar?

333,33 + 333,33 + 333,33 = 999,99

Falta um centavo. Podemos acrescentá-lo à primeira pessoa, à última ou deixar que o usuário escolha. A frase "dividimos igualmente" não resolve isso. E essa decisão cabe ao(à) senhor(a), não ao conhecimento de JavaScript.

Para a nossa página, vamos adotar esta regra: as partes podem diferir em no máximo um centavo; o restante é distribuído um centavo por vez às primeiras pessoas da lista. Assim, 1000 dividido entre três pessoas resulta em 333,34; 333,33; 333,33. Com 1000,01, sobram dois centavos: 333,34; 333,34; 333,33. Todo o dinheiro é distribuído e a soma das partes bate com a conta.

Agora, vamos pedir ao agente que registre a decisão no documento:

Registre a regra de arredondamento no comportamento desejado do TASK_SPEC.md.
Mostre as linhas alteradas. Ainda não mude o código.

Confira se o arquivo passou a incluir algo assim:

A soma das partes é exatamente igual ao total.
As partes diferem em no máximo 0,01.
Os centavos restantes vão para as primeiras pessoas, um para cada;
a página explica essa regra.

Leia com atenção especial "para as primeiras pessoas, um para cada". Se o agente escrever "todo o restante fica com a primeira pessoa", ele mudou a decisão: com dois centavos restantes, a primeira pessoa pagaria 0,02 a mais que as outras. Peça para corrigir essa linha e confira o arquivo de novo. O importante é o sentido, não a correspondência exata das palavras.

É por isso que vale testar a especificação com números. Encontramos uma decisão que faltava antes de o agente escolher uma alternativa e escrever o código com base nela. Por enquanto, foram só algumas linhas para ajustar.

Deixe o Claude fazer as perguntas

Nem todos os pontos em aberto ficam evidentes de início. Entregue o rascunho ao agente e peça ajuda para definir a tarefa:

Leia @TASK_SPEC.md. Ajude a encontrar as condições que estão faltando.
Faça uma pergunta por vez e sugira uma resposta para cada uma.
Não considere sua sugestão aprovada até eu responder.
Depois de cada decisão acordada, atualize o TASK_SPEC.md
e mostre o trecho alterado para eu conferir.
Ainda não escreva código.

A seguir, um exemplo dessa conversa. Em outra sessão, as perguntas podem ser diferentes; o importante é acompanhar como as respostas mudam o documento.

Claude: "A gorjeta está incluída no valor da conta ou é cobrada à parte? Sugiro um campo separado para a porcentagem, com valor inicial 0."
O(a) senhor(a): "À parte. Calculamos a porcentagem sobre o valor da conta, acrescentamos a gorjeta e dividimos o total. Mostre na página o valor da gorjeta e o total geral."

Claude: "Se a gorjeta resultar em uma fração de centavo, como devemos arredondar? Sugiro arredondar para o centavo mais próximo e, quando der exatamente meio centavo, para cima."
O(a) senhor(a): "Isso. Primeiro arredondamos o valor da gorjeta e depois o acrescentamos à conta. Em seguida, dividimos o total pela nossa regra."

Claude: "Quais valores vamos aceitar? Sugiro um valor positivo com ponto ou vírgula, um número inteiro de pessoas a partir de um e uma porcentagem inteira não negativa. Em caso de erro, mostramos uma dica junto ao campo."
O(a) senhor(a): "Pode ser. O valor pode ter até duas casas decimais, sem separador de milhar. Se um campo estiver vazio ou o valor for inválido, escondemos o resultado, mesmo que já tenhamos calculado antes."

As perguntas esclareceram mais do que a gorjeta. Agora estão definidos os valores aceitos, a ordem do arredondamento e o comportamento em caso de erro. Depois de registrar as respostas, confira o trecho atualizado do arquivo:

Gorjeta: campo separado com porcentagem inteira a partir de 0; valor inicial 0.
Calculamos a gorjeta sobre o valor da conta e arredondamos para o centavo mais próximo;
metade exata de um centavo é arredondada para cima.
A gorjeta arredondada é acrescentada à conta e, então, dividimos o total.
Mostramos o valor da gorjeta, o total geral e a parte de cada pessoa.
Se um valor estiver vazio ou for inválido, o resultado fica oculto,
e o campo correspondente mostra uma dica.

Confira a ordem: primeiro arredondamos a gorjeta, depois a acrescentamos à conta e, por fim, dividimos o total. As mesmas palavras em outra ordem poderiam definir outra regra. Peça também ao agente que atualize o scope: o campo da gorjeta e o cálculo do total foram acrescentados à primeira versão. Confira se ele realmente alterou os dois blocos, em vez de apenas confirmar no chat.

O resultado e como verificá-lo

"A soma das partes é igual ao total" é um requisito do resultado. "Informe 1000, três pessoas e 0% de gorjeta; clique no botão; confira 333,34, 333,33 e 333,33" é uma verificação. Ela define uma ação e o que esperamos observar.

Vamos pedir ao agente que acrescente algumas verificações ao arquivo agora, antes da implementação. Nós mesmos conferimos os valores esperados. Caso contrário, é fácil aceitar o resultado e, sem perceber, ajustar as expectativas à página pronta.

A linha com 10,05 verifica a ordem das operações: 10% resultam em 1,005, que arredondamos para 1,01. Se arredondarmos em outra etapa, o total pode mudar. Para conferir o formato, repita o teste com ponto: 10.05 deve dar o mesmo resultado. Também teste um valor negativo, um número fracionário de pessoas, uma porcentagem negativa ou fracionária e o campo de gorjeta vazio: o cálculo não deve acontecer.

Cada condição importante tem algo que pode ser observado. "A página abriu" não prova que os valores estão corretos, assim como um endereço de link correto não prova que a página esperada carregou. Confira o comportamento que motivou a tarefa.

Montando o TASK_SPEC

O agente registrou as decisões no arquivo durante a conversa. Agora vamos relê-lo por inteiro: as respostas foram incluídas? As verificações correspondem aos requisitos? Ainda há condições antigas? Este é o documento final do nosso exemplo. Ele tem seis pilares: contexto, comportamento desejado, scope, non-goals, plano de verificação e início seguro. Os títulos ajudam a encontrar cada parte, e o conteúdo veio da análise da tarefa.

# TASK_SPEC.md

## CONTEXTO
Um grupo quer dividir a conta de um restaurante.
O projeto ainda não existe; a pasta de trabalho está vazia, exceto pelo TASK_SPEC.md.

## COMPORTAMENTO DESEJADO
Resultado do trabalho: um index.html que abre com um clique duplo
e uma breve descrição da verificação.
A página tem três campos e um botão "Calcular":
- valor da conta maior que 0, com até duas casas decimais;
  separador: ponto ou vírgula, sem separador de milhar;
- número de pessoas: inteiro a partir de 1;
- porcentagem da gorjeta: inteiro a partir de 0, valor inicial 0.
A gorjeta é calculada sobre a conta e arredondada para o centavo mais próximo;
metade exata de um centavo é arredondada para cima.
A gorjeta arredondada é somada à conta; depois, dividimos o total.
A gorjeta, o total e as partes numeradas são exibidos.
A soma das partes é igual ao total; a diferença entre elas não passa de 0,01.
O restante é distribuído um centavo por vez às primeiras pessoas;
a página explica essa regra.
Valor vazio ou inválido: o resultado fica oculto,
e o campo inválido mostra uma dica.

## SCOPE
Uma página: três campos, cálculo, dicas e exibição dos valores.
Dividir o total igualmente, com a distribuição de centavos descrita.

## NON-GOALS
Contas de usuário e histórico de contas não são necessários: não guardamos dados.
Sem divisão por prato: é outra versão da calculadora.
Limite: estilos e script dentro do index.html,
sem servidor ou bibliotecas externas, para abrir o arquivo localmente.

## PLANO DE VERIFICAÇÃO
Abrir o index.html com um clique duplo. Clicar em "Calcular" para:
- 1000 / 3 pessoas / 0% → 333,34; 333,33; 333,33;
- 1000,01 / 3 / 0% → 333,34; 333,34; 333,33;
- 1000 / 3 / 10% → gorjeta 100,00, total 1100,00,
  partes 366,67; 366,67; 366,66;
- 10,05 / 3 / 10% → gorjeta 1,01, total 11,06,
  partes 3,69; 3,69; 3,68; informar 10.05 dá o mesmo resultado;
- 1000 / 1 / 0% → uma parte de 1000,00.
Em cada caso, somar as partes e comparar com o total.
Testar 0 e um valor fracionário no número de pessoas, uma conta negativa,
porcentagem negativa ou fracionária, mais de duas casas decimais
no valor e deixar cada campo vazio, um de cada vez:
o campo mostra uma dica e o resultado fica oculto, mesmo após um cálculo.
Conferir a numeração das partes e a explicação da distribuição dos centavos.

## INÍCIO SEGURO
Ler a especificação e conferir o conteúdo da pasta de trabalho.
Se já houver arquivos do projeto, parar e esclarecer a tarefa;
não substituir nem excluir arquivos existentes.
Primeiro, perguntas e plano sem código; depois, aguardar aprovação.
Se a implementação exigir mudanças fora do scope,
esclarecer a especificação antes de fazê-las.

O documento cresceu com as decisões que realmente fizeram falta. Não há nele uma receita passo a passo para escrever JavaScript, mas está claro o que fazer com a gorjeta e como conferir os centavos. Outras tarefas podem exigir menos detalhes.

Ao preparar uma especificação, vale passar por esta breve lista:

Quando as condições mudam

Agora, um pequeno exercício. O usuário olha a especificação e diz: "Porcentagem é inconveniente. Quero informar a gorjeta como um valor, por exemplo, 100". Quais partes do TASK_SPEC precisam ser atualizadas? Tente identificá-las antes de ler a análise.

No comportamento desejado, o campo de porcentagem dá lugar ao valor da gorjeta: não negativo, com ponto ou vírgula e no máximo duas casas decimais. O valor inicial continua sendo 0. Removemos a fórmula da porcentagem e o arredondamento da gorjeta calculada: basta somar à conta o valor informado. No scope, muda o cálculo; no plano de verificação, mudam os dados de entrada e os casos inválidos. A divisão do total e os non-goals permanecem iguais.

O teste "conta de 1000, gorjeta de 100, três pessoas" ainda dá os conhecidos 366,67; 366,67; 366,66. Mas só esses valores não distinguem a versão nova da antiga, com gorjeta de 10%. Acrescente outra conta: 500 mais 100 fixos, para duas pessoas. Cada uma deve pagar 300; com os antigos 10%, seriam 275. Esse teste detecta a mudança da regra.

Peça ao agente que atualize o comportamento desejado, o scope e as verificações, e depois mostre todos os trechos alterados. Abra o arquivo e confira se a fórmula antiga da porcentagem foi removida e se os novos testes correspondem à entrada de um valor fixo. Não deixe a fórmula antiga junto de uma nota dizendo "agora por valor": a especificação deve dar uma única resposta. No exemplo principal, mantivemos a versão original com porcentagem; aqui analisamos uma alteração separada.

Como isso funciona com o Claude Code

Depois de conferir cada alteração, releia o TASK_SPEC inteiro antes de iniciar a implementação. Veja se o objetivo, os limites e as verificações descrevem a mesma tarefa. Em seguida, passe o arquivo explicitamente ao agente:

Leia @TASK_SPEC.md. Primeiro, confira se há contradições
ou condições que ainda precisam ser esclarecidas.
Mostre um plano curto e a lista de arquivos que você criará ou alterará.
Não mude o código antes da aprovação do plano.

Agora há algo para conferir antes mesmo da implementação. Se o plano incluir um servidor para armazenar as contas, peça que seja revisto: o histórico foi excluído e a página deve abrir localmente. Se o plano estiver adequado, autorize a implementação. Depois, abra o arquivo gerado e percorra os cenários registrados, inclusive a entrada inválida depois de um cálculo bem-sucedido.

Os non-goals são condições em texto; eles não bloqueiam alterações tecnicamente. Por isso, é importante conferir tanto o plano quanto o resultado. A mensagem "pronto" do agente ajuda a entender o que ele fez, mas não substitui os seus valores de referência.

Se o TASK_SPEC for mantido no projeto depois da conclusão do trabalho, marque a tarefa como encerrada. Enquanto o trabalho estiver em andamento, mantenha as decisões do arquivo atualizadas. Deixe a formulação e o registro a cargo do agente, mas confira as decisões no próprio documento: o trecho alterado depois de cada conversa e o arquivo inteiro antes da implementação.