Plugin para Agentes de Codificacao: Gerencie Sua Arquitetura Sem Sair do Terminal

No mes passado, eu vi um desenvolvedor da nossa equipe fazer algo que parecia impossivel de funcionar.

Ele estava no meio de uma sessao de refatoracao no Claude Code, dividindo um servico monolitico em tres menores. No meio do processo, ele digitou: "Crie tres novos containers no Archyl — OrderService, InventoryService e NotificationService — dentro do sistema ECommerce. Adicione relacionamentos 'calls' entre o OrderService e os outros dois."

Dez segundos depois, o modelo C4 no Archyl tinha tres novos containers, corretamente conectados com relacionamentos, posicionados exatamente onde deveriam estar na arquitetura. Ele nunca trocou de aba. Nunca abriu o navegador. Apenas continuou codificando.

Foi quando percebi que o plugin estava pronto para ser lancado.

O Problema da Troca de Contexto

A documentacao de arquitetura tem um problema fundamental de UX: ela vive em um lugar diferente do codigo.

Voce esta na sua IDE. Acabou de reestruturar um modulo, renomear tres servicos e dividir um banco de dados em replicas de leitura e escrita. O codigo esta pronto. Agora voce precisa atualizar a arquitetura. Isso significa abrir o Archyl no navegador, encontrar o projeto certo, navegar ate o diagrama correto, atualizar os containers, adicionar relacionamentos, talvez escrever um ADR para explicar por que voce fez a mudanca.

Leva cinco minutos. Mas esses cinco minutos tem um custo oculto: troca de contexto. Seu cerebro precisa sair do codigo, entrar em um modo de diagramacao visual, lembrar o que acabou de fazer, traduzir isso em conceitos de arquitetura e depois voltar a codificar. A maioria dos desenvolvedores simplesmente... nao faz. Eles dizem a si mesmos que vao atualizar a documentacao depois. Depois nunca chega.

E por isso que o drift de arquitetura existe. Nao porque as equipes nao se importam com documentacao, mas porque a ferramenta esta no lugar errado na hora errada.

Arquitetura na Sua Conversa

O Archyl Developer Plugin coloca toda a sua arquitetura dentro do contexto do seu agente de codificacao. E um plugin para o Claude Code (e compativel com Codex e outros agentes) que ensina o agente a usar todas as mais de 200 ferramentas MCP do Archyl.

O que isso significa na pratica? Significa que voce pode fazer o seguinte:

Durante uma refatoracao, diga ao seu agente para atualizar a arquitetura:

Acabei de dividir o PaymentService em PaymentProcessor e PaymentGateway.
Atualize a arquitetura — remova o container antigo, crie os dois novos,
e mova todos os relacionamentos existentes para o novo container apropriado.

Durante uma revisao de codigo, pergunte sobre o contexto arquitetural:

Obtenha o modelo C4 completo e me diga quais componentes dependem do UserRepository.
Existem regras de conformidade que eu deveria conhecer antes de alterar a camada de dados?

Durante o planejamento de trabalho, verifique se a documentacao ainda esta precisa:

Qual e o drift score atual? Mostre quais elementos desviaram
e o que a IA acha que esta desatualizado.

Apos uma reuniao de design, registre a decisao sem sair do terminal:

Crie um ADR: decidimos migrar de REST para gRPC em toda a comunicacao
interna entre servicos. Contexto: requisitos de latencia da equipe mobile.
Vincule ao ApiGateway e a todos os containers de servicos backend.

O agente cuida das chamadas MCP, gerencia os IDs dos projetos e encadeia as operacoes. Voce so descreve o que quer em linguagem natural.

O Que o Plugin Cobre

O plugin da ao seu agente conhecimento estruturado em sete dominios:

Modelagem C4 — Crie e gerencie sistemas, containers, componentes, elementos de codigo e relacionamentos. O agente entende a hierarquia C4 e aplica convencoes de nomenclatura adequadas (PascalCase para sistemas e containers, nomes exatos de simbolos para elementos de codigo).

Documentacao — Escreva ADRs, crie documentos de projeto, defina fluxos de usuario e revise insights gerados por IA. Os ADRs sao vinculados aos elementos C4 que afetam, para que as decisoes arquiteturais permanecam conectadas a arquitetura.

Governanca — Crie regras de conformidade, execute verificacoes de compliance e monitore o drift de arquitetura. O agente pode configurar guardrails antes mesmo de uma sessao de codificacao com IA comecar.

Operacoes — Acompanhe releases entre ambientes, documente contratos de API (OpenAPI, gRPC, GraphQL), mapeie canais de eventos (Kafka, NATS, SQS) e gerencie o technology radar.

Colaboracao — Adicione comentarios, crie change requests (como PRs para arquitetura) e gerencie whiteboards. Discussoes sobre arquitetura acontecem onde as discussoes sobre codigo acontecem.

Historico — Tire snapshots, viaje no tempo pelas versoes da arquitetura e compare diferencas. Quando alguem perguntar "como era a arquitetura antes da migracao?", o agente pode responder.

Integracoes — Configure webhooks para notificacoes de mudancas na arquitetura, gerencie widgets do marketplace e visualize a arquitetura global de todos os projetos da organizacao.

Tres Passos para Configurar

A configuracao e simples:

1. Adicione o marketplace e instale o plugin:

/plugin marketplace add archyl-com/agent-skills
/plugin install archyl-developer@archyl-com-agent-skills

2. Adicione o servidor MCP ao .mcp.json do seu projeto:

{
    "mcpServers": {
        "archyl": {
            "type": "http",
            "url": "https://api.archyl.com/mcp",
            "headers": {
                "X-API-Key": "arch_your_api_key_here"
            }
        }
    }
}

3. Reinicie seu agente e comece a conversar com sua arquitetura.

Pronto. O plugin carrega automaticamente e o agente sabe como usar todas as ferramentas. Sem arquivos de configuracao, sem prompts customizados, sem integracao manual.

Por Que Open Source

O plugin e totalmente open source em github.com/archyl-com/agent-skills. Existem algumas razoes para isso.

Primeiro, transparencia. Quando um plugin ensina um agente de IA a interagir com sua arquitetura, voce deveria poder ler cada instrucao que ele da. A definicao da skill, os arquivos de referencia, os exemplos de workflow — esta tudo la, em markdown puro.

Segundo, contribuicoes. O Archyl tem mais de 200 ferramentas MCP, e os melhores workflows surgem do uso real. Quando uma equipe descobre um padrao que funciona — digamos, um workflow para auditar a arquitetura antes de um grande release — ela pode contribuir de volta. O plugin melhora porque a comunidade o utiliza.

Terceiro, portabilidade. O conteudo da skill nao esta preso ao Claude Code. Ele funciona com qualquer agente que suporte o formato de plugin. Os manifestos .claude-plugin e .codex-plugin estao ambos incluidos. Se um novo agente de codificacao surgir no proximo mes com suporte a plugins, o conteudo da skill se transfere diretamente.

O Que Muda

A mudanca e sutil, mas significativa.

Antes do plugin, a documentacao de arquitetura era uma atividade separada. Voce escrevia codigo, depois documentava. Dois workflows, duas ferramentas, dois modos mentais. A documentacao estava sempre um passo atras porque estava sempre um passo distante.

Com o plugin, a documentacao de arquitetura se torna parte da conversa de codificacao. Voce nao "atualiza os docs" — voce menciona o que mudou e o agente cuida do resto. A arquitetura se mantem sincronizada nao porque alguem lembrou de atualiza-la, mas porque atualiza-la se tornou algo sem esforco.

Isso e especialmente poderoso em workflows agenticos. Quando um agente de IA esta fazendo mudancas no seu codebase, ele pode simultaneamente atualizar a arquitetura. A mesma sessao que refatora o codigo tambem atualiza o modelo C4, registra o ADR e executa uma verificacao de conformidade. A governanca de arquitetura se torna uma parte natural do fluxo de desenvolvimento, nao algo pensado depois.

Comece Agora

Instale o plugin, conecte seu servidor MCP e tente pedir ao seu agente para descrever sua arquitetura. Depois peca para ele fazer uma mudanca. Na primeira vez que voce atualizar um modelo C4 a partir de uma conversa no terminal, vai se perguntar por que alguma vez funcionou de outra forma.

O plugin esta disponivel agora. A documentacao completa esta nos nossos guias, e o codigo-fonte esta no GitHub.

Sua arquitetura nao deveria viver em uma aba diferente. Agora ela nao precisa mais.