Context Engineering: fornecendo o conhecimento certo aos agentes de IA

Um prompt claro ainda pode gerar a alteração errada se o agente ler um contrato de API antigo ou não descobrir qual serviço é responsável pelo comportamento. Context Engineering é o trabalho de selecionar, recuperar e manter as informações disponíveis para o modelo durante uma tarefa.

Isso inclui instruções, arquivos de código, esquemas de dados (regras sobre o formato das informações), resultados de ferramentas e o histórico da conversa. Um arquivo no repositório só ajuda quando o agente o encontra e lê. Em Effective context engineering for AI agents, a Anthropic descreve essa visão mais ampla e iterativa.

Depois de AI Gateways e roteamento de modelos, este artigo desenvolve Prompt Engineering: as instruções definem o pedido; o contexto fornece as evidências necessárias para agir.

Recupere os fatos certos

Em um sistema dividido entre serviços, um agente que trabalha em order-service talvez também precise do contrato da API de inventory (o formato e as regras das chamadas), das regras dos eventos de payment e do histórico de mudanças no banco de dados. Ler apenas o código do serviço local pode esconder dependências importantes.

Comece com um conjunto pequeno e específico para a tarefa:

1. O código responsável pelo comportamento e uma implementação existente que sirva de referência.
2. O contrato autoritativo de cada integração afetada.
3. As instruções aplicáveis ao repositório e os comandos de teste.
4. O teste com falha, o resultado observado durante a execução ou o critério de aceitação que motivou a alteração.

Amplie esse conjunto quando as evidências apontarem para outra dependência. Mantenha os caminhos e as versões das fontes para que um revisor possa refazer o raciocínio.

Exemplo: o serviço certo e o contrato errado

Suponha que o agente encontre commerce-pricing, mas recupere um guia antigo que diz que o navegador deve enviar uma porcentagem de desconto. A API de pricing candidata aceita um código e retorna uma cotação autoritativa. Encontrar o serviço foi um sucesso; as evidências usadas para implementar a mudança continuaram erradas.

Neste exemplo ilustrativo de checkout, inspecione as evidências antes de editar:

Fonte recuperada	Verificação	Ação
Guia de integração antigo	Qual versão da API e qual release ele descreve?	Mantenha-o como contexto histórico e sinalize o conflito
Schema de pricing no commit candidato	Ele define a entrada do código, a saída da cotação e os casos de erro?	Leia as operações e os exemplos relevantes
Consumer de orders e testes de contrato	Qual versão do contrato o candidato realmente consome?	Verifique a compatibilidade antes de presumir que a migração terminou

Registre o repositório, o commit e o caminho da fonte para cada decisão. Um documento mais recente, por si só, não estabelece qual contrato rege um consumer implantado. Se o schema e a implementação divergirem, identifique a pessoa responsável e determine se é um defeito, uma migração planejada ou documentação desatualizada.

Avalie a recuperação de contexto separadamente da implementação. Monte um conjunto pequeno de tarefas com fontes obrigatórias identificadas por revisores. Meça quantas fontes necessárias foram recuperadas e quanto do material recuperado era relevante; depois, verifique se a alteração gerada realmente seguiu essas fontes. Deixar de encontrar um contrato autoritativo e ignorar um contrato já carregado exigem correções diferentes. O conjunto de fontes rotuladas é um benchmark delimitado, não uma afirmação de que se conhecem todos os arquivos relevantes da empresa.

Inclua significado e atualidade junto com os dados

Em Making Your Data Ready for Agentic AI, Pramod Sadalage e Prem Chandrasekaran distinguem qualidade dos dados, significado de negócio e controle de acesso.

Para o checkout, estabeleça estes detalhes a partir do contrato e da resposta da ferramenta:

Dado	Significado a estabelecer	Verificação antes de usar
Valor da cotação	Moeda, unidades e inclusão de impostos e frete	Confira o schema da cotação e a representação de valor acordada
Desconto	Percentual ou valor fixo; itens elegíveis e exclusões	Use a versão atual da política de pricing
Expiração	Fuso horário e se o limite é inclusivo	Avalie usando o relógio autoritativo e a regra de validade
Política recuperada	Revisão da fonte e revisão indexada	Detecte se o índice ainda não incorporou uma mudança de política

Registre separadamente os timestamps da fonte e os timestamps de atualização bem-sucedida do índice. Quando o significado ou a atualidade exigidos forem desconhecidos, retorne um resultado específico de dados ausentes. A validação de schema pode detectar dados malformados; as pessoas responsáveis pelo negócio ainda precisam confirmar seu significado.

Uma janela de contexto maior é útil, mas insuficiente

Uma janela maior pode ajudar em análises amplas, mas capacidade disponível e uso efetivo são questões diferentes. O estudo Lost in the Middle constatou que o desempenho de recuperação dependia da posição das informações relevantes nos contextos dos modelos testados. Isso é evidência para testar o comportamento com contextos longos, não uma lei universal sobre todos os modelos mais recentes. Consulte o estudo original.

Arquivos sem relação com a tarefa também podem introduzir convenções conflitantes e aumentar o custo de processamento. Prefira um índice que indique onde procurar e, em seguida, recupere as fontes relevantes em vez de copiar todos os repositórios para cada pedido. O capítulo 6, “RAG and Agents”, de Chip Huyen em AI Engineering discute em mais detalhes a recuperação de informações e o contexto de agentes.

A arquitetura também afeta o que precisa ser descoberto. Uma alteração em uma interface pode exigir rastrear implementações, registros e consumidores que usam um vocabulário diferente do pedido. Complemente a busca textual com referências a símbolos, relações de importação e responsabilidade pelos contratos, quando disponíveis. O artigo sobre Spec-Driven Development examina o custo de manutenção da arquitetura e os limites das evidências atuais.

Para mudanças de frontend, inclua no conjunto de trabalho os tokens, as orientações de componentes e os exemplos do sistema de design. Equipes que estão explorando design com IA podem experimentar o OpenDesign para criar ou refinar um sistema DESIGN.md a partir de referências de marca e usá-lo em protótipos web. Confira as orientações geradas com o frontend atual antes de adotá-las.

Cobertura de idiomas, dados de treinamento e limites de tokens

Não há uma porcentagem única de inglês e português brasileiro que valha para os dados de treinamento de todos os modelos. Estatísticas públicas mostram páginas coletadas na web; cada modelo usa uma seleção própria de textos. Por exemplo, as estatísticas de idioma do Common Crawl apresentam a proporção de páginas HTML classificadas por idioma principal na coleta CC-MAIN-2026-39:

Dado público	O que mede	O que não informa
Inglês: 41,86%; português: 2,49%	Páginas em uma coleta do Common Crawl, classificadas pelo idioma principal	Proporção de todo o texto da internet ou dos dados de treinamento de qualquer modelo; nem uma separação entre português brasileiro e europeu
Llama 3: mais de 5% em idiomas diferentes do inglês	Proporção divulgada pela Meta para os dados de pré-treinamento de um modelo, em mais de 30 idiomas	A participação do português ou a composição do treinamento de outros modelos

O detector do Common Crawl analisa páginas HTML e informa um idioma principal, então o número de português agrupa as variedades. É uma evidência útil de que o português aparece menos do que o inglês nesse rastreamento, não um censo do material na internet nem uma medida do que todo modelo viu. A apresentação do Llama 3 pela Meta é um exemplo de divulgação específica de um modelo; sua proporção agregada de idiomas diferentes do inglês não deve ser generalizada para outros modelos.

A quantidade de texto é só parte da explicação. A qualidade e a variedade das fontes, a repetição de material e o treinamento posterior também afetam os resultados. Em um estudo de 2025 sobre conjuntos de textos em português, pesquisadores continuaram o treinamento de um modelo experimental com material selecionado em português e melhoraram seu desempenho em tarefas nesse idioma. Isso mostra que as escolhas de treinamento importam; não prevê o desempenho de outro modelo.

Tokens trazem outro limite. Um tokenizador divide o texto em pedaços chamados tokens, e modelos diferentes podem dividir o mesmo texto de formas diferentes. Estes dois pedidos curtos dão basicamente a mesma instrução:

Idioma	Exemplo	Tokens com OpenAI o200k_base
Inglês	“Please explain how the number of input tokens affects the context window and API cost.”	16
Português brasileiro	“Explique como a quantidade de tokens de entrada afeta a janela de contexto e o custo da API.”	21

Nesta comparação específica, a versão em português brasileiro usa 31% mais tokens. Isso é um exemplo, não uma taxa geral de conversão entre português e inglês: vocabulário, formulação e tokenizador do modelo podem mudar a contagem. Esses números afetam quanto contexto cabe e, em chamadas de API cobradas por token, o uso faturado de entrada. O custo total também depende do modelo, de entradas em cache e do texto gerado.

Conte o pedido completo considerando o modelo escolhido: instruções de sistema e desenvolvedor, definições de ferramentas, arquivos recuperados e histórico da conversa também ocupam contexto. Use o Tokenizador da OpenAI ou tiktoken para as codificações da OpenAI e a API de contagem de tokens da Anthropic, específica para o modelo, para pedidos ao Claude. A contagem da Anthropic é uma estimativa; quando disponível, confira o uso real depois da chamada. Remova contexto irrelevante antes de traduzir fatos úteis só para reduzir a contagem; compare qualidade e custo em tarefas representativas. As orientações sobre o idioma do prompt explicam como comparar instruções em inglês e português brasileiro.

Use a documentação como ponto de partida

README.md pode explicar o propósito, a configuração e a arquitetura. AGENTS.md pode registrar instruções operacionais para agentes compatíveis, como comandos de build e convenções locais. O suporte e as regras de descoberta variam de ferramenta para ferramenta; confirme se o agente carrega o arquivo e como aplica instruções em diretórios aninhados. O site do AGENTS.md descreve o formato e as ferramentas participantes.

Esses arquivos devem apontar para artefatos autoritativos, em vez de duplicar todos os detalhes:

# Serviço de pedidos

É responsável pela criação de pedidos e pelas transições de estado dos pedidos.

## Contratos
- API HTTP: contracts/orders.openapi.yaml
- API de inventory: ../inventory/contracts/inventory.openapi.yaml
- Evento de payment: contracts/payment.processed.schema.json
- Histórico do schema do banco de dados: migrations/

## Resumo das integrações
- Lê estoque: GET /api/v1/stock/{sku}
- Reserva estoque: POST /api/v1/reservations
- Consome payment.processed da exchange RabbitMQ payment-events
  por meio da queue order-payments.

A distinção entre exchange, routing key e queue é importante. Um catálogo deve usar os mesmos termos e o mesmo message broker do contrato. Se um sistema fizer a ponte entre brokers, documente essa ponte explicitamente.

Mostre os fluxos importantes, incluindo as falhas

Mermaid mantém o código-fonte dos diagramas revisável junto ao código, e um agente que entende texto pode lê-lo sem processar imagens. Agentes multimodais também podem inspecionar imagens; nenhuma representação garante uma interpretação correta.

O fluxo ilustrativo de pedidos a seguir inclui um caminho de falta de estoque que um diagrama mostrando apenas o sucesso deixaria de fora:

sequenceDiagram
    accTitle: Interação entre pedidos e estoque
    accDescr: O cliente web solicita um pedido. O serviço de pedidos solicita uma reserva. Havendo estoque, são retornados os IDs da reserva e do pedido com status 201; sem estoque, é retornado status 409.
    participant Web as Cliente web
    participant Order as Serviço de pedidos
    participant Inventory as Serviço de estoque
    Web->>Order: POST /api/v1/orders
    Order->>Inventory: POST /api/v1/reservations
    alt Estoque disponível
        Inventory-->>Order: 201 Created, ID da reserva
        Order-->>Web: 201 Created, ID do pedido
    else Estoque insuficiente
        Inventory-->>Order: 409 Conflict
        Order-->>Web: 409 Conflict, itens indisponíveis
    end

Timeouts, expiração de reservas e compensações ainda precisam de decisões próprias no contrato. Um diagrama ajuda na navegação; ele não é a especificação completa.

Torne fácil descobrir quem é responsável por cada serviço

Um arquivo pequeno, SERVICES.md, pode ser suficiente para direcionar uma investigação. Identifique os serviços independentemente dos nomes das pastas locais e registre os caminhos dos contratos relativos ao repositório responsável:

Contrato ou recurso	ID do serviço	ID do repositório	Artefato autoritativo
POST /api/v1/orders	commerce-orders	acme/orders	contracts/orders.openapi.yaml
POST /api/v1/reservations	commerce-inventory	acme/inventory	contracts/inventory.openapi.yaml
routing key payment.processed	commerce-payments	acme/payments	contracts/payment.processed.schema.json

Esses identificadores são ilustrativos. Em um catálogo real, inclua URLs canônicas dos repositórios e as equipes responsáveis. Um repositório pode conter vários serviços; quando necessário, registre o subdiretório de origem. Descobrir um serviço não concede acesso: o agente ainda precisa das permissões apropriadas no workspace ou connector.

Rastreie o checkout entre limites de serviços

Para os descontos do checkout, rastreie a entrada em web até a API de orders e a cotação de pricing. Recupere primeiro os contratos atuais e, depois, prepare checkouts editáveis apenas para os componentes que precisam de alterações. Registre as revisões candidatas, os consumers downstream e os casos de aceitação que atravessam limites entre repositórios.

Use IDs estáveis para os repositórios e um mapeamento local de checkouts fornecido para que colegas possam usar layouts de pastas diferentes. Um ponteiro para o catálogo precisa ser descoberto por instruções carregadas ou ferramentas configuradas. Registre explicitamente falhas de acesso e dependências desconhecidas.

O guia de referência para vários repositórios, abaixo, descreve em detalhes a inicialização do catálogo, o mapeamento de checkouts, a análise de impacto e a entrega coordenada.

Mantenha o contexto atual e rastreável

Automatize verificações quando a fonte for estruturada. Gere tabelas de API a partir de OpenAPI, valide exemplos de eventos usando schemas e faça o CI falhar quando a documentação gerada e versionada divergir de uma geração atualizada.

A justificativa de arquitetura e o significado de negócio ainda exigem revisão. Uma regra que apenas verifica se um arquivo Markdown foi alterado não consegue estabelecer se a alteração está correta.

flowchart LR
    accTitle: Fluxo de atualização da documentação
    accDescr: Regenere a documentação após mudanças no código ou contrato, verifique schemas e links, revise comportamento e anotações de arquitetura e então faça merge do código e da documentação.
    A["Mudanças no código ou contrato"] --> B["Regenerar a documentação derivada"]
    B --> C["Verificar schemas, links e diffs gerados"]
    C --> D["Revisar comportamento e anotações de arquitetura"]
    D --> E["Fazer merge do código e da documentação em conjunto"]

Para material recuperado, preserve a fonte, a versão ou horário da recuperação e os conflitos conhecidos. Se a documentação e o código divergirem, mostre a discrepância e identifique qual contrato rege a alteração.

Trate documentos externos, textos de issues e saídas de ferramentas como dados da tarefa, não como autoridade para sobrepor instruções ou ampliar permissões. Recupere somente as informações necessárias para a tarefa e mantenha credenciais fora dos pacotes de contexto.

Um bom contexto facilita a revisão de uma decisão. O próximo artigo trata do ambiente que permite ao agente agir: Harness Engineering.

Referência: configuração do catálogo e entrega coordenada

Use este guia quando uma tarefa abranger vários repositórios; as verificações de recuperação de contexto descritas acima também se aplicam a um único repositório.

Quando uma funcionalidade abrange vários repositórios

Um agente não consegue inferir com confiabilidade os limites de um sistema usando apenas o AGENTS.md de um microserviço. Importações de código, clientes de API, registros de implantação e logs detalhados dão pistas, mas podem deixar de fora sistemas que usam o serviço, serviços compartilhados ou dependências alcançadas por gateways. Use essas pistas para confirmar um mapa documentado do sistema; não as trate como a arquitetura comprovada.

Separe três perguntas: quais repositórios pertencem ao sistema, quais são afetados por esta tarefa e quais o agente consegue acessar e editar. As respostas não precisam ser iguais. Um serviço compartilhado de identidade pode atender vários sistemas sem precisar de mudanças para esta funcionalidade.

Separe a identidade do repositório da localização local

Os membros da equipe não precisam usar o mesmo layout de pastas. A documentação compartilhada deve identificar repositórios por IDs estáveis e URLs canônicas. Cada ambiente de desenvolvimento pode mapear esses IDs para seus próprios checkouts.

Por exemplo, um catálogo compartilhado poderia conter esta entrada. Este é um formato ilustrativo definido pela equipe, não um arquivo de configuração que os agentes entendam automaticamente:

repositories:
  acme/orders:
    url: https://github.com/acme/orders.git
    services: [commerce-orders]
    instructions: AGENTS.md
    contracts:
      - contracts/orders.openapi.yaml

O mapeamento local de um desenvolvedor poderia então ser:

checkouts:
  acme/web: /home/alex/projects/storefront
  acme/orders: /home/alex/work/order-service
  acme/pricing: /mnt/workspaces/pricing

Outra pessoa pode usar caminhos completamente diferentes para os mesmos IDs. O mapeamento local deve ficar fora dos metadados compartilhados do repositório. Uma ferramenta de configuração da equipe pode criar ou localizar os checkouts selecionados, validar os remotes e as revisões do Git e disponibilizar o mapeamento para o agente. Sem essa ferramenta, forneça o mapeamento explicitamente na tarefa. Não presuma que um nome inventado de arquivo de registro será descoberto automaticamente.

Um workspace padronizado para a tarefa é outra opção: um script de bootstrap pode preparar um diretório temporário com layout previsível apenas para os repositórios selecionados. A reprodutibilidade vem desse processo de configuração e das revisões registradas, não da expectativa de que todos organizem suas pastas pessoais da mesma forma.

Dê a cada serviço um ponto estável de descoberta

Mantenha o contexto compartilhado do sistema em um repositório de documentação ou serviço de catálogo. O AGENTS.md de cada aplicação pode indicar onde encontrá-lo sem depender de caminhos frágeis como ../../system-context:

## Contexto do sistema
- ID do serviço: commerce-orders
- ID do repositório: acme/orders
- Sistema: Commerce
- Repositório compartilhado de documentação: https://github.com/acme/system-context
- Para tarefas entre repositórios, leia SYSTEM.md, SERVICES.md e WORKFLOW.md.
- Resolva checkouts locais pelo mapeamento de workspace fornecido.
- Se o contexto compartilhado estiver inacessível, informe o que está faltando.
- Antes de editar outro repositório, leia as instruções aplicáveis a ele.

As URLs acima são exemplos para a localização da sua organização. Um link ajuda a encontrar a fonte, mas não garante carregamento automático nem autenticação. Configure um connector de repositório, uma ferramenta de consulta ao catálogo ou um checkout local da documentação e ensine o agente a usá-lo. Para cada tarefa, registre a revisão da documentação compartilhada consultada.

Um AGENTS.md dentro de orders não rege arquivos de frontend nem de pricing. Da mesma forma, o AGENTS.md do repositório de documentação rege os arquivos daquele repositório; ele não se torna automaticamente uma política global. Carregue os procedimentos compartilhados de forma deliberada e siga as regras locais de cada repositório alterado. A orientação do AGENTS.md descreve instruções por diretório; o comportamento exato de descoberta ainda depende do agente.

Como o agente encontra o catálogo inicialmente?

A descoberta precisa começar por um ponto de entrada que o agente realmente receba. Um catálogo existir em algum lugar da empresa não é suficiente. Configure pelo menos um destes pontos de entrada:

Ponto de entrada	Como o agente descobre a localização	O que a equipe precisa fornecer
Instruções do repositório	O AGENTS.md carregado indica o catálogo ou o repositório de documentação	Um ponteiro mantido em cada repositório participante
Instruções da organização ou workspace	As instruções iniciais configuradas para o agente identificam o catálogo	Configuração específica da ferramenta que de fato carrega essas instruções
Ferramenta de catálogo configurada	O runtime oferece uma ferramenta cuja descrição explica o que ela consulta	Uma integração instalada, configuração do endpoint e autenticação
Contexto explícito da tarefa	O usuário fornece a localização do catálogo e o método de acesso	Informações suficientes para recuperar as entradas relevantes

Para um agente que começa em orders, a cadeia de descoberta pode ser simples:

Tarefa: Adicionar suporte a códigos de desconto ao checkout
  → Carregar orders/AGENTS.md
  → Ler o ponteiro do catálogo e o ID do serviço: commerce-orders
  → Recuperar a entrada do catálogo desse serviço pelo acesso configurado
  → Seguir as relações do sistema, da API e dos consumers relevantes ao checkout
  → Resolver os IDs de repositório candidatos para fontes remotas ou checkouts locais
  → Ler as instruções de cada repositório-alvo antes de editar

A primeira etapa depende da ferramenta: confirme que ela carrega o AGENTS.md ou peça explicitamente que o leia. Mencionar o catálogo nesse arquivo não instala um connector, configura um servidor nem concede acesso.

Se a equipe disponibilizar uma ferramenta de catálogo, a descrição dela deve explicar quando usá-la e quais identificadores aceita. Por exemplo, uma ferramenta definida pela equipe chamada lookup_service(service_id) poderia retornar URLs de repositórios, contratos, responsáveis e relações; uma ferramenta search_services(query) poderia localizar candidatos quando o ID do serviço for desconhecido. Esses nomes são ilustrativos, não recursos internos dos agentes. O mesmo acesso pode ser implementado por uma CLI ou API documentada; MCP é um transporte opcional.

Configure a autenticação no ambiente de execução ou no connector, não no AGENTS.md. O fato de um desenvolvedor estar conectado a um catálogo pelo navegador não demonstra que a ferramenta de API do agente consiga acessá-lo. Diferencie uma entrada ausente de uma falha de autorização ou de um catálogo indisponível.

Mantenha o ponteiro de descoberta pequeno e estável. Templates de repositório podem incluí-lo, e uma verificação de CI pode confirmar sua presença e se aponta para a localização esperada. Isso reduz divergências de configuração sem copiar o conteúdo do catálogo para cada repositório. Teste todo o caminho de descoberta durante a integração: o agente configurado consegue recuperar a entrada do serviço atual e localizar uma dependência conhecida?

Se nenhum desses pontos de entrada estiver disponível, o agente deve informar que não consegue estabelecer os limites do sistema e pedir a localização do catálogo ou a equipe responsável. Ainda pode inspecionar evidências locais, mas não deve apresentar relações de repositórios inferidas como fatos confirmados.

Descubra de forma ampla e recupere de forma seletiva

Milhares de microserviços não exigem milhares de clones locais. Nessa escala, use um catálogo pesquisável de sistemas, responsáveis por serviços, localizações de repositórios, APIs oferecidas e consumidas e relações entre eventos. Por exemplo, o modelo de sistemas do Backstage representa sistemas, componentes e APIs. Um catálogo é um índice a confirmar com artefatos autoritativos, não uma prova de que todas as dependências foram registradas.

Recupere progressivamente mais detalhes:

1. Encontre candidatos: consulte a capacidade de negócio ou jornada do usuário relevante, como checkout, em vez de carregar o catálogo inteiro no prompt.
2. Inspecione os limites: recupere schemas de API, contratos de eventos e trechos de código-fonte dos serviços candidatos usando ferramentas remotas disponíveis. Confira dependências e consumers de qualquer contrato que possa mudar.
3. Prepare o conjunto de trabalho: reutilize ou clone apenas os repositórios necessários para editar, investigar mais a fundo ou fazer builds locais. Registre as revisões escolhidas e carregue as instruções aplicáveis.
4. Amplie quando as evidências exigirem: adicione outro repositório quando uma dependência descoberta afetar a tarefa. Informe dependências inacessíveis ou desconhecidas em vez de presumir que o escopo está completo.

Para uma funcionalidade de código de desconto, o agente talvez leia metadados de vários serviços, mas precise de checkouts editáveis apenas dos repositórios de frontend, orders e pricing. Um serviço de inventory sem alterações pode exigir somente seu contrato para análise e um test double ou uma instância de teste implantada para verificação.

A recuperação de fontes e a configuração de runtime são decisões separadas. Mesmo com três checkouts, a aplicação pode depender de outros serviços. Use pacotes ou imagens publicados, test doubles compatíveis com o contrato ou um ambiente de integração, conforme apropriado. Declare quais limites foram simulados e quais foram verificados contra serviços reais; mocks locais não demonstram compatibilidade do sistema inteiro.

Transforme o pedido da funcionalidade em um mapa de impacto

Suponha que a funcionalidade seja “permitir que clientes apliquem um código de desconto no checkout”. Delimitar o sistema reduz a busca, mas o agente ainda precisa rastrear o comportamento para determinar o conjunto de mudanças:

Repositório	Responsabilidade neste exemplo	Mudança candidata	Verificação
acme/web	Receber o código e exibir a cotação	Adicionar entrada, mensagens de validação e totais	Testes de UI e fluxo de checkout
acme/orders	Coordenar o checkout e persistir a cotação aceita	Aceitar o código opcional e solicitar uma cotação no servidor	Testes de API e persistência
acme/pricing	Ser responsável pelas regras de elegibilidade e pelo cálculo de preço	Avaliar o código e retornar a cotação autoritativa	Testes de regras e de contrato

Esta é uma hipótese inicial a conferir com o código-fonte e os contratos. Se pricing já aceitar códigos de desconto, talvez sua implementação não precise mudar. Se outro consumer depender da resposta de orders, inclua verificações de compatibilidade para esse consumer. O frontend deve exibir a cotação do servidor, não inventar um segundo conjunto de regras de preço.

Registre o escopo acordado em changes/checkout-discounts.md: repositórios e revisões afetados, mudanças em contratos, casos de aceitação, decisões pendentes e dependências entre mudanças. Mantenha ali o plano específico da funcionalidade; atualize o AGENTS.md somente quando as instruções de trabalho contínuo mudarem.

Um pedido inicial poderia ser:

Implemente suporte a códigos de desconto em todo o fluxo de checkout do Commerce.

Leia SYSTEM.md, SERVICES.md e WORKFLOW.md em acme/system-context
usando o acesso configurado ao repositório. Resolva acme/web, acme/orders
e acme/pricing pelo mapeamento local de workspace fornecido; prepare
checkouts ausentes somente quando necessário. Leia os arquivos AGENTS.md
aplicáveis e rastreie o fluxo da cotação antes de decidir quais repositórios editar.

Registre o mapa de impacto e o plano de compatibilidade em
changes/checkout-discounts.md em acme/system-context. Implemente as mudanças
necessárias nestes três repositórios de aplicação, execute verificações locais
e o cenário de checkout entre serviços e informe os resultados por repositório.
Se outro repositório precisar de alterações, identifique-o e explique por quê.

Coordene a verificação e a entrega

Repositórios separados têm históricos e releases separados. A aprovação dos testes unitários em cada repositório não demonstra que as versões propostas funcionam em conjunto. Execute verificações de contrato e um cenário de integração usando as revisões candidatas reais, depois registre essa combinação de versões no plano de mudança.

Neste exemplo, uma implantação compatível poderia primeiro adicionar suporte a pricing, depois o suporte de order-service a um código opcional e, por fim, habilitar a funcionalidade no frontend. Verifique se clientes antigos continuam compatíveis e defina o procedimento de rollback. Não presuma que o merge de vários pull requests crie uma implantação atômica.

Se o fluxo da equipe usa PRs, crie uma branch e um pull request vinculado para cada repositório alterado, com um registro compartilhado conectando-os. Um único agente com acesso adequado pode trabalhar nesses checkouts; agentes separados são opcionais. O essencial é ter um mapa compartilhado, escopo explícito, instruções locais e evidências de que os componentes funcionam em conjunto.