IA e Design Docs: O sofrimento acabou

Se você é desenvolvedor e provavelmente já deva ter mexido ou tá desenvolvendo usando inteligência artificial, eu acredito que você já deva ter tido momentos de amor e ódio pela inteligência artificial. Momentos que ela cria aquele código que você fala: "Eu sou o cara mais produtivo do mundo", mas também momentos que ela sai fazendo uma besteira danada de forma irresponsável e acaba te deixando na mão. Isso gera uma frustração e até ansiedade, vamos dizer assim.

O fato é que eu gastei aí, eu acho que mais de 1000 horas na frente do computador, trabalhando firme, estudando muito forte sobre a e eu digo que eu acabei pegando bastante o jeito e entendendo bem como é que ela funciona. E nesse vídeo eu vou passar um item de um workflow que eu acabei montando para você desenvolver softwares guiados, orientados a inteligência artificial, que vai minimizar bastante esses riscos que você tem de alucinação e fazer com que a IA, no final das contas, ela saia destruindo o seu código, deixando você ainda mais nervoso e aí mais atrapalhando do que ajudando. Mas antes da gente ir direto ao assunto, eu queria aproveitar esse momento para pedir para você dar um like nesse vídeo.

ah, se inscrever no nosso canal e saiba que aqui na Full Cycle a gente tem um curso chamado curso Full Cycle 4. 0, que um dos pilares agora do curso é inteligência artificial. Como um desenvolvedor consegue trabalhar com inteligência artificial para aumentar a produtividade da forma que ele nem consegue imaginar.

Então, se você quer saber mais sobre isso, clica no link aqui abaixo. A gente também tem MBA em arquitetura, pós-graduação de desenvolvedor para se tornar tech lead, até mesmo pós-graduação na linguagem GO. Então, o link tá aqui embaixo, clica, vamos bater um papo.

Quero entender esse momento profissional, quem sabe você não vem aí estudar com a gente. Beleza? Mas galera, o lance é o seguinte, sem mais delongas, tá?

Trabalhar com inteligência artificial nos dias de hoje é basicamente ter um workflow, ter uma forma bem organizada e estruturada para que ela entenda como você trabalha e para que ela entenda realmente o que você quer. Eu acredito que você já saiba, saber o que pedir, como pedir pra inteligência artificial é uma das coisas mais importantes. Entender de prompts é muito importante.

Quando eu ouvia falar no passado engenharia de prompt, isso me dava até gastura de pensar que já era mais uma buz word que os caras estavam criando. Quando eu comecei ler e entender paper por paper científico de como esses prompts funcionam, eu percebi que eu tava arranhando apenas ali a ponta do iceberg. Hoje eu acabei conseguindo, né, trabalhar de uma forma muito mais precisa com o IA através de um framework, né, vamos dizer assim, um workflow que eu acabei ah adotando para mim, tá?

Ah, e eu quero compartilhar aqui com vocês e mostrar um único item desse cara aqui, beleza? Ah, inclusive, deixa aí no comentário para eu saber como você tá trabalhando com ia hoje. Você tá no modo go horse, você já tem uma metodologia, qual IDE que você tá usando?

Você tá usando VS Code com GitHub Copilots? Tá usando Jet Brains? Tá usando Cursor?

Deixa aí o comentário e eu quero saber a sua relação de amor e ódio que você tem com inteligência artificial nos dias de hoje. Vamos ali ver. Mas pessoal, vamos ajustar as expectativas do que você vai ver nesse vídeo, beleza?

Bom, primeiramente eu vou falar para vocês desse workflow que eu tenho utilizado para trabalhar ah com inteligência artificial para mundo do desenvolvimento, né? A gente vai falar também sobre design docs, tipos de documentos para que você entenda o que é importante, o que não é importante para um projeto, para você não gastar seu tempo. Aí eu vou mostrar para vocês alguns assistentes que eu criei que vão gerar essas documentações e eu vou mostrar essas documentações no cursor, num projeto para que você entenda como que tudo isso acaba se conectando.

Fechou? Então vamos lá, pessoal, rapidamente aqui. Workflow de IA para desenvolvedores.

Isso aqui é basicamente como eu trabalho nos dias de hoje depois de todas as batidas de cabeça que eu acabei tendo. Então eu começo a perceber que quando você cria um projeto, você vai precisar de uma das coisas mais importantes que você vai ter, que é documentação. Parece algo chato, mas quando você entende, tá, que documentação ele é um ativo para você, igual um teste, não tem mais a desculpa para você não ter.

Sabe quando você trabalha com teste e quando você cria esse teste no dia um do seu projeto, quando você tiver 5 anos de projeto, esse teste ainda vai te ajudar para que o seu projeto não quebre lá na frente as documentações, né? E você tem que saber quais e o por e quando você vai utilizar, elas fazem exatamente isso hoje em dia no mundo da IA, tá? Ela é um ativo que você tem que ter.

O ponto é que você tem que saber criar rapidamente isso de uma forma que faça sentido e que não atrapalhe o tempo de desenvolvimento do seu software, tá? Primeira parte é essa. Segunda parte, implementação, tá?

Como que eu implemento softwares utilizando inteligência artificial? Quais são as fases que você utiliza? Qual o workflow que você utiliza?

Tem bastante coisa que você faz para conseguir trabalhar a implementação. Você tem a parte de code review, né? Porque depois que você implementa o seu par, você mesmo, né?

Outros desenvolvedores vão fazer o code review. E para fazer esse code review você consegue fazer com uma agilidade danada, desde que você tenha um workflow decente para realizar. e também toda a parte de correção de software que você vai ter, tanto para softwares que já existem, que você tá chegando no projeto, como softwares ah que estavam sendo desenvolvidos ali, achou um bug e tem que corrigir, tá?

Hoje a gente vai focar nesse cara aqui, design Docs. E eu quero explicar para vocês claramente que documentação não é algo tão ah um bicho de sete cabeças e tão chato. Você vai entender que isso é tão importante como desenvolver um teste ali no seu software.

O ponto é que você não precisa de documentação para tudo em todas as situações, tá? você tem que ponderar o tamanho do projeto, para que que esse projeto e para que que essa documentação ela vem ali para te ajudar. Então vamos percorrer rapidamente esses tipos de documentação, somente para você ter uma ideia, e depois a gente vai para um assistente que eu criei aqui, beleza?

Então o seguinte, existem documentações focadas muito mais no lado do produto, ou seja, no que o software faz, tá? E essa documentação normalmente ela é criada por pessoas de produto, mas você desenvolvedor também pode criar para conseguir dar contexto pra sua inteligência artificial baseado nas na nas especificações que foram dadas ali para você. Quais são esses tipos de documentação?

Tem várias, mas eu separei aqui as principais que eu acredito. Uma, PRD, products documents, ou seja, ela vai fazer uma definição de alto nível do que se trata o projeto, seus requisitos funcionais, não funcionais, as restrições de negócio, as restrições de tecnologia e tudo mais. Você tem a TRD, que é technical reference documents.

Esse tipo de documentação, ela especifica mais tecnicamente como que o seu software vai comunicar com outros softwares, com outros componentes, quais são as APIs, end points, contratos. Ou seja, é um documento mais técnico, mas ele deixa claro como o seu software ele vai falar. Basicamente é isso.

Nós temos aqui a FRD, que é functional requirements document, que vai detalhar para você ainda mais em aspectos um pouco mais de baixo nível como que vai ser os requisitos, né? como que vai funcionar o seu software passo por passo. Obviamente que você não precisa dar o detalhe do detalhe, mas como que aquele módulo, como que aquela funcionalidade, aquela feature vai funcionar, isso aí é importante.

E tem também muitas empresas que trabalham com users e stories, porque é uma forma bem interessante da área de produto conseguir comunicar com a área de desenvolvimento através de histórias, né? quando, como, onde, em qual situação, você vai contando uma história e baseado nessa história a gente consegue fazer implementações. Então isso aí é importante para contextualizar o que vai ser feito.

Uma outra coisa que nesse caso aí é importantíssimo são decisões técnicas, porque até aqui a gente tem um pouco de documentação técnica, mas é muito mais referente ao produto em si, tá? Aqui nessa categoria de decisão técnica, a gente tem dois documentos que são importantes, obviamente que podem ter muito mais. Eu tô trazendo o que a gente, que eu vejo mais utilizar no mercado, um RFC, eu acredito que você já devo ter ouvido falar, que é o famoso request for comments.

Normalmente, eu acho que é muito comum você BRFC, projetos open source, querem fazer uma mudança técnica, uma nova melhoria, uma mudança ah que afeta muitas vezes coisas. A pessoa que quer fazer aquela mudança cria um documento, coloca todas as justificativas, a ideia como é que vai ficar, como é que não vai ficar e tudo mais e manda isso para comentários para outros desenvolvedores, para as pessoas das equipes, para comentarem e gerar uma discussão em cima até esse documento ele ficar ali bem próximo da decisão final de como que as coisas vão ser implementadas. Tendo, né, esse request for comments, existem duas situações.

Uma situação onde o request for comments, quando ele é considerado aprovado, significa que aquela própria documentação dele já é a decisão final. Mas você pode fazer isso em duas etapas ou apenas não usar RFC e utilizar um documento chamado de ADR, que é Architectural Decision Record, que é basicamente, tá, um documento bem simples que sim, que vai mostrar ali o porqu uma decisão técnica foi tomada, porque aquele banco de dados foi escolhido, porque o Cash vai ser utilizado daquela forma, porque aquela biblioteca vai ser utilizada, o porquê das coisas e ali vai ser, vai trazer a contextualização, vai falar a decisão técnica, vai falar se essa decisão tá em vigor ou não, né, vai trazer os pontos positivos e vai trazer os riscos também e pontos que você consegue mitigar esses riscos. Por quê?

Toda vez que você cria e toma uma decisão, se você não souber o lado ruim dessa decisão é porque você não tá pronto para tomar essa decisão técnica. E esses documentos eles forçam a você a pensar que você tá tomando a decisão correta, mas que você esteja claro dos riscos que ela pode trazer também pro seu projeto, tá? Outro ponto aqui é engineering guidelines.

Todo projeto tem que ter guidelines para ele ser desenvolvido. O que que significa? Como que vai ser o padrão de código, né?

quais vão ser as as boas práticas que a gente vai utilizar, como que a equipe de engenharia vai trabalhar em determinadas situações, como que a gente vai trabalhar, estabelecer as pontos de segurança básica. E obviamente, né, se você tiver numa empresa onde a parte de compliance, de segurança for muito grande, essa parte de segurança ela acaba tendo a sua própria categorização, tá? Mas isso aí é um ponto importante.

Outra coisa, como são feitos code reviews, como são desenvolvidos os testes, como é que vão funcionar as pipelines, o processo de aprovação. Então esses tipos de coisas são extremamente importantes. Como que você vai fazer uma PR?

Então tudo isso acaba entrando em engineering guidelines, beleza? Ah, aí a gente tem também decisões arquiteturais. E o ponto aqui, galera, é importante você entender o seguinte.

Você não precisa, e eu quero deixar muito claro isso aqui para vocês, ter tudo isso de documentos, mas uma vez que você sabe as possibilidades que você tem, você pode escolher fazer um blend de quais documentos você quer no seu projeto, tá? Tô deixando bem claro para ninguém sair falando que o Wesley escreveu aí que você tem que ter 10. 000 documentos para trabalhar com IA, não é isso.

Mas você sabendo quais documentos existem, você sabe qual você vai usar no contexto, no tamanho do seu projeto. Beleza? Aqui a gente tem documentos de design e arquitetura, tá?

Tem gente que acredita que arquitetura é design. Eu não vou entrar na discussão se arquitetura e design são coisas diferentes ou são coisas iguais. Isso é um consenso aí que nunca todo mundo acaba chegando.

Existem muitas decisões acaloradas em relação a isso. Mas uma coisa é importante, você pode ter e recomendo principalmente para microsserviços ou ecossistemas muito grandes, documentos de system design, onde você tem uma visão high level mesmo de como o seu projeto ele funciona, como ele se comunica, quais são os componentes ali que ele acaba trabalhando. Mas você também pode ter documentos de baixo nível, onde você mostra em relação até em componentização, às vezes em classes ou coisas desse tipo, como o seu documento, né, como que a sua aplicação ela vai acabar funcionando.

E se você consegue entender bem desses componentes, fica muito claro, né, as barreiras, como que as coisas funcionam dentro do seu software e obviamente é importante pro seu time e a e a própria inteligência artificial entender um pouco mais dessas barreiras. E também a gente começa a ter modelo C4, onde a gente tem contex, container, component, code. A gente fala bastante disso inclusive no nosso MBA.

Então são documentos que apesar de um documento como C4, ele ser um documento visual, hoje em dia você consegue criar essa, vamos dizer, visão utilizando, sei lá, por exemplo, plento, representar aquela visão gráfica, ou seja, a própria IA consegue entender um C4 através do código dela. Então isso é bem importante para você se ligar, tá? Então, se liga, design e arquitetura também é importante e também a gente pode ter documentos de operação e infraestrutura, tá?

Como é que vai funcionar a sua estreira de CD, como que a gente vai trabalhar com pontos operacionais, né? Como que eu rodo o sistema, como que eu reinicio o sistema, quando der um problema, né? Como que eu consigo ter respostas de incidentes, né?

Como que eu posso fazer um pósmorting, ou seja, tem muita coisa interessante desde documentos de infraestrutura. Novamente, galera, tô mostrando aqui para vocês as possibilidades que você tem de coisas que são úteis, que são ativos pro seu projeto e que a sua IA ela pode te ajudar com isso. Agora, na prática, como que eu crio esses caras?

Dá trabalho criar qual o tamanho desses documentos? Obviamente vai depender da complexidade do software, mas existem formas que faz com que essa complexidade ela diminua bastante. Aqui eu tenho nesse caso o chat GPT aqui onde você pode dar uma olhada, mas a grande sacada nesse caso é que eu criei através de prompts e novamente galera, uma das coisas mais importantes que você tem que entender quando fala de inteligência artificial é entender sobre prompt.

Galera, muda a sua vida, acredite, né? Existem diversos tipos de prompts para cada caso de uso específico. Pra documentação você usa um prompt, pra implementação você usa outro prompt.

Pra correção de bug é um outro prompt. E esses prompts eles têm, por exemplo, encadeamentos, chafts, tree of thoughts, a advance, ah, reacting, você tem zero shot, f shot, one shot. Tem diversos tipos ali de prompts específicos para você conseguir trabalhar aqui, tá?

Eu tenho, por exemplo, um context generator, ou seja, é um documento que vai meio que gerar o seu PRD para ir a entender o contexto do seu projeto. Eu tenho aqui um ADR generator. Eu posso falar: "Quero criar uma ADR sobre a utilização do Reds como cash, certo?

Eu não vou ficar criando documentação aqui na frente, mas eu quero que você entenda a ideia de como que você pode trabalhar com esses documentos. Aqui ele fala, ó, antes de começar, você pode falar um pouco sobre sobre o seu projeto? Eu vou falar.

É um e-commerce desenvolvido em GO, mas nessa parte vamos fazer o a o catálogo e precisamos de cash. Tô escrevendo qualquer coisa aqui. Que que acontece baseado nisso, esse cara ele começa a perguntar, a confirmar a informação e você vai iterando, tá?

E você vai perceber que muitas vezes em poucos minutos, você consegue trabalhar com isso. Só para esclarecer, sim é que você já possui uma estrutura de de ADR ou criar do zero. Vou colar criar do zero.

Olha só, eu fui dando sim aqui porque eu tô falando com você, então ah, a gente acaba não prestando atenção. Aí ele vai sugerir até modelos mais detalhados ou modelos básicos de ADR que eu posso trabalhar, por exemplo. Ah, eu vou colocar sim, pode usar esse modelo.

E a partir de agora a gente vai discutir sobre desde o título da ADR, tá? ou até mesmo as decisões, os motivos e tudo mais. Você gostaria de usar esse título, ó, uso do Reds como cash pro catálogo de produtos?

Sim. Então você começa a perceber que as coisas elas começam a ficar um pouco mais simples pra gente trabalhar. Qual é o contexto?

O catálogo tem ataxa de leitura, a lentidão do banco de dados? Vocês esperam escalar o serviço? Existem restrição de latência?

Tudo isso e a restrição de latência é exposta em 50 msegundos. Então tô tentando adiantar aqui somente para você entender a ideia. Então, olha só, ele gerou o contexto.

Catálogo de produtos será um componente essencial com alta taxa de leitura em períodos de pico, promoções, a consulta direto no banco. Além disso, espero que o sistema escale horizontalmente. Então, perceba que ele tá gerando o contexto e ele confirma comigo se eu quero isso ou se eu quero alterar.

E aí eu vou seguindo nesse fluxo até eu ter um documento mais ou menos dessa forma aqui. Deixa eu abrir meu cursor para você. Então, se você olhar, eu tenho um contexto de um projeto que eu fiz através daquele geração de contexto.

Então, eu tenho contexto e visão geral, o problema que eu tenho, os objetivos e os resultados que eu espero, indicador de sucesso, o que para mim faz com que eu tenha certeza que esse meu projeto deu certo. Isso aqui, galera, é outcome que a IA vai olhar e falar: "O meu software só tá funcionando se isso aqui tiver funcionando. " Quais são os escopos, né?

O que tá fora do escopo? Qual que é arquitetura e abordagem técnica? Quais são as dependências?

Quais são as restrições? Quais são os riscos, as observações. Mas além disso, eu posso ter documentos, como, por exemplo, a estratégia de, nesse caso, de qual estratégia de de rate limiting que eu vou usar?

Então, uso de leak bucket, né? Qual é o contexto, qual a decisão, né? Como que vai ser a implementação, concorrência, consequência, positiva, negativa.

Galera, isso é um ativo pro seu projeto, porque isso vai ser guardado para sempre. 5 anos depois a gente sabe o porque essa decisão foi tomada. E essa se essa decisão ela está ah deprecada, se ela foi aceita, quando ela não foi, se ela foi substituída por alguma outra, que você pode colocar o link aqui embaixo e tudo isso aá gerando para você.

Agora, sabe o que é mais interessante? Uma vez que você tem essas documentações ou você tem até uma base de código, você pode chegar, por exemplo, para um cursor da vida e falar o seguinte, ó, gera as minhas regras. O cursor hoje em dia ele tem recursos que é chamado de generate rules, tá?

Vou colocar aqui, ó, generate cursor rules. Quando você dá um enter ou até mesmo fala algo, vou colocar utilização do Reds, o que que ele vai fazer? Ele vai entender o seu código, tá?

Vai ler todos os seus arquivos. E baseado nesses arquivos que ele lê, o que que ele vai fazer? Ele vai criar arquivos aqui mostrando, né, como que a Iala deve se comportar para aqueles tipos de implementação.

Por exemplo, ah, como que eu vou trabalhar com o rate limiting, a implementação, né? Então essa regra foi gerada pelo cursor, mas esses detalhes foram utilizados pelo código que eu tinha, mas também pela documentação. Então a partir daqui já fica muito claro o que a Soia pode ou não fazer simplesmente gerando essas regras.

Então entende, baseado num documento, eu consigo gerar regras, eu consigo ter mais controle da minha IA e fazendo esse tipo de controle, simplesmente o meu jogo ele acaba mudando, porque eu sei o que eu tenho que fazer, né? a IA ela tem uma clareza muito maior, mas somente isso eu já digo para você que não é o suficiente, tá? Que ele trouxe uma sugestão de utilização do Reds, tá?

Então, ó, ele entendeu a escolha do Reds, o modelo que a gente vai trabalhar, por exemplo, a o script para trabalhar com lua, né, para eu trabalhar de forma atômica. É super importante isso pra gente conseguir trabalhar e evitar problemas de concorrência. Então aqui ele trouxe sugestões, óbvio que eu vou revisar e vou trabalhar com isso aqui, mas perceba que as regras do jogo vão ficar bem mais claras.

Pessoal, como eu disse para você, isso aqui não é tudo. Você precisa, de uma forma geral, ter processos de implementação com IA. A documentação é a primeira fase.

A segunda fase é a implementação. E para ter essa implementação, você tem todos esses pontos que você tem que percorrer, porque cada desses tem uma forma de trabalhar com a quando você entende esse framework, você vai perceber que isso entra no piloto automático, você é muito produtivo e você minimiza muito o risco da IA fazer besteira. Ela ainda faz besteira?

Faz, mas muito menos do que você sair escrevendo para ela melhorar ou implementar uma feature. O o nível do jogo muda e conforme o tempo vai passando e cada dia mais a IA, né, ela vai melhorando, né, ali para você, o que que isso vai significar? Que o nível de precisão seu vai aumentar para caramba.

Então, se você quer trabalhar muito bem com IA hoje, tente ter um framework, um workflow, né? e pontos como eu coloquei aqui para você, comece a fazer seus testes, você vai ver que o seu projeto ele vai mudar da água pro vinho. E óbvio, né, se você quer aprender mais sobre isso, clica no link aqui abaixo.

Nos nossos cursos, a gente tá adicionando pilares bem fortes de A para você conseguir fazer exatamente isso que eu tô falando aqui para você. Fechou? Eu também quero que você deixe um comentário de como você tá trabalhando com IA hoje, se tá sendo produtivo, se tá sendo improdutivo, se você passa raiva, se você não passa raiva, como que se você faz algo parecido com o que eu tô fazendo, deixa aí um comentário, eu quero entender como é que você tá trabalhando.

Fechou? É isso aí, galera. Então, até o nosso próximo vídeo aqui no canal Full Psycho.

Um abraço aí para vocês.