Arquitetura de Agentes

Esta é uma página de especificação técnica voltada para desenvolvedores. Ela usa o vocabulário interno do Apothem — classes de adaptadores, materializadores, manifesto de propagação, convergência de convenção entre congêneres — sem suavizá-lo para um público geral.

O Apothem lê um único perfil compartilhado (~/.config/apothem/profile.yaml) e materializa a configuração nativa para dezessete adaptadores registrados. Os harnesses não compartilham um modelo de capacidade agêntica: alguns expõem hooks de pré-chamada de ferramenta, alguns executam regras a partir de arquivos .md planos, alguns embutem cada regra em um único arquivo de instruções, e alguns renderizam uma configuração orientada por perfil no momento da instalação. Esta página mapeia essa divergência e a disciplina que o Apothem aplica sobre ela.

Matriz de capacidades agênticas por harnessCopy Anchor Link

A matriz abaixo cobre todos os dezessete harnesses. Colunas: a superfície de hook PreToolUse que o adaptador conecta (quando um harness documenta hooks que o adaptador não registra, a célula informa isso), o formato que o Apothem usa para ativar regras, a classe do adaptador (consulte Classes de adaptadores), e se o adaptador renderiza uma configuração nativa por meio de um materializador.

Notas sobre a matriz:

• claude-code é o adaptador com a superfície nativa mais ampla. Ele carrega hooks nativos PreToolUse, PostToolUse, Stop e SessionStart e entrega templates de settings do fornecedor. Ele grava um único bloco gerenciado delimitado por sentinelas em CLAUDE.md e deixa a prosa do operador fora das sentinelas inalterada.
• codex instala hooks de ciclo de vida nativos via hooks.json, converte agentes para TOML, encapsula prompts de comando como skills do Codex e deixa config.toml sob propriedade do operador.
• antigravity mantém ~/.gemini/GEMINI.md como âncora de contexto global e instala um plugin do Apothem em ~/.gemini/antigravity-cli/plugins/apothem/. Os arquivos de hook são mantidos como material de suporte até que o adaptador assuma a tradução do esquema de hooks da Antigravity.
• cursor ativa regras por meio de um arquivo .mdc que carrega o frontmatter MDC do fornecedor (description, globs, alwaysApply); o adaptador não grava nenhum arquivo único .cursorrules.
• windsurf usa .devin/rules/; o adaptador não grava nenhum arquivo único .windsurfrules.
• hermes e open-claw renderizam arquivos de configuração nativos e conectam os diretórios de skills de suporte do Apothem pela configuração de diretório de skills documentada de cada harness. Cohorts compartilhados não suportados permanecem sob subárvores de suporte de propriedade do Apothem.
• qwen-code renderiza chaves documentadas de settings.json para contexto e despacho de hooks e então usa os diretórios nativos de comandos, skills e agentes do Qwen.

Disciplina de orquestração entre harnessesCopy Anchor Link

O Apothem aplica a convergência de convenção entre congêneres: o mesmo fluxo de trabalho invocável pelo operador é projetado no idioma nativo de cada harness em vez de ser forçado em um único formato compartilhado. Uma regra que se ativa como um arquivo .md plano sob o claude-code torna-se uma regra de workspace .mdc sob o cursor, uma seção embutida de GEMINI.md sob o gemini-cli, e uma referência concatenada no QWEN.md do qwen-code mais diretórios de descoberta nativos — a mesma intenção, no dialeto de cada harness.

O conjunto canônico-mestre reside em:

src/apothem/{rules,commands,skills,agents,output-styles,hooks,conformity,statuslines}/

Cada adaptador propaga um subconjunto desse conjunto. O subconjunto por harness é declarado em src/apothem/lib/propagation-manifest.yaml; o manifesto é a única fonte de verdade sobre quais artefatos chegam a qual harness e em que forma. Um adaptador nunca inventa artefatos fora do manifesto, e o manifesto nunca atribui a um harness um artefato cuja superfície ele não tem como hospedar.

Classes de adaptadores explicadasCopy Anchor Link

O Apothem classifica os adaptadores em três classes conforme como traduzem o perfil compartilhado em saída nativa.

• Classe I — propagação bruta. O adaptador copia os artefatos canônicos-mestre (um subconjunto declarado no manifesto) diretamente para o local de configuração do harness sem nenhuma etapa de renderização. Não há materializador. antigravity, codebuddy, codex, cursor, gemini-cli, github-copilot, glm, kimi-code, kiro, trae, windsurf e zed são Classe I.
• Classe II-A — bruta + templates de settings vinculados ao fornecedor. O adaptador faz a propagação bruta dos artefatos e adicionalmente gerencia templates de settings específicos do fornecedor vinculados ao esquema do fornecedor. claude-code é Classe II-A.
• Classe II-B — materializador de superfície única renderizado a partir do perfil. O adaptador renderiza o perfil compartilhado em uma única superfície de configuração nativa por meio de um materializador. hermes, open-claw, opencode e qwen-code são Classe II-B.

Comportamento em tempo de materializaçãoCopy Anchor Link

A distinção de classe aparece no momento da materialização — quando um operador executa a CLI contra um harness:

• apothem install --harness <H> propaga o subconjunto do manifesto para <H> e, para adaptadores Classe II-A / II-B, renderiza a configuração nativa.
• apothem verify --harness <H> verifica se os arquivos gerenciados existem e podem ser analisados. Com --profile PATH, também os verifica contra o que esse perfil produziria e falha quando há divergência.
• apothem status reporta se cada harness está instalado e se divergiu do perfil compartilhado atual.
• apothem doctor reporta a saúde por harness em cada adaptador registrado: ok, not_installed, needs_project, verify_failed, hook_failed ou error.

Consulte a referência da CLI para as superfícies completas de comandos.

Taxonomia de divergênciaCopy Anchor Link

Os dezessete harnesses divergem ao longo de três eixos. Toda diferença por harness na matriz se reduz a um destes.

O trabalho do Apothem é manter uma intenção coerente do operador constante enquanto esses três eixos variam por harness. O manifesto de propagação e o contrato de classe de adaptador são os dois mecanismos que mantêm essa intenção estável ao longo da divergência.