devloop: um harness agêntico para um ciclo de entrega de software

Projeto Final — 5-Day AI Agents: Intensive Vibe Coding with Google (imersão Kaggle/Google, 15–19 jun 2026) Disciplina: Prof. Ivanovitch (PPGEEC/UFRN) Grupo: Vitor Yeso · Igor Sérgio de França Correia · Reilta Christine Dantas Maia Repositório: github.com/vitoryeso/lifecycle-loop-demo · Demo ao vivo: https://vitoryeso.com/devloop

Resumo

Apresentamos o devloop, um harness agêntico repo-agnóstico que conduz qualquer repositório por um ciclo de entrega de software — issue → dev agent → review + testes → release → deploy — no qual agentes de LLM não apenas revisam, mas implementam e corrigem código, com portões humanos nos pontos irreversíveis. O sistema é validado sobre um alvo real — o GitCrack, cliente Git desktop em Tauri desenvolvido por um dos membros do grupo — em um ciclo no qual o loop detecta uma vulnerabilidade de Cross-Site Scripting (XSS) no código real, um dev agent escreve a correção (DOM seguro) e o primeiro teste do projeto, e o portão de qualidade vira de RED para GREEN. Enquadramos a arquitetura na taxonomia de externalização de Zhou et al. (2026), tratando o devloop como a camada de harness que unifica memória, skills e protocolos em execução governada.

1. Introdução

A imersão propõe o paradigma de vibe coding agêntico: o desenvolvedor deixa de ser quem digita cada linha e passa a orquestrar agentes dentro de um ciclo de vida de software governado. O trabalho final pede um projeto que encarne essa tese.

Nosso ponto de partida foi um projeto real e já existente do grupo — o GitCrack, um cliente Git visual (Tauri 2 + Rust + React + TypeScript) — que, como a maioria dos protótipos vibe-coded, não possuía testes, CI, revisão automatizada nem varredura de segurança. Em vez de construir um exemplo isolado, decidimos construir a camada de automação que faltava e aplicá-la ao GitCrack. O resultado, o devloop, separa claramente dois papéis:

• harness (lifecycle-loop-demo): o framework repo-agnóstico, em Python stdlib-only;
• target (projects/GitCrack): o repositório real que é processado pelo ciclo.

Essa separação é o que permite afirmar que o devloop é uma ferramenta reusável, e não um demo específico: ele roda os mesmos estágios contra qualquer repositório.

2. Fundamentação: externalização em agentes LLM

Adotamos como mapa conceitual o survey "Externalization in LLM Agents: A Unified Review of Memory, Skills, Protocols and Harness Engineering" (Zhou et al., arXiv 2604.08224, 2026). Sua tese central:

agentes de LLM são construídos cada vez menos mudando os pesos do modelo e cada vez mais reorganizando o runtime em volta dele — deslocando o esforço cognitivo para a infraestrutura.

O paper organiza esse runtime em quatro eixos de externalização:

O devloop é, precisamente, um exercício de harness engineering: ele não afina nenhum modelo; ele organiza skills, protocolos e um estado de execução (o loop) em uma linha de montagem governada por portões.

3. Arquitetura do devloop

3.1 O ciclo

 ① ISSUE ─▶ ② DEV AGENT ─▶ ③ REVIEW+TESTS ─▶ ④ RELEASE ─▶ ⑤ DEPLOY+MONITOR
    ▲            ▲______________|  (reintrodução p/ correção ③→②)   │
    └───────────────────── monitor reabre incidente ────────────────┘

Cada estágio é conduzido pelo orquestrador ci/loop.py contra um --target. Três portões humanos (human-in-the-loop) guardam os pontos irreversíveis: merge→develop, merge release→main, deploy de produção. Todo o resto — triagem, implementação, revisão, testes, notas de release — é automatizado por agentes.

3.2 Os agentes e o mapeamento à taxonomia de externalização

O ponto central — e a contribuição que consideramos mais forte — é o dev agent: os demais agentes apenas aconselham; o dev agent escreve código. É ele que transforma "revisão assistida por IA" em vibe coding de fato (issue → código → PR).

4. Estudo de caso: GitCrack

O GitCrack renderiza o DAG de commits de um repositório (com lanes, merges e labels de branch) e oferece operações Git (merge, rebase, cherry-pick) via backend Rust. Ele tinha zero testes e nenhum portão de qualidade — o alvo ideal para demonstrar o que o harness adiciona.

A passada (detecção e correção; código real, modelo google/gemini-3.5-flash via OpenRouter):

1. ② PR — introduz-se uma feature real: um tooltip que renderiza a mensagem do commit. A implementação contém um risco: el.innerHTML = \…${commit.summary}``.
2. ③ REVIEW — RED. Duas trilhas independentes convergem no mesmo defeito: - a revisão por LLM aponta o XSS ("commit.summary é untrusted; use DOM seguro"); - o scanner determinístico emite [high] xss-sink: innerHTML assignment. O portão fica vermelho — humano deve olhar.
3. ② DEV AGENT (reintrodução para correção ③→②). O dev agent recebe o achado + a fonte, reescreve o arquivo com DOM seguro (textContent + createElement), preservando a assinatura, e commita em fix/tooltip-xss.
4. ③ RE-REVIEW — GREEN. A re-revisão por LLM confirma ("mitigates XSS… No issues found"), o scanner fica limpo, e o primeiro teste do GitCrack — escrito também pelo dev agent (regressão de XSS em vitest) — passa (2 passed).

Um detalhe honesto e didático: na primeira tentativa o dev agent errou a assinatura da função de teste; o portão ③ falhou; o agente iterou com a fonte e ficou verde — o loop reprocessou até passar.

5. Avaliação

Defense-in-depth (Red/Blue/Green). O achado do XSS foi corroborado por dois mecanismos de naturezas distintas — regex determinístico e julgamento por LLM. O barato/determinístico nunca perde o padrão conhecido; o caro/LLM entende o contexto ("mensagem de commit é untrusted") e escreve o patch. Cada um cobre o ponto cego do outro.

Avaliação do avaliador. ci/eval_security.py mede o próprio scanner contra um golden set rotulado (evals/security_cases.jsonl): recall = 1,00 (nenhuma vulnerabilidade conhecida escapa) e precision = 0,83 — a queda de precisão é um falso-positivo honesto (a palavra eval( dentro de um comentário), reportado, não escondido. Um agente que não se mede não se confia.

Observabilidade de trajetória. A SPA (web/index.html, publicada em vitoryeso.com/devloop) renderiza o loop como grafo dirigido e, para cada etapa agêntica, exibe a entrada (prompt/contexto) e a saída (resposta crua do modelo). Isso materializa a trajectory evaluation: a banca audita o que cada agente recebeu e devolveu, em vez de confiar apenas no resultado final.

6. Mapeamento às Units do curso

7. Escopo e limitações

• ⑤ Deploy + Monitor fora de escopo. Um deploy sondado por /health que reabre incidentes é conceito de serviço web; o GitCrack é app desktop (Tauri). Discutimos o estágio, mas não o encenamos sobre o alvo (o serviço FastAPI de referência do harness serve para ilustrá-lo).
• Modelo único na demo. A passada foi executada com gemini-3.5-flash. Uma comparação multi-modelo (GLM, Qwen, GPT) está prevista como trabalho futuro.
• Portões como processo, não bloqueio (repo privado no plano Free). Rulesets/branch protection do GitHub exigem repo público ou plano Pro; os portões humanos são convenção de processo neste repositório.

8. Reprodutibilidade

# passada real (requer .env com chave OpenRouter; local, gitignored)
python -m ci.loop --target projects/GitCrack --range HEAD~1..HEAD --issue docs/sample_issue.md
# correção pelo dev agent
python -m ci.dev_agent --target projects/GitCrack --file src/tooltip.ts --branch fix/tooltip-xss \
  --task "Fix the XSS: render via safe DOM, not innerHTML. Keep the API."
# gates offline
pytest -q                     # inclui o runner de spec (SDD)
python -m ci.eval_security    # métricas do scanner
python -m mcp.server          # servidor MCP (JSON-RPC no stdin)

Demo sem terminal: https://vitoryeso.com/devloop (botão "Rodar a passada").

9. Divisão do trabalho

O projeto uniu duas frentes complementares, integradas em conjunto pelo grupo:

• GitCrack (o target) — Igor Sérgio e Reilta Maia: o cliente Git em Tauri (DAG de commits, operações Git) que serve de peça real na linha de montagem.
• devloop (o harness) — Vitor Yeso: a camada agêntica que conduz o repositório pelo ciclo de desenvolvimento.

A decisão de integrar as duas frentes — passar o GitCrack pelo loop e enquadrar o conjunto na proposta da disciplina — foi tomada e refinada coletivamente. Cada frente só faz sentido com a outra: sem o alvo real não há o que demonstrar; sem o harness o alvo segue sem testes nem portões.

10. Conclusão

O devloop demonstra, sobre código real, a tese da imersão e do survey de externalização: capacidade agêntica útil emerge menos de um modelo maior e mais de um harness bem projetado — memória (specs), skills, protocolos (MCP) e um dev agent — coordenados em um ciclo governado por humanos nos pontos certos. Neste exemplo, o resultado não é apenas um assistente que aponta problemas: o loop encontra um defeito, propõe a correção e a verifica, deixando ao humano a decisão de merge. Trata-se de uma demonstração sobre um caso representativo, não de uma garantia de correção em geral.

Referências

1. Zhou, C. et al. Externalization in LLM Agents: A Unified Review of Memory, Skills, Protocols and Harness Engineering. arXiv:2604.08224, 2026.
2. Google/Kaggle. 5-Day AI Agents: Intensive Vibe Coding Course. Whitepapers das Units 1–5, 2026.
3. GitCrack (o target) — cliente Git em Tauri, de Igor Sérgio e Reilta Maia: github.com/igorsergioJS/GUI-git- (repositório privado).
4. Repositório do harness (devloop): github.com/vitoryeso/lifecycle-loop-demo.