Act Operator – harness open source para controlar projetos LangGraph 1.0+ "prontos para produção real"
(github.com/Proact0)Por que os resultados são diferentes, se o modelo de IA e a pessoa são os mesmos?
Toda vez é preciso recriar a base do zero, cada equipe usa Agents de um jeito diferente, surgem conflitos de código, e só vão se acumulando protótipos que não conseguem operar em produção…
Aqui sempre aparece uma anomalia crônica que ocorre na colaboração entre pessoas que usam ferramentas de IA.
Quando um desenvolvedor familiarizado com a tecnologia pede ao Claude Code para implementar um workflow, sai um código excelente. Mas, quando um desenvolvedor que está tendo o primeiro contato faz o mesmo pedido ao mesmo Claude Code, o resultado é um código genérico, inconsistente e sutilmente errado. É o mesmo modelo. Por que isso acontece?
O problema não era o modelo, mas sim a lacuna de contexto (Context Gap) — e isso se aplica da mesma forma tanto a pessoas quanto a agentes de IA.
A razão pela qual um novo membro da equipe, colocado no projeto sem onboarding, se perde na mesma base de código é a mesma: as convenções são implícitas, a arquitetura existe só na cabeça de alguém, e não há um ambiente estruturado que sirva de guia. Com agentes de IA não é diferente.
Até profissionais experientes batem nessa parede. Quando a sessão muda, o agente esquece o design anterior. O agente de hoje não conhece a arquitetura definida ontem. Isso porque o conhecimento existe apenas na cabeça das pessoas, e não dentro da base de código. Se a pessoa não consegue encontrar as convenções, o agente também não consegue.
Para resolver isso, não é preciso melhorar prompts nem usar um modelo melhor. É preciso projetar o próprio ambiente em que pessoas e agentes operam juntos.
[ O harness já existia desde o começo. ]
A palavra harness vem do francês antigo 'harnois'. Seu significado original é "equipamento militar, ferramenta de controle".
A partir da década de 1690, consolidou-se seu sentido figurado: "controlar uma força não controlada e usá-la na direção correta (to control for use as power)".
É o mesmo contexto em que se diz que uma usina eólica "faz harnessing do vento" ao transformá-lo em energia.
Na engenharia, esse princípio apareceu repetidamente, mudando apenas de forma.
- Wiring Harness: dispositivo que reúne fios complexamente entrelaçados em um único feixe, transformando-os em uma unidade controlável. É padrão na indústria automotiva há décadas.
- Test Harness: ambiente de execução composto por stubs e drivers, que permite isolar e executar um componente específico sem toda a infraestrutura. É um conceito central de testes de software.
- Pipelines de CI/CD: um ambiente de controle estruturado para que o código não vá direto para produção, mas passe por camadas de build, teste e validação. Isso também é um harness.
Todos eles têm algo em comum.
O projeto de um ambiente externo para controlar, na direção correta, um objeto não controlado (fios, componentes de código, fluxo de deploy).
Por isso, no início de 2026, quando a OpenAI criou um sistema na escala de 1 milhão de linhas em 5 meses com o agente Codex, sem escrever manualmente uma única linha de código, foi uma consequência natural dar o nome de Harness Engineering à aplicação desse antigo princípio aos agentes de IA. Não é coincidência que Martin Fowler e a equipe de engenharia da Anthropic tenham usado a mesma palavra na mesma época.
E a LangChain também melhorou sua posição no Terminal Bench 2.0 do 30º para o 5º lugar apenas aprimorando o harness.
Por isso, o act-operator foi criado como um harness para controlar estruturas LangGraph 1.0+ que possa ser usado em produtos reais.
[ Ultra-Quick Start ]}
Em um ambiente com uv instalado, a configuração de um harness de projeto LangGraph 1.0+ para produção real fica pronta com esta única linha abaixo.
uvx --from act-operator act new
[ As 3 camadas do Act Operator ]
No desenvolvimento baseado em IA, o harness é um sistema de scaffolding, conhecimento executável e feedback loop que envolve pessoas e agentes de IA para que ambos possam gerar saídas corretas de forma estável, independentemente de quem esteja trabalhando.
O Act Operator implementa isso em três camadas:
- Scaffolding: um esqueleto completo de projeto, com convenções modulares e classes base embutidas, garantindo baixo acoplamento mínimo e alta coesão mínima, montado antes do primeiro prompt do agente
- SSOT executável: conhecimento codificado em arquivos operáveis, lidos em runtime por agentes e pessoas
- Feedback loop: especificações que mantêm o agente alinhado entre sessões
[ SSOT executável ]
Equipes comuns compartilham conhecimento de desenvolvimento e design por meio de wikis, documentos de arquitetura e conhecimento oral — e às vezes nem isso. O problema é que documentos envelhecem, wikis ficam desatualizadas, e o conhecimento oral não sobrevive às mudanças na equipe.
O harness codifica esse conhecimento em arquivos que funcionam — não como documentação estática, mas como referências executáveis que agentes e pessoas leem diretamente. O Act Operator gerencia isso em três camadas complementares de componentes SSOT, considerando acoplamento e coesão:
- Act Template (scaffold): o próprio esqueleto do projeto — workflow básico de CI, classes base, estrutura de testes, configuração de monorepo, gerenciamento de variáveis de ambiente e guia de uso
- Agent Skills: um total de 5 skills, mais de 50 padrões de referência, árvores de decisão e templates de arquitetura
- Drawkit: shapes predefinidos de arquitetura Act para draw.io — um vocabulário visual compartilhado para comunicação entre pessoas
Cada componente mira um alvo diferente, mas referencia as mesmas convenções de base. O Act Template estabelece a fundação estrutural em que agentes e desenvolvedores trabalham. As skills mostram ao agente como construir corretamente dentro dessa estrutura, e o Drawkit ensina a equipe a visualizar a arquitetura.
[ Outras informações sobre o open source ]
- Além do Claude Code, funciona com qualquer ferramenta que suporte diretórios de skills, como OpenCode, Cursor e Gemini CLI.
- Suporte a documentação em coreano e inglês
- Licença Apache 2.0 – distribuído 200% grátis no PIPY
Feedback e contribuições de todos são muito bem-vindos (e estrelas no GitHub também★..!). Obrigado :)
Ainda não há comentários.