Esta postagem é o conteúdo de uma apresentação sobre 'Engenharia de Harness' como estudo de caso, realizada em 2 de maio de 2026, na guilda Dabakodan DaoLab VibeCoding.
A Nextain é uma empresa que desenvolve e apoia tecnologias para a AX de empresas com produtos de software. Atualmente, assumiu a operação do sistema do Onmam.com, um portal de igrejas coreanas, e está trabalhando na AX.
Estamos realizando a migração do sistema legado que estava em um antigo centro de dados IDC, configurando um ambiente para desenvolvimento e operação baseados em agentes, e trabalhando na estabilização e melhoria de funcionalidades.
Por ser um sistema legado antigo, houve tentativas e erros, e estamos incorporando isso com a experiência e tecnologia da empresa ao aplicar o naia-business-adk ao Onmam.com.
Como parte dessa experiência, compartilhamos um estudo de caso explicando a engenharia de harness no evento.
Mensagem principal deste artigo "Mais importante do que usar bem a IA é criar um ambiente onde a IA não cometa erros."
1. Primeiro, apresentando nosso serviço
Onmam.com — Plataforma de gerenciamento de igrejas usada por 13.876 igrejas em todo o país
www.onmam.com ← Encontrar igrejas, portal de membros
home.onmam.com ← Aplicativo de canal (conteúdo/pagamento)
{nome_da_igreja}.onmam.com ← Website de igreja individual
Infraestrutura: Servidor IDC antigo → Migração completa para GCP (Google Cloud) concluída em abril de 2026 DB: Dados de 13.876 igrejas × Cloud SQL
2. Vamos começar com um incidente
"Um dia de abril de 2026"
11h da manhã. De repente, todos os serviços do Onmam.com ficaram sem resposta.
Usuários: "Por que o site não está funcionando?"
Ao rastrear a causa — o código de consulta da lista de posts no arquivo Board.php.
-- Consulta que causou o problema (simplificada)
SELECT * FROM boards
JOIN (
SELECT bbs_id, COUNT(*) FROM all_boards GROUP BY bbs_id -- ← Este é o problema
) AS summary ON boards.id = summary.bbs_id
WHERE church_id = ?
Esta única consulta estava realizando um full scan em todos os dados das 13.876 igrejas a cada vez. Com o pico de tráfego, 145 consultas de 600 a 800 segundos foram executadas simultaneamente → paralisia completa do servidor.
O que isso tem a ver com IA?
Provavelmente, um desenvolvedor humano escreveu este código pela primeira vez. Mas hoje, os desenvolvedores escrevem esse tipo de código com a ajuda da IA.
O problema é — a IA não sabe "como este código funciona no ambiente de 13.876 igrejas". A IA se concentra em implementar a funcionalidade solicitada e não conhece o contexto do nosso serviço.
Então, os desenvolvedores começaram a se perguntar: "Como impedimos que a IA escreva código sem conhecer nosso serviço?"
3. Engenharia de Harness — Explicação em 30 segundos
Assim como são necessárias rédeas e arreios (Harness) para lidar com um cavalo,
agentes de IA também precisam de restrições, guias e mecanismos de validação.
Agente = Modelo + Harness
Harness = Projetar todo o ambiente em que a IA trabalha
Não é simplesmente "fazer boas perguntas à IA". É o design de um sistema que impede estruturalmente que a IA cometa o mesmo erro quando ela falha.
4. Harnesses realmente criados no Onmam.com
[Harness #1] AGENTS.md — O "Mapa do Nosso Serviço" para a IA
alpha-adk/
├── CLAUDE.md ← Arquivo que a IA deve ler obrigatoriamente ao iniciar uma sessão
├── AGENTS.md ← Lista de regras do projeto
└── .agents/
└── context/
└── agents-rules.json ← Regras operacionais específicas
A IA lê esses arquivos obrigatoriamente antes de tocar no código do Onmam.com. Eles contêm o seguinte:
- "Testes e modificações de código são realizados apenas no ambiente alpha"
- "home.onmam.com é um aplicativo de canal separado, não um portal"
- "O padrão de tabela derivada GROUP BY em Board.php é absolutamente proibido"
Aquela falha de antes? Agora, se a IA tentar criar o mesmo padrão, ela para ao ver esta regra.
[Harness #2] Hooks — "Mecanismos de Segurança" que atuam antes e depois das ações da IA
Hooks atualmente em operação neste workspace:
Pouco antes de a IA executar um comando Bash →
✓ pr-guard.js : Bloqueia o merge de PRs sem revisão
✓ commit-guard.js : Bloqueia commits que violam regras
✓ deploy-guard.js : Bloqueia a implantação no servidor de produção sem aprovação
✓ git-push-guard.js : Bloqueia git push sem aprovação
✓ destructive-git-guard.js : Bloqueia comandos destrutivos como git reset --hard
Pouco antes de a IA modificar um arquivo →
✓ prod-gateway-guard.js : Impede o uso de chaves de API de produção em arquivos de ambiente de desenvolvimento
✓ design-doc-guard.js : Bloqueia a modificação não autorizada de documentos de design
Logo após a IA modificar um arquivo →
✓ cascade-check.js : Verifica arquivos afetados em cascata pelo arquivo modificado
Exemplo de funcionamento real de deploy-guard.js:
Tentativa da IA de executar comando de implantação em produção:
$ gcloud run deploy onmam-web ...
→ [Harness] Comando de implantação em produção bloqueado: gcloud run deploy
Projeto: onmam-web
A implantação em produção requer aprovação prévia.
Método de aprovação: Adicione um item de aprovação em .claude/deploy/approvals.json
A IA não executa a implantação em produção diretamente.
Mesmo que a IA tente, por engano ou de forma muito agressiva, fazer upload de algo para o servidor de produção, ela é fisicamente bloqueada.
[Harness #3] Ambiente Alpha — O playground exclusivo da IA para experimentação
Produção: www.onmam.com ← Usado pelas igrejas reais
Staging: staging.onmampick.org ← Verificação final antes da implantação
Alpha: luke-*-alpha.onmampick.org ← Espaço de trabalho com IA
Regra: Todo o trabalho com a IA é feito apenas no ambiente alpha.
Por que isso é importante — O que realmente aconteceu em 29 de abril de 2026:
A IA confundiu
home.onmam.comcom o aplicativoportale escreveu uma configuração de vhost incorreta. Como estava no ambiente alpha → nenhum impacto no serviço real. Este erro foi registrado em AGENTS.md → a IA não cometerá o mesmo erro novamente.
A essência do harness está aqui: Se um erro ocorre → é registrado no harness → e então esse erro se torna estruturalmente impossível de acontecer novamente.
[Harness #4] Skills — "Nossas Próprias Ferramentas" para a IA
skills/
├── email/ ← Envio de e-mail (inclui destinatários, regras SMTP)
├── sms/ ← Envio de SMS
├── web-monitoring/ ← Monitoramento do status do serviço
└── service-management/ ← Comandos de operação do serviço
Se a IA diz "envie um e-mail" — ela lê este arquivo de skill e sabe automaticamente para quem, em que formato e com qual SMTP deve enviar. Não há necessidade de perguntar "qual é o endereço de e-mail do destinatário?" a cada vez.
5. Por que os desenvolvedores se interessam por isso
"Problemas da era do desenvolvimento sem IA"
Dependência da capacidade individual do desenvolvedor → a qualidade diminui se um sênior sai
Deve ser pego por revisão de código → uma pessoa precisa verificar manualmente
"Problemas de equipes com IA, mas sem harness"
A IA gera código rapidamente, mas → não conhece o contexto do nosso serviço
Repete os mesmos erros → a IA cria bugs e as pessoas os corrigem
A IA pode acessar diretamente o servidor de produção → não se sabe quando um acidente pode ocorrer
"Equipes com IA + harness"
A IA escreve código conhecendo nossas regras → geração com contexto
Se um erro ocorre, é registrado no harness → prevenção estrutural do mesmo erro
Acesso à produção é aprovado por humanos → autonomia segura
Parafraseando a Toss:
"Com o harness, elevamos o nível mínimo de produtividade de toda a organização. Não dependemos da capacidade individual, e todos os membros da equipe produzem resultados acima de um certo nível."
6. Resumo — O que queremos transmitir aos não-desenvolvedores
Na era da IA, a definição de "fazer bem" está mudando.
Antes: Desenvolvedor que escreve bom código Agora: Desenvolvedor que projeta bem o ambiente onde a IA escreve código
O cerne desse design de ambiente é a engenharia de harness.
E isso não é apenas uma história para desenvolvedores.
Harness que não-desenvolvedores também podem fazer:
→ Escrever claramente as regras de trabalho em documentos
→ Definir para a IA "isso pode ser feito, isso não pode ser feito"
→ Registrar "por que a IA cometeu um erro" quando ela falha
= Isso em si é o início da engenharia de harness
Estrutura do Harness do Onmam.com em um relance
alpha-adk/
├── CLAUDE.md ← [Guia] Leitura obrigatória ao iniciar uma sessão de IA
├── AGENTS.md ← [Guia] Regras do projeto (SoT)
├── .agents/context/
│ └── agents-rules.json ← [Guia] Regras operacionais específicas
├── .claude/
│ ├── hooks/
│ │ ├── deploy-guard.js ← [Sensor] Bloqueio de implantação em produção
│ │ ├── prod-gateway-guard.js← [Sensor] Bloqueio de chave de API de produção
│ │ ├── commit-guard.js ← [Sensor] Validação de regras de commit
│ │ ├── pr-guard.js ← [Sensor] Imposição de aprovação de PR
│ │ ├── session-inject.js ← [Sensor] Injeção de contexto em cada sessão
│ │ └── cascade-check.js ← [Sensor] Verificação de impacto em cascata após modificação
│ └── settings.json ← [Permissão] Configuração de execução de hook
├── skills/
│ ├── email/ ← [Ferramenta] Skill de envio de e-mail
│ ├── web-monitoring/ ← [Ferramenta] Monitoramento de serviço
│ └── service-management/ ← [Ferramenta] Comandos de operação de serviço
└── data-private/memory/ ← [Loop de Feedback] Registro de erros → Prevenção de recorrência
├── project_onmam_incidents.md ← Registro de padrão de falha de Board.php
├── project_onmam_app_structure.md← Registro de erro home≠portal
└── feedback_alpha_only.md ← Registro de regras exclusivas do alpha
Harness = O conjunto desses arquivos Todos são commitados no repositório Git. Todo o contexto da equipe! é acumulado como código.
