Cada conhecimento em seu lugar

Uma equipe começa com uma frase simples em seu arquivo de instruções: “rode os testes antes de concluir”. Depois de alguns erros, acrescenta arquitetura, comandos de migração, preferências de um cliente, o manual inteiro do ERP, exemplos de API, segredos de homologação e “nunca registre access token”. O arquivo cresce. Regras antigas contradizem novas; detalhes de banco aparecem numa tarefa de interface; a proibição crítica continua sendo apenas um pedido que o modelo pode interpretar mal.

O problema não é falta de conhecimento. É conhecimento colocado na superfície errada.

Use este modelo mental:

A seta não escolhe um produto. AGENTS.md no Codex e CLAUDE.md no Claude Code são implementações de instrução persistente. Os detalhes mudam; a pergunta permanece: isto deve estar sempre no contexto, ser recuperado sob demanda ou ser imposto fora do modelo?

As sete superfícies, sem mistério

1. Instrução permanente: comportamento estável e sempre relevante

Uma instrução permanente orienta como o agente deve trabalhar naquele escopo. Exemplos no sistema de manutenção:

# Regras do repositório
- Preserve contratos públicos da API; mudanças incompatíveis exigem versão nova.
- Rode `pnpm test` e `pnpm typecheck` antes de declarar conclusão.
- Nunca edite arquivos sincronizados em `sources/`.

Ela serve para convenções do repositório, comandos de verificação, limites de escopo e expectativas de revisão que importam em quase toda tarefa. A documentação atual do Codex recomenda manter AGENTS.md pequeno e colocar orientação perto do diretório ao qual se aplica. A documentação atual do Claude Code recomenda fatos que valem em toda sessão e move procedimentos longos para skills ou regras com escopo de caminho.

Não use instrução permanente para copiar manuais, registrar o estado de um ticket, guardar tokens ou impor uma proibição crítica. Instrução é contexto interpretado pelo modelo, não configuração infalível. Se “access tokens nunca podem aparecer em logs” bloqueia release, implemente redaction, teste com fixture falsa e scanner no CI; mantenha a frase apenas como explicação.

2. Memória: fato durável, não depósito de conversa

Memória carrega adiante algo aprendido: “o usuário prefere relatórios em português do Brasil” ou “neste repositório, o ERP é a fonte de verdade do saldo”. Uma memória profissional precisa de:

• fato atômico, sem a conversa inteira;
• origem e data;
• escopo: pessoa, organização ou projeto;
• confiança e validade/revisão;
• classificação de sensibilidade e lista de quem pode ler;
• chave para corrigir ou excluir.

{
  "key": "project.inventory_source",
  "value": "ERP",
  "origin": "ADR-014 aprovado por Operações e TI",
  "scope": "maintenance-app",
  "review_by": "2026-11-09",
  "sensitivity": "internal",
  "delete_key": "project.inventory_source"
}

Não persista automaticamente uma conversa: ela pode conter hipótese vencida, dado pessoal, segredo ou instrução maliciosa obtida de uma página. O modelo pode propor uma memória; uma política decide se ela pode ser gravada. Memória não substitui fonte oficial: preços, versões e políticas externas devem ser consultados novamente.

Em agosto de 2026, Claude Code documenta CLAUDE.md e auto memory como mecanismos distintos, ambos carregados como contexto, não como enforcement. Codex também separa orientação persistente, memórias e skills. Portanto, “está na memória” significa “pode influenciar a próxima execução”, não “será obedecido” nem “continua verdadeiro”.

3. Skill: procedimento repetível carregado quando necessário

Uma skill empacota conhecimento procedural: gatilho, entradas, sequência, referências, scripts, verificações e condição de parada. Exemplo: revisar uma migração PostgreSQL antes do deploy.

Gatilho: alteração de schema ou arquivo de migração
Entrada: diff, schema atual, política de rollback
Passos: detectar lock → estimar impacto → testar ida/volta → revisar backup
Saída: relatório com riscos e evidências
Parada: migração aprovada ou bloqueio explícito
Não usar: mudança apenas de CSS

Uma skill não é “seja cuidadoso”. Também não é autoridade adicional: seu script e suas ferramentas continuam sujeitos ao sandbox e às permissões do host. Teste acionamento positivo, negativo e ambíguo. A documentação do Codex descreve divulgação progressiva: metadados ficam disponíveis para descoberta; o conteúdo completo da skill, suas referências e scripts entram apenas quando necessários. Isso preserva contexto sem esconder o procedimento.

4. Hook, teste, policy ou CI: controle determinístico

Um hook executa em um ponto do ciclo, por exemplo antes de uma ferramenta ou depois de uma edição. CI executa verificações no fluxo de integração. Testes, linters e scanners comparam fatos observáveis. Use essas superfícies quando a regra pode ser verificada mecanicamente e não deve depender da interpretação do modelo.

Orientação: “não registre tokens”
Controle: redaction central + teste com `fake-token-for-test`
Portão: scanner falha o job se o padrão aparecer no artefato
Evidência: job, comando, fixture e saída

Codex e Claude Code documentam hooks de ciclo de vida capazes de verificar ou bloquear ações. Isso também cria risco: um hook é código executado com a autoridade do processo. Revise-o como software, fixe sua origem, limite tempo e entrada, trate texto vindo de ferramentas como não confiável e não transforme todo julgamento humano em regex bloqueante. CI é preferível como último portão compartilhado; um hook local dá feedback mais cedo, mas pode não existir na máquina de outra pessoa.

5. MCP: conexão padronizada, não confiança automática

O Model Context Protocol (MCP) conecta uma aplicação de IA a capacidades externas. Na arquitetura:

• host: aplicação que coordena, como Codex ou Claude Code;
• cliente: conexão mantida pelo host para um servidor;
• servidor: programa local ou remoto que expõe capacidades;
• resources: dados legíveis;
• tools: funções executáveis;
• prompts: modelos de interação reutilizáveis.

Na fotografia revisada em 2026-08-09, a especificação latest do MCP aponta para 2026-07-28. Ela define protocolo e capacidades, mas declara que MCP não determina como a aplicação usa o modelo ou o contexto. A própria especificação exige cautela: descrições de ferramentas podem ser não confiáveis, ações requerem consentimento, e o protocolo sozinho não consegue impor todos os princípios de segurança.

Por isso, manage_everything com credencial administrativa é um desenho ruim, mesmo que o schema seja válido. Prefira ferramentas estreitas como read_work_order e reserve_part, credenciais separadas, escopo por unidade, validação de entrada e saída, confirmação para efeitos irreversíveis, egress allowlist, auditoria e revogação. Um recurso lido pode conter prompt injection; trate sua resposta como dado, não como nova instrução com autoridade.

6. Subagente: contexto isolado para trabalho focado

Um subagente recebe uma tarefa delimitada, ferramentas e uma saída contratada. É útil quando o trabalho pode ser separado: um agente somente leitura inventaria contratos, outro executa testes, um terceiro revisa segurança. O contexto isolado reduz interferência e permite menor conjunto de ferramentas.

name: erp-contract-reviewer
mission: revisar somente o contrato da integração ERP
inputs: [openapi.yaml, ADR-014, testes de contrato]
tools: [read, search]
output: findings.json
stop: encontrou evidência suficiente ou registrou bloqueio

Não delegue apenas para parecer sofisticado. Coordenação consome tokens, tempo e revisão; dois agentes podem editar a mesma fronteira, repetir pesquisa ou confirmar o erro um do outro. Contexto separado também não é sandbox: restrinja ferramentas, arquivos, credenciais, duração e efeitos. A documentação atual do Claude Code permite configurar prompts, ferramentas, modos de permissão, hooks e skills por subagente; Codex também documenta subagentes especializados. A regra geral é menor autoridade que a do agente principal, salvo justificativa explícita.

7. Documentação: explicação e fonte consultada sob demanda

Documentação registra conceitos, arquitetura, decisões, contratos, runbooks e exemplos para pessoas e agentes. Ela pode ser longa porque não precisa entrar inteira em toda execução. A instrução permanente deve rotear: “para mudanças no ERP, leia docs/integrations/erp.md”. A documentação deve ter dono, data de revisão, versão aplicável e links verificáveis.

Uma ADR explica por que o ERP é dono do estoque; OpenAPI descreve a interface; runbook ensina recuperar a fila; tutorial ensina um iniciante. Nenhum deles substitui teste. Se um documento afirma uma regra crítica, ligue-o ao controle que prova a regra e à telemetria que mostra seu comportamento em produção.

A matriz de decisão

Situação	Superfície principal	Por quê	Controle complementar
“rode estes três comandos em toda mudança”	instrução do repositório	estável e sempre relevante	CI executa de verdade
“cliente prefere PT-BR”	memória governada	fato durável e escopado	revisão/exclusão
“como revisar uma migração”	skill	procedimento repetível	testes da skill
“token jamais em logs”	redaction + teste + CI	proibição determinística	instrução explica intenção
consultar saldo do ERP	MCP read_inventory	capacidade externa viva	credencial read-only e auditoria
revisar 200 arquivos sem editar	subagente read-only	trabalho focado e isolável	limite de tempo e saída estruturada
explicar arquitetura e decisões	documentação	profundidade sob demanda	data, dono e links
“neste ticket preserve a v1”	prompt/ticket	restrição temporária	critério de aceite

Mais de uma superfície pode cooperar. A regra está documentada, uma instrução aponta para ela, a skill executa o procedimento e o CI comprova a propriedade. O erro é copiar o mesmo texto inteiro em todas, porque as cópias divergem.

Excesso de contexto é custo e ruído

Contexto é a informação disponível ao modelo numa execução: instruções, conversa, arquivos, ferramentas e resultados. Mesmo quando cabe na janela, não é gratuito. Texto irrelevante compete por atenção, aumenta tokens e dificulta descobrir qual regra prevalece. Regras contraditórias podem produzir escolhas inconsistentes; a documentação do Claude Code alerta explicitamente para esse caso e recomenda instruções concisas.

Faça um orçamento de contexto:

1. carregue sempre somente identidade, limites e comandos essenciais;
2. use roteamento para documentação e regras por diretório;
3. carregue skills e referências quando o gatilho ocorrer;
4. recupere memória por escopo e validade;
5. exponha somente ferramentas necessárias à tarefa;
6. remova instruções deriváveis do próprio repositório;
7. meça tokens, falhas de aderência e tempo — não presuma melhoria.

Uma instrução menor não é automaticamente melhor: retire apenas o que é irrelevante, duplicado, vencido ou melhor imposto em outra camada. Preserve justificativas surpreendentes e armadilhas que o código não revela.

Privilégio acompanha capacidade

Quanto mais uma superfície pode fazer, maior o dano possível. Use uma análise simples:

ativo → ação possível → abuso/erro → impacto → limite → teste → auditoria

Para reserve_part, o ativo é o estoque; o abuso é reservar peça de outra unidade ou repetir a baixa; o impacto é indisponibilidade e custo; limites incluem unidade, quantidade, chave idempotente e confirmação; testes tentam cruzar unidade e repetir; auditoria registra ator, ordem e resultado.

Não passe segredo no prompt, memória, skill ou retorno de ferramenta. O host deve fornecer credenciais ao transporte ou processo apropriado, com escopo mínimo e rotação. O nome read_order não prova que a implementação é somente leitura. Valide schema e efeito real, limite egress e mantenha aprovação humana para ação de alto impacto.

Da automação simples à Era Maestro

Era Maestro é usada nesta obra como metáfora pedagógica para uma pessoa orquestrar vários agentes especializados; não é um estágio oficial da OpenAI, Anthropic ou MCP, nem uma meta obrigatória. A complexidade só sobe se uma avaliação demonstrar ganho.

Comece com um workflow determinístico quando os passos são conhecidos. A Anthropic recomenda a solução mais simples e diferencia workflows, em que o código determina o caminho, de agentes, em que o modelo decide dinamicamente. Antes de subir um nível, preserve um baseline e meça em casos fixos e holdout:

• taxa de tarefa correta e gravidade dos erros;
• custo e latência ponta a ponta;
• chamadas de ferramentas e pedidos de aprovação;
• incidentes de permissão ou dados;
• trabalho de revisão humana;
• conflitos, repetição e falhas de handoff;
• capacidade de parar e recuperar.

Use subagentes quando as tarefas são realmente decomponíveis, paralelas ou exigem avaliação independente. Evite-os quando o trabalho é curto, sequencial, compartilha estado frágil ou cada agente precisa reler o mesmo contexto. A “Era Maestro” é aprovada apenas se qualidade líquida melhora dentro dos limites de custo e segurança. Se quatro agentes custam mais e não vencem o workflow no holdout, volte ao workflow; isso é engenharia, não retrocesso.

Laboratório executável: o fiscal de superfícies

Objetivo: detectar conhecimento colocado numa superfície insegura. Hipótese: regras estruturais simples localizam falhas que uma revisão visual deixa passar. Ambiente: Python 3.10+, somente biblioteca padrão, sem rede e sem segredos. Duração: 30 a 45 minutos.

Salve como surface_guard.py:

from __future__ import annotations

import json
import sys


BAD = [
    {"id": "I-1", "surface": "instruction", "always_relevant": False,
     "deterministic_block": True, "text": "Nunca registre access token"},
    {"id": "M-1", "surface": "memory", "value": "entire conversation + sk-fake-test",
     "origin": "", "scope": "all", "review_by": "", "delete_key": ""},
    {"id": "S-1", "surface": "skill", "trigger": "qualquer tarefa",
     "steps": [], "stop": ""},
    {"id": "X-1", "surface": "mcp", "external": True,
     "tool": "manage_everything", "credential_scope": "admin:*", "approval": "never"},
    {"id": "A-1", "surface": "subagent", "bounded_task": "",
     "tools": ["*"], "stop": "", "output": ""},
    {"id": "D-1", "surface": "documentation", "owner": "", "reviewed": ""},
]


GOOD = [
    {"id": "I-1", "surface": "instruction", "always_relevant": True,
     "deterministic_block": False, "text": "Rode testes e typecheck antes de concluir"},
    {"id": "M-1", "surface": "memory", "value": "ERP owns inventory balance",
     "origin": "ADR-014", "scope": "maintenance-app",
     "review_by": "2026-11-09", "delete_key": "project.inventory_source"},
    {"id": "S-1", "surface": "skill", "trigger": "schema migration changed",
     "steps": ["inspect locks", "test forward", "test rollback"],
     "stop": "evidence produced or explicit blocker"},
    {"id": "C-1", "surface": "control", "executable": True,
     "fixture": "fake-token-for-test", "blocking": True},
    {"id": "X-1", "surface": "mcp", "external": True,
     "tool": "read_inventory", "credential_scope": "inventory:read:NORTH",
     "approval": "read-allowlisted", "egress": ["erp.internal"]},
    {"id": "A-1", "surface": "subagent",
     "bounded_task": "review ERP contract without edits", "tools": ["read", "search"],
     "stop": "findings complete or blocker", "output": "findings.json"},
    {"id": "D-1", "surface": "documentation", "owner": "platform-team",
     "reviewed": "2026-08-09"},
]


def validate(items: list[dict]) -> list[str]:
    findings: list[str] = []
    for item in items:
        surface, item_id = item.get("surface"), item.get("id", "unknown")
        if surface == "instruction":
            if not item.get("always_relevant"):
                findings.append(f"{item_id}:instruction-not-always-relevant")
            if item.get("deterministic_block"):
                findings.append(f"{item_id}:critical-rule-needs-control")
        elif surface == "memory":
            required = ("origin", "scope", "review_by", "delete_key")
            if any(not item.get(field) for field in required):
                findings.append(f"{item_id}:ungoverned-memory")
            value = str(item.get("value", "")).lower()
            if "conversation" in value or "sk-" in value:
                findings.append(f"{item_id}:memory-may-contain-secret-or-transcript")
        elif surface == "skill":
            if not item.get("trigger") or not item.get("steps") or not item.get("stop"):
                findings.append(f"{item_id}:skill-without-trigger-steps-stop")
        elif surface == "control":
            if not all(item.get(field) for field in ("executable", "fixture", "blocking")):
                findings.append(f"{item_id}:control-not-provable")
        elif surface == "mcp":
            broad = item.get("tool") == "manage_everything" or "*" in item.get("credential_scope", "")
            if broad or not item.get("egress"):
                findings.append(f"{item_id}:mcp-excessive-authority")
            if item.get("approval") in (None, "never"):
                findings.append(f"{item_id}:mcp-without-approval-policy")
        elif surface == "subagent":
            if (not item.get("bounded_task") or "*" in item.get("tools", [])
                    or not item.get("stop") or not item.get("output")):
                findings.append(f"{item_id}:unbounded-subagent")
        elif surface == "documentation":
            if not item.get("owner") or not item.get("reviewed"):
                findings.append(f"{item_id}:documentation-without-owner-review")
        else:
            findings.append(f"{item_id}:unknown-surface")
    return sorted(findings)


def main() -> int:
    mode = sys.argv[1] if len(sys.argv) > 1 else "prove"
    items = BAD if mode == "bad" else GOOD if mode == "prove" else None
    if items is None:
        print("usage: python surface_guard.py [bad|prove]", file=sys.stderr)
        return 64
    findings = validate(items)
    result = {"mode": mode, "valid": not findings, "findings": findings,
              "surfaces_checked": len(items)}
    print(json.dumps(result, indent=2))
    if mode == "bad":
        expected = {
            "I-1:instruction-not-always-relevant", "I-1:critical-rule-needs-control",
            "M-1:ungoverned-memory", "M-1:memory-may-contain-secret-or-transcript",
            "S-1:skill-without-trigger-steps-stop", "X-1:mcp-excessive-authority",
            "X-1:mcp-without-approval-policy", "A-1:unbounded-subagent",
            "D-1:documentation-without-owner-review",
        }
        assert set(findings) == expected
        return 2
    assert findings == []
    assert {item["surface"] for item in items} == {
        "instruction", "memory", "skill", "control", "mcp", "subagent", "documentation"
    }
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Execute a falha provocada e depois a configuração corrigida:

python surface_guard.py bad
# esperado: 9 achados e exit code 2

python surface_guard.py prove
# esperado: "valid": true, 7 superfícies e exit code 0

O detector é didático: sk- é apenas um padrão de fixture e não um scanner de segredos de produção. Ele prova coerência do manifesto, não segurança do agente. Em produção, combine testes específicos, scanner mantido, revisão do código de hooks, política do host e evals adversariais.

Diagnóstico das falhas

Achado	Causa	Correção
instrução não é sempre relevante	estado temporário foi promovido	mover para ticket, prompt ou regra escopada
regra crítica está só em texto	orientação foi confundida com barreira	criar controle executável e CI
memória sem origem/validade	conversa foi tratada como verdade	selecionar fato, governar e permitir exclusão
skill sem gatilho/parada	conselho vago virou workflow	declarar entrada, passos, evidência e stop
MCP com autoridade excessiva	protocolo foi confundido com permissão	ferramenta estreita, credencial mínima e egress
subagente ilimitado	isolamento foi confundido com sandbox	missão, ferramentas, prazo e saída delimitados
documentação órfã	ninguém responde por atualidade	dono, versão e revisão periódica

Critérios de aceite

• cada regra do projeto possui superfície, escopo, dono e validade;
• proibições mecanicamente verificáveis possuem teste ou portão fora do modelo;
• instruções sempre carregadas são pequenas, não contraditórias e realmente recorrentes;
• memórias possuem origem, ACL, revisão e exclusão; nenhum segredo ou transcript integral;
• skills têm gatilhos positivos/negativos, passos, referências e condição de parada;
• ferramentas MCP têm efeito estreito, schema, credencial mínima, egress, aprovação e auditoria;
• subagentes têm missão delimitada, ferramentas mínimas, stop e saída verificável;
• documentação possui dono, versão e ligação com controles;
• multiagente só avança após vencer baseline em qualidade líquida, custo e segurança;
• os modos bad e prove retornam respectivamente 2 e 0.

Exercícios e recuperação ativa

1. Classifique vinte itens reais do seu projeto. Justifique por que cada um não pertence às outras superfícies.
2. Pegue uma regra “nunca faça X”. Crie fixture falsa, teste que falha e portão de CI; mantenha uma frase curta de intenção.
3. Escreva uma skill de revisão de migração e prove que ela não dispara numa alteração apenas de interface.
4. Redesenhe manage_everything como três ferramentas MCP estreitas. Para cada uma, defina credencial, confirmação, egress e log.
5. Compare um workflow fixo com um subagente em dez casos congelados e cinco holdouts. Registre acerto, custo, latência e revisão humana. Aceite “não adotar”.
6. Mutile GOOD: remova a parada da skill, use admin:* no MCP e troque o agente para tools: ["*"]. Preveja os achados antes de executar.

Sem consultar, explique: por que uma skill não é memória? Por que MCP não fornece menor privilégio automaticamente? Por que AGENTS.md ou CLAUDE.md não bloqueia sozinho um vazamento? Em que situação documentação longa é melhor que instrução curta? Qual evidência autorizaria a evolução para a Era Maestro?

Limpeza e conclusão

Se criou o laboratório numa pasta descartável, remova apenas o arquivo que conferiu:

Remove-Item -LiteralPath .\surface_guard.py

Verifique o caminho antes de executar. Não remova evidências exigidas pelo projeto sem preservá-las no local correto.

A regra final é simples: contexto orienta; dados precisam de governança; procedimentos precisam de gatilho; controles precisam executar; integrações precisam de limites; agentes precisam de escopo; documentação precisa de dono. A melhor arquitetura não é a que possui todas as superfícies. É a que usa a menor combinação capaz de produzir resultado e evidência com risco aceitável.