IA não entende
seu sistema
até você ensinar ela.
Como aumentar produtividade em grandes codebases com Inteligência Artificial.
Mas antes... quem sou eu? 👋
me.jpgQuem sou eu
- 💻 Software Engineer
- ⚽ Apaixonado por futebol — 10 e Faixa
- 🇾🇪 São-paulino de coração
- 🥩 Apreciador de um bom churrasco
O que faço hoje
Trabalho como Engenheiro de Software em uma fintech americana: Payabli.
Trafego de milhoes de dados, diferentes contextos, tendo que ser 100% acertivo.
Aí descobri: a IA é boa... mas precisa saber usa-la antes de qualquer coisa. 🚀
Uma experiência que TODO dev já teve.
No começo do projeto
- Você pede uma feature
- A IA entende rápido
- O código funciona de primeira
- Tudo parece mágico ✨
Quando o projeto cresce
- A IA "esquece" o que vocês combinaram
- Inventa funções que não existem
- Mistura padrões diferentes
- Repete código que já tinha
- Quebra coisa que estava funcionando 💥
Querer fazer tudo de uma vez.
login + carrinho + pagamento + admin + relatórios.
tem que tá pronto."
O que a IA faz
- Tenta tudo de uma vez
- Perde detalhes no caminho
- Mistura padrões
- Mete biblioteca aleatória
- Entrega 30% que parece 100%
Por quê?
A IA tem uma janela de contexto limitada.
Muito input ao mesmo tempo = ela se afoga.
→ Vamos voltar nesse conceito daqui a pouco. 👀
Cada conversa lembra da anterior.
Segunda
Você explica pacientemente:
- Padrão do projeto
- Onde criar arquivos
- Quais libs usar
- Regras de negócio
Terça
Nova conversa. Você explica:
- Padrão do projeto de novo
- Onde criar arquivos de novo
- Quais libs usar de novo
- Regras de negócio de novo
A IA não tem memória entre sessões.
Sua empresa não é seu projeto pessoal.
Múltiplos repos
frontend/
api/
worker/
infra/→ Onde a IA deveria criar o arquivo?
E ainda tem
A IA não tem como adivinhar isso.
→ E nada disso funciona sem revisão humana. Voltamos nisso. 🚨
O que é contexto?
Tudo que a IA precisa saber pra responder bem.
Inclui
- Histórico da conversa
- Código do projeto
- Regras de negócio
- Padrões do time
- Documentação
- Stack tecnológica
Analogia
Imagina um dev novo chegando hoje no time.
Você manda: "implementa o checkout".
Sem mostrar o repo. Sem explicar nada.
Que código ele vai entregar?
IA sem contexto = dev novo no escuro.
Janela de contexto.
Toda IA tem um limite de leitura.
Capacidade típica
- GPT-4 → ~128k tokens
- Claude → ~200k tokens
- Gemini → até 1M tokens
~ 1 token ≈ 0.75 palavra
O problema real
Quanto MAIS você joga de uma vez:
- Maior a chance de se perder
- Detalhes do meio somem
- Respostas ficam inconsistentes
Solução: dar só o que importa, na hora certa.
RAG — Retrieval Augmented Generation.
A técnica que resolve a janela de contexto.
❌ Sem RAG
Você joga TUDO no prompt:
- O repo inteiro
- Toda documentação
- Todas as regras
→ IA se afoga, custa caro, lento
✅ Com RAG
A IA busca só o que precisa:
- Indexa tudo num banco
- Consulta o que é relevante
- Carrega só o necessário
Analogia: índice de livro vs ler livro inteiro.
Skills — comportamento reutilizável.
Uma "habilidade" que a IA carrega quando precisa.
Pense em uma skill como
- 🧠 Uma "personalidade" temporária
- 📋 Conjunto de regras + instruções
- 🎯 Focada em uma tarefa específica
- ♻️ Reutilizável em qualquer projeto
Exemplo
Skill /code-review:
- Sabe o que checar
- Sabe o formato de saída
- Segue um checklist fixo
→ A IA vira um code reviewer.
O que é o ai-flow?
"Um sistema operacional para desenvolvimento com IA."
O objetivo NÃO era
- Criar um prompt melhor
- Um pacote de IA
- Mais automação aleatória
O objetivo era
CONTÍNUO
A Arquitetura do ai-flow.
Maps = memória persistente da IA.
Estrutura
MAPS/{projeto}/
├── map.json
├── context.md
├── prd/
├── plan/
└── adr/Multi-repo? Resolvido.
"contexts": [
"backend",
"database",
"business-rules"
]O map guarda
A IA para de improvisar.
Lembra do RAG? Os maps são o que a IA consulta. 🎯
Projeto ativo.
Cada repositório tem um arquivo .ai-project.
# .ai-project
MAPS/meu-projetoResultado
- A IA sabe onde está
- A IA sabe qual contexto carregar
- O dev não precisa repetir tudo
Os artefatos do ai-flow.
Três documentos que o workflow gera e consulta.
📄 PRD
Product Requirements Document
O QUÊ precisa ser feito.
- Problema
- Solução
- Critérios de aceite
- Casos de borda
→ Gerado pelo /spec
📋 PLAN
Plano de Execução
COMO vai ser feito.
- Quebra em baby steps
- Paths e comandos
- Ordem de implementação
- Critério de "pronto"
→ Gerado pelo /planejar
📐 ADR
Architecture Decision Record
POR QUE essa decisão.
- Contexto da decisão
- Alternativas consideradas
- Trade-offs
- Consequências
→ Cresce com o projeto
O ciclo — não é uma esteira.
Cada iteração refina e expande o sistema.
Cada etapa alimenta a próxima
- O PRD informa o PLAN
- O PLAN guia a implementação
- O context.md mantém consistência
- O review valida tudo
O segredo
> prompts aleatórios.
/spec — O dev descreve a feature.
A skill gera
- Problema
- Solução
- Critérios de aceite
- Casos de borda
- Impactos no sistema
Resultado
→ PRD_001_Tela_Login_Feature.md ✅
/planejar — Quebrar em baby steps.
Lembra da janela de contexto? É por isso que quebramos em pedaços.
### Etapa 1 — Entidade
- Criar Product
- Criar repository
### Etapa 2 — Commands
- CreateProductCommand
- Handler
- ValidatorCada etapa cabe na janela de contexto.
/implementar — A skill faz o trabalho.
O que a skill faz
- Descobre o repo correto
- Cria branch
- Implementa
- Segue os padrões
- Executa testes
- Faz commit
Sem precisar repetir
- "usa esse padrão"
- "coloca nesse path"
- "não usa essa biblioteca"
O contexto já existe. ✨
/code-review — A IA valida o que foi feito.
A IA valida
- Critérios do PRD
- Regras do PLAN
- Padrões do projeto
- Segurança
- Performance
- Legibilidade
+ SonarQube
- Quality Gate
- Cobertura de testes
- Vulnerabilidades
- Bugs
- Code Smells
Tudo no mesmo fluxo.
MCP — Model Context Protocol.
O padrão que faz a IA agir, não só conversar.
🔧 Azure DevOps
- Ler work items
- Criar branch
- Abrir PR
- Consultar sprint
📊 SonarQube
- Ler métricas
- Validar Quality Gate
- Coletar vulnerabilidades
→ As skills usam os MCPs pra executar ações reais nos seus sistemas.
O workflow importa mais que o modelo.
Porque o diferencial é:
O perigo do "vibe coding".
IA também acelera bagunça. 🚨
Perigos
- Código sem entendimento
- Arquitetura inconsistente
- Dependência da IA
- Devs sem base técnica
- Código impossível de manter
Revisão humana não é opcional.
IA não substitui engenharia.
O humano continua no controle. 🧠
A próxima geração de devs
não vai competir digitando mais rápido.
estruturando melhor. 🚀
ai-flow é um agregador, não um concorrente.
❌ O que NÃO é
- Mais uma IA
- Substituto do Claude/Cursor
- Concorrente do Copilot
✅ O que É
- Orquestra Claude, Cursor, Gemini, Codex
- Estrutura o workflow
- Persiste o contexto
- Padroniza as skills
Comece em 3 comandos
$ /setup-project # a própria skill te guia
$ /spec "sua primeira feature"
→ Repo completo: github.com/zavadzki72/ai-flow
Vamos ver isso funcionando?
/spec
Gerando um PRD
/planejar
Criando plano de execução
/implementar
Gerando código seguindo padrões
/code-review
Validando qualidade automaticamente
Obrigado!
Perguntas? 🙋
Feito com café, IA e muito contexto. ☕