Architecture Intelligence para equipes AI-Native

Algo mudou nos ultimos seis meses. Agentes de IA passaram de escrever funcoes para escrever servicos inteiros. Claude Code, Cursor, Codex — eles nao sao mais assistentes. Sao membros da equipe. Abrem PRs, revisam codigo, lancam features.

Mas eis o que me tira o sono: esses agentes nao fazem ideia de como a arquitetura se parece.

Um agente consegue escrever um servico Go perfeitamente limpo em dez minutos. Mas ele nao sabe que a equipe decidiu tres meses atras rotear toda a comunicacao entre servicos pelo Kafka. Nao sabe que o servico de pagamentos tem acesso direto ao banco de dados proibido. Nao sabe que Python foi movido para "hold" no technology radar no trimestre passado.

O resultado? Drift arquitetural na velocidade da maquina.

Construimos o Archyl para resolver isso. E hoje, lancamos a maior atualizacao desde o lancamento: Architecture Intelligence — um ecossistema completo que transforma o Archyl no sistema nervoso do desenvolvimento AI-native.

O problema: agentes codificam rapido, mas codificam as cegas

Quando um desenvolvedor humano entra em uma equipe, ele passa dias lendo documentacao, fazendo perguntas, construindo um modelo mental do sistema. Aprende as regras — escritas e nao escritas. Entende os limites.

Agentes de IA pulam tudo isso. Recebem uma tarefa, escrevem codigo, abrem um PR. Se ninguem detecta a violacao arquitetural na revisao, vai para producao. Multiplique isso por dez agentes trabalhando em dez servicos em tres equipes, e sua arquitetura cuidadosamente projetada se corroi em semanas.

Ja vimos isso acontecer. Uma equipe com um modelo C4 impecavel em janeiro tinha um drift score de 40% em marco. Nao porque pararam de se importar — mas porque seus agentes nao sabiam que a arquitetura existia.

A solucao: arquitetura como infraestrutura

Documentacao de arquitetura nao deveria ser algo que voce mantem. Deveria ser algo que se mantem sozinho — e que cada agente consulta antes de escrever uma unica linha de codigo.

Foi isso que construimos. Eis o que estamos lancando hoje.

10 Agent Skills

O skill original archyl-developer dava aos agentes acesso a mais de 200 ferramentas MCP. Mas era uma caixa de ferramentas sem fluxo de trabalho. Hoje, adicionamos nove skills especializados que cobrem o ciclo completo de desenvolvimento:

Antes de codificar

archyl-preflight — Execute antes de implementar qualquer feature. Verifica sua abordagem planejada contra o modelo C4, as regras de conformidade, o technology radar e os contratos API. Voce recebe um veredito claro PASS / WARN / FAIL antes de escrever uma unica linha de codigo.

> Estou prestes a adicionar um cache Redis ao servico de usuarios. Tudo bem?

Verificacao Preflight: AVISO
- Redis esta aprovado no technology radar ✓
- O servico de usuarios existe no modelo C4 ✓
- ⚠ Nenhum container de cache documentado — sugerimos criar um
- ⚠ A regra "No Direct DB Access from Handlers" se aplica — garanta que o cache seja acessado pela camada de servico

Depois de implantar

archyl-postship — Execute depois de implantar. Analisa o que voce acabou de construir, atualiza o modelo C4, cria ADRs para decisoes arquiteturais e registra Change Requests para revisao do arquiteto. Sua documentacao se atualiza sozinha como efeito colateral do trabalho.

Durante a revisao

archyl-review — Um bot de revisao de arquitetura. Verifica o diff do seu PR contra a arquitetura documentada e fornece feedback estruturado: violacoes de conformidade, cruzamento de limites, tecnologias nao aprovadas, contratos API ausentes. Pense no ESLint, mas para arquitetura.

Para visibilidade

archyl-changelog — Gera uma linha do tempo legivel de todas as mudancas arquiteturais: novos servicos, relacionamentos modificados, decisoes ADR, evolucao do drift. Perfeito para reunioes de revisao de arquitetura.

archyl-dora — Correlaciona metricas DORA com mudancas arquiteturais. Sua decomposicao em microservicos melhorou o lead time? O pico de drift precedeu o aumento do change failure rate? Agora voce tem os dados.

archyl-roi — Quantifica o impacto financeiro das decisoes arquiteturais. "Nosso investimento em regras de conformidade economizou um estimado de $23.000 no ultimo trimestre ao reduzir retrabalho." Esse e o tipo de dado que faz orcamentos de arquitetura serem aprovados.

Para prevencao

archyl-predict — Preve riscos arquiteturais antes que se materializem. "No ritmo atual, seu drift score cruzara 50% ate maio. O PaymentService tem 12 dependencias de entrada — considere a decomposicao."

archyl-autofix — Quando drift e detectado, propoe correcoes especificas. Seja atualizar a documentacao para corresponder ao codigo, ou sugerir mudancas no codigo para se realinhar com a arquitetura. Cria Change Requests para revisao humana.

Para coordenacao

archyl-orchestrate — Quando multiplos agentes trabalham em diferentes servicos simultaneamente, este skill negocia contratos API, resolve conflitos de dependencias e garante que mudancas entre equipes nao quebrem a arquitetura.

6 GitHub Actions

Governanca arquitetural pertence ao CI. Lancamos seis GitHub Actions que executam automaticamente em cada PR e merge:

A configuracao recomendada e um unico arquivo:

name: Architecture
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  pr-checks:
    if: github.event_name == 'pull_request'
    uses: archyl-com/actions/.github/workflows/archyl-pr.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      drift-threshold: 70
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

  main-update:
    if: github.event_name == 'push'
    uses: archyl-com/actions/.github/workflows/archyl-main.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

Nao esta no GitHub? Tambem oferecemos templates para GitLab CI e Bitbucket Pipelines.

Packs de regras de conformidade

Configurar governanca arquitetural do zero e tedioso. Entao construimos cinco packs de regras pre-construidos que voce pode instalar em segundos:

Instale pelo agent skill: "Instale o pack de regras de conformidade de microservicos." Pronto.

SDKs

Para equipes que constroem integracoes personalizadas, publicamos SDKs oficiais:

npm install @archyl/sdk    # Node.js 18+, zero dependencies
pip install archyl-sdk     # Python 3.10+

const archyl = new ArchylClient({ apiKey: 'arch_...', organizationId: 'uuid' });
const drift = await archyl.governance.computeDrift(projectId);
const predictions = await archyl.projects.getPredictions(projectId);

Tres novas APIs alimentadas por IA

Sob o capo, lancamos tres novas capacidades no backend:

Predictive Analytics (GET /projects/:id/predict) — Analise estatistica real. Regressao linear sobre drift scores, trajetorias de metricas DORA, taxas de decaimento de conformidade e deteccao de hotspots de complexidade por analise de acoplamento fan-in/fan-out. Nao intuicoes — matematica.

Architecture Diff Analysis (POST /projects/:id/architecture-diff) — Envie um git diff, receba um delta estruturado do modelo C4. Analise alimentada por IA que detecta novos servicos, dependencias alteradas e decisoes arquiteturais. Sugere ADRs quando decisoes significativas sao detectadas.

ROI Computation (GET /projects/:id/roi) — Quantifica os retornos do investimento em arquitetura. Divide suas metricas DORA antes/depois, calcula ganhos de produtividade (horas economizadas x custo por hora), ganhos de confiabilidade (incidentes evitados x custo por incidente) e classifica seus ADRs por impacto financeiro.

Todas as tres estao disponiveis como ferramentas MCP, entao cada agent skill pode chama-las diretamente.

O ciclo completo

Veja como tudo se encaixa:

Agente recebe a tarefa
       │
       ▼
  archyl-preflight ──── valida a abordagem contra a arquitetura
       │
       ▼
  Agente escreve codigo
       │
       ▼
  archyl-review ──────── revisa o PR contra o modelo C4
       │
       ▼
  CI: conformance-check ─ bloqueia violacoes
  CI: drift-score ──────── aplica alinhamento
       │
       ▼
  Merge para main
       │
       ▼
  CI: auto-cr ──────────── registra Change Request
  CI: generate-context ─── atualiza archyl.txt
       │
       ▼
  archyl-postship ──────── atualiza modelo C4 + ADRs
       │
       ▼
  Proximo agente le archyl.txt ← o ciclo se repete

A arquitetura nao e mantida. Ela se mantem sozinha.

Primeiros passos

1. Instale os skills:

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

2. Adicione as GitHub Actions: Copie o workflow acima em .github/workflows/architecture.yml.

3. Gere seu primeiro archyl.txt: Execute a action generate-context ou peca ao seu agente: "Gere o arquivo de contexto de arquitetura para este projeto."

4. Comece a codificar. Seu agente agora conhece a arquitetura.

O que vem a seguir

Esta e a base. Estamos trabalhando em dashboards frontend para predicoes e ROI, integracao mais profunda com mais agentes de codificacao e um marketplace comunitario para packs de regras de conformidade.

Documentacao de arquitetura sempre foi aquilo que as equipes queriam fazer mas nunca encontravam tempo. Quando os agentes escrevem o codigo, a arquitetura se torna a unica coisa que os humanos precisam gerir. O Archyl garante que eles nao precisem fazer isso sozinhos.

Tudo o que lancamos hoje e open source. Adorariamos receber seu feedback.