Da ideia ao código: por que começo meus projetos por diagramas, requisitos e logs

Eu sou um desenvolvedor de meio século. Comecei na eletrônica, passei por redes de computadores, voltei com força para a programação, mas, na verdade, nunca deixei de programar. Ao longo do caminho, escrevi scripts, pequenos sistemas, ferramentas especiais, firmwares e soluções sob medida para resolver problemas reais. Depois de tantos anos transitando entre hardware, software, redes e sistemas embarcados, uma coisa ficou muito clara para mim: desenvolver bem exige planejamento.

Código não nasce apenas da vontade de programar. Código nasce de uma intenção bem compreendida. Antes de abrir o editor e sair escrevendo funções, classes, rotas, tarefas, drivers ou módulos, é preciso entender o que se pretende construir. E, para mim, uma das formas mais eficientes de organizar esse entendimento é por meio de diagramas.

Diagramas economizam muitas palavras. Um bom diagrama de blocos, por exemplo, pode explicar em poucos segundos como um sistema se organiza. Um diagrama de sequência pode mostrar como os módulos conversam entre si. Um diagrama de caso de uso ajuda a entender quem interage com o sistema e com qual finalidade. Em firmware, principalmente, uma máquina de estados bem desenhada pode evitar muitos erros de lógica, travamentos e comportamentos inesperados.

Hoje temos excelentes ferramentas para isso. Mermaid e Draw.io são dois exemplos muito úteis. O Mermaid permite escrever diagramas em texto, o que combina muito bem com documentação versionada em Git e com o uso de IA Generativa. O Draw.io, por sua vez, é uma ferramenta visual muito rica, adequada para diagramas mais livres, técnicos e detalhados. O ponto mais interessante é que essas ferramentas aproximam a diagramação do fluxo real de desenvolvimento: os diagramas podem ser escritos, lidos, revisados e até gerados por IA.

Começar pelo arquivo de requisitos

Uma prática que adoto é iniciar o desenvolvimento por um arquivo de requisitos. Mesmo quando sou o único programador envolvido, procuro registrar tudo que o cliente me disse. No início, esse conteúdo pode estar um pouco desordenado. Isso não é problema. O importante é que ele não gere confusão, contradição ou dupla interpretação.

Esse primeiro documento funciona como uma coleta bruta de intenção. É onde eu coloco as funcionalidades desejadas, restrições, observações, expectativas, regras de negócio, limitações técnicas e qualquer detalhe que tenha surgido na conversa. Depois releio, reorganizo e ajusto o texto para deixá-lo mais claro.

A partir daí, uso a IA Generativa como parceira de análise. No meu caso, utilizo a IDE Windsurf, que me permite trabalhar com diferentes modelos geradores de código. Escolho aquele que melhor lida com texto, interpretação e organização documental, e peço para gerar um documento de requisitos mais estruturado, um plano de versionamento e, pelo menos, um diagrama de caso de uso.

Em muitos projetos também peço diagramas de blocos, diagramas de sequência e máquinas de estados. Este último é especialmente importante em firmware, porque boa parte dos sistemas embarcados trabalha com eventos, transições, sensores, estados internos, temporizações e respostas condicionais.

A IA não substitui a revisão humana

Depois que a IA gera a documentação inicial, o trabalho não está concluído. Pelo contrário, é aí que começa uma etapa essencial: a revisão crítica.

Eu leio tudo que foi criado e faço perguntas. Está faltando algo? Algum requisito ficou ambíguo? Alguma regra foi inventada pela IA sem estar no pedido original? Alguma parte pode ser melhorada? Existe algum fluxo que não foi representado? O diagrama realmente reflete o funcionamento esperado?

Esse diálogo com a IA é muito produtivo quando usamos uma postura de engenharia. Não basta aceitar a primeira resposta. É preciso conversar com detalhes, pedir refinamentos, confrontar o modelo com situações de uso e validar se a documentação realmente representa o sistema que desejamos construir.

Quando tudo está mais claro, documentado e coerente, peço então que a IA comece o desenvolvimento. Mas não peço apenas o código. Peço também os testes. Para mim, código sem teste nasce frágil. Mesmo que os testes não cubram tudo no primeiro momento, eles já estabelecem uma base de verificação e ajudam a impedir que mudanças futuras destruam comportamentos já esperados.

Meu método PDCL: Plan, Do, Check, Log

O método que venho adotando pode ser chamado de PDCL. Ele é inspirado no conhecido PDCA, mas com uma adaptação importante para o desenvolvimento assistido por IA: o “L” representa o Log.

No início, fazemos o Plan, ou seja, o planejamento. É a fase dos requisitos, diagramas, organização das ideias, plano de versionamento e entendimento do problema. Depois entramos no Do, que é o fazer: implementação do código, criação dos testes, estruturação dos módulos e execução das primeiras versões funcionais.

De certa forma, já fazemos uma primeira checagem ainda na documentação. Quando revisamos requisitos, diagramas e fluxos, estamos verificando se o projeto faz sentido antes mesmo de programar. Mas a checagem real acontece quando o código começa a rodar. É nesse ponto que entra o Log.

Eu gosto de orientar a IA, desde o início, a gerar logs detalhados. No Windsurf existe um recurso muito útil chamado Rules, sobre o qual pretendo escrever em outro artigo. Com essas regras, consigo orientar o comportamento da IA durante o desenvolvimento. Uma das minhas orientações é que o código seja instrumentado com logs claros e amigáveis.

Para mim, um bom log deve conter timestamp, nome do arquivo de código, função chamada, linha aproximada ou ponto lógico da execução, nível da mensagem e um texto compreensível. Também gosto de usar emoticons, quando o contexto permite, porque eles ajudam visualmente a identificar sucesso, erro, alerta, processamento, entrada de dados, saída de dados e eventos importantes.

O log não é apenas uma mensagem jogada no terminal. Ele é uma ferramenta de raciocínio. Quando bem feito, permite reconstruir a sequência de execução do sistema. Permite entender se o código passou pelas etapas corretas. Permite localizar onde algo saiu do esperado. E, principalmente, permite que a própria IA analise o comportamento do software com base em evidências.

O log como ferramenta de checagem pela IA

Esse é o ponto central do PDCL. Quando temos logs bem estruturados, podemos pedir à IA para analisar a execução do sistema. Em vez de apenas dizer “não funcionou”, fornecemos a ela uma trilha de eventos. A IA pode verificar se a sequência está correta, se alguma função foi chamada fora de ordem, se alguma etapa foi pulada, se um valor inesperado apareceu ou se determinado módulo não respondeu como deveria.

Assim, passamos a trabalhar com a IA como um par de desenvolvimento. Alteramos o código, executamos, coletamos logs, analisamos e ajustamos. O ciclo se repete: planejamos, fazemos, checamos pelos logs e melhoramos o sistema. Se algo precisa ser corrigido, voltamos ao planejamento daquele ponto específico, ajustamos o requisito ou o fluxo, modificamos o código e verificamos novamente.

Esse processo é especialmente poderoso em sistemas embarcados. Em firmware, muitas vezes não temos uma interface gráfica rica para mostrar o que está acontecendo. O log serial, o log em arquivo, o log via rede ou até mensagens estruturadas enviadas para outro sistema podem se tornar a principal forma de entender a vida interna do programa.

Em aplicações backend, o mesmo raciocínio se aplica. Logs ajudam a rastrear requisições, validar regras de negócio, detectar gargalos, acompanhar falhas e entender a interação entre serviços. No frontend, logs bem posicionados ajudam a compreender estados da interface, eventos do usuário e falhas de comunicação com APIs.

Desenvolvimento incremental e documentação viva

Sabemos que o desenvolvimento de software é incremental. Raramente um sistema nasce completo, perfeito e fechado. O normal é que ele evolua. Novas necessidades aparecem, o cliente entende melhor o que quer, o programador descobre limitações técnicas, e a própria implementação revela melhorias possíveis.

Por isso, no meu processo, a documentação não é algo morto. Ela deve ser atualizada continuamente. Ao final de uma etapa de desenvolvimento, gosto de pedir à IA que faça uma espécie de engenharia reversa do código. Ou seja, peço para ela analisar o que foi realmente implementado e verificar se a documentação ainda está coerente.

Se durante a codificação surgiram melhorias, novas decisões arquiteturais ou ajustes de fluxo, a documentação precisa refletir isso. O arquivo de requisitos, os diagramas, o plano de versionamento e os testes devem acompanhar a evolução do código. Caso contrário, teremos um problema comum em muitos projetos: a documentação diz uma coisa, mas o software faz outra.

Quando usamos IA Generativa nesse processo, a atualização documental fica muito mais acessível. A IA pode revisar o código, sugerir ajustes nos diagramas, atualizar descrições de módulos, gerar changelogs e até propor novos testes. Mas a responsabilidade final continua sendo nossa. A IA auxilia, mas quem valida a intenção, o contexto e a qualidade da solução somos nós.

A importância dos diagramas no diálogo com a IA

Um benefício adicional dos diagramas é que eles melhoram muito o diálogo com a IA. Quando descrevemos um sistema apenas em texto, podemos acabar deixando lacunas. Já um diagrama impõe estrutura. Ele mostra relações, dependências, fluxos e fronteiras.

Se usamos Mermaid, por exemplo, podemos pedir à IA para gerar ou revisar um diagrama diretamente em texto. Isso facilita manter os diagramas dentro do repositório, junto com o código. Um diagrama de sequência em Mermaid pode documentar como uma requisição passa por uma API, chega a um serviço, consulta o banco de dados e retorna ao usuário. Uma máquina de estados pode representar o comportamento de um dispositivo embarcado em espera, leitura, processamento, transmissão e erro.

Essa capacidade de transformar requisitos em diagramas, diagramas em código, código em testes e logs em diagnóstico cria um ciclo muito produtivo. Não se trata apenas de “usar IA para programar mais rápido”. Trata-se de usar IA para pensar melhor o desenvolvimento.

Livros que reforçam essa prática

Dois livros dialogam muito bem com essa forma de trabalhar. O primeiro é “Clean Code”, de Robert C. Martin. Ele reforça a importância de escrever código claro, organizado, legível e fácil de manter. Embora o livro não seja especificamente sobre IA, seus princípios continuam muito atuais. Quando pedimos que uma IA gere código, precisamos ter critérios para avaliar se aquele código é limpo, compreensível e sustentável.

Outro livro importante é “Domain-Driven Design”, de Eric Evans. Ele nos lembra que software não é apenas tecnologia; software representa um domínio de conhecimento. Antes de programar, precisamos entender o problema, a linguagem usada pelas pessoas envolvidas e as regras que dão sentido ao sistema. Isso combina diretamente com a prática de começar pelos requisitos, conversar sobre eles, organizar o domínio e só depois partir para a implementação.

Também poderíamos citar práticas associadas a TDD, desenvolvimento incremental, arquitetura limpa e engenharia de software ágil. Mas o ponto principal é simples: bons sistemas não nascem apenas de código. Eles nascem de compreensão, documentação, validação e melhoria contínua.

Conclusão

A grande lição que aprendi ao longo da minha trajetória é que programar não é apenas escrever instruções para uma máquina. Programar é transformar intenção em estrutura. É sair de uma conversa, muitas vezes confusa e incompleta, e construir algo funcional, verificável e evolutivo.

Por isso começo pelos requisitos. Depois avanço para os diagramas. Em seguida uso a IA para organizar, revisar, propor e desenvolver. Peço testes desde o início. Oriento a geração de logs detalhados. Uso esses logs como instrumento de checagem. E, ao final de cada ciclo, atualizo a documentação com base no que realmente foi implementado.

Esse é o espírito do PDCL: Planejar, Fazer, Checar e Logar. O log não entra apenas como detalhe técnico. Ele entra como parte do método. Ele é a memória operacional do sistema, a trilha que permite entender o que aconteceu e a base para melhorar continuamente.

Com IA Generativa, esse processo se torna ainda mais forte. Mas ele exige disciplina. A IA pode acelerar o desenvolvimento, mas não substitui a clareza do engenheiro, a revisão cuidadosa, o domínio do problema e a responsabilidade sobre o resultado final. Quando unimos requisitos, diagramas, testes, logs e documentação viva, criamos um caminho muito mais seguro para desenvolver software com qualidade, velocidade e consciência técnica.