Aplique o método DARE numa feature

Passos

1. Entenda as quatro fases e a divisão humano/IA

   Antes de escrever qualquer coisa, internalize o ciclo. O DARE tem quatro fases, e o ponto central
   é quem está no controle em cada uma.

   1. Design — humano dirige, IA assiste. Você decide o problema, os critérios de sucesso e os
      limites. A IA pode fazer perguntas, mas não decide escopo.
   2. Architect — humano decide, IA rascunha. Juntos vocês produzem um contrato preciso e
      executável. Você continua sendo a autoridade sobre o quê; a IA ajuda a moldar como será estruturado.
   3. Review — portão humano. Nada prossegue sem o seu "aprovado" explícito. Este é o checkpoint
      que te salva de pagar tokens para implementar a coisa errada.
   4. Execute — IA dirige, humano supervisiona. A IA implementa as tasks e roda o Ralph Loop
      (implementar → testar → lint → checar tipos → corrigir → repetir) até tudo ficar verde.

   A única regra pra lembrar

   Estratégia (o quê e o porquê) é sempre humana. Tática (o como) é sempre da IA. Cada fase é só uma
   passagem de bastão entre essas duas, e o Review é o portão de segurança no meio.

   Checkpoint

   Responda estas três perguntas pra você mesmo antes de continuar (escreva-as):

   • Qual fase decide se uma feature vale a pena ser construída? (Design.)
   • Qual artefato precisa ser concreto o suficiente para que um stub o reprove? (BLUEPRINT.md.)
   • O que acontece no Review se você achar uma lacuna? (Você volta e corrige o blueprint — não prossegue.)

   Se alguma resposta pareceu nebulosa, releia a visão geral acima. O resto do lab assume que você
   sabe nomear quem é dono de cada decisão.

2. Escolha uma feature e escreva o DESIGN.md

   Agora você é dono da fase de Design. Escolha uma feature pequena. Mantenha minúscula — o
   equivalente a um endpoint ou o comportamento de uma tela. Se não tiver nenhuma ideia à mão, use
   este exemplo:

   Feature de exemplo: um serviço de "encurtar URL". O usuário envia uma URL longa e recebe um
   código curto; visitar o código curto redireciona para a URL original.

   Crie um arquivo chamado DESIGN.md com estas cinco seções. O trabalho aqui é estratégia, não código.

   # DESIGN — Encurtador de URL
   
   ## Problema e contexto
   Usuários querem compartilhar URLs longas em lugares com limite de tamanho (chat, impressão).
   Precisamos de um serviço que transforme uma URL longa em um código curto e redirecione ao visitar.
   
   ## Critérios de sucesso (testáveis)
   - Um POST de URL válida retorna um código curto de 6–8 caracteres URL-safe.
   - GET /{código} para um código conhecido responde com um redirect HTTP para a URL original.
   - GET /{código} para um código desconhecido responde com 404.
   - A mesma URL longa enviada duas vezes retorna o mesmo código (idempotente).
   
   ## Restrições
   - Códigos devem ser URL-safe (sem /, + ou =).
   - A URL original deve ser uma URL http/https sintaticamente válida.
   
   ## Não-objetivos
   - Sem contas de usuário ou autenticação.
   - Sem analytics/rastreamento de cliques.
   - Sem códigos customizados (vanity).
   

   Regras para bons critérios de sucesso

   Cada critério precisa ser testável — uma entrada específica produzindo uma saída específica e
   observável. "Deve ser rápido" não é testável; "responde em menos de 200 ms para um código conhecido"
   é. Escreva critérios que você poderia entregar a outra pessoa e ela saberia exatamente quando a
   feature está pronta.

   Por que não-objetivos importam

   Não-objetivos são a cerca em volta da imaginação da IA. Se você não escrever "sem autenticação",
   a IA pode gentilmente adicionar um sistema de login que você nunca quis — isso é escopo que o modelo
   inventou. Cada não-objetivo é um token que você não vai desperdiçar depois.

   Entregável deste passo: um DESIGN.md com as cinco seções preenchidas para a sua feature.

3. Escreva o BLUEPRINT.md com um contrato anti-stub

   Com o Design aprovado (por você), entre na fase Architect. O BLUEPRINT.md traduz seus
   critérios de sucesso em um contrato executável: um modelo de dados mais cada endpoint especificado
   com seu request e seu response por status code.

   A disciplina crítica é o contrato anti-stub. Não escreva "implementar o endpoint de criação".
   Escreva exatamente o que entra, o que sai e para qual status. Eis o exemplo:

   # BLUEPRINT — Encurtador de URL
   
   ## Modelo de dados
   Link:
     - id: identificador único
     - code: string, 6–8 chars URL-safe, único
     - original_url: string, http/https válida
     - created_at: timestamp
   
   ## Endpoint: POST /links
   Corpo do request:
     { "url": "https://exemplo.com/caminho/muito/longo" }
   
   Responses:
     - 201 Created
       { "code": "Ab3xZ9", "short_url": ".../Ab3xZ9", "original_url": "https://exemplo.com/caminho/muito/longo" }
     - 422 Unprocessable Entity  (url ausente ou não http/https)
       { "error": "url precisa ser uma URL http ou https válida" }
   
   Comportamento:
     - Normalizar a URL (remover espaços, host em minúsculas).
     - Se já existir um Link com a mesma original_url normalizada, retornar o código existente (201, idempotente).
     - Caso contrário, gerar um código URL-safe aleatório de 6 chars; em colisão, regenerar (máx. 5 tentativas).
   
   ## Endpoint: GET /{code}
   Responses:
     - 302 Found  -> header Location = original_url
     - 404 Not Found  (nenhum Link com esse código)
       { "error": "código desconhecido" }
   

   O teste anti-stub

   Leia cada endpoint e pergunte: um stub que retorna um valor fixo satisfaria esta spec?
   Se "gerar um código" não tem regra para colisões, um stub retornando "AAAAAA" toda vez passaria —
   logo a spec está fraca demais. Repare como o exemplo fecha esse buraco com "em colisão, regenerar".
   Cada linha de comportamento existe para fazer o "não fez nada" falhar.

   Checklist do seu blueprint

   • O modelo de dados lista cada campo com seu tipo e restrições
   • Cada endpoint lista um formato de request e um formato de response para cada status code (sucesso e erros)
   • Todo comportamento não-trivial (normalização, idempotência, colisões, validação) está detalhado
   • Nenhuma linha diz "implementar X", "tratar Y" ou "etc." — isso são stubs disfarçados

   Entregável deste passo: um BLUEPRINT.md onde cada endpoint poderia ser implementado por alguém
   que nunca viu seu DESIGN.md, sem precisar chutar nada.

4. Decomponha em TASKS e monte o DAG

   Agora a fase Execute começa no papel. Quebre o blueprint em tasks atômicas — cada uma de
   15 a 60 minutos de trabalho focado, cada uma com uma Definition of Done (DoD) anti-stub. Depois
   conecte-as pelas suas dependências reais e mínimas para formar um DAG (grafo acíclico dirigido).

   Tasks no mesmo rank não têm dependência entre si, então poderiam rodar em paralelo. Os ranks
   rodam em sequência.

   # TASKS — Encurtador de URL
   
   ## T1 — Modelo de dados e armazenamento do Link
   DoD: Um Link com code, original_url, created_at pode ser criado e buscado por code;
        o code é único no nível de armazenamento. Teste: criar dois links, buscar cada um por code.
   Depende de: (nenhuma)
   
   ## T2 — Validação e normalização de URL
   DoD: Dada uma string, retorna a URL normalizada ou um erro de validação; rejeita não-http(s).
        Teste: URL válida normaliza; "ftp://x" e "" são rejeitados.
   Depende de: (nenhuma)
   
   ## T3 — Gerador de código com retry em colisão
   DoD: Retorna um code URL-safe de 6 chars; em colisão simulada, regenera; falha após 5 tentativas.
        Teste: caminho de colisão forçada regenera e por fim retorna um code único.
   Depende de: (nenhuma)
   
   ## T4 — Endpoint POST /links
   DoD: URL válida -> 201 com code (idempotente em repetições); inválida -> 422 com corpo de erro.
        Teste: cobre 201, repetição idempotente e 422.
   Depende de: T1, T2, T3
   
   ## T5 — Endpoint GET /{code}
   DoD: Code conhecido -> 302 para original_url; desconhecido -> 404 com corpo de erro.
        Teste: cobre 302 e 404.
   Depende de: T1
   

   O grafo de dependências (DAG)

   Ler as linhas "Depende de" te dá os ranks:

   Rank 0 (paralelo):  T1   T2   T3
                         \   |   /
   Rank 1:                  T4          T5   (T5 só precisa de T1, então também pode começar assim que T1 terminar)
   

   • Rank 0: T1, T2, T3 — independentes, poderiam ser construídas ao mesmo tempo.
   • Rank 1: T4 depende de T1+T2+T3; T5 depende só de T1.

   Regras para uma boa decomposição

   • Atômica: se uma task levaria mais de ~60 minutos, divida. Se duas tasks são sempre feitas
     juntas em menos de 15 minutos, junte.
   • Dependências reais mínimas: só desenhe uma aresta se a task genuinamente não pode começar sem a
     outra. Inventar dependências mata o paralelismo; perder uma real causa builds quebrados.
   • DoD anti-stub: toda DoD nomeia um teste concreto. "Endpoint funciona" é uma DoD amigável a stub;
     "cobre 201, repetição idempotente e 422" não é.

   Entregável deste passo: um TASKS.md listando tasks atômicas com DoDs anti-stub e suas
   dependências, mais o agrupamento por rank (o DAG) escrito.

5. Auto-revisão: cace stubs antes de gastar tokens

   Este é o portão de Review — o checkpoint que faz o DARE valer a pena. Antes de entregar estes
   artefatos a uma IA, você faz o papel de revisor. Seu objetivo é encontrar todo lugar onde a IA
   poderia legitimamente produzir um stub e ainda satisfazer sua spec. Cada um que você achar é um
   bug pego de graça.

   A auditoria anti-stub

   Percorra seus três arquivos e cheque cada item. Corrija o que falhar antes de seguir.

   • DESIGN.md — critérios são testáveis. Leia cada critério de sucesso. Você conseguiria
     escrever um teste automatizado a partir dele como está? Se disser "trata erros graciosamente",
     troque pelas entradas específicas e saídas esperadas.
   • DESIGN.md — não-objetivos são explícitos. Existe alguma feature adjacente que a IA poderia
     "gentilmente" adicionar? Nomeie-a como não-objetivo.
   • BLUEPRINT.md — cada status code está especificado. Para cada endpoint, você lista o response
     de sucesso e cada response de erro com seu corpo? Um 404/422 ausente é onde a IA inventa comportamento.
   • BLUEPRINT.md — sem verbos vagos. Procure por "implementar", "tratar", "processar", "gerenciar",
     "etc.", "e assim por diante". Cada um é um buraco. Troque pela regra concreta.
   • TASKS.md — cada DoD nomeia um teste. Uma DoD sem teste observável é um ímã de stub.
     "Funciona" → "dado X, retorna Y".
   • TASKS.md — dependências são reais. Para cada aresta, confirme que a task realmente não pode
     começar sem a dependência. Remova arestas inventadas; adicione qualquer real que faltar.
   • Sem ciclos. Siga seus links "depende de" — você nunca deve conseguir voltar em loop a uma task.

   O teste do mock

   Para cada função ou endpoint, faça a pergunta decisiva:

   Se alguém substituísse isto por um mock com valor fixo, algum dos meus critérios de sucesso ou testes de DoD falharia?

   Se a resposta for "não" para algum item, esse item está subespecificado. Aperte-o até que um mock
   falhasse visivelmente. Essa única pergunta é a essência do DARE — é por isso que o método produz
   software funcionando em vez de stubs convincentes.

   Por que este portão existe

   Tudo até aqui te custou minutos de escrita. A execução custa tokens, tempo e esforço de revisão.
   Pegar um endpoint subespecificado agora é quase de graça; pegá-lo depois que a IA construiu um stub
   em volta dele não é. Aprove só quando cada caixa acima estiver marcada.

   Entregável deste passo: os mesmos três arquivos, revisados — com uma nota curta no fim do
   TASKS.md listando ao menos um risco de stub que você achou e como o fechou.

6. Entregue e saiba como executar

   Você passou uma feature por todas as quatro fases do DARE. Hora de entregar — e de entender o que
   acontece quando uma execução real começa.

   Critério de submissão

   Coloque seus três artefatos em um só lugar e compartilhe:

   1. Crie um repositório git (ou um gist) contendo exatamente três arquivos na raiz:
      DESIGN.md, BLUEPRINT.md e TASKS.md.
   2. Confirme que cada um atende ao seu entregável dos passos anteriores:
      • DESIGN.md: problema, critérios de sucesso testáveis, restrições, não-objetivos.
      • BLUEPRINT.md: modelo de dados + cada endpoint com request/response por status code, comportamento anti-stub.
      • TASKS.md: tasks atômicas com DoDs anti-stub, dependências reais, o agrupamento por rank/DAG e sua nota de risco de stub.
   3. Commite e faça push. Entregue a URL do repositório ou gist como seu entregável do lab.

   git init
   git add DESIGN.md BLUEPRINT.md TASKS.md
   git commit -m "Artefatos DARE para <minha feature>"
   # faça push para o remoto de sua escolha, depois entregue a URL
   

   Como é a execução (próximos passos)

   Com os artefatos aprovados, a execução é mecânica. Para cada rank do DAG, um assistente de IA pega
   as tasks e roda o Ralph Loop em cada uma:

   1. Implementar a task para satisfazer sua Definition of Done.
   2. Rodar os testes, o linter e o checador de tipos.
   3. Se algo estiver vermelho, ler a falha e corrigir.
   4. Repetir até testes, lint e tipos ficarem todos verdes.

   Como tasks do mesmo rank são independentes, podem ser executadas em paralelo; o próximo rank só começa
   depois que suas dependências terminam. Como toda DoD nomeia um teste, "pronto" é objetivo — o loop tem
   uma condição de parada clara, e um stub não passa.

   O que você aprendeu

   Você não só preencheu templates. Você praticou o movimento central do DARE: tirar a estratégia da
   sua cabeça e colocá-la no papel, numa forma tão concreta que a IA não tem mais nada para inventar.
   Esse é o método inteiro. Toda feature futura são as mesmas quatro fases — Design, Architect, Review,
   Execute — na escala que você precisar.