Archyl Harness

Agentes de programação conhecem seu repositório perfeitamente — e sua arquitetura, nem um pouco. Eles reescrevem um serviço que outro agente está refatorando naquele mesmo instante, introduzem a dependência que seu time baniu em um ADR dois anos atrás e deixam sua documentação descrevendo um sistema que não existe mais.

O Archyl Harness resolve isso. Ele envolve qualquer agente de programação — Claude Code, Codex, Cursor, seu bot de CI ou os próprios agentes gerenciados do Archyl — em um ciclo governado, construído sobre sua arquitetura documentada:

O ciclo que um agente executa:

plan_work ──▶ start_work_session ──▶ code (Guard watches every write)
                                          │
finish_work_session ◀─── heartbeat ◀──────┘
      │
      ├─▶ leases released
      ├─▶ outcome pinned to the touched elements (memory)
      └─▶ draft Architecture Change Request (optional)

E como cada sessão adquire reservas consultivas (leases) sobre os elementos C4 que toca, dois agentes trabalhando no mesmo serviço enxergam um ao outro antes de colidir — nos briefings de cada um e ao vivo no seu diagrama.

Opcional por design

O harness é opt-in: nada nele é ativado só porque você documentou uma arquitetura. Um agente entra no ciclo apenas se você fizer uma destas três coisas — conectar o servidor MCP com ?profile=coding, instalar a skill archyl-harness que ensina o protocolo, ou adicionar o hook Guard. Desfaça isso e os agentes daquele repositório voltam a se comportar exatamente como antes.

Todo o resto do Archyl funciona sem ele. Recuperação de contexto, análise de impacto, propriedade dos elementos, verificações de conformidade, detecção de desvio e o sistema de memória estão todos acessíveis pelo catálogo completo, sem nenhuma sessão de trabalho. Usar o Archyl como uma arquitetura documentada que seus agentes conseguem ler — e pular este guia por inteiro — é uma forma perfeitamente prevista de usá-lo.

As duas metades são adotadas separadamente porque não têm as mesmas permissões. Um registro tira sua autoridade da curadoria humana: um ADR, uma regra de conformidade ou uma solicitação de mudança aprovada carregam um status porque uma pessoa os colocou ali, e uma entrada errada fica lá em silêncio até que alguém a leia e a corrija. Um protocolo, por outro lado, emite instruções sobre as quais os agentes agem: é um risco de outra natureza, que merece uma decisão deliberada em vez de um padrão.

Essa linha também é traçada dentro do produto, não apenas ao redor dele. Os agentes podem ler o registro e escrever nele, mas o que escrevem volta aos próximos agentes como contexto datado e atribuído — nunca como regra. Só os ADRs e as regras de conformidade são apresentados como vinculantes, e o único caminho entre algo que um agente registrou e esse estatuto passa por uma pessoa: um ADR, ou uma solicitação de mudança de arquitetura que alguém aprovou.

Configuração em cinco minutos

Você precisa de um projeto Archyl com arquitetura documentada (execute primeiro a descoberta com IA se o seu estiver vazio) e de uma chave de API com escopo write, criada em Perfil → Chaves de API.

Opção A — um único comando

Na raiz do seu repositório:

curl -fsSL https://raw.githubusercontent.com/archyl-com/agent-skills/main/templates/setup.sh | bash

O script pede sua chave de API e seu projeto e então configura tudo o que vem a seguir. Pronto — pule direto para Sua primeira sessão.

Opção B — passo a passo

1. Conecte o servidor MCP com o perfil coding. No seu repositório, crie ou complemente o .mcp.json:

{
  "mcpServers": {
    "archyl": {
      "type": "http",
      "url": "https://api.archyl.com/mcp?profile=coding",
      "headers": { "X-API-Key": "${ARCHYL_API_KEY}" }
    }
  }
}

?profile=coding faz diferença: ele reduz a superfície de 189 ferramentas para as 16 de que um agente de programação precisa, o que mantém o contexto dele pequeno e suas escolhas óbvias.

2. Instale o plugin (Claude Code):

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

Isso instala as skills (incluindo a archyl-harness, que ensina o protocolo de sessão ao seu agente) e o hook Guard.

3. Ative o Guard. Exporte duas variáveis onde quer que seu agente rode:

export ARCHYL_API_KEY=arch_...
export ARCHYL_PROJECT_ID=<your project uuid>

É tudo de que o Guard precisa. Ele é fail-open: sem essas variáveis (ou sem rede) ele não faz nada, então nunca pode quebrar seu fluxo de trabalho.

Sua primeira sessão

Peça qualquer mudança ao seu agente — digamos, "adicione limitação de requisições à API pública". Com o harness instalado, é isto que acontece:

Antes de programar, o agente declara o trabalho:

▶ start_work_session(task: "add rate limiting to the public API",
                     agentName: "claude-code/vincent")

# Harness Session
- Session ID: 4c2e…
- Gate: warn
  - error-level guardrail applies: no-direct-db-from-handlers
- Leased elements: container `ApiGateway`, component `RateLimiter`
- Conflicts: none

## Most relevant elements
- ApiGateway (container) — handles all public traffic …
## Related decisions (respect these)
- ADR-017: All throttling is enforced at the gateway [accepted]
## What previous sessions did here
- ApiGateway (claude-code/sarah, 3 days ago): extracted auth middleware …

O agente agora sabe onde trabalhar, quais decisões o restringem e o que o último agente fez ali — sem ler todo o seu repositório.

Durante a programação, o Guard confere cada arquivo que o agente está prestes a escrever contra suas regras de conformidade. Uma violação crítica bloqueia a escrita mostrando a regra e sua sugestão; o agente se ajusta e continua.

Ao terminar, o agente fecha o ciclo:

▶ finish_work_session(sessionId: "4c2e…",
    summary: "Added token-bucket rate limiting in ApiGateway middleware",
    decisions: ["limits configured per-plan in Redis"],
    createChangeRequest: true)

As reservas são liberadas, o resumo fica fixado como memória em ApiGateway para o próximo agente, e um rascunho de solicitação de mudança de arquitetura chega ao Archyl para que uma pessoa avalie como o modelo C4 deve ser atualizado.

Cada decisão é registrada como uma memória própria: uma sessão posterior pode substituí-la, reconfirmá-la ou deixá-la envelhecer sem tocar em nada mais do que a sua sessão deixou. As decisões voltam aos próximos agentes como contexto datado e atribuído — nunca como regras. A um agente só são apresentados como vinculantes os ADRs e as regras de conformidade, e a solicitação de mudança é o caminho pelo qual uma decisão alcança esse estatuto.

Acompanhando seus agentes: o console Fleet

Abra Agent Hub → Fleet para ver o trabalho em andamento: quantos agentes estão trabalhando, quais elementos C4 estão reservados agora, e um cartão por sessão ativa com sua tarefa, os elementos que detém, seu gate e a atualidade do seu heartbeat. Sessões encerradas vão para Sessões recentes com o resumo que cada uma reportou.

Uma sessão cujo heartbeat para é sinalizada, e expira sozinha 30 minutos depois. Você também pode cancelá-la daqui, o que libera suas reservas imediatamente.

A mesma informação chega até você onde você realmente olha — no diagrama. Todo elemento que um agente detém exibe um selo com seu nome, e clicar nele equivale a perguntar o que ele está fazendo: a tarefa declarada, tudo o mais que ele detém, e há quanto tempo deu sinal de vida.

Para os agentes gerenciados do Archyl você também pode guiar um agente em execução: escreva uma mensagem na página de execução e ela é injetada no próximo passo de raciocínio dele.

O gate

Toda sessão começa com um veredicto de preflight:

Use exclusive: true para mudanças que não podem concorrer com ninguém: migrações de schema, alterações de contrato.

Configuração do Guard

Em vez de variáveis de ambiente, um arquivo .archyl.json versionável na raiz do repositório pode carregar a metade não secreta: { "apiUrl": "…", "projectId": "…" }. Mantenha a chave de API no ambiente.

Memória

Os resultados de sessão são apenas a metade automática da memória. Agentes e colegas também podem escrever na memória deliberadamente:

▶ remember(projectId: …, element: "ApiGateway", kind: "pitfall",
    content: "The gateway strips custom headers longer than 8KB — payloads must go in the body.")

• remember fixa um fato em um elemento (ou no projeto inteiro), tipado como note, convention ou pitfall. Use para o conhecimento que não aparece nem no código nem no modelo: manias do deploy, razões históricas, pontos frágeis.
• recall busca em toda a memória — resultados, notas, convenções, armadilhas — por termos, por elemento ou por tipo. O ranking mistura significado com palavras, então um agente que pergunta por "rate limiting" encontra a nota que outra pessoa escreveu sobre "throttling". Passe o seu sessionId para que as memórias entregues a você possam receber o crédito depois.
• find_relevant_context e start_work_session entregam automaticamente as memórias mais recentes dos elementos envolvidos, então o próximo agente já começa com o que os anteriores aprenderam.

Escrever uma memória é deduplicado: reafirmar um fato que já existe não guarda uma segunda cópia, e sim confirma a que já está lá (a resposta traz deduplicated: true) — porque um agente reafirmando o que aprendeu é evidência, não ruído. Uma memória parecida mas não idêntica é guardada e devolvida em similarTo, para que quem escreve substitua de propósito em vez de contradizer em silêncio.

A memória também aprende com o uso. Quando uma sessão termina, usedMemories nomeia as memórias em que ela realmente se apoiou. Essa citação é o sinal forte: as memórias citadas mantêm sua posição, enquanto uma memória entregue a cinco sessões e nunca nomeada por nenhuma delas é rebaixada como ruído. Nada é apagado automaticamente — as memórias ignoradas vão para uma fila de revisão, para uma pessoa julgar.

A memória tem um ciclo de vida, para continuar verdadeira em vez de só se acumular. Quando uma memória entregue pelo recall se mostra correta, confirme-a de novo com confirm_memory: o relógio de frescor reinicia e ela continua pesando mais do que a informação mais antiga. Quando um fato muda, não deixe as duas versões vivas: remember(supersedes: "Old title") substitui a memória antiga, que sai da busca mas permanece no histórico e no grafo. Tudo o que não é confirmado decai suavemente no ranking (meia-vida de 45 dias), e para um agente prestes a mexer no código as armadilhas sempre pesam mais que as notas simples.

As memórias formam um grafo de conhecimento, no estilo do Obsidian. Dê um title a uma memória e ela passa a ser endereçável: qualquer outra memória pode referenciá-la com [[Title]] no conteúdo. Os links também resolvem elementos C4 pelo nome ([[ApiGateway]]) e decisões ([[ADR-17]]) — e um link para um título que ainda não existe fica pendente e se conecta no momento em que essa memória é criada. Toda memória expõe seus backlinks, então o conhecimento é navegável nos dois sentidos — e o recall segue os links: os melhores resultados trazem junto seus vizinhos ligados por wiki-links, marcados com via.

A memória também percebe quando a arquitetura se move sob ela. Quando um elemento ao qual uma memória está fixada muda, essa memória é sinalizada para revisão: recall continua a servi-la, mas marcada com [VERIFY — the element drifted since this was written], e ela cai no ranking em vez de desaparecer. Um fato escrito sobre um serviço desde então dividido não é automaticamente falso — apenas deixa de ser confiável sem um olhar humano.

A memória é criptografada em repouso como toda coluna de conteúdo sensível, e se gerencia pela interface: o painel de Memória no Agent Hub, mais uma seção por elemento no painel de detalhes do diagrama. O painel foi feito para triagem — a coluna da esquerda conta o que precisa de revisão, o que está sendo ignorado e o que envelheceu, depois divide o resto por tipo, e cada linha carrega uma borda colorida dizendo num relance o quanto confiar.

Mude para o mapa de conhecimento para a outra pergunta: não o que sabemos mas onde. Uma célula por elemento C4, mostrando o que o projeto sabe sobre ele e quão fresco é esse saber — incluindo os elementos sobre os quais ninguém escreveu nada, que costuma ser a metade mais útil do quadro.

Em CI

Os mesmos blocos rodam no seu pipeline com as GitHub Actions: generate-context faz commit de um briefing archyl.txt para agentes sem acesso MCP, conformance-check condiciona os pull requests às suas regras, e auto-cr abre solicitações de mudança de arquitetura a partir das mudanças mescladas.

Solução de problemas

Nenhuma sessão aparece no console Fleet. O agente está conectado sem o protocolo do harness. Verifique se o plugin está instalado (a skill archyl-harness ensina o protocolo) e se a URL do MCP inclui ?profile=coding — com o catálogo completo de 189 ferramentas, os agentes costumam explorar em vez de seguir o ciclo.

O Guard nunca bloqueia nada. É por design: ele falha em aberto. Confirme que ARCHYL_API_KEY e ARCHYL_PROJECT_ID estão exportadas no ambiente em que o agente roda, e que seu projeto tem regras de conformidade com severidade critical.

Uma sessão fica presa como ativa. As sessões expiram 30 minutos após o último heartbeat e liberam suas reservas automaticamente. Para liberá-las na hora, cancele a sessão pelo console Fleet.

Quais agentes são suportados? Tudo que fala MCP ganha Context, Plan e o protocolo de sessão. O hook Guard e as skills hoje visam o Claude Code; outros agentes podem aplicar as mesmas regras via run_conformance_check ou pelas actions de CI.