oh-my-agent — harness multiagente de IA para IDEs voltado ao uso prático
(github.com/first-fluke)Quando você diz a um agente “crie um app de TODO”, ele até cria alguma coisa. O problema é que frequentemente cria algo fora do esperado, sai do escopo e repete os mesmos erros.
Para resolver esse tipo de problema, no começo surgiram abordagens estruturadas como AGENTS.md e, mais recentemente, Skills. Mas, ao observar as skills que de fato são compartilhadas, aparecem alguns problemas em comum.
- Falta a informação mais importante: versão das bibliotecas
- A descrição do papel termina em uma declaração como
"You are a Senior engineer" - Conteúdos que caberiam em poucas palavras-chave são expandidos de forma verbosa, desperdiçando tokens
Como resultado, essas skills muitas vezes nem são bem seguidas pelo modelo e, além de desperdiçarem contexto, tendem a virar dead code que ninguém quer abrir no longo prazo.
[Abordagem]
Com o oh-my-agent, a ideia foi resolver esse problema não com prompt, mas com processo. Em vez de apenas dizer “faça de novo” quando o agente erra, há uma estrutura para registrar por que deu errado e refletir isso na próxima execução.
Um dos principais mecanismos é a pontuação de Clarification Debt (CD). Quando o agente entende mal os requisitos ou sai do escopo, pontos são acumulados.
- clarify: +10 — pergunta simples de confirmação
- correct: +25 — correção de direção por mal-entendido da intenção
- redo: +40 — rollback e reinício por desvio de escopo
- Iniciar o trabalho sem verificar o Charter: +15
- Modificar arquivos fora do escopo permitido: +20
- Repetir o mesmo erro: multiplicador x1.5
Ao passar de 50 pontos, torna-se obrigatória a elaboração de uma Root Cause Analysis (RCA); acima de 80, a sessão é interrompida. As lições obtidas daí são acumuladas em lessons-learned.md e aplicadas imediatamente a partir da sessão seguinte. É uma estrutura em que o processo compensa mesmo quando o prompt é escrito de forma simples.
Além disso, há alguns protocolos comuns para evitar que o agente aja por conta própria.
- Clarification Protocol
A ambiguidade dos requisitos é dividida em LOW / MEDIUM / HIGH. Se for LOW, segue adiante; se for MEDIUM, apresenta opções; se for HIGH, o trabalho é interrompido para esclarecimento. - Difficulty Guide
As tarefas são divididas em Simple / Medium / Complex, ajustando a profundidade dos protocolos necessários. - Context Budget
Define-se um orçamento de tokens por modelo para reduzir desperdício de contexto desnecessário.
Essa abordagem também se conecta ao que a OpenAI chamou de Harness Engineering. A ideia é que usar bem agentes não é uma questão de uma única linha de prompt, mas de como controlar os agentes por meio de uma estrutura.
[Estrutura do projeto]
O oh-my-agent gerencia isso dentro da estrutura do projeto.
.agents/= SSOT
Skills, workflows e configurações ficam reunidos em.agents/, usado como single source of truth. Não depende de uma IDE específica.- Equipe de agentes baseada em papéis
Além dos papéis básicos como PM, QA, Frontend, Backend, Mobile e Debug, desta vez foram 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 multicloud, políticas OPA / Sentinel e guia de controles da série ISO 42000
- Orquestração centrada em workflows
Planejamento, review, debug e execução paralela formam o fluxo básico. O workflow/brainstorm, adicionado recentemente, explora o design antes de escrever código.
Ele segue a sequência análise da base de código → perguntas de esclarecimento → proposta de abordagem → aprovação do usuário → salvamento do documento de design, e depois continua com/plan → implementação.
[Dois modos de orquestração]
/coordinate funciona de forma rápida: executa, e se surgir problema, corrige depois. O PM decompõe a tarefa, executa os agentes e depois o QA faz uma única revisão. Se surgirem issues CRITICAL/HIGH, o trabalho correspondente é executado novamente. No geral, é um loop leve e rápido de 7 etapas.
Já o /ultrawork enfatiza fortemente a validação de qualidade. Ele é dividido em cinco etapas — PLAN → IMPL → VERIFY → REFINE → SHIP — e cada etapa tem um gate; se não passar, não é possível seguir para a próxima. Das 17 etapas, 11 são de review, e na etapa REFINE são feitos também divisão de arquivos, remoção de duplicação, análise de efeitos colaterais e limpeza de dead code.
Pode parecer um pouco excessivo, mas, à medida que o nível de abstração da programação sobe de linguagem de máquina → linguagem de programação → linguagem natural, provavelmente faz sentido concordar que, no fim, o mais importante é a validação.
[Contexto da expansão do projeto]
Há um mês, ele havia sido apresentado como oh-my-ag, um orquestrador dedicado ao Antigravity. Mas, nesse meio-tempo, várias AI IDEs passaram a usar .agents/skills/ como caminho de skills do projeto, e deixou de fazer sentido mantê-lo exclusivo de uma IDE específica. Por isso, ele foi expandido para a forma de um harness genérico e passou a se chamar oh-my-agent.
[Como começar]
curl -fsSL https://raw.githubusercontent.com/first-fluke/oh-my-agent/… | bash
Ele oferece suporte às principais AI IDEs, como Antigravity, Claude Code, Codex CLI e Cursor.
Se você já usa uma AI IDE, pode valer a pena experimentar. No fim, o objetivo do desenvolvedor é atingir QCD (Quality, Cost, Delivery) ao mesmo tempo. Ele foi criado com a ideia de que o desenvolvimento com agentes não é exceção.
🔗 GitHub: first-fluke/oh-my-agent
4 comentários
Sou usuário desde antes, então é uma notícia bem-vinda. Usei o coordinate com satisfação. Eu já estava pensando que seria bom poder validar mais, então, se o modo Ultra é ainda mais minucioso, vou experimentar já amanhã.
Obrigado! Se por acaso ele não obedecer muito bem, por favor me avisem.
Ao adicionar um script no
package.json, ele acabou mantendo só a pasta do workspace e apagando todos os outros arquivos. Estou recuperando agora, mas é inacreditável.Você executou isso dentro do Claude ou do agente? Não há nenhum código que apague o
package.jsonou todos os arquivos. Agradeço se puder compartilhar o fluxo completo!/tmp/oh-my-agent-*oma cleanup.cursor/skills.cursor/skills