PRD + SPEC: Os 2 Documentos que Mudam Tudo no AI Coding

A Importância da Especificação Técnica (SPEC)

O que é a SPEC?

• A SPEC é uma especificação técnica de um projeto, essencial para o desenvolvimento de software, e já existe há anos no setor.

• Com a chegada de novas ferramentas como cloud Code e Antigravity, muitos desenvolvedores ignoraram a importância da documentação, focando apenas na codificação.

Desafios do Desenvolvimento Sem Documentação

• Ignorar a documentação pode levar à entrega de aplicações de baixa qualidade devido à falta de contexto durante o desenvolvimento.

• O apresentador compartilha um processo básico que utiliza para desenvolver funcionalidades, visando resultados profissionais com menos retrabalho.

Apresentação do Palestrante

• Breno se apresenta como fundador da Lion Lab e diretor em tecnologia, incentivando os espectadores a interagir com o canal e compartilhar conhecimento.

Estrutura do Processo de Desenvolvimento

• O processo começa com teoria seguida pela prática; ele planeja mostrar um workflow para melhorar as especificações técnicas dos projetos.

• A abordagem "spec drive" é apresentada como uma metodologia tradicional em empresas de tecnologia antes da implementação.

Problemas com Vibe Coding

• Muitos desenvolvedores enfrentam dificuldades ao usar prompts vagos em ferramentas modernas, resultando em baixa assertividade nas entregas.

• É crucial evitar que os agentes cheguem à "dumb zone", onde não conseguem mais progredir devido à sobrecarga de informações.

Etapas do Desenvolvimento Específico

• O desenvolvimento começa com uma equipe de produto gerando um PRD (Product Requirements Document), seguido pela criação da SPEC por um profissional técnico.

• A SPEC transforma ideias comerciais em requisitos técnicos claros para os desenvolvedores implementarem sem precisar entender todos os benefícios comerciais.

Construindo Projetos com LLMs: Desafios e Estratégias

Problemas Iniciais na Construção de Projetos

• O orador discute a dificuldade de gerenciar projetos que possuem mais de 15 arquivos, enfatizando que o tempo gasto em debugging pode superar o tempo dedicado à resolução real dos problemas.

• A falta de uma especificação clara (PRD) resulta em retrabalho significativo, pois as LLMs podem gerar soluções inadequadas se não forem orientadas corretamente.

• As LLMs tendem a replicar padrões de código errôneos que encontraram durante seu treinamento, levando a erros frequentes nas implementações.

Importância da Documentação e Pesquisa

• O orador menciona que ao enviar prompts muito longos para as LLMs, elas podem pular etapas importantes no processo de desenvolvimento devido à ansiedade em entregar resultados rapidamente.

• É crucial entender o processo correto para evitar falhas; muitos desenvolvedores já aplicam boas práticas, mas é importante sempre revisar e melhorar os métodos utilizados.

Etapas Sugeridas para Desenvolvimento Eficiente

• O orador sugere três etapas principais: pesquisa (wizard), exploração do código base e geração de anotações do PRD. Isso ajuda a estruturar melhor o trabalho antes da implementação.

• Com ferramentas como cloud cowork e antigravity, é possível explorar diretamente o código sem precisar copiar e colar manualmente, facilitando a interação com as LLMs.

Implementação e Geração de Especificações Técnicas

• Ao implementar novas funcionalidades, deve-se iniciar com uma pesquisa detalhada sobre o que precisa ser feito antes de qualquer codificação efetiva.

• A documentação das decisões tomadas durante as conversas com as LLM é vital; caso contrário, informações cruciais podem ser perdidas quando se tenta gerar um PRD final.

Finalização do Processo

• Após gerar um documento inicial com as anotações discutidas, deve-se criar uma nova janela para desenvolver a especificação técnica detalhada do projeto.

• É importante manter janelas limpas ao criar especificações técnicas para evitar confusões ou perda de contexto nas interações subsequentes.

Entendendo a Precisão e Alucinação em Modelos de IA

A Importância da Precisão nos Tokens

• O apresentador discute a relação entre o número de tokens e a precisão do modelo, destacando que com 200.000 tokens a precisão é de 70%, enquanto com 1 milhão cai para menos de 50%.

• Ele menciona que isso resulta em "alucinações", onde o modelo pode gerar informações incorretas ou irreais.

Diferença entre PRD e Spec

• O apresentador explica que muitas pessoas confundem PRD (Product Requirements Document) com Spec (Specification), e se propõe a esclarecer as diferenças.

• O PRD descreve o problema, refina objetivos e define metas, focando no contexto de negócios, sem incluir detalhes técnicos.

Estrutura do PRD

• O documento deve conter user stories que refletem como os usuários interagem com o produto, proporcionando uma visão clara para a IA.

Características da Spec

• A spec é mais técnica e detalha sprints, etapas do desenvolvimento que são subdivisões das tarefas principais.

• Após aprovação do PRD, uma IA pode ser utilizada para gerar a spec automaticamente.

Uso de Formatos na Spec

• O apresentador menciona sua preferência por usar JSON nas specs, embora também utilize Markdown. Ele destaca um vídeo anterior sobre um paper da Antropic que utilizou specs em JSON.

Detalhes das Sprints e Features

• As sprints definem entregáveis específicos e critérios de aceitação para validar se o desenvolvimento está correto.

API Spec e Data Models

• A API spec deve incluir todos os endpoints necessários para integração entre front-end e back-end.

• Os data models abordam migrações e esquemas relacionados ao banco de dados.

Validação das Specs

• O apresentador enfatiza a importância de definir claramente as funções dos agentes utilizados nas sprints, cada um com responsabilidades específicas.

Exemplos Práticos na Criação da Spec

• Um exemplo prático é dado sobre como implementar autenticação com email e senha, incluindo validações necessárias no formulário.

Cenários Alternativos na Desenvolvimento

• É destacado que muitos desenvolvimentos falham em considerar cenários alternativos importantes; apenas seguir o "caminho feliz" não é suficiente.

Critérios de Aceitação Detalhados

• Para garantir um desenvolvimento completo, devem ser incluídos critérios claros como validação de email inválido ou mensagens adequadas durante erros.

Esses pontos fornecem uma visão abrangente sobre as discussões realizadas no vídeo sobre documentação técnica em projetos envolvendo inteligência artificial.

Tratamento de Erros em Especificações Técnicas

Importância do Tratamento de Erros

• Um e-mail inválido pode gerar um erro significativo, exigindo que o desenvolvedor retorne ao agente para resolver a questão. Isso destaca a necessidade de especificações técnicas bem elaboradas.

• A falta de clareza nas especificações pode resultar em ações adicionais desnecessárias durante o desenvolvimento.

Estrutura da Sprint e Critérios de Aceite

• O apresentador utiliza um formato JSON para organizar as sprints, começando pela "Sprint 001", que envolve a criação da estrutura base do projeto React.

• Cada sprint possui critérios de aceite claros, como a execução correta das funcionalidades esperadas.

Validação e Cenários de Teste

Mapeamento de Respostas da API

• É essencial mapear todas as respostas das APIs, incluindo mensagens para cenários onde ocorrem erros, como senhas ou e-mails incorretos.

• O apresentador enfatiza que é necessário comunicar claramente à IA como tratar diferentes situações.

Notas Arquiteturais e Colaboração

• O uso de templates ajuda na documentação das decisões tomadas durante as conversas com colegas, facilitando a geração posterior da especificação técnica.

Organização das Sprints

Divisão em Sprints

• As demandas são divididas em quatro sprints, cada uma com entregáveis específicos e critérios de aceite definidos.

• Um avaliador valida cada sprint antes que o trabalho avance para a próxima fase, aumentando a qualidade do produto final.

Complexidade no Desenvolvimento

• A complexidade é avaliada através do número estimado de rodadas necessárias para concluir cada tarefa. Isso pode aumentar o tempo total do desenvolvimento mas melhora a entrega final.

Geração da Especificação Técnica

Uso do Markdown e JSON

• A especificação gerada em Markdown não deve ser tratada como um único documento; ela deve ser dividida em partes menores (ou sprints).

• O apresentador menciona que é possível utilizar comandos dentro do cloud code para desenvolver cada parte separadamente.

Métricas e Melhorias Contínuas

• A coleta de métricas sobre o desempenho dos agentes permite melhorias contínuas no processo. Isso inclui ajustes nas especificações conforme necessário.

Conclusão sobre Formatos Utilizados

Flexibilidade entre Formatos

• Tanto Markdown quanto JSON são válidos; o apresentador prefere JSON por oferecer uma visualização mais clara das sprints e suas respectivas funcionalidades.

Avaliação Visual das Sprints

• A escolha pelo formato JSON facilita a visualização dos elementos dentro da sprint, permitindo melhor acompanhamento do progresso.

Como Planejar e Implementar Sprints Eficazes?

Estrutura do Processo de Desenvolvimento

• O processo começa com a entrada de uma especificação (spec MD) que gera sprints, podendo ser Jon ou não. Um arquivo de progresso é utilizado para acompanhar o desenvolvimento.

• Após enviar a tarefa ao coder, um avaliador valida os critérios da sprint. Se falhar, feedback é dado para correção; se passar, o progresso é atualizado.

• A importância do planejamento é destacada: foram necessárias 3 horas de discussão para gerar uma única feature, enquanto o desenvolvimento levou apenas 30 minutos.

Importância da Documentação

• A documentação detalhada do sistema facilita futuras implementações e garante que todos os aspectos sejam considerados durante o desenvolvimento.

• Muitos desenvolvedores não dedicam tempo suficiente ao planejamento e acabam esperando soluções rápidas sem cobrir todos os casos de uso.

Quando Usar Especificações Técnicas

• Especificações são essenciais em projetos complexos com múltiplos arquivos e lógica de negócios complicada. Para correções pontuais, pode-se usar um agente para resolver bugs específicos.

• Em situações simples ou protótipos descartáveis, as especificações podem não ser necessárias.

Consequências da Falta de Planejamento

• Ignorar a criação de especificações pode levar a problemas futuros como refatoração e sistemas quebrados. O custo dessas falhas será pago eventualmente.

• A substituição no desenvolvimento não afeta o papel do planejador ou do criador da especificação técnica; esses papéis continuam sendo fundamentais.

Workflow Proposto para Melhorar Especificações

• Um workflow foi preparado para ajudar na elaboração de melhores especificações antes do envio ao desenvolvimento.

• O apresentador sugere baixar uma ferramenta específica para avaliar as specs antes da implementação prática.

Esses pontos fornecem uma visão clara sobre a importância do planejamento cuidadoso no desenvolvimento ágil e como isso impacta diretamente na eficiência das sprints e na qualidade final dos produtos desenvolvidos.

Análise de Especificações Técnicas

Importância da Comunicação na Análise de Especificações

• O analista revisa as especificações e faz perguntas para garantir que todos os cenários sejam considerados, incluindo o "caminho feliz" e o "caminho alternativo".

• É crucial que o analista questione aspectos não abordados nas especificações, como cenários de erro, por exemplo, quando um usuário insere um e-mail incorreto.

• O analista identifica lacunas técnicas e a falta de critérios de aceitação em sprints, sugerindo a adição de casos relevantes para cada funcionalidade.

Detalhes sobre Comportamento do Jogo

• O comportamento no lançamento da bola é discutido; questões como ângulo de saída são levantadas para definir claramente a mecânica do jogo.

• A importância das perguntas feitas pelo analista é destacada, pois elas ajudam a cobrir mais cenários e evitar problemas futuros durante o desenvolvimento.

Workflow Eficiente no Desenvolvimento

• Um workflow bem estruturado pode melhorar significativamente a qualidade das especificações técnicas enviadas aos desenvolvedores.

• A IA pode ser utilizada para tarefas menores, mas sem uma validação adequada do código completo, os resultados podem ser insatisfatórios.

Planejamento e Visão de Negócio

• Um planejamento prévio detalhado permite que desenvolvedores utilizem modelos menores e menos complexos com maior eficácia.

• Desenvolvedores precisam ter uma visão clara do negócio para se adaptarem às exigências atuais do mercado.