publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

context agent

Browse source
This commit is contained in:
Luiz Silva 2026-10-08 15:08:09 -03:00
parent 29e5bc979e
commit f47e12fe81
23 changed files with 347 additions and 226 deletions
Download patch file Download diff file Expand all files Collapse all files

26
rules/identidade-modulo.md
View file

@ -5,7 +5,7 @@ description: Identificação obrigatória do projeto/módulo via memorias-ia/mod
scope: global
trigger: always_on
priority: critica
updatedAt: "2026-10-06"
updatedAt: "2026-10-08"
---
# Regra: Identidade do Projeto via `memorias-ia/modulo.yml`
@ -38,11 +38,25 @@ modulo-caminho: <rota-na-url>
modulo-descricao: <texto-descritivo>
modulo-tipo: <texto-tipo-arquitetura>
# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA)
# Credenciais para autenticação em testes (agent-browser, E2E, QA)
# Formato Simples (aplicação com contexto único de acesso):
modulo-acesso:
usuario: <login-ou-email>
senha: <senha-de-teste>
# Ou Formato Multi-Contexto (quando a aplicação possui acessos distintos - evita mistura de tokens):
# modulo-acesso:
# interno:
# usuario: <login-operador>
# senha: <senha-operador>
# cliente:
# usuario: <login-cliente>
# senha: <senha-cliente>
# externo:
# usuario: <login-cidadao>
# senha: <senha-cidadao>
# anonimo: null # acesso público/deslogado
# Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/)
modulo-wiki: <caminho-da-wiki>
```
@ -51,11 +65,11 @@ modulo-wiki: <caminho-da-wiki>
| Campo | Tipo | Descrição | Exemplo |
| :--- | :--- | :--- | :--- |
| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e identificador mandatório de sessão isolada no `agent-browser` (`--session <modulo-id>`). | `e-licencie.sigma` |
| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e prefixo da sessão isolada no `agent-browser` (`--session <modulo-id>_<contexto?>`). | `e-licencie.sigma` |
| **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/sigma/` |
| **`modulo-descricao`** | `string` | Descrição textual do propósito funcional e escopo de negócio do módulo. | `Módulo para gestão de monitoramentos ambientais` |
| **`modulo-tipo`** | `string` | Descrição textual da arquitetura e tecnologias empregadas no módulo. | `aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres` |
| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`). | `{ usuario: "admin@gov.br", senha: "123" }` |
| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) ou organizadas por contexto (`interno`, `externo`, `cliente`, `anonimo`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`), prevenindo mistura de tokens. | `{ usuario: "admin@gov.br", senha: "123" }` ou subchaves de contexto |
| **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` |
---
@ -63,10 +77,10 @@ modulo-wiki: <caminho-da-wiki>
## Regra Universal de Consulta
Sempre que qualquer agente, persona, workflow ou skill necessitar de:
1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`), Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<modulo-wiki>/dev/<modulo-id>/adrs/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session <modulo-id>`)**;
1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`), Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<modulo-wiki>/dev/<modulo-id>/adrs/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session <modulo-id>_<contexto?>`)**;
2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `<modulo-caminho>llm.md`), links de navegação ou proxies;
3. **Propósito ou Stack (`modulo-descricao` e `modulo-tipo`)**: para contextualizar novos agentes, gerar propostas comerciais, marketing, reels, análises de arquitetura ou testes;
4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística em rotinas de teste e validação de interface;
4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair as credenciais do contexto específico (`interno`, `externo`, `cliente`, etc.) ou credenciais diretas de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística sem contaminação de cookies/tokens entre perfis;
5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia;
6. **Sincronização do Submódulo (`.agent`)**: Ao iniciar qualquer sessão ou interação no projeto hospedeiro, o agente DEVE assegurar que o submódulo `.agent` esteja atualizado com a branch `master` remota executando `git submodule update --init --recursive --remote`.

82
rules/testes-interface-agent-browser.md
View file

@ -1,7 +1,7 @@
---
type: rule
name: testes-interface-agent-browser
description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) e com isolamento por sessão (--session <modulo>).
description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) e com isolamento por sessão e contexto (--session <modulo>_<contexto?>).
scope: global
trigger: always_on
updatedAt: "2026-10-08"
@ -13,7 +13,7 @@ updatedAt: "2026-10-08"
Quando uma IA precisa testar o frontend, validar jornadas de usuário, inspecionar componentes gráficos ou simular interações na tela, é crucial utilizar uma ferramenta rápida, determinística e econômica em tokens. Além disso, o operador humano deve sempre ter visibilidade do que a IA está executando em tempo real na interface gráfica.
Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Para viabilizar testes concorrentes e evitar interferências mútuas entre múltiplos módulos ou workspaces, todo comando deve operar em sessão isolada identificada pelo módulo.
Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Para viabilizar testes concorrentes e evitar interferências mútuas entre múltiplos módulos ou workspaces, todo comando deve operar em sessão isolada identificada pelo módulo e pelo contexto de acesso.
Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA.
@ -27,24 +27,38 @@ Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar
2. **Executar SEMPRE em Modo Visível (`--headed`)**:
- A janela do navegador **deve sempre aparecer na área de trabalho do operador**.
- É **terminantemente proibido** rodar testes ocultos (headless silencioso), a menos que o operador humano solicite expressamente essa exceção.
- Usar a flag `--headed` nos comandos de abertura (`agent-browser --session <modulo> open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
3. **Isolamento Mandatório de Sessão (`--session <modulo>`)**:
- **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo.
- Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>`.
- Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos em testes simultâneos multi-módulos.
- Caso um mesmo módulo necessite de sub-isolamento para testes paralelos, deve-se adotar o sufixo determinístico `<modulo-id>-<slug-ou-pid>`.
- Usar a flag `--headed` nos comandos de abertura (`agent-browser --session <modulo>_<contexto?> open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
3. **Isolamento Mandatório de Sessão e Contexto (`--session <modulo>_<contexto?>`)**:
- **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo e o contexto de acesso.
- Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml` e `<contexto?>` discrimina o papel ou natureza do acesso), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto?>`.
- **Prevenção de Mistura de Tokens:** Caso a aplicação possua mais de um tipo de acesso (`interno`, `externo`, `anonimo`, `cliente`, etc.), o `<contexto>` **DEVE SER OBRIGATORIAMENTE PREENCHIDO** para evitar que cookies, tokens JWT e estados de login residuais contaminem outros fluxos de teste.
- Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>_<contexto>.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos.
- Caso um mesmo módulo e contexto necessite de sub-isolamento para testes paralelos, adota-se o discriminador determinístico: `<modulo>_<contexto>_<slug-ou-pid>`.
4. **Utilizar o modelo de referências (`@ref`)**:
- Mapear a tela via `agent-browser --session <modulo> snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
- Mapear a tela via `agent-browser --session <modulo>_<contexto?> snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
- Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
5. **Registrar evidências e fechar sessão**:
- Registrar comprovações visuais com `agent-browser --session <modulo> screenshot <arquivo.png>`.
- Encerrar graciosamente o navegador com `agent-browser --session <modulo> close` ao término do fluxo.
6. **Credenciais Canônicas de Teste (`modulo-acesso`)**:
- Sempre que o teste exigir autenticação (login, sessão administrativa), o agente **DEVE OBRIGATORIAMENTE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml`**.
- Registrar comprovações visuais com `agent-browser --session <modulo>_<contexto?> screenshot <arquivo.png>`.
- Encerrar graciosamente o navegador com `agent-browser --session <modulo>_<contexto?> close` ao término do fluxo.
6. **Credenciais Canônicas por Contexto (`modulo-acesso`)**:
- Sempre que o teste exigir autenticação, o agente **DEVE OBRIGATORIAMENTE extrair as credenciais do contexto específico** em `modulo-acesso` de `memorias-ia/modulo.yml` (ex: `modulo-acesso.interno`, `modulo-acesso.cliente`, etc.).
- Para sessões anônimas (`_anonimo`), nenhum login deve ser realizado, garantindo a validação da experiência do usuário público sem tokens.
- É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.
---
## 🔒 Contextos Canônicos de Sessão (`<modulo>_<contexto>`)
| Contexto | Finalidade e Natureza | Exemplo de Sessão | Credenciais em `modulo.yml` |
| :--- | :--- | :--- | :--- |
| **`interno`** | Operador interno, suporte, técnico, atendente, administrador | `--session <modulo>_interno` | `modulo-acesso.interno` (ou `modulo-acesso` simples) |
| **`cliente`** | Cliente final, solicitante corporativo, empresa contratante | `--session <modulo>_cliente` | `modulo-acesso.cliente` |
| **`externo`** | Portal público autenticado, cidadão, requerente externo | `--session <modulo>_externo` | `modulo-acesso.externo` |
| **`anonimo`** | Usuário deslogado, consulta pública por código, login, landing | `--session <modulo>_anonimo` | Nenhuma (perfil limpo sem cookies/tokens) |
| **`<especifico>`** | Papel especializado de domínio (ex: `fiscal`, `auditor`) | `--session <modulo>_<papel>` | `modulo-acesso.<papel>` |
---
## Instalação e Configuração
O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium:
@ -63,55 +77,56 @@ Documentação de referência: **https://agent-browser.dev/**
## Protocolo Operacional Padrão
Todo teste ou navegação de interface executado pela IA deve seguir o fluxo com isolamento de sessão:
Todo teste ou navegação de interface executado pela IA deve seguir o fluxo com isolamento de sessão e contexto:
### 1. Obter Identificador do Módulo e Abertura com Janela Visível
```bash
# Obter o modulo-id canônico de memorias-ia/modulo.yml
MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
CONTEXTO="interno" # ou "cliente", "externo", "anonimo"
# Abrir sempre visível ao operador humano na sessão isolada do módulo
agent-browser --session "$MODULO" open --headed http://localhost:8080
# Abrir sempre visível ao operador na sessão isolada por módulo e contexto
agent-browser --session "${MODULO}_${CONTEXTO}" open --headed http://localhost:8080
```
### 2. Inspeção de Elementos Interativos
```bash
# Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2)
agent-browser --session "$MODULO" snapshot -i
agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i
```
### 3. Interações por Referência Direta
```bash
# Interagir diretamente com os elementos identificados no snapshot
agent-browser --session "$MODULO" fill @e1 "usuario@exemplo.com"
agent-browser --session "$MODULO" fill @e2 "senhaSegura123"
agent-browser --session "$MODULO" click @e3
agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "usuario@exemplo.com"
agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "senhaSegura123"
agent-browser --session "${MODULO}_${CONTEXTO}" click @e3
```
### 4. Validação e Evidência
```bash
# Aguardar estabilização se houver transição assíncrona
agent-browser --session "$MODULO" wait 1000
agent-browser --session "${MODULO}_${CONTEXTO}" wait 1000
# Obter novo snapshot para verificar estado pós-ação
agent-browser --session "$MODULO" snapshot -i
agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i
# Capturar evidência gráfica do teste
agent-browser --session "$MODULO" screenshot evidencias/teste-login-sucesso.png
agent-browser --session "${MODULO}_${CONTEXTO}" screenshot evidencias/teste-login-sucesso.png
# Verificar erros no console do navegador
agent-browser --session "$MODULO" console
agent-browser --session "${MODULO}_${CONTEXTO}" console
```
### 5. Finalização
```bash
# Fechar a sessão isolada do navegador ao concluir o teste
agent-browser --session "$MODULO" close
# Fechar a sessão isolada do navegador ao concluir o fluxo daquele contexto
agent-browser --session "${MODULO}_${CONTEXTO}" close
```
---
@ -119,23 +134,25 @@ agent-browser --session "$MODULO" close
## Boas Práticas e Proibições
### Proibido ❌
- **Proibido executar sem a flag `--session <modulo>`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada.
- **Proibido executar sem a flag `--session <modulo>_<contexto?>`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada.
- **Proibido misturar acessos com perfis diferentes na mesma sessão genérica sem contexto** (ex: logar como operador interno e depois testar fluxo de cliente ou anônimo na mesma sessão, causando mistura de tokens).
- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`.
- **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`).
- **Proibido navegar para URLs desconhecidas** ou inventadas pela IA fora do escopo aprovado do teste.
- **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <modulo> close`).
- **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <modulo>_<contexto?> close`).
### Permitido e Recomendado ✅
- Manter sessões persistentes quando necessário via `--session <modulo> --restore`.
- Utilizar sub-isolamento determinístico (`<modulo-id>-<slug-ou-pid>`) caso múltiplos testes do mesmo módulo ocorram simultaneamente no mesmo host.
- Usar `agent-browser --session <modulo> screenshot --annotate` para inspecionar layouts complexos com visão computacional.
- Manter sessões persistentes por contexto quando necessário via `--session <modulo>_<contexto> --restore`.
- Utilizar sub-isolamento determinístico (`<modulo>_<contexto>_<slug-ou-pid>`) caso múltiplos testes do mesmo contexto ocorram simultaneamente no mesmo host.
- Usar `agent-browser --session <modulo>_<contexto> screenshot --annotate` para inspecionar layouts complexos com visão computacional.
- Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`.
---
## Impacto
- **Isolamento e Concorrência**: Múltiplos agentes ou módulos rodando testes E2E simultâneos não conflitam de abas nem fecham janelas alheias.
- **Isolamento de Tokens e Cookies**: Evita vazamento de credenciais e estados de autenticação entre acessos de operador interno, cliente corporativo, cidadão e visitante anônimo.
- **Isolamento e Concorrência**: Múltiplos agentes ou testes E2E simultâneos não conflitam de abas nem fecham janelas alheias.
- **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real.
- **Eficiência de tokens**: A árvore de acessibilidade reduz o consumo de contexto em até 90% comparado a inspeções de DOM HTML bruto.
- **Confiabilidade**: Interações determinísticas por `@ref` eliminam fragilidade de seletores CSS dinâmicos.
@ -148,4 +165,3 @@ agent-browser --session "$MODULO" close
- Skill associada: `skills/testar-interface-agent-browser/SKILL.md`
- Rule associada: `rules/identidade-modulo.md`
- Ferramentas CLI: `.agent/TOOLS`