Camada de Inteligência — Os 4 Pilares

Como Arc OS valida, aprende, foca e melhora a si mesmo.

Visão Geral

A Camada de Inteligência fica entre as mensagens do usuário e as respostas do Claude. Ela opera em quatro estágios:

         INPUT                    PROCESSING                 OUTPUT
    ┌──────────────┐        ┌──────────────────┐       ┌─────────────────┐
    │ User Message  │───────►│  Context Router   │       │ Claude Response  │
    │               │        │  (skill scoring)  │       │  + eval warnings │
    │ Fix It / 👎   │        │                  │       │                 │
    │ (feedback)    │        │  Learnings       │       │ Quality metrics │
    │               │        │  (correction     │       │  logged         │
    └──────────────┘        │   injection)     │       └────────┬────────┘
                            │                  │                │
                            │  buildGsdPrompt()│        ┌───────┴────────┐
                            └────────┬─────────┘        │ Nightly Loop   │
                                     │                  │ (improvement   │
                                     ▼                  │  proposals)    │
                              Claude CLI                └────────────────┘

Pilar 1: Binary Eval Engine

O que é: Regras declarativas que verificam cada resposta antes da entrega.

Por quê: A saída de IA deve ter portões de qualidade, como testes unitários para código.

Como funciona:

Cada skill pode ter um arquivo .evals.json com regras:

{
  "rules": [
    { "id": "gm-001", "type": "string_not_contains", "value": "--force", "severity": "warning" },
    { "id": "gm-002", "type": "max_length", "value": 4000, "severity": "info" }
  ]
}

Após o Claude gerar uma resposta, o motor de evals executa todas as regras aplicáveis:

Aprovado: resposta entregue normalmente
Reprovado: resposta entregue + rodapé de aviso anexado

[Claude's response about git operations]
---
Eval: ⚠️ No force push | ℹ️ Response under 4000 chars

Tipos de Regras

Tipo	O que verifica
`string_contains`	A resposta deve conter o texto literal
`string_not_contains`	A resposta NÃO deve conter o texto
`regex_match`	A resposta deve corresponder ao padrão regex
`regex_not_match`	A resposta NÃO deve corresponder ao regex
`max_length`	A resposta deve ter <= N caracteres
`min_length`	A resposta deve ter >= N caracteres

Decisões de Design Importantes

Não bloqueante: Avisos não suprimem respostas. O usuário vê tanto a resposta quanto o alerta.
Por skill: Cada skill tem critérios de qualidade distintos.
Por projeto: A mesma skill pode ter regras diferentes para stacks tecnológicas diferentes.
Sem IA na validação: As regras são determinísticas. Aprovação/reprovação binária. Sem ambiguidade.

Referência de design: Anthropic Skill Creator — evals estruturados com asserções binárias.

Pilar 2: Context Router

O que é: Seleção inteligente de skills que injeta apenas as skills relevantes em cada prompt.

Por quê: 25 skills carregadas ao mesmo tempo = diluição de contexto. O modelo tenta aplicar conselhos de deploy em code reviews.

Como funciona:

Antes de montar o prompt, o roteador pontua cada skill registrada em relação à mensagem do usuário:

Score = (trigger matches x 2) + (keyword matches x 1)
Sort by score descending → take top 5

Exemplo:

User: "Review this code for XSS vulnerabilities"

Scoring:
  code-review:     trigger "review" (2) + keyword "XSS" (1) = 3
  code-review-protocol: trigger "code review" (2)            = 2
  deployment-flow: no match                                  = 0
  git-manager:     no match                                  = 0

Injected into prompt:
  SKILLS_HINT (focus on these):
  - code-review: Security audit and code quality review...
  - code-review-protocol: Structured code review with OWASP...

Por que Sugestão, Não Filtragem

O roteador sugere skills, mas não bloqueia outras. O Claude ainda tem acesso completo.

Abordagem	Risco
Filtragem rígida (`--allowedTools`)	Classificação errada quebra a sessão
Mutações de symlink	Alterações no sistema de arquivos em processo em execução
Dicas consultivas	Seguro: dica errada = Claude ignora

Triggers vs Keywords

Triggers (2 pts): Sinais explícitos de invocação. O usuário solicita diretamente essa capacidade.

"deploy", "review", "scaffold", "audit"

Keywords (1 pt): Contexto semântico mais amplo. Sugere relevância sem ser um comando.

"OWASP", "Docker", "CI/CD", "performance"

Referência de design: Priming de contexto — atenção focada sem filtragem rígida.

Pilar 3: Reflect Loop

O que é: Captura automática de correções como regras persistentes.

Por quê: Correções de IA devem sobreviver a reinicializações. Uma correção = melhoria permanente.

Como funciona:

CEO presses 🛠️ Fix It
    │
    ├── addLearning(source: "fixit", rule: "Fix requested for: <last response>")
    ├── projectLearnings reloaded from disk
    └── Fix prompt sent to Claude for immediate correction

CEO presses 👎
    │
    ├── addLearning(source: "negative", rule: "Negative feedback on: <response>")
    ├── qualityTracker.logFeedback(positive: false)
    └── projectLearnings reloaded from disk

As regras são armazenadas em learnings.md:

# Learnings

## Rules

- [2026-04-03T14:22:00Z] [fixit] Always use t-call for translations in Odoo QWeb
- [2026-04-03T15:10:00Z] [negative] Avoid sudo in deployment scripts

Em cada mensagem subsequente, os logs acumulados são injetados:

LEARNINGS (past corrections — follow these rules):
- Avoid sudo in deployment scripts
- Always use t-call for translations in Odoo QWeb

Propriedades Principais

Automático: Sem escrita manual de regras. Pressione um botão → regra criada.
Persistente: Sobrevive a reinicializações do bot. Gravado em disco como Markdown.
Por projeto: Cada Child Bot tem seu próprio learnings.md. Correções do Odoo não afetam o bot de React.
Mais recente primeiro: Correções mais recentes têm maior visibilidade no prompt.
Com limite: Máximo de 2000 caracteres no bloco LEARNINGS. Regras mais antigas são descartadas.

Referência de design: Claude Reflect System — correções se tornam regras permanentes que evitam regressões.

Pilar 4: Karpathy Loop

O que é: Análise automatizada noturna de métricas de qualidade com propostas de melhoria enviadas ao CEO.

Por quê: Humanos esquecem de revisar performance. O sistema deve encontrar seus próprios pontos fracos.

Como funciona:

Todo dia às 03:00 UTC, scripts/nightly-improve.ts executa:

Lê o registry — enumera todos os Child Bots de bot_registry.json
Lê as métricas — carrega quality-metrics.json por filho
Encontra os de baixo desempenho — filtra skills onde:
- applied_count >= 3 (tamanho mínimo de amostra para evitar ruído)
- E success_rate < 80% OU feedback_negative > feedback_positive
Lê os logs — extrai padrões de correção relacionados
Gera propostas — baseado em template (determinístico, sem IA)
Envia ao CEO — relatório resumido + cartões de proposta individuais no Telegram

Fluxo de Aprovação do CEO

Telegram: Proposal Card
┌──────────────────────────────────────┐
│ Improvement Proposal                  │
│                                       │
│ Child: citadel-v2                     │
│ Skill: code-review                    │
│ Reason: low success rate (72%)        │
│ Feedback: 👍 4 / 👎 6                │
│                                       │
│ Related learnings:                    │
│   • Always use t-call for i18n        │
│                                       │
│ [✅ Approve]  [❌ Reject]             │
└──────────────────────────────────────┘

Aprovar: Faz backup de skill.md → skill.v1.md (máx. 3 versões). Marca como aprovado.
Rejeitar: Marca como rejeitado em proposals.json. Nenhuma alteração é feita.

Decisões de Design Importantes

Propostas baseadas em template: Nenhuma IA gera as melhorias. O sistema identifica o problema; o humano decide a correção.
CEO no loop: Sem reescrita autônoma de skills. É necessária a aprovação com um toque.
Versionamento de skills: Backups evitam perda de dados. Máximo de 3 versões por skill.
Tamanho mínimo de amostra: Skills com menos de 3 usos são excluídas da análise (evitar falsos positivos).

Referência de design: Karpathy AutoResearch Loop — modificar → verificar → manter/descartar → repetir. Com a adição crítica de aprovação humana.

Como os 4 Pilares Trabalham Juntos

Day 1:
  CEO sends message → Context Router suggests relevant skills
  Claude responds → Evals check output → Warning: "No force push"
  CEO sees warning, presses Fix It → Learning saved to learnings.md

Day 2:
  CEO sends similar message → Learnings injected: "Don't use --force"
  Claude avoids the mistake → No eval warnings → thumbs-up
  Quality metrics improve for that skill

Day 30:
  Nightly loop detects git-manager skill has 95% success rate
  No proposal needed — skill is healthy

Day 30 (different skill):
  Nightly loop detects code-review at 68% success
  Sends proposal to CEO → CEO approves → skill backed up
  CEO manually improves skill.md
  Next cycle: success rate climbs

O sistema cria um ciclo de feedback positivo: correções se tornam regras persistentes → regras melhoram a qualidade → métricas refletem a melhoria → o loop noturno confirma a saúde do sistema.

Pilar 5: Sage Worker (Phase 40.11+)

O que é: Análise de skills, benchmarking e descoberta no marketplace com IA.

Por quê: A melhoria manual de skills não escala. É necessária análise automatizada da qualidade das skills e acesso à expertise da comunidade.

Como funciona:

Análise de Skills

Selecione qualquer skill na UI Skill Evolution → clique em "Sage Analyze" → Sage (Claude Haiku) avalia:

Clareza e completude das instruções da skill
Cobertura das regras de eval
Recomendações de melhoria

Benchmarks A/B

Compare duas versões de uma skill:

Selecione uma atualização de skill (PR)
Execute o benchmark → Sage testa ambas as versões com prompts de exemplo
Os resultados mostram a comparação de qualidade com um resumo

Descoberta no Marketplace

Pesquise skills criadas pela comunidade em claudemarketplaces.com:

"Sage Scout" → pesquise por palavra-chave
Analise a compatibilidade com seu projeto
Instale globalmente ou faça fork para um projeto específico

Referência de design: Gerenciadores de pacotes (npm, pip) para gerenciamento de skills de IA, com análise de compatibilidade via LLM.