projetando sistemas com IA
Recursos selecionados para complementar sua leitura
Uma fintech em São Paulo tinha 50 engenheiros trabalhando em uma plataforma de pagamentos. O cycle time médio era de 3 semanas por feature. Code reviews levavam dias. Deploys aconteciam nas quintas-feiras, com todo mundo prendendo a respiração.
Então, eles reestruturaram. Cinco engenheiros. Mesma plataforma. Mesma velocidade de features — na verdade, mais rápida. O cycle time caiu para 3 dias.
Eles não contrataram engenheiros 10x. Não adotaram um framework mágico. Eles redesenharam a arquitetura para que agentes de IA pudessem construir, testar e implantar de forma autônoma.
A diferença não foi o ferramental de IA. Todo time tinha acesso aos mesmos modelos, aos mesmos assistentes de código, aos mesmos pipelines de CI/CD. A diferença foi a arquitetura. O codebase deles foi projetado para a IA operar. O codebase de todos os outros foi projetado para humanos entenderem — e a IA lutava contra a arquitetura a cada passo.
Este artigo apresenta os princípios arquiteturais por trás dessa mudança. Não teoria. Não especulação. Padrões extraídos de times que estão entregando software em produção com agentes de IA hoje, em fevereiro de 2026.
Se sua arquitetura exige uma reunião de 30 minutos para ser compreendida, nenhum agente de IA vai conseguir construir sobre ela de forma eficaz.
A maioria das arquiteturas de software carrega três tipos de dívida invisível que tornam o desenvolvimento assistido por IA doloroso ou impossível.
Abra qualquer codebase maduro. Olhe o serviço que lida com faturamento. Agora responda a estas perguntas:
As respostas não estão no código. Estão em threads do Slack de 2023, na cabeça do engenheiro que saiu há seis meses, e em um documento de post-mortem que ninguém consegue encontrar.
Um agente de IA lendo esse código vê o o quê, mas não o porquê. Sem o porquê, ele não consegue fazer modificações seguras. Não consegue raciocinar sobre edge cases. Não consegue estender o sistema sem arriscar regressões.
Conhecimento implícito é o assassino silencioso do desenvolvimento assistido por IA.
Todo time tem convenções que não existem em nenhum documento:
UserService, na verdade, é responsável por permissões também — o nome é enganoso."Essas convenções são perfeitamente razoáveis para um time humano que almoça junto. São catastróficas para um agente de IA que interpreta instruções literalmente.
Architecture Decision Records (ADRs) são raros. Quando existem, estão desatualizados. O resultado é que cada decisão arquitetural — por que escolhemos PostgreSQL ao invés de MongoDB, por que separamos este serviço daquele, por que usamos event sourcing para pedidos, mas CRUD para produtos — vive apenas na memória coletiva.
Um agente de IA operando em um sistema sem decisões documentadas vai:
O problema central não é que a IA é limitada. O problema é que nossas arquiteturas foram projetadas para um canal de comunicação — conversa humana — do qual agentes de IA não conseguem participar plenamente.
A solução não é uma IA melhor. A solução é uma arquitetura melhor.
Arquitetura AI-native não é um framework. É um conjunto de restrições que torna qualquer codebase mais operável tanto por humanos quanto por agentes de IA. Todo princípio serve ao mesmo objetivo: substituir o implícito pelo explícito, o ambíguo pelo determinístico, e o tribal pelo documentado.
A regra: Cada decisão, convenção e requisito deve existir como código ou especificação legível por máquina. Se não está escrito em um formato que uma ferramenta consiga processar (parsear), não existe.
Por que importa para a IA: Agentes de IA processam arquivos. Eles não participam de daily meetings. Cada pedaço de conhecimento que vive na cabeça de uma pessoa é uma lacuna no entendimento do agente sobre seu sistema.
Antes: Convenções implícitas
// src/services/OrderService.ts (847 linhas)
// "Todo mundo sabe" que pedidos acima de R$50.000 precisam de aprovação manual
// "Todo mundo sabe" que retentamos pagamentos falhos 3 vezes
// "Todo mundo sabe" que pedidos brasileiros precisam de validação de CPF
export class OrderService {
async createOrder(data: CreateOrderInput) {
// ... 200 linhas de lógica de negócio entrelaçada
// sem separação clara de regras
}
}
Depois: Especificações explícitas
// specs/orders/business-rules.ts
export const ORDER_RULES = {
manualApprovalThreshold: {
amount: 50_000_00, // centavos
currency: 'BRL',
reason: 'Requisito de compliance: pedidos acima de R$50.000 exigem revisão manual',
documentedAt: '2024-03-15',
owner: 'compliance-team',
},
paymentRetry: {
maxAttempts: 3,
backoffMs: [1000, 5000, 15000],
reason: 'SLA do processador de pagamento permite 3 retentativas em janela de 60s',
documentedAt: '2024-06-01',
},
taxValidation: {
BR: {
requiredFields: ['cpf'],
validationPattern: /^\d{3}\.\d{3}\.\d{3}-\d{2}$/,
reason: 'Receita Federal exige CPF para todas as transações B2C',
documentedAt: '2024-01-20',
},
},
} as const
// CLAUDE.md (ou AGENTS.md — regras do projeto legíveis por máquina)
// ## Regras de Negócio
// - Todas as regras de negócio ficam em specs/orders/business-rules.ts
// - Nunca faça hardcode de thresholds nos arquivos de serviço
// - Toda regra deve ter: value, reason, documentedAt, owner
// - Antes de modificar uma regra, leia o campo 'reason'
O arquivo CLAUDE.md (ou AGENTS.md) é o arquivo mais importante de um codebase AI-native. É o manual de instruções que todo agente de IA lê antes de tocar no seu código. Trate-o como infraestrutura.
A regra: Nenhum arquivo excede 200 linhas de código. Nenhuma função excede 30 linhas. Cada módulo faz exatamente uma coisa e declara suas dependências explicitamente.
Por que importa para a IA: Modelos de linguagem têm janelas de contexto. Um arquivo de 2.000 linhas força a IA a manter o arquivo inteiro em contexto para fazer qualquer alteração. Um módulo de 150 linhas permite que a IA se concentre em um único problema bem delimitado.
Modulos pequenos criam limites claros. Limites claros significam que um agente de IA pode modificar um módulo sem entender o sistema inteiro.
A regra: Defina contratos de API, schemas de dados e limites de interface antes de escrever qualquer implementação. O contrato é a fonte da verdade. A implementação se conforma ao contrato, nunca o inverso.
Por que importa para a IA: Contratos são especificações legíveis por máquina. Um agente de IA com um spec OpenAPI consegue gerar código cliente correto, stubs de servidor e testes sem ambiguidade.
A regra: Cada teste deve produzir o mesmo resultado toda vez que roda, independente de ordem, ambiente ou tempo (timing). Zero testes flakey. Zero dependências de ordem. Zero dependência de serviços externos.
Por que importa para a IA: Quando um agente de IA roda testes e vê uma falha, ele precisa saber se a falha foi causada por suas mudanças ou pela infraestrutura de testes. Testes instáveis fazem agentes de IA "alucinarem" sobre o estado do sistema.
Checklist de testes determinísticos:
Date.now() ou Math.random() sem injeção controlada.A regra: Cada API, modelo de dados, configuração e limite de módulo deve ser descrito em um formato legível por máquina. O sistema descreve a si mesmo para qualquer consumidor — humano ou IA.
A pilha de autodescrição:
CLAUDE.md / AGENTS.md (Regras e convenções).A regra: Cada portão de qualidade (quality gate) deve ser automatizado e produzir output legível por máquina (JSON). Um agente de IA deve conseguir acionar a verificação, ler os resultados e agir sobre eles de forma autônoma.
Você não pode reescrever seu codebase da noite para o dia, mas pode migrar incrementalmente:
CLAUDE.md e documentar ADRs críticas.beforeEach.| Dimensão | Peso | Como Medir |
|---|---|---|
| Explicitude | 20% | % de regras de negócio documentadas como código/specs. |
| Tamanho de Módulos | 15% | % de arquivos abaixo de 200 LOC. |
| Cobertura de Contratos | 20% | % de endpoints com specs OpenAPI/schema. |
| Determinismo de Testes | 20% | Taxa de aprovação em 10 execuções idênticas consecutivas. |
| Autodescrição | 10% | % de modelos de dados com schemas legíveis por máquina. |
| Automação de Verificação | 15% | % de checks de qualidade com output estruturado. |
process.env.NODE_ENV para lógica de negócio (invisível para a IA).A maioria da arquitetura de software foi projetada para humanos entenderem. A arquitetura AI-native é projetada para agentes de IA operarem.
Isso não é sobre substituir humanos. É sobre projetar sistemas onde agentes de IA e humanos podem colaborar efetivamente. A IA lida com o trabalho mecânico e o humano lida com o trabalho criativo e estratégico.
Os times que redesenharem agora terão anos de vantagem. Comece medindo seu AI-readiness score hoje.
Software Architect
Pós-graduado em arquitetura de software e soluções. Conecto profundidade técnica com resultados de negócio para entregar produtos que as pessoas realmente usam. Também mentoro desenvolvedores e criadores em programas ao vivo, podcasts e iniciativas de comunidade focadas em tecnologia inclusiva.
Checklist de 47 pontos para encontrar bugs, riscos de segurança e problemas de performance antes do lançamento.
Continue explorando tópicos similares
Quando qualquer pessoa — mesmo sem conhecimento técnico — consegue construir suas próprias ferramentas usando IA e vibe coding, o que acontece com empresas que vendem software pago? Uma análise de quais ferramentas morrem, quais se transformam, e por que a moeda real muda de software para infraestrutura, dados e ecossistemas.
Um guia de arquitetura em nível de produção para construir um sistema estilo Instagram com feed personalizado, stories, reels, mensagens, notificações, ranking em tempo real e operação global.

Um guia completo de system design para construir uma plataforma de compartilhamento de corridas lidando com milhões de viagens simultâneas, matching geoespacial em tempo real, precificação dinâmica e predição de ETA em escala global.
Templates testados em produção, usados por desenvolvedores. Economize semanas de setup no seu próximo projeto.
Consultorias modulares para founders e CTOs fracionados. Você recebe diagnóstico acionável e acompanhamento direto comigo.
2 vagas para consultorias no Q2