Seu primeiro projeto — da ideia à primeira fatia verificável

Começar pequeno não significa pensar pequeno

“Quero criar um aplicativo de manutenção” ainda não é um projeto executável. Não sabemos quem sente a dor, em qual momento, qual decisão será melhorada nem como reconhecer sucesso. Se o agente começar agora, preencherá lacunas com suposições e poderá entregar muitas telas que não resolvem o problema.

Neste capítulo, construiremos o planejamento da menor versão útil: um técnico consulta uma ordem de serviço fictícia e registra uma observação. Não haverá ERP, autenticação corporativa ou IA dentro do produto nesta primeira fatia. Essas capacidades podem entrar depois, quando a base e os riscos forem compreendidos.

Pré-requisito: distinguir prompt, agente e harness. Você não precisa dominar frameworks. Ao final, terá PROJECT_BRIEF.md, uma especificação curta, um ticket vertical, um plano de avaliação e uma decisão de parada.

Vocabulário essencial

• Project brief: resumo do problema, público, valor, limites e restrições.
• Artifact kind: tipo de artefato produzido, como site, ERP, aplicativo, automação ou jogo. O tipo muda a estratégia de avaliação.
• Tracer bullet: implementação mínima que atravessa o caminho real e produz sinal verificável. A metáfora vem de um projétil que torna visível a trajetória; não significa código descartável.
• Fatia vertical (vertical slice): pequena funcionalidade que atravessa interface, regra, dados e testes, em vez de concluir uma camada inteira isoladamente.
• Critério de aceite: condição observável que decide se um requisito foi atendido.
• Prova de conceito (proof of concept): experimento para responder uma dúvida técnica. Pode ser descartado.
• Definition of Done: conjunto de portões aplicável a qualquer entrega, como testes, documentação e revisão.

Passo 1 — escrever o problema sem mencionar solução

Use a estrutura:

Quando [situação], [pessoa] precisa [decisão ou ação],
mas hoje [obstáculo], causando [consequência observável].

Exemplo:

Quando chega a um equipamento, o técnico precisa confirmar qual ordem executar, mas hoje consulta mensagens dispersas, causando atraso e risco de trabalhar na OS errada.

Compare com “precisamos de React e PostgreSQL”. A segunda frase escolhe tecnologia sem provar a dor. Tecnologia entra depois, como hipótese de solução.

Verificação: mostre o problema a alguém que não conhece o projeto. Essa pessoa consegue apontar situação, ator, necessidade, obstáculo e consequência?

Passo 2 — delimitar usuário, jornada e resultado

Defina uma única jornada inicial:

Técnico abre a lista
→ seleciona OS-101
→ lê equipamento e descrição
→ registra observação
→ vê confirmação persistida

O resultado observável será: após recarregar a página, a observação sintética continua associada à OS-101. Isso é mais forte que “a interface ficou bonita” e menor que “todo o módulo de manutenção funciona”.

Registre fora do escopo: login corporativo, anexos, aprovação, estoque, notificações e ERP. Fora de escopo não significa “nunca”; significa “não pode bloquear esta evidência”.

Passo 3 — escolher o tipo de artefato

Pergunta	Indicação
precisa abrir por link em computador e celular?	site/web
precisa operar processos empresariais e registros oficiais?	ERP/sistema empresarial
depende de câmera, sensores, offline ou loja?	aplicativo móvel
reage automaticamente a eventos entre sistemas?	automação
o valor está em regras lúdicas e interação em tempo real?	jogo

Nosso exemplo será web. Isso determina que a avaliação precisa de navegador, teclado, diferentes larguras, console e rede — além de testes do código.

Passo 4 — estimar risco e complexidade

Classifique impacto sobre dados, dinheiro, permissões, pessoas e sistemas externos. O demonstrador usa dados sintéticos e não envia ações externas: risco baixo, fluxo S2 porque é uma funcionalidade ponta a ponta.

Se o mesmo formulário encerrasse uma OS real e consumisse estoque, o risco subiria. O modelo poderia propor a intenção, mas a política do servidor verificaria identidade, permissão, estado e idempotência.

Passo 5 — escrever critérios antes do código

Critérios bons são binários ou possuem limiar explícito:

1. A lista exibe OS-101 e OS-102 a partir de dados sintéticos.
2. Abrir OS-101 mostra equipamento, descrição e observações.
3. Observação vazia é recusada com mensagem associada ao campo.
4. Observação válida reaparece após recarregar.
5. A jornada funciona apenas por teclado em 360×800 e 1440×900.
6. Não há erro de console no caminho principal.
7. Nenhum dado real, segredo ou chamada externa é usado.

“Design moderno” não é critério suficiente. Pode virar uma rubrica com hierarquia, contraste, consistência e legibilidade, mas ainda precisa de referência e julgamento separado.

Passo 6 — definir a primeira fatia vertical

O fluxo deve caber numa sessão coerente e produzir uma demonstração. Ele não exige “fazer todo o frontend”, depois “todo o backend”. Cada caixa contém somente o necessário para a jornada.

Ticket vertical

# Registrar observação sintética em uma OS

## Resultado
O técnico abre OS-101, registra texto não vazio e o encontra após recarregar.

## Fora de escopo
Login, anexos, ERP, edição e exclusão.

## Aceite
- [ ] vazio é recusado;
- [ ] texto válido persiste;
- [ ] teclado conclui a jornada;
- [ ] testes e console estão limpos.

## Evidência
Comandos, saída dos testes e captura dos estados inicial, inválido e persistido.

Passo 7 — separar hipótese de implementação

Talvez você não saiba se localStorage funciona no ambiente desejado. Isso é uma hipótese isolável: crie uma página descartável, grave um valor, recarregue e observe. Registre a conclusão; não transforme automaticamente o protótipo em arquitetura de produção.

Para o demonstrador, armazenamento local é suficiente. Para múltiplos usuários, auditoria e concorrência, não é. O limite precisa aparecer no texto para evitar que exemplo didático seja copiado como recomendação empresarial.

Passo 8 — preparar a avaliação

Antes de construir, responda:

• qual comando prova que o projeto compila?
• qual teste cobre vazio e persistência?
• como abrir o navegador no ambiente?
• qual largura será inspecionada?
• o que constitui falha crítica?
• quais evidências serão guardadas?

Estado permitido quando o navegador não puder abrir: UNVERIFIED, com o bloqueio registrado. Nunca converta ausência de ferramenta em aprovação.

Passo 9 — implementar sem terceirizar entendimento

Peça ao agente para auditar a estrutura antes de alterar. Durante a execução, acompanhe decisões, não cada caractere. Ao receber código:

1. localize onde a entrada é validada;
2. identifique onde o estado é gravado;
3. explique a falha quando o armazenamento está indisponível;
4. execute os comandos;
5. examine o diff;
6. compare com os critérios, não com a quantidade de arquivos.

Se você não consegue explicar o caminho principal, o projeto ainda não é uma evidência de aprendizagem.

Passo 10 — parar de forma explícita

A primeira fatia termina quando todos os critérios passam, os limites estão documentados e existe uma próxima decisão. Não acrescente autenticação “porque sobrou tempo”. Termine, registre e só então escolha o próximo ticket.

PASS: critérios executados e evidência presente
FAIL: critério executado e resultado divergente
UNVERIFIED: não foi possível executar a prova
BLOCKED: dependência impede progresso e está identificada

Como escolher tecnologia sem transformar preferência em requisito

Depois de definir a primeira fatia, surge a pergunta: “qual linguagem ou framework devo usar?”. Ela é legítima, mas chega depois do problema porque a tecnologia precisa servir às restrições. Quatro perguntas são mais úteis que uma lista de ferramentas populares:

1. Onde a aplicação será usada? Navegadores corporativos favorecem uma aplicação web. Trabalho em campo sem conexão pode exigir capacidades offline e sincronização.
2. Que conhecimento a equipe possui? Uma tecnologia familiar reduz o tempo para diagnosticar falhas. Uma novidade precisa pagar seu custo de aprendizado.
3. Com quais sistemas ela conversa? ERP, identidade corporativa e banco existente podem limitar protocolos e ambientes.
4. Qual risco precisa ser controlado? Dados pessoais e ações administrativas exigem mais isolamento, auditoria e testes que uma página informativa.

Compare duas propostas. A primeira diz: “usar microsserviços, Kubernetes e cinco agentes porque são modernos”. A segunda diz: “usar uma aplicação web única porque há uma equipe pequena, uma jornada inicial e baixo volume; separar serviços se métricas demonstrarem uma fronteira independente”. A segunda possui justificativa verificável: relaciona escolha, restrição e sinal que autorizaria mudança futura.

Registre decisões caras de reverter em um ADR (Architecture Decision Record, ou registro de decisão arquitetural). Uma decisão facilmente substituível pode ficar no ticket. Essa diferença evita documentos cerimoniais e preserva o motivo de escolhas importantes.

Matriz mínima entre critério e evidência

Um critério sem método de prova permite interpretações conflitantes. Para a primeira fatia, escreva antes de implementar:

Critério	Como provocar	Evidência	Falha crítica
técnico cria uma OS válida	preencher equipamento, descrição e prioridade	resposta criada, registro persistido e item na lista	interface diz sucesso, mas registro não existe
campo obrigatório é protegido	enviar sem equipamento	mensagem ligada ao campo e nenhuma gravação	API aceita dado incompleto
usuário não lê outra unidade	solicitar ID de outro local	resposta negada e evento auditável	conteúdo de outra unidade aparece
repetição não duplica integração	reenviar a mesma chave idempotente	um efeito e mesma referência	duas reservas no ERP

“A tela ficou bonita” pode provar layout, mas não persistência ou autorização. Para esses riscos, combine interface com resposta da API, estado do banco ou teste automatizado. Observe a fronteira onde o dano realmente vive.

Como confirmar que a fatia terminou

Execute a jornada como usuário e provoque pelo menos uma falha prevista. Registre comando, ambiente, entrada, saída e resultado. Se o comportamento depende de uma pessoa — como aprovar ação crítica — registre quem possui autoridade e o que foi aprovado.

O projeto pode ter trabalho futuro. Terminar a fatia significa provar seu escopo pequeno e declarar o restante fora dela. Essa fronteira impede que um protótipo infinito pareça progresso e prepara o próximo capítulo, que organiza como construir e julgar por complexidade.

Como era e como funciona atualmente

Durante muito tempo, projetos pequenos começavam por um documento extenso de requisitos ou, no extremo oposto, por código sem especificação. A IA tornou o segundo extremo mais tentador: uma descrição curta pode gerar muitas telas em minutos. Velocidade de geração, porém, não reduz a necessidade de descobrir regras; ela apenas permite cristalizar suposições mais depressa.

A prática atual combina investigação curta, especificação verificável e fatias verticais. A IA ajuda a levantar perguntas, comparar opções, criar protótipos e executar tickets. A pessoa responsável continua decidindo objetivo, risco, prioridade e aceite. Em vez de tentar prever toda a plataforma, a equipe preserva decisões duráveis e aprende com uma entrega pequena.

O método antigo ainda pode ser adequado em ambientes regulados que exigem documentação formal antes da execução. Mesmo nesses casos, critérios precisam se conectar a testes e evidências. Da mesma forma, um protótipo rápido continua útil para uma hipótese descartável. O erro não está no documento longo ou no protótipo; está em tratá-los como prova de algo que não verificaram.

Erros frequentes

Erro	Sinal	Correção
começar por pastas	árvore enorme sem jornada	escrever problema e fluxo primeiro
pedir o aplicativo inteiro	muitos arquivos, pouca prova	reduzir para uma fatia vertical
aceitar “funcionou”	nenhuma saída registrada	exigir comando, resultado e inspeção
usar dados reais	risco de privacidade	fixture sintética e explícita
misturar produto com processo	“tem IA” porque Codex escreveu	classificar pelo comportamento do produto
continuar sem parada	escopo cresce após o aceite	fechar o ticket e abrir decisão separada

Exercício guiado e desafio

Preencha os modelos PROJECT_BRIEF.md, SPEC.md, TICKET_VERTICAL.md e EVAL_RECIPE.md do kit comum para o exemplo de OS. Entregue os quatro arquivos e uma matriz ligando cada critério a uma forma de prova.

Depois transfira o método para outro domínio: lista de compras, chamados de TI ou catálogo de equipamentos. Mude os dados e a jornada; preserve problema, critérios, fatia e evidência.

Recuperação ativa

O que diferencia ideia de problema verificável? Por que uma fatia vertical ensina mais cedo que uma camada completa? Quando um protótipo deve ser descartado? O que muda na avaliação quando o artefato é web? Qual a diferença entre FAIL e UNVERIFIED? Por que “concluído” não é uma evidência?

O próximo capítulo organiza quem prepara a prova, quem constrói e quem julga.