Melhores Práticas: Descrições Claras, Aproveitamento de Checkpoints, Controle de Escopo e Técnicas de Iteração

O Que Você Vai Aprender

Ao concluir esta lição, você dominará:

• Como escrever descrições de produtos de alta qualidade para que a IA entenda suas ideias
• Como utilizar o mecanismo de checkpoints para controlar a qualidade de cada fase
• Como definir claramente os limites do escopo através de não-objetivos, evitando a expansão do projeto
• Como validar ideias rapidamente e otimizar continuamente através de iterações graduais

Os Desafios Que Você Enfrenta

Você já se deparou com situações como estas?

• "Fui muito claro, por que o resultado gerado não é o que eu queria?"
• "Um detalhe não está satisfatório, e tudo o que vem depois está errado, é doloroso corrigir"
• "Conforme avanço, as funcionalidades vão aumentando, e fica impossível finalizar"
• "Quero implementar todas as funcionalidades de uma vez, mas no final não consigo fazer nada"

Quando Usar Estas Técnicas

Seja você um usuário iniciante do AI App Factory ou já tenha alguma experiência, estas melhores práticas ajudarão você a:

• Melhorar a qualidade do resultado: Fazer com que a aplicação gerada esteja mais alinhada com as expectativas
• Economizar tempo de correção: Evitar acúmulo de erros e detectar problemas no início
• Controlar o escopo do projeto: Focar no MVP e entregar rapidamente
• Reduzir custos de desenvolvimento: Validação em fases, evitando investimentos inválidos

🎒 Preparação Antes de Começar

Pré-requisitos

• Ter lido Início Rápido para entender os conceitos básicos do AI App Factory
• Ter lido Visão Geral do Pipeline de 7 Fases para entender o fluxo completo
• Ter completado pelo menos uma execução completa do pipeline (assim você terá uma sensação intuitiva do resultado de cada fase)

Ideia Central

As melhores práticas do AI App Factory giram em torno de quatro princípios fundamentais:

1. A qualidade da entrada determina a qualidade da saída: Descrições claras e detalhadas do produto são o primeiro passo para o sucesso
2. Checkpoints são a linha de defesa da qualidade: Confirme cuidadosamente após a conclusão de cada fase para evitar acúmulo de erros
3. Foco no MVP: Defina claramente os não-objetivos, controle o escopo e entregue rapidamente as funcionalidades principais
4. Iteração contínua: Valide primeiro a ideia central e depois expanda gradualmente as funcionalidades

Estes princípios são baseados em experiências práticas com código-fonte. Segui-los pode aumentar sua eficiência de desenvolvimento em várias vezes.

Siga Comigo

Técnica 1: Forneça uma Descrição Clara do Produto

Por Quê

Quando a IA interpreta suas ideias, ela depende apenas das informações textuais que você fornece. Quanto mais clara a descrição, mais o resultado gerado estará alinhado com suas expectativas.

Como Fazer

Uma boa descrição de produto contém os seguintes elementos:

• Público-alvo: Quem usará este produto?
• Problema central: Que dificuldades o usuário está enfrentando?
• Solução: Como o produto resolve esta dificuldade?
• Funcionalidades-chave: Quais funcionalidades são obrigatórias?
• Cenários de uso: Em que situações o usuário utilizará o produto?
• Restrições: Há limitações ou requisitos especiais?

Exemplos Comparativos

❌ Descrição Ruim	✅ Descrição Boa
Criar um aplicativo de fitness	Aplicativo para ajudar iniciantes em fitness a registrar treinos, suportando registro de tipo de exercício, duração, calorias queimadas e visualização de estatísticas semanais de treino. O público-alvo são jovens que estão começando a se exercitar, as funcionalidades principais são registro rápido e acompanhamento de progresso, sem compartilhamento social ou funcionalidades pagas
Criar um aplicativo de controle financeiro	Aplicativo móvel para ajudar jovens a registrar despesas diárias rapidamente, com funcionalidades principais de registrar valor, selecionar categoria (alimentação, transporte, entretenimento, outros) e visualizar gastos totais do mês e estatísticas por categoria. Suporta uso offline, dados salvos apenas localmente
Criar uma ferramenta de gerenciamento de tarefas	Ferramenta simples para ajudar pequenas equipes a gerenciar tarefas, suportando criação de tarefas, atribuição de membros, definição de prazos e visualização de lista de tarefas. Membros da equipe podem compartilhar status de tarefas. Não requer fluxos de trabalho complexos ou gerenciamento de permissões

Checkpoint ✅

• [ ] A descrição define claramente o público-alvo
• [ ] A descrição explica o problema central que o usuário enfrenta
• [ ] A descrição lista as funcionalidades-chave (não mais que 5)
• [ ] A descrição inclui restrições ou não-objetivos

---

Técnica 2: Confirme Cuidadosamente nos Checkpoints

Por Quê

Após a conclusão de cada fase do pipeline, há uma pausa no checkpoint aguardando sua confirmação. Esta é a linha de defesa da qualidade, permitindo que você detecte problemas no início e evite que erros se propaguem para fases subsequentes.

Se um problema for detectado nesta fase, basta reexecutar a fase atual; se descoberto apenas no final, pode ser necessário reverter várias fases, desperdiçando muito tempo e tokens.

Como Fazer

Ao confirmar cada checkpoint, verifique o seguinte:

Checkpoint da Fase Bootstrap:

• [ ] A definição do problema em input/idea.md está precisa
• [ ] O perfil do usuário-alvo está claro e específico
• [ ] A proposta de valor principal está definida
• [ ] As suposições são razoáveis

Checkpoint da Fase PRD:

• [ ] As histórias de usuário estão claras, com condições de aceitação
• [ ] A lista de funcionalidades não excede 7 itens (princípio do MVP)
• [ ] Os não-objetivos (Non-Goals) estão claramente listados
• [ ] Não inclui detalhes técnicos (como React, API, banco de dados)

Checkpoint da Fase UI:

• [ ] A estrutura das páginas é razoável, não mais que 3 páginas
• [ ] O protótipo pode ser visualizado no navegador
• [ ] O fluxo de interação está claro
• [ ] O estilo visual é distinto (evita o estilo comum de IA)

Checkpoint da Fase Tech:

• [ ] A escolha da stack tecnológica é razoável e alinhada com o princípio do MVP
• [ ] O design do modelo de dados é simples, não mais que 10 tabelas
• [ ] A lista de endpoints da API está completa
• [ ] Não introduz microsserviços, cache ou outros designs excessivos

Checkpoint da Fase Code:

• [ ] A estrutura do código frontend e backend está completa
• [ ] Inclui casos de teste
• [ ] Não há tipos any óbvios
• [ ] Inclui README.md explicando como executar

Checkpoint da Fase Validation:

• [ ] O relatório de validação não contém problemas de segurança graves
• [ ] A cobertura de testes é > 60%
• [ ] A instalação de dependências ocorre sem conflitos
• [ ] A verificação de tipos TypeScript passa

Checkpoint da Fase Preview:

• [ ] O README.md contém instruções completas de execução
• [ ] A configuração Docker pode ser construída normalmente
• [ ] Os serviços frontend e backend podem ser iniciados localmente
• [ ] Inclui instruções de configuração de variáveis de ambiente

Fluxo de Confirmação do Checkpoint

Em cada checkpoint, o sistema oferece as seguintes opções:

• Continuar: Se o resultado estiver conforme o esperado, prossiga para a próxima fase
• Tentar Novamente: Se houver problemas no resultado, forneça feedback e reexecute a fase atual
• Pausar: Se precisar de mais informações ou quiser ajustar a ideia, pause o pipeline

Princípios de Decisão:

• ✅ Continuar: Todos os itens de verificação atendem aos requisitos
• ⚠️ Tentar Novamente: Problemas menores (formato, omissões, detalhes) que podem ser corrigidos imediatamente
• 🛑 Pausar: Problemas graves (direção errada, escopo fora de controle, incapacidade de correção) que requerem replanejamento

Alerta de Armadilha

Erro Comum

Não pule a confirmação do checkpoint apenas para "terminar logo"!

O pipeline foi projetado para "pausar e confirmar em cada fase" justamente para que você detecte problemas a tempo. Se você tiver o hábito de clicar em "continuar", e só descobrir problemas no final, pode ser necessário:

• Reverter várias fases
• Reexecutar grande parte do trabalho
• Desperdiçar muitos tokens

Lembre-se: O tempo investido na confirmação do checkpoint é muito menor que o custo de refazer tudo.

---

Técnica 3: Utilize Não-Objetivos para Controlar o Escopo

Por Quê

Os não-objetivos (Non-Goals) são a arma principal do desenvolvimento MVP. Listar claramente o que "não será feito" pode efetivamente prevenir a expansão do escopo.

A raiz do fracasso de muitos projetos não é ter poucas funcionalidades, mas ter funcionalidades demais. Cada nova funcionalidade aumenta a complexidade, o tempo de desenvolvimento e os custos de manutenção. Definir limites claros e focar no valor central é a chave para entregar rapidamente.

Como Fazer

Na fase Bootstrap, liste claramente os não-objetivos:

## Não-Objetivos (Funcionalidades Não Incluídas Nesta Versão)

1. Não suporta colaboração multiusuário
2. Não suporta sincronização em tempo real
3. Não suporta integração com serviços de terceiros (como pagamento, mapas)
4. Não fornece análise de dados ou funcionalidades de relatórios
5. Não inclui funcionalidades de compartilhamento social
6. Não requer autenticação ou login de usuário

Na fase PRD, inclua os não-objetivos como um capítulo independente:

## Não-Objetivos (Explicitamente Não Incluídos Nesta Versão)

As seguintes funcionalidades, embora valiosas, não estão no escopo deste MVP:

| Funcionalidade | Motivo | Planejamento Futuro |
| --- | --- | --- |
| Colaboração multiusuário | Foco em usuários individuais | Considerar na v2.0 |
| Sincronização em tempo real | Aumenta complexidade técnica | Considerar se houver feedback forte dos usuários |
| Integração de pagamento | Não é valor central | Considerar na v1.5 |
| Análise de dados | Não necessário para MVP | Considerar na v2.0 |

Critérios de Julgamento para Não-Objetivos

Como determinar se algo deve ser um não-objetivo:

• ❌ Esta funcionalidade não é essencial para validar a ideia central → Defina como não-objetivo
• ❌ Esta funcionalidade aumentará significativamente a complexidade técnica → Defina como não-objetivo
• ❌ Esta funcionalidade pode ser substituída por métodos manuais → Defina como não-objetivo
• ✅ Esta funcionalidade é a razão de existir do produto → Deve ser incluída

Alerta de Armadilha

Armadilha de Expansão de Escopo

Sinais comuns de expansão de escopo:

1. "Já que é simples, vou adicionar rapidamente..."
2. "Os concorrentes têm esta funcionalidade, nós também precisamos..."
3. "Os usuários podem precisar, é melhor fazer logo..."
4. "Esta funcionalidade é interessante, pode destacar o produto..."

Quando tiver essas ideias, faça três perguntas:

1. Esta funcionalidade é útil para validar a ideia central?
2. Se não fizer esta funcionalidade, o produto ainda funcionará?
3. Adicionar esta funcionalidade vai atrasar a entrega?

Se as respostas forem "não", "sim" e "sim", então coloque-a decididamente nos não-objetivos.

---

Técnica 4: Iteração Gradual e Validação Rápida

Por Quê

O conceito central do MVP (Produto Mínimo Viável) é validar ideias rapidamente, não fazer tudo perfeito de uma vez.

Através do desenvolvimento iterativo, você pode:

• Obter feedback dos usuários no início
• Ajustar a direção a tempo
• Reduzir custos irrecuperáveis
• Manter o impulso de desenvolvimento

Como Fazer

Etapas do desenvolvimento iterativo:

Primeira Rodada: Validação da Funcionalidade Central

1. Use o AI App Factory para gerar a primeira versão da aplicação
2. Inclua apenas as 3-5 funcionalidades mais centrais
3. Execute e teste rapidamente
4. Mostre o protótipo a usuários reais e colete feedback

Segunda Rodada: Otimização Baseada no Feedback

1. Com base no feedback dos usuários, determine os pontos de melhoria de maior prioridade
2. Modifique input/idea.md ou artifacts/prd/prd.md
3. Use factory run <stage> para reexecutar a partir da fase correspondente
4. Gere a nova versão e teste

Terceira Rodada: Expansão de Funcionalidades

1. Avalie se os objetivos centrais foram alcançados
2. Selecione 2-3 funcionalidades de alto valor
3. Gere e integre através do pipeline
4. Continue iterando e refinando gradualmente

Exemplo Prático de Iteração

Cenário: Você quer criar um aplicativo de gerenciamento de tarefas

Primeira Rodada MVP:

• Funcionalidades centrais: criar tarefas, visualizar lista, marcar como concluída
• Não-objetivos: gerenciamento de membros, controle de permissões, notificações de lembrete
• Tempo de entrega: 1 dia

Segunda Rodada de Otimização (baseada no feedback):

• Feedback dos usuários: querem adicionar etiquetas às tarefas
• Modificar o PRD, adicionar funcionalidade de "classificação por etiquetas"
• Reexecutar o pipeline a partir da fase UI
• Tempo de entrega: meio dia

Terceira Rodada de Expansão (após validação bem-sucedida):

• Adicionar funcionalidade de gerenciamento de membros
• Adicionar lembretes de prazos
• Adicionar funcionalidade de comentários em tarefas
• Tempo de entrega: 2 dias

Checkpoint ✅

Antes de cada iteração, verifique:

• [ ] A nova funcionalidade está alinhada com o objetivo central
• [ ] A nova funcionalidade tem suporte de demanda dos usuários
• [ ] A nova funcionalidade aumentará significativamente a complexidade
• [ ] Há critérios de aceitação claros

---

Técnicas Avançadas

Técnica 5: Economize Tokens Dividindo Sessões

Por Quê

Executar o pipeline por longos períodos leva ao acúmulo de contexto, consumindo muitos tokens. A execução em sessões divididas permite que cada fase tenha um contexto limpo e exclusivo, reduzindo significativamente os custos de uso.

Como Fazer

Em cada checkpoint, escolha "Continuar em Nova Sessão":

# Execute em uma nova janela de terminal
factory continue

O sistema automaticamente:

1. Lê .factory/state.json para restaurar o estado
2. Inicia uma nova janela do Claude Code
3. Continua a partir da próxima fase a ser executada
4. Carrega apenas os arquivos de entrada necessários para aquela fase

Comparação:

Método	Vantagens	Desvantagens
Continuar na Mesma Sessão	Simples, não precisa trocar de janela	Acúmulo de contexto, alto consumo de tokens
Nova Sessão	Cada fase tem contexto limpo exclusivo, economiza tokens	Precisa trocar de janela

Prática Recomendada

Para projetos grandes ou com orçamento limitado de tokens, recomendamos fortemente o uso de "Continuar em Nova Sessão".

Para instruções detalhadas, consulte o tutorial de Otimização de Contexto.

---

Técnica 6: Lidar com Falhas e Novas Tentativas

Por Quê

Durante a execução do pipeline, podem ocorrer falhas (entrada insuficiente, problemas de permissão, erros de código, etc.). Entender como lidar com falhas permite que você recupere o progresso mais rapidamente.

Como Fazer

Melhores práticas para tratamento de falhas (referência failure.policy.md:267-274):

1. Falha Antecipada: Detecte problemas o mais cedo possível para evitar desperdiçar tempo em fases subsequentes
2. Logs Detalhados: Registre informações de contexto suficientes para facilitar a investigação de problemas
3. Operações Atômicas: A saída de cada fase deve ser atômica, facilitando o rollback
4. Preservar Evidências: Arquive os produtos de falha antes de tentar novamente, facilitando análise comparativa
5. Tentativas Graduais: Ao tentar novamente, forneça orientações mais específicas em vez de simplesmente repetir

Cenários Comuns de Falha:

Tipo de Falha	Sintoma	Solução
Saída Ausente	input/idea.md não existe	Tentar novamente, verificar caminho de escrita
Expansão de Escopo	Número de funcionalidades > 7	Tentar novamente, solicitar redução para MVP
Erro Técnico	Falha na compilação TypeScript	Verificar definições de tipos, tentar novamente
Problema de Permissão	Agente tenta escrever em diretório não autorizado	Verificar matriz de limites de capacidade

Lista de Verificação para Recuperação de Falhas:

• [ ] A causa da falha foi identificada
• [ ] A solução de correção foi implementada
• [ ] As configurações relevantes foram atualizadas
• [ ] Reiniciar a partir da fase que falhou

Falhas São Normais

Não tenha medo de falhas! O AI App Factory foi projetado com um mecanismo completo de tratamento de falhas:

• Cada fase permite uma tentativa automática
• Produtos de falha são automaticamente arquivados em artifacts/_failed/
• É possível reverter para o checkpoint de sucesso mais recente

Ao encontrar uma falha, analise calmamente a causa e siga a estratégia de falha apropriada.

---

Resumo da Lição

Esta lição apresentou as seis melhores práticas do AI App Factory:

1. Descrição Clara do Produto: Descreva detalhadamente o público-alvo, problema central, funcionalidades-chave e restrições
2. Confirmação Cuidadosa nos Checkpoints: Verifique a qualidade da saída após cada fase para evitar acúmulo de erros
3. Utilize Não-Objetivos para Controlar o Escopo: Liste claramente as funcionalidades que não serão feitas para prevenir expansão do escopo
4. Iteração Gradual: Valide primeiro a ideia central e depois expanda gradualmente com base no feedback dos usuários
5. Economize Tokens Dividindo Sessões: Crie novas sessões em cada checkpoint para reduzir custos
6. Trate Falhas Corretamente: Utilize o mecanismo de tratamento de falhas para recuperar o progresso rapidamente

Seguindo estas melhores práticas, sua experiência com o AI App Factory será mais fluida, a qualidade das aplicações geradas será maior e a eficiência de desenvolvimento aumentará em várias vezes.

---

Próxima Lição

Na próxima lição, aprenderemos sobre a Referência de Comandos CLI.

Você vai aprender:

• Todos os parâmetros e opções do comando factory init
• Como o comando factory run inicia a partir de uma fase específica
• Como o comando factory continue cria uma nova sessão para continuar
• Como factory status e factory list visualizam informações do projeto
• Como factory reset redefine o estado do projeto

---

Apêndice: Referência de Código-Fonte

Clique para expandir e ver a localização do código-fonte

Última atualização: 2026-01-29

Funcionalidade	Caminho do Arquivo	Linhas
Técnicas de Descrição do Produto	README.md	186-210
Mecanismo de Checkpoints	agents/orchestrator.checkpoint.md	98-112
Controle de Não-Objetivos	README.md	199-203
Estratégia de Tratamento de Falhas	policies/failure.policy.md	267-274
Isolamento de Contexto	policies/context-isolation.md	10-42
Padrões de Código	policies/code-standards.md	Completo

Constantes Principais:

• MAX_RETRY_COUNT = 1: Cada fase permite uma tentativa automática por padrão

Regras Principais:

• Quantidade de funcionalidades Must Have ≤ 7 (princípio do MVP)
• Quantidade de páginas ≤ 3 (fase UI)
• Quantidade de modelos de dados ≤ 10 (fase Tech)
• Cobertura de testes > 60% (fase Validation)