Desenvolvimento AI-Native com Angular: Construindo o Painel do Jogo do Abate (Jujutsu Kaisen)

Olá, dev! Se você se interessa por arquiteturas de software modernas e engenharia orientada a agentes de inteligência artificial, este projeto traz um estudo de caso prático e interessante. Vamos analisar a construção do Culling Games Control Panel: uma aplicação de controle e monitoramento baseada no universo de Jujutsu Kaisen.

Neste artigo, veremos como foi construída uma SPA (Single Page Application) com suporte a SSR (Server-Side Rendering) que gerencia participantes, exibe estatísticas em tempo real, registra logs de atividade e permite a simulação de regras temáticas (como a transferência de pontuações).

Mais do que apenas um exemplo estético, este projeto é um exemplo didático de Engenharia de Software AI-Native, demonstrando a transição de um protótipo visual concebido no Google AI Studio para uma base de código de produção desenvolvida localmente com o agente Antigravity sob o framework de especificação OpenSpec e utilizando as tecnologias mais recentes do Angular.

---

Arquitetura de Desenvolvimento Orientada a Agentes (AI-Native)

Antes de detalharmos o código, vale ressaltar que a aplicação foi desenvolvida seguindo um fluxo de trabalho moderno em que o desenvolvedor humano atua como arquiteto e revisor de decisões executadas por agentes autônomos de IA.

O ciclo de vida do desenvolvimento seguiu as seguintes etapas:

1. Modelagem de UI (Google AI Studio): O protótipo visual inicial contendo a paleta de cores escura, componentes de exibição e tipografia foi exportado diretamente do AI Studio

2. Definição de Especificações (OpenSpec): Mapeamos as regras de negócio em especificações técnicas claras, documentando as rotas da API, modelo de dados e requisitos não-funcionais.

3. Desenvolvimento Agêntico (Antigravity + Angular CLI): O agente Antigravity assumiu a tarefa de ler as especificações do OpenSpec e a base estática do protótipo, integrando-as em um projeto Angular limpo, estruturado e aplicando as melhores práticas de desenvolvimento (Angular Agent Skills).

4. Verificação Automatizada: Scripts de teste foram criados e rodados localmente para garantir a integridade das regras especificadas.

---

Pré-requisitos e Instalação

Para executar a aplicação e os seus testes em sua máquina local, certifique-se de possuir:

• Node.js (versão 26 ou superior recomendada)

• npm

Navegue até a pasta da aplicação para instalar as dependências:

cd culling-games-panel
npm install

---

1. Arquitetura do Frontend: Componentes Standalone

A aplicação adota o padrão de Componentes Standalone (introduzido nas versões recentes do Angular), removendo a necessidade de módulos NgModules complexos. A estrutura de componentes divide-se de forma clara entre Smart Components (gerenciadores de estado e requisições) e Dumb Components (focados exclusivamente em apresentação):

• CullingGamesBoardComponent (Smart Component): Serve como container principal da tela. Ele gerencia o estado consolidado da lista de feiticeiros e aciona os serviços para atualizar dados via requisições HTTP.

• PlayerRegistrationComponent (Dumb Component): Formulário responsável por coletar dados de novos feiticeiros (nome, colônia inicial, técnica e pontos).

• PlayerGridComponent (Dumb Component): Grid responsiva que exibe os participantes ativos em formato de cartões de perfil.

• KoganeLogsComponent (Dumb Component): Painel lateral que atua como feed de eventos em tempo real, informando as transferências de pontos e novas inscrições.

---

2. Persistência de Dados: Backend Express no Servidor SSR

A fim de simplificar o ambiente de estudo e focar nos conceitos de arquitetura, a persistência de dados foi implementada de forma simplificada em memória.

O motor de Server-Side Rendering (SSR) do Angular está configurado com um servidor Express tradicional no arquivo src/server.ts. Esse arquivo, além de renderizar as páginas do lado do servidor, expõe endpoints REST que gerenciam o estado dos feiticeiros:

// REST API Endpoints dentro do Express no servidor SSR
app.get('/api/players', (req, res) => {
  res.json(players);
});

app.post('/api/players', (req, res) => {
  const newPlayer: Sorcerer = req.body;
  if (!newPlayer.name || !newPlayer.colony) {
    res.status(400).json({ error: 'Name and Colony are required.' });
    return;
  }
  players.unshift(newPlayer);
  res.status(201).json(newPlayer);
});

app.put('/api/players/:id/points', (req, res) => {
  const { id } = req.params;
  const { points } = req.body;
  const player = players.find(p => p.id === id);
  if (!player) {
    res.status(404).json({ error: 'Player not found.' });
    return;
  }
  player.points = points;
  res.json(player);
});

---

3. Reatividade Moderna: Angular Signals-based Forms

Uma das maiores novidades no ecossistema do Angular é a introdução experimental da biblioteca de formulários reativos baseados em sinais (@angular/forms/signals). Este projeto serve como um ótimo estudo de caso para entender como ligar campos de entrada a sinais atômicos de reatividade nativa sem depender de fluxos complexos de RxJS ou da reatividade tradicional baseada em objetos do FormGroup.

Observe no código de player-registration.component.ts como a validação e o mapeamento são estruturados:

import { Component, output, signal } from '@angular/core';
import { form, FormField, submit, required, min, max } from '@angular/forms/signals';
import { Sorcerer } from '../../models';

@Component({
  selector: 'app-player-registration',
  standalone: true,
  imports: [FormField],
  templateUrl: './player-registration.component.html'
})
export class PlayerRegistrationComponent {
  readonly playerRegistered = output<Omit<Sorcerer, 'id'>>();

  // Modelo reativo declarado como um Signal contendo o objeto de dados
  protected readonly model = signal({
    name: '',
    colony: 'Tokyo Colony No. 1',
    technique: '',
    points: 0,
    status: 'Alive' as 'Alive' | 'Deceased'
  });

  // O Signal-based Form vincula validações de forma declarativa sobre o modelo
  protected readonly registrationForm = form(this.model, (s) => {
    required(s.name, { message: 'Sorcerer Name is required.' });
    required(s.colony, { message: 'Starting Colony is required.' });
    min(s.points, 0, { message: 'Points cannot be negative.' });
    max(s.points, 1000, { message: 'Points cannot exceed 1000.' });
  });

  onSubmit() {
    submit(this.registrationForm, async () => {
      const val = this.model();
      this.playerRegistered.emit({
        name: val.name.trim(),
        colony: val.colony,
        technique: val.technique.trim(),
        points: val.points,
        status: val.status
      });

      // Reseta o estado do modelo usando signals
      this.model.set({
        name: '',
        colony: 'Tokyo Colony No. 1',
        technique: '',
        points: 0,
        status: 'Alive'
      });
      this.registrationForm().reset();
    });
  }
}

No arquivo HTML player-registration.component.html, os inputs se vinculam diretamente ao controle de sinal:

<input 
  type="text" 
  [formField]="registrationForm.name"
  placeholder="e.g., Hajime Kashimo" 
  class="..."
>
@if (registrationForm.name().touched() && registrationForm.name().errors().length) {
  <div class="text-red-500 text-[9px] uppercase tracking-wider font-mono font-bold">
    {{ registrationForm.name().errors()[0].message }}
  </div>
}

---

4. Garantia de Qualidade: Estratégia de Testes Automatizados

A estabilidade e as regras de negócio da aplicação são asseguradas por duas vertentes de testes automatizados:

🧪 Testes Unitários com Vitest

Em substituição ao Karma tradicional, o projeto utiliza o Vitest, um test runner extremamente rápido que consome o arquivo de configuração vitest.config.ts. Os testes cobrem a lógica do serviço de estado (CullingGamesService), o ciclo de validação do formulário e a renderização estrutural dos componentes.

• Executar os testes em execução única (recomendado para CI):

  npx ng test --watch=false
  

• Executar em modo contínuo (Watch Mode):

  npx ng test
  

Testes End-to-End (E2E) com Playwright

O Playwright realiza testes completos simulando o fluxo de uso da aplicação em navegadores reais. Ele valida interações complexas como o registro de feiticeiros, a transferência de pontuações entre participantes vivos e as restrições impostas por regras de negócio (como bloquear transações de pontos para personagens declarados como mortos).

O arquivo playwright.config.ts possui uma diretiva webServer que inicializa o servidor de desenvolvimento local de forma autônoma e aguarda a porta 4200 estar ativa antes de iniciar a suíte.

• Executar os testes E2E em modo headless (terminal):

  npm run e2e
  

• Executar em modo interativo com a interface gráfica do Playwright:

  npm run e2e:ui
  

---

5. Extensibilidade Agêntica: Skills de IA & Atuação no Navegador (/browser)

Um dos maiores diferenciais deste projeto de Engenharia AI-Native é a forma como o agente de IA é guiado por diretrizes específicas de desenvolvimento e realiza verificações em tempo real.

Como Instalar e Utilizar as Skills do Angular e OpenSpec

Para ensinar estes padrões modernos ao seu agente de codificação e habilitar este fluxo de trabalho no seu próprio repositório:

1. Instalação das Skills Oficiais do Angular: Utilize a CLI de gerenciamento de skills do Angular (através do npx) para injetar as diretrizes de reatividade moderna no contexto do agente:

   npx skills add https://github.com/angular/skills
   

   Isso adicionará a pasta .agents/skills/angular-developer no seu workspace, contendo o arquivo SKILL.md com instruções detalhadas sobre Signals, Componentes Standalone e boas práticas que o agente consumirá antes de codificar.

2. Instalação do CLI do OpenSpec: O OpenSpec permite gerenciar o ciclo de vida das especificações de mudanças através de um conjunto de comandos simples. Instale-o globalmente em sua máquina usando:

   npm install -g @fission-ai/openspec@latest
   

   Após a instalação, você pode iniciar o framework no seu repositório rodando:

   openspec init
   

   Isso cria a pasta .agent/workflows/ (contendo comandos integrados como /opsx:propose, /opsx:apply e /opsx:archive), estruturando a transição segura e rastreável de tarefas feitas por agentes.

Verificação de UI com Atuação de Navegador (/browser)

Os testes e2e não precisam ser verificados apenas via console. Durante o ciclo de vida do OpenSpec, o desenvolvedor ou o próprio agente pode executar comandos de verificação visual por meio de ferramentas de automação baseadas em Chrome Headless (com a diretiva /browser ou ferramentas de subagentes de navegação).

Isso garante que o agente:

• Inicie a build do servidor local em segundo plano.

• Abra o navegador automaticamente, navegue pela aplicação e interaja com os elementos DOM (ex: preencher o formulário de cadastro, clicar nos botões de incremento de pontos).

• Capture imagens e vídeos (WebP) do fluxo de telas para validar de forma autônoma a fidelidade visual e a coerência estética das interfaces em relação ao design concebido no AI Studio.

---

Como Executar a Aplicação Localmente

Após instalar as dependências com npm install, inicie o servidor local:

npm run start

Acesse o endereço http://localhost:4200 em seu navegador. A aplicação será inicializada com dados estáticos de simulação, permitindo adicionar novos participantes, modificar pontos de personagens específicos e verificar a atualização dinâmica das estatísticas gerais exibidas no cabeçalho do painel.

---

Conclusão e Próximos Passos

Este repositório é um exemplo prático de como novas ferramentas de IA generativa facilitam a prototipação e a codificação, fornecendo uma base de estudo rica tanto para a arquitetura moderna do Angular quanto para o desenvolvimento de software auxiliado por agentes autônomos.

Se você deseja avançar no estudo deste projeto, sugerimos os seguintes exercícios:

1. Persistência de dados externa: Substituir a lista em memória no servidor SSR por conexões a um banco de dados real.

2. Integração com IA: Consumir a API do Gemini no backend Express para gerar comentários automáticos em formato de notícias do Kogane sempre que um feiticeiro ganhar pontos ou for registrado no jogo.

3. Novas regras de negócio: Estender a validação de formulários baseada em sinais para incluir novas colônias e tipos de habilidades.

Todo o código-fonte, suítes de teste e especificações estão contidos neste repositório: Repositório no GitHub

Bons estudos e até o próximo projeto!