Os 6 Princípios da Arquitetura AI-Native

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.

Princípio 1: Explícito Sobre Implícito

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.

Princípio 2: Módulos Pequenos e Composíveis

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.

Princípio 3: Desenvolvimento Contract-First

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.

Princípio 4: Testes Determinísticos

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:

• Cada teste cria seu próprio estado.
• Serviços externos são "mockados" (gateways, e-mail, storage).
• Sem Date.now() ou Math.random() sem injeção controlada.

Princípio 5: Sistemas Autodescritivos

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:

1. Camada 4: CLAUDE.md / AGENTS.md (Regras e convenções).
2. Camada 3: OpenAPI / AsyncAPI (Contratos e eventos).
3. Camada 2: JSON Schema / Zod (Validação runtime).
4. Camada 1: Tipos TypeScript (Contratos em tempo de compilação).
5. Camada 0: Schema do banco (Prisma/Drizzle) (Fonte de verdade do modelo).

Princípio 6: Verificação Automatizada

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.

Caminho de Migração: Do Legado Para o AI-Native

Você não pode reescrever seu codebase da noite para o dia, mas pode migrar incrementalmente:

• Semana 1 (Fundação): Criar o CLAUDE.md e documentar ADRs críticas.
• Semana 2 (Limites): Quebrar os 5 maiores arquivos do projeto em módulos menores.
• Semana 3 (Contratos): Adicionar OpenAPI/Zod para as rotas principais.
• Semana 4 (Determinismo): Eliminar testes flakey e resetar o banco no beforeEach.

Medindo o AI-Readiness Score

Anti-Patterns: O Que Mata a Arquitetura AI-Native

1. O Arquivo Deus: Um arquivo com 3.000 linhas que faz tudo.
2. Máquinas de Estado Implícitas: Status de pedidos espalhados por 7 serviços sem um esquema central.
3. Drift Documentação-Código: READMEs mentirosos e specs desatualizados.
4. Comportamento Dependente de Ambiente: Usar process.env.NODE_ENV para lógica de negócio (invisível para a IA).

A Mudança Fundamental

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.

Referências e Leitura Adicional

• Martin Fowler: Microservices e MonolithFirst.
• Sam Newman: Building Microservices.
• Anthropic: Claude Code Best Practices.
• OpenAPI Initiative: OpenAPI 3.1 Specification.