Desenvolvimento Agentic e Arquitetura com IA

MCP (Model Context Protocol) e um protocolo aberto criado pela Anthropic que padroniza como LLMs se conectam a fontes de dados e ferramentas externas. Funciona como uma "porta USB-C" para IA: uma interface unica que conecta qualquer modelo a qualquer recurso.

Com 1.864+ servidores registrados e adocao por todas as grandes plataformas (Claude, Cursor, Windsurf, VS Code), MCP nao e mais experimental. E infraestrutura. Saber usar e construir servidores MCP e o que separa quem usa IA de quem constroi sistemas com IA.

Protocolo cliente-servidor, JSON-RPC 2.0, tools/resources/prompts como primitivas, host vs client vs server, ciclo de vida de conexao, capability negotiation.

A evolucao do transporte MCP de stdio (standard input/output) para Streamable HTTP. Stdio funciona bem localmente, mas em producao voce precisa de HTTP para escalar, autenticar e monitorar conexoes entre clientes e servidores MCP.

Servidores MCP em producao precisam de autenticacao (OAuth 2.1), rate limiting, logging e deploy distribuido. Stdio nao suporta nada disso. HTTP com SSE (Server-Sent Events) se tornou o padrao para servidores remotos.

Streamable HTTP transport, Server-Sent Events (SSE), OAuth 2.1 para autenticacao, stdio vs HTTP trade-offs, session management, reconnection handling.

MCP Server Cards sao documentos JSON publicados em .well-known/mcp.json que descrevem as capacidades de um servidor MCP. Permitem que clientes descubram automaticamente quais ferramentas, recursos e prompts um servidor oferece, sem configuracao manual.

A descoberta automatica elimina a configuracao manual de servidores. Em vez de listar endpoints e capacidades num arquivo de config, o cliente simplesmente consulta o .well-known/mcp.json e sabe o que esta disponivel. Isso habilita composicao dinamica de ferramentas.

Well-known URIs, server card schema, capability advertisement, tool discovery, dynamic registration, versioning de capacidades.

A pratica de conectar LLMs a recursos do mundo real via MCP: sistemas de arquivos, terminais, bancos de dados, APIs, documentacao e servicos SaaS. Cada conexao e um servidor MCP que expoe tools (acoes), resources (dados) ou prompts (templates).

O poder de um LLM isolado e limitado. Quando voce conecta um modelo ao GitHub, ao banco de dados, ao Slack e ao sistema de arquivos via MCP, ele se torna um agente capaz de executar tarefas reais. A diferenca entre "chatbot" e "assistente de engenharia" esta nas conexoes.

Tool definitions com JSON Schema, resources como URIs enderecaveis, prompts como templates reutilizaveis, composicao de multiplos servidores, sandboxing e permissoes.

A construcao de um servidor MCP do zero: definir quais ferramentas expor, como estruturar inputs/outputs, como validar requisicoes e como fazer o deploy. Um servidor MCP e basicamente um processo que fala JSON-RPC e expoe capacidades que um LLM pode invocar.

Usar servidores prontos e o basico. Construir os seus e o que transforma qualquer sistema legado, API interna ou workflow proprietario em algo que um LLM pode operar. Voce cria a ponte entre a IA e o seu dominio especifico.

@modelcontextprotocol/sdk, handler patterns, input validation com Zod/JSON Schema, error handling, logging estruturado, testes de servidor, deploy com Docker.

Os riscos concretos de dar a um LLM acesso a ferramentas que afetam o mundo real: deletar arquivos, executar comandos, fazer deploy, enviar emails. Inclui prompt injection via tools, exfiltracao de dados, acao em loop destrutivo e falta de auditoria.

Um agente com acesso ao terminal pode rodar rm -rf se o prompt for manipulado. Um agente com acesso ao email pode enviar dados sensiveis. Entender os riscos antes de dar poder a um LLM e a diferenca entre engenharia e negligencia.

Principio do menor privilegio, tool poisoning, prompt injection indireta via resources, sandboxing de execucao, human-in-the-loop, audit logging, rate limiting, permissoes granulares.

Agentes de IA especializados em tarefas especificas do ciclo de desenvolvimento. Em vez de um agente generalista que faz tudo mal, voce cria agentes focados: um que escreve codigo, outro que revisa, outro que gera testes, outro que documenta, outro que investiga bugs.

Agentes especializados produzem output de qualidade muito superior a um agente generico. O system prompt e afinado, as tools sao relevantes, o contexto e focado. Times que adotam esse padrao reportam reducao de 40-60% no retrabalho de code review.

System prompts especializados, tool sets limitados por papel, context isolation, handoff entre agentes, agent profiles, separation of concerns aplicada a IA.

As arquiteturas de como multiplos agentes trabalham juntos. Hierarquico: um agente supervisor delega para sub-agentes. Orchestrator-worker: um agente central distribui tarefas e agrega resultados. Pipeline: agentes em sequencia, cada um transformando o output do anterior.

Escolher o padrao errado de orquestracao multiplica custo e latencia sem ganho de qualidade. Um pipeline simples resolve 80% dos casos. Orquestracao complexa so compensa quando ha interdependencias reais entre as tarefas.

Hierarchical delegation, fan-out/fan-in, pipeline sequencing, DAG de execucao, state sharing entre agentes, error propagation, timeout e retry strategies.

Um pipeline concreto de agentes para desenvolvimento de features: o Feature Author escreve o codigo, o Test Gen cria testes, o Code Reviewer identifica problemas, o Security Scanner verifica vulnerabilidades, e o CI/CD Agent integra e faz deploy.

Este e o padrao que times de ponta estao adotando. Cada agente ve apenas o que precisa, opera com system prompt afinado e produz output estruturado que alimenta o proximo estagio. O resultado e uma feature que sai com testes, revisao e scan de seguranca inclusos.

Stage gates, artifact passing, feedback loops entre estagios, quality gates automatizados, rollback em caso de falha, metricas por estagio do pipeline.

Os principais frameworks para construir agentes em 2026. Anthropic Agent SDK e OpenAI Agents SDK sao oficiais dos provedores. Google ADK (Agent Development Kit) e o mais recente. LangGraph oferece grafos de estado. CrewAI foca em papeis e colaboracao.

Cada framework tem trade-offs reais. SDKs oficiais sao simples mas limitam a um provedor. LangGraph da controle fino mas adiciona complexidade. CrewAI e rapido pra prototipar mas pode ser limitante em producao. Escolher errado custa meses de reescrita.

Agent primitives por framework, tool integration, memory/state management, observabilidade, vendor lock-in vs portabilidade, custos em escala, maturidade e comunidade.

A pratica de usar modelos diferentes para tarefas diferentes dentro do mesmo sistema. Modelos baratos e rapidos (Haiku, GPT-4o-mini) fazem triagem, classificacao e tarefas simples. Modelos capazes (Opus, o3) fazem raciocinio complexo, revisao e decisoes criticas.

Usar Opus pra tudo custa 10-50x mais que uma estrategia mista. Um roteador com Haiku que decide qual modelo usar por tarefa reduz custos em 60-80% sem perda perceptivel de qualidade. Em escala, isso e a diferenca entre viavel e inviavel.

Model routing, cost-per-token analysis, task complexity classification, fallback chains, quality gates por modelo, A/B testing de modelos, budget caps.

A analise critica de quando usar multiplos agentes versus um agente unico com um loop bem desenhado. Multi-agent adiciona complexidade de comunicacao, state management e debugging. Um agente solo com boas tools e iteracao resolve a maioria dos problemas reais.

A tendencia natural e over-engineer com multi-agent porque parece mais sofisticado. Na pratica, a maioria dos workflows de desenvolvimento funciona melhor com um agente iterativo que tem acesso as tools certas. Multi-agent compensa quando ha papeis genuinamente distintos com contextos incompativeis.

Complexidade acidental vs essencial, single-agent loop patterns, when to split, communication overhead, context window management em multi-agent, debugging distribuido.

A pratica de comecar qualquer feature ou sistema com um design document estruturado, antes de escrever uma linha de codigo. O design doc define o problema, as restricoes, a abordagem tecnica, as alternativas consideradas e os criterios de sucesso.

Sem spec, um agente de IA gera codigo que resolve o problema que ele imagina, nao o que voce precisa. Com spec, voce da ao agente uma descricao precisa do que construir, reducao de ambiguidade de 80-90%. O design doc e o contrato entre a intencao humana e a execucao da IA.

Problem statement, constraints e non-goals, abordagem tecnica, alternativas consideradas, criterios de aceitacao, formato RFC/ADR, iteracao com IA no design.

O GitHub Spec Kit e um framework open-source para spec-driven development com IA. Com 72.7k stars, se tornou o padrao de facto para estruturar requisitos que alimentam agentes de codigo. Suporta 22+ plataformas incluindo Claude Code, Cursor, Copilot e Windsurf.

Em vez de inventar seu proprio formato de spec, voce usa um que ja foi validado por milhares de projetos. O Spec Kit gera specs que os agentes entendem nativamente, com semelhantica clara e estrutura consistente. Adocao massiva significa documentacao e tooling ricos.

Spec templates, agent-compatible formats, multi-platform specs, spec validation, integration com CI, spec versioning, community patterns.

Usar IA para decompor um problema grande em partes implementaveis, identificando premissas implicitas, riscos tecnicos e dependencias ocultas. A IA funciona como um "sparring partner" que questiona o escopo e revela blind spots no design.

Decomposicao ruim e a causa numero 1 de projetos que falham. A IA consegue identificar riscos que o dev nao ve porque esta proximo demais do problema. Usar IA para questionar premissas antes de codar economiza semanas de retrabalho.

Task decomposition prompts, assumption surfacing, risk matrix automatizada, dependency graph generation, scope validation, MECE decomposition com IA.

Tratar a spec como a unica fonte de verdade que alimenta tres coisas simultaneamente: o agente de codigo (que implementa), o agente de testes (que valida) e o CI (que verifica). A spec nao e documentacao passiva, e um contrato executavel.

Quando spec, codigo e testes divergem, voce tem bugs. Quando a spec e o contrato central, qualquer mudanca no requisito se propaga automaticamente para testes e implementacao. Isso elimina a classe inteira de bugs causada por "o dev entendeu diferente do PM".

Spec como single source of truth, derivacao automatica de testes, spec-to-code traceability, change propagation, spec drift detection, contract testing.

Um padrao onde dois agentes trabalham a partir da mesma spec mas sem ver o trabalho um do outro. O agente de testes gera os testes a partir da spec. O agente de codigo implementa a partir da mesma spec. Se os testes passam, a implementacao esta correta. Se falham, ha divergencia.

Quando o mesmo agente escreve codigo e testes, os testes tendem a validar o que o codigo faz (nao o que deveria fazer). Separar os agentes cria tensao saudavel: os testes refletem a spec, o codigo reflete a spec, e a discordancia entre eles revela bugs reais.

Context isolation entre agentes, spec como unico input compartilhado, test-first vs code-first race, red-green-refactor com IA, adversarial testing, mutation testing com agentes.

A pratica de manter requisitos, design docs e codigo em sincronia permanente, usando IA para detectar drift entre as camadas. Quando um requisito muda, a IA identifica quais design docs e quais trechos de codigo precisam ser atualizados.

Em projetos reais, requisitos mudam toda semana. Sem alinhamento continuo, em dois meses o codigo nao reflete mais o design, que nao reflete mais os requisitos. Essa divergencia e a principal fonte de bugs em sistemas complexos. A IA pode automatizar a deteccao.

Drift detection, bi-directional traceability, automated impact analysis, change cascade, spec CI checks, living documentation, architecture decision records (ADRs) com IA.

RAG e a tecnica de buscar informacao relevante de uma base de dados e injetar no contexto do LLM antes de gerar a resposta. Em vez de depender apenas do conhecimento treinado no modelo, voce da acesso a documentacao atualizada, codigo do projeto e dados especificos do dominio.

LLMs tem knowledge cutoff e nao conhecem seu codigo privado. RAG resolve os dois problemas: da acesso a informacao atualizada e ao contexto especifico do seu projeto. Para codebases grandes (100k+ linhas), RAG e a unica forma viavel de dar contexto relevante sem estourar a context window.

Retrieval pipeline, embedding models, vector stores, semantic search vs keyword search, context injection, relevance scoring, RAG vs fine-tuning trade-offs.

Chunking e como voce divide o codigo fonte em pedacos para indexar. Chunking burro divide por linhas fixas (500 linhas por chunk). Chunking inteligente usa AST (Abstract Syntax Tree) para dividir por funcoes, classes e modulos, respeitando os limites semanticos do codigo.

Chunking por linhas corta funcoes no meio, mistura contextos e produz resultados irrelevantes na busca. Chunking por AST mantém a coerencia semantica: cada chunk e uma funcao completa, uma classe inteira, um modulo com seus imports. A qualidade do RAG depende diretamente da qualidade do chunking.

Tree-sitter para parsing multi-linguagem, AST node types, hierarchical chunking, overlap strategies, chunk size vs retrieval quality, docstring inclusion, import resolution.

Um pipeline de busca em dois estagios: primeiro, vector search retorna os top-K candidatos (rapido e barato). Depois, um LLM reranker avalia esses candidatos e reordena por relevancia real (mais preciso mas mais caro). Combina velocidade com precisao.

Vector search sozinho retorna resultados por similaridade semantica, mas "similaridade" nao e "relevancia". Um chunk sobre autenticacao pode ser semanticamente similar a um sobre autorizacao sem ser relevante. O LLM reranker entende a intencao da query e filtra o que realmente importa.

Bi-encoder vs cross-encoder, retrieval recall vs precision, top-K selection, reranking prompts, hybrid search (vector + BM25), Reciprocal Rank Fusion, cost vs quality curve.

Enriquecer cada chunk de codigo com metadata estruturada: linguagem, tipo (funcao, classe, test, config), dependencias, camada arquitetural (controller, service, repository), ultimo autor, frequencia de mudanca. Essa metadata permite filtros na busca e melhora drasticamente a precisao.

Sem metadata, uma busca por "funcao de autenticacao" retorna testes, configs e implementacoes misturados. Com metadata, voce filtra "tipo=implementacao, camada=service" e recebe exatamente o que precisa. A metadata transforma busca generica em busca precisa.

Metadata schema design, automated tagging com AST, git blame integration, dependency extraction, filtered search, faceted retrieval, metadata freshness.

O ecossistema de ferramentas para implementar RAG em codebases. CodeRAG integra com MCP para servir contexto. Code-graph-rag usa grafos de dependencia. CocoIndex faz indexacao incremental. Tree-sitter faz parsing multi-linguagem para chunking estrutural.

Implementar RAG do zero e um projeto de meses. Essas ferramentas resolvem os problemas ja conhecidos (chunking, indexacao, busca, serving) e deixam voce focar no que importa: a qualidade do contexto que chega ao LLM. Saber qual ferramenta usar pra cada caso acelera em 10x.

CodeRAG server via MCP, graph-based retrieval, incremental indexing, Tree-sitter grammars, embedding models para codigo, vector databases (Qdrant, Chroma, Pinecone), self-hosted vs managed.

Tratar o indice RAG como infraestrutura de primeira classe: atualizado automaticamente no CI/CD a cada merge, com embeddings regenerados para arquivos modificados, e servido via MCP para que qualquer agente tenha acesso ao contexto atualizado.

Um indice desatualizado e pior que nenhum indice: o LLM recebe contexto obsoleto e gera codigo baseado em APIs que mudaram. Integrar re-indexacao no CI/CD garante que o indice esta sempre fresco. Servir via MCP garante que qualquer agente pode consumir.

Incremental re-indexing, CI/CD hooks para indexacao, embedding invalidation, MCP resource serving, cache de embeddings, monitoring de freshness, cost of re-indexing.

Usar IA para entender codebases grandes e sistemas complexos que levam semanas para um dev novo compreender. A IA navega pelo codigo, explica padroes, identifica fluxos de dados e mapeia relacoes entre componentes, funcionando como um "guia interativo" da codebase.

Onboarding em codebases grandes leva 3-6 meses. Com leitura assistida por IA, esse tempo cai para dias. Alem disso, devs seniors que ja conhecem o sistema usam leitura assistida para explorar partes do codigo que nunca tocaram, entendendo impactos antes de mudar.

Code navigation com IA, call graph exploration, "explain this function in context", dependency chain walking, architectural overview generation, pattern recognition em codebases.

Usar IA para mapear dependencias entre modulos, identificar hotspots (codigo que muda muito e causa muitos bugs), medir acoplamento entre componentes e quantificar divida tecnica. A IA combina analise estatica do codigo com historico do git para produzir um mapa completo.

Voce nao pode refatorar o que nao entende. Antes de mexer em codigo legado, precisa saber quais modulos sao acoplados, quais sao hotspots de bugs e onde a divida tecnica e mais cara. Sem esse mapa, refatoracao e um tiro no escuro que frequentemente piora a situacao.

Dependency graph generation, churn analysis (git log), complexity metrics (cyclomatic, cognitive), coupling score, hotspot detection, tech debt quantification, risk scoring.

Usar IA para aplicar refatoracoes consistentes em centenas de arquivos simultaneamente. Renomear APIs, migrar padroes, atualizar imports, converter tipos. A IA entende o contexto semantico de cada mudanca, nao apenas faz find-and-replace.

Refatoracoes grandes feitas manualmente levam semanas e introduzem inconsistencias. Com IA, uma migracao de API que tocaria 200 arquivos pode ser feita em horas, com cada transformacao respeitando o contexto local do arquivo. A IA ajusta o padrao conforme o uso.

Semantic codemods, batch transformation com review, consistency verification, rollback safety, test-first refactoring, incremental migration, feature flags em refatoracao.

Usar IA para identificar responsabilidades misturadas em modulos e propor reorganizacoes que aumentam a coesao e reduzem o acoplamento. A IA analisa quais funcoes/classes sao usadas juntas, quais pertencem a dominios diferentes e sugere uma nova estrutura modular.

Codigo legado tende a acumular responsabilidades em "god modules" que fazem de tudo. Separar manualmente e arriscado porque voce nao enxerga todas as dependencias. A IA varre o grafo de dependencias inteiro e propoe cortes que minimizam breaking changes.

Cohesion analysis, responsibility extraction, module boundary detection, interface design, dependency inversion, strangler fig pattern, incremental extraction.

Duas estrategias de organizar codigo: feature slice agrupa por funcionalidade (tudo de "pagamentos" junto), vertical slice agrupa por camada tecnica (todos os controllers juntos, todos os services juntos). Cada abordagem tem implicacoes diferentes pra IA e pra manutenibilidade.

A organizacao do codigo afeta diretamente a qualidade do contexto que a IA recebe. Feature slices dao contexto completo de uma funcionalidade num unico diretorio. Vertical slices forcam a IA a navegar entre camadas. A escolha impacta a eficacia de agentes e a velocidade de desenvolvimento.

Feature-based architecture, vertical slice architecture, bounded contexts, context locality para IA, colocation de arquivos, shared kernel, trade-offs de cada abordagem.

Como padroes arquiteturais classicos (DDD, Hexagonal, Clean Architecture) se adaptam a era da IA. Repositorios IA-first sao organizados com CLAUDE.md/AGENTS.md na raiz, specs em /docs, context files por feature e convencoes explicitas que agentes entendem.

Arquiteturas que funcionavam bem para devs humanos podem ser hostis para agentes. Clean Architecture com sua separacao estrita e otima para humanos mas multiplica o contexto necessario para um agente. Repositorios IA-first balanceiam separacao com localidade de contexto.

DDD aggregate roots como context boundaries, Hexagonal ports/adapters para tool integration, IA-first repo structure, CLAUDE.md como system prompt, AGENTS.md para convencoes, context files (.cursorrules, .github/copilot), documentation-as-context.