Contexto Empresarial: Como Injetar Conhecimento do Seu Negócio no Agente

Você pede para o agente criar um endpoint de pagamento e ele gera código com Stripe — mas sua empresa usa Pagar.me. Pede para refatorar um módulo e ele ignora a arquitetura hexagonal que o time adotou há seis meses. Solicita um teste e ele usa Jest quando o projeto inteiro roda com Vitest.

Esses erros não acontecem porque o modelo é ruim. Acontecem porque ele não conhece o seu negócio. E a solução não é trocar de modelo — é injetar contexto empresarial.

O que é Contexto Empresarial

Contexto empresarial é o conhecimento específico do seu negócio, time e projeto que você injeta no agente de codificação para que ele opere como um membro informado da equipe — não como um estagiário genérico no primeiro dia.

Pense assim: quando um desenvolvedor sênior entra na sua empresa, ele passa semanas absorvendo padrões de código, entendendo decisões arquiteturais, aprendendo o glossário interno e descobrindo por que certas escolhas foram feitas. Contexto empresarial é esse mesmo onboarding — compactado em arquivos que o agente lê antes de cada interação.

Na prática, contexto empresarial inclui:

• Padrões de código — convenções de nomenclatura, estrutura de pastas, estilo de imports
• Regras de negócio — lógica específica do domínio que não existe em nenhuma documentação pública
• Decisões arquiteturais — por que você usa PostgreSQL e não MongoDB, por que escolheu Clean Architecture
• Glossário — termos internos que o modelo não conhece (ex: “pedido” vs “order”, “parceiro” vs “supplier”)
• Ferramentas e integrações — quais APIs, SDKs e serviços o projeto usa
• Histórico de decisões — ADRs (Architecture Decision Records) que explicam o “porquê” por trás de cada escolha

O que contexto empresarial não é: fine-tuning. Você não está retreinando o modelo. Está fornecendo informação em tempo de execução que orienta o comportamento do agente dentro do seu projeto específico.

Como Funciona

O mecanismo é direto: agentes de codificação leem arquivos de contexto no início de cada sessão. Esses arquivos são injetados no prompt do sistema, dando ao modelo uma camada persistente de conhecimento sobre o seu projeto.

[IMAGEM: diagrama do fluxo de injeção de contexto]

O Fluxo de Injeção

1. Você cria arquivos de contexto no repositório (markdown, YAML, ou formato específico da ferramenta)
2. O agente detecta esses arquivos automaticamente ao abrir o projeto
3. O conteúdo é injetado no início do contexto de cada conversa
4. O agente opera com esse conhecimento como base para todas as decisões

Cada ferramenta implementa isso de forma diferente, mas o princípio é universal: contexto persistente que sobrevive entre sessões.

Mecanismos por Ferramenta

CLAUDE.md — O Padrão Anthropic

O CLAUDE.md é o arquivo que o Claude Code lê automaticamente na raiz do projeto. Funciona como um README para o agente — 40 linhas de contexto podem eliminar correções repetitivas da noite para o dia.

# CLAUDE.md

## Arquitetura
- Clean Architecture com 4 camadas: domain, application, infra, presentation
- Injeção de dependência via tsyringe
- Todos os use cases retornam Either<Error, Result>

## Convenções
- Nomenclatura: camelCase para variáveis, PascalCase para classes
- Imports absolutos via @/ (configurado no tsconfig)
- Testes: Vitest + Testing Library (NÃO usar Jest)

## Regras de Negócio
- Pedidos acima de R$500 exigem aprovação de gerente
- CPF é validado com dígito verificador (não aceitar mock)
- Timezone sempre America/Sao_Paulo para datas de negócio

O Claude Code suporta hierarquia: um CLAUDE.md na raiz define regras globais, e arquivos em subdiretórios adicionam contexto específico daquela área.

Cursor Project Rules — Contexto Granular

O Cursor evoluiu do antigo .cursorrules (arquivo único) para o sistema de Project Rules — arquivos .mdc em .cursor/rules/ que permitem contexto granular por tipo de arquivo ou padrão glob.

---
description: Regras para componentes React
globs: ["src/components/**/*.tsx"]
alwaysApply: true
---

- Usar functional components com arrow functions
- Props tipadas com interface (não type)
- Exportar componente como default
- Testes no mesmo diretório: ComponentName.test.tsx
- Usar Radix UI para primitivos de acessibilidade

A vantagem do sistema de rules do Cursor é a especificidade: você pode ter regras diferentes para backend e frontend, para testes e código de produção, para migrations e seeders.

Kiro Steering — Contexto com Inclusão Condicional

O Kiro (IDE e CLI) usa steering files em .kiro/steering/. Cada arquivo markdown pode definir quando deve ser incluído:

---
inclusion: always
---
# Padrões do Projeto

Usamos TypeScript strict mode em todo o projeto.
API segue padrão REST com versionamento via URL (/v1/, /v2/).

O campo inclusion controla quando o steering é ativado — always para regras universais, ou condições específicas para contexto situacional.

GitHub Copilot Custom Instructions

O Copilot lê .github/copilot-instructions.md para instruções no nível do repositório. Funciona silenciosamente em background, garantindo que o Copilot siga os padrões do time sem que cada desenvolvedor precise configurar nada individualmente.

# Copilot Instructions

## Stack
- Node.js 20 + TypeScript 5.4
- Fastify (NÃO Express)
- Prisma ORM com PostgreSQL
- Zod para validação de input

## Regras
- Sempre validar input com Zod schema antes de processar
- Erros retornam formato RFC 7807 (Problem Details)
- Logs estruturados com pino (não console.log)

MCP Servers — Contexto Dinâmico

Enquanto arquivos markdown fornecem contexto estático, MCP servers (Model Context Protocol) permitem contexto dinâmico — o agente consulta sistemas externos em tempo real.

Exemplos práticos:

• MCP de documentação interna — o agente consulta sua wiki/Confluence para entender processos
• MCP de banco de dados — o agente vê o schema atual sem você precisar colar DDLs
• MCP de APIs internas — o agente conhece os endpoints disponíveis e seus contratos
• MCP de tickets — o agente lê o Jira/Linear para entender o contexto da task

A diferença fundamental: arquivos de contexto são declarativos (você escreve o que o agente precisa saber), enquanto MCP servers são interativos (o agente busca o que precisa quando precisa).

Por que Importa

Sem contexto empresarial, agentes de codificação operam no modo “Stack Overflow genérico” — geram código que funciona em isolamento mas não se encaixa no seu projeto.

Erros Comuns de Agentes Sem Contexto

Pesquisas recentes mostram que times com contexto bem estruturado reportam redução significativa no tempo de correção de outputs do agente. Um estudo da Augment Code com dados DORA identificou que, sem contexto adequado, o volume de PRs pode subir 98% enquanto a frequência de deploy permanece estagnada — porque o código gerado precisa de revisão extensiva para se adequar aos padrões do projeto.

A Anthropic reporta que 70 a 90% do código na empresa é escrito por IA — mas isso só funciona porque o contexto empresarial está profundamente integrado nos workflows.

O Custo da Ausência

Quando o agente não tem contexto:

1. Retrabalho — você gasta mais tempo corrigindo output do que teria gasto escrevendo do zero
2. Inconsistência — cada interação gera código em estilo diferente
3. Dívida técnica — padrões divergentes se acumulam silenciosamente
4. Frustração — o time perde confiança na ferramenta e volta ao modo manual

Tipos de Contexto e Como Estruturar

Nem todo contexto tem o mesmo peso. Organizar por camadas ajuda a manter a informação gerenciável e atualizada.

Hierarquia de Contexto

┌─────────────────────────────────────┐
│  Nível 1: Universal (sempre ativo)  │
│  Stack, linguagem, convenções base  │
├─────────────────────────────────────┤
│  Nível 2: Domínio (por área)        │
│  Regras de negócio, glossário       │
├─────────────────────────────────────┤
│  Nível 3: Módulo (por componente)   │
│  Padrões específicos de cada parte  │
├─────────────────────────────────────┤
│  Nível 4: Tarefa (situacional)      │
│  Contexto para uma task específica  │
└─────────────────────────────────────┘

O que Incluir em Cada Nível

Nível 1 — Universal:

• Stack tecnológico (linguagem, framework, runtime)
• Convenções de código (naming, imports, formatação)
• Ferramentas de build e test
• Estrutura de diretórios

Nível 2 — Domínio:

• Glossário de termos do negócio
• Regras de negócio críticas
• Integrações externas (APIs, serviços)
• Decisões arquiteturais (ADRs)

Nível 3 — Módulo:

• Padrões específicos do módulo (ex: “neste módulo, use repository pattern”)
• Dependências internas entre módulos
• Contratos de interface

Nível 4 — Tarefa:

• Contexto da issue/ticket atual
• Requisitos específicos da feature
• Restrições temporárias (ex: “não alterar módulo X, está em freeze”)

Princípios de Contexto Efetivo

1. Seja prescritivo, não descritivo — “Use Vitest” é melhor que “O projeto usa Vitest para testes”
2. Inclua o porquê — “Usamos PostgreSQL (não MongoDB) porque precisamos de transações ACID para o módulo financeiro”
3. Dê exemplos — um bloco de código vale mais que três parágrafos de explicação
4. Mantenha atualizado — contexto desatualizado é pior que nenhum contexto
5. Priorize o que causa mais erros — se o agente erra a mesma coisa 3 vezes, adicione uma regra

Contexto vs Fine-Tuning: Quando Usar Cada Um

Uma dúvida comum: “não seria melhor fazer fine-tuning do modelo com nossos dados?”

A resposta curta: para 95% dos casos em agentes de codificação, contexto em tempo de execução é superior a fine-tuning.

Use contexto quando:

• Regras mudam com frequência
• Cada projeto tem padrões diferentes
• Você precisa de auditabilidade (quem mudou o quê)
• O time precisa entender e editar as regras

Use fine-tuning quando:

• Você precisa mudar o estilo de resposta do modelo (tom, formato)
• O volume de chamadas justifica otimização de custo por token
• O conhecimento é estável e universal na organização
• Você tem infraestrutura de ML para manter o pipeline

Para agentes de codificação operando em repositórios, contexto via arquivos é quase sempre a escolha certa. Fine-tuning faz mais sentido para chatbots de atendimento ou modelos especializados em domínios muito específicos (médico, jurídico).

ROI: Impacto Mensurável

Contexto empresarial não é “nice to have” — é a diferença entre um agente que acelera o time e um que gera retrabalho.

Métricas Observáveis

• Taxa de aceitação de sugestões — com contexto bem estruturado, sobe de ~30% para 60-80%
• Tempo de revisão — cai significativamente quando o código já segue os padrões
• Consistência — PRs geradas por agente ficam indistinguíveis de código humano do time
• Onboarding de ferramentas — novos devs produzem código alinhado desde o dia 1 (o agente ensina os padrões)

Como Medir na Prática

1. Antes: conte quantas correções de estilo/padrão você faz por semana em outputs do agente
2. Implemente: crie os arquivos de contexto para os 5 erros mais frequentes
3. Depois: meça novamente após 2 semanas

Times que implementam contexto empresarial de forma estruturada reportam que o agente passa de “ferramenta que precisa de supervisão constante” para “par que entende o projeto”.

Próximos Passos

Injetar contexto empresarial é o passo que transforma agentes de codificação de brinquedo em ferramenta de produção. Comece pequeno:

1. Hoje: crie um arquivo de contexto básico (CLAUDE.md, .cursorrules, ou equivalente) com stack, convenções e 3 regras que o agente mais erra
2. Esta semana: adicione glossário e decisões arquiteturais
3. Este mês: estruture por níveis e adicione contexto por módulo

Se você quer implementar contexto empresarial de forma estruturada para o seu time — com hierarquia de regras, MCP servers customizados e integração com seus sistemas internos — a ft.ia.br ajuda empresas a configurar agentes que realmente entendem o negócio.

Para explorar como skills especializadas complementam o contexto empresarial (transformando regras genéricas em comportamentos especializados por tarefa), veja nosso artigo sobre o que são skills e como especializar agentes.

Contexto empresarial é a ponte entre um modelo genérico e um agente que opera como membro do seu time. Quanto mais preciso o contexto, mais autônomo o agente pode ser — e menos tempo você gasta corrigindo outputs que não se encaixam no seu projeto.