Pitch: oh-my-agent — Harness de Agentes Multi AI IDE para Uso em Produção

Quando você diz a um agente "crie um app de TODO", ele até cria algo. O problema é que frequentemente cria a coisa errada, foge do escopo e repete os mesmos erros.

Para resolver isso, surgiram abordagens estruturais como AGENTS.md e, mais recentemente, Skills. Porém, ao analisar as skills que são compartilhadas na prática, alguns problemas aparecem com frequência:

Faltam informações sobre versões de bibliotecas — justamente o mais importante.
A descrição do papel se resume a declarações como "You are a Senior engineer".
Conteúdo que caberia em poucas palavras-chave é esticado em textos longos, desperdiçando tokens.

Como resultado, essas skills não são bem seguidas pelo modelo, desperdiçam contexto e, a longo prazo, se tornam código morto que ninguém quer abrir.

[Abordagem]

Com o oh-my-agent, quisemos resolver esse problema não com prompts, mas com processo. Em vez de simplesmente dizer "refaça" quando o agente erra, registramos por que errou e refletimos isso na próxima execução.

O mecanismo central é o Clarification Debt (CD) Scoring. Quando o agente interpreta mal um requisito ou foge do escopo, pontos são acumulados:

• clarify: +10 — pergunta simples de confirmação
• correct: +25 — correção de direção por má interpretação
• redo: +40 — rollback e reinício por fuga de escopo
• Iniciar trabalho sem verificar o Charter: +15
• Modificar arquivo fora do escopo permitido: +20
• Repetir o mesmo erro: multiplicador x1.5

Acima de 50 pontos, é obrigatório escrever uma Root Cause Analysis (RCA). Acima de 80, a sessão é interrompida. As lições extraídas são acumuladas em lessons-learned.md e aplicadas a partir da sessão seguinte. Mesmo com prompts simples, o processo faz a correção.

Além disso, para evitar que o agente aja por conta própria, existem alguns protocolos comuns:

Clarification Protocol — A ambiguidade dos requisitos é classificada como LOW / MEDIUM / HIGH. Se LOW, prossegue. Se MEDIUM, apresenta opções. Se HIGH, para e esclarece.

Difficulty Guide — As tarefas são divididas em Simple / Medium / Complex, ajustando a profundidade dos protocolos necessários.

Context Budget — Define orçamentos de tokens por modelo para reduzir desperdício de contexto.

Essa abordagem está alinhada com o conceito de Harness Engineering mencionado pela OpenAI. Usar bem um agente não é questão de uma linha de prompt — é questão de qual estrutura de controle você coloca ao redor dele.

[Estrutura do Projeto]

O oh-my-agent gerencia tudo isso dentro da estrutura do projeto.

.agents/ = SSOT — Skills, workflows e configurações ficam sob .agents/ como fonte única da verdade. Sem dependência de IDE específica.

Equipe de agentes baseada em papéis — Papéis básicos como PM, QA, Frontend, Backend, Mobile e Debug, além dos recém-adicionados DB Agent e TF Infra Agent.

• DB Agent: modelagem SQL / NoSQL / Vector DB, incluindo recomendações de segurança ISO 27001
• TF Infra Agent: Terraform multi-cloud, políticas OPA / Sentinel, guia de controles da série ISO 42000

Orquestração orientada a workflows — Planejamento, revisão, debug e execução paralela como fluxo padrão. O novo workflow /brainstorm permite explorar o design antes de escrever código: análise do codebase → perguntas de esclarecimento → proposta de abordagem → aprovação do usuário → salvamento do documento de design, seguido de /plan → implementação.

[Dois Modos de Orquestração]

O /coordinate é voltado para velocidade — rodar rápido e corrigir quando surgem problemas. O PM decompõe as tarefas, executa os agentes e o QA faz uma revisão. Se aparecem issues CRITICAL/HIGH, a tarefa é reexecutada. É um loop leve de 7 etapas.

Já o /ultrawork enfatiza a verificação de qualidade. Divide-se em cinco fases — PLAN → IMPL → VERIFY → REFINE → SHIP — cada uma com um gate que impede avanço sem aprovação. Das 17 etapas, 11 são de revisão. Na fase REFINE, são realizados: divisão de arquivos, remoção de duplicatas, análise de efeitos colaterais e limpeza de dead code.

Pode parecer excessivo, mas à medida que o nível de abstração da programação sobe — de linguagem de máquina para linguagens de alto nível e agora para linguagem natural — a verificação se torna o que mais importa.

[Contexto da Expansão]

Há um mês, o projeto foi apresentado como oh-my-ag, um orquestrador exclusivo para o Antigravity. Desde então, vários AI IDEs passaram a usar .agents/skills/ como caminho de skills do projeto, e não fazia mais sentido mantê-lo preso a uma IDE específica. Por isso foi expandido para o formato de harness universal, tornando-se oh-my-agent.

[Como Começar]

curl -fsSL https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.sh | bash

Suporta os principais AI IDEs: Antigravity, Claude Code, Codex CLI, Cursor, entre outros.

Se você já usa um AI IDE, vale experimentar. No fim das contas, o objetivo do desenvolvedor é equilibrar QCD (Quality, Cost, Delivery) ao mesmo tempo. O desenvolvimento com agentes não é exceção — e foi com essa mentalidade que o projeto foi criado.

🔗 GitHub: first-fluke/oh-my-agent