SeConectai_Web/Conhecimento/AGENTS.md

Vibe Frontend Agents — Orquestrador Principal

Este arquivo é a fonte central de regras para qualquer IA/agente que trabalhe neste projeto. Ele deve ser lido antes de qualquer alteração. Os arquivos em agents/, skills/, prompts/ e checklists/ complementam estas instruções e devem ser carregados conforme a tarefa.

---

1. Missão

Melhorar ou construir interfaces sem comprometer regras de negócio, integrações, autenticação, segurança, dados, contratos de API ou estabilidade do sistema.

O objetivo não é apenas “deixar bonito”. O objetivo é produzir uma interface:

• clara;
• coerente;
• acessível;
• responsiva;
• rápida;
• reutilizável;
• testável;
• previsível;
• simples de manter;
• segura para evoluir.

---

2. Regra de ouro: analisar antes de modificar

Antes de editar qualquer arquivo de um projeto existente:

1. Identifique a stack, framework, gerenciador de pacotes e processo de build.
2. Mapeie a estrutura de pastas e responsabilidades principais.
3. Identifique rotas, layouts, componentes, hooks/composables, stores, serviços e estilos.
4. Localize autenticação, autorização, chamadas de API, contratos de dados e integrações.
5. Verifique se existe design system ou biblioteca de componentes já adotada.
6. Verifique lint, typecheck, testes, Storybook, E2E e comandos de validação.
7. Entenda exatamente o escopo solicitado pelo usuário.
8. Determine quais agentes especializados realmente precisam participar.
9. Só então altere o código.

Nunca reescreva grandes partes do projeto apenas porque uma solução diferente parece mais elegante.

---

3. Proteção obrigatória do sistema

Quando a solicitação for de frontend, UI, UX, responsividade, acessibilidade, SEO ou performance, NÃO altere os itens abaixo sem necessidade técnica real e autorização explícita:

• banco de dados;
• migrations;
• seeds;
• entidades persistidas;
• schemas de banco;
• contratos públicos de API;
• endpoints;
• controllers do backend;
• services de regra de negócio;
• autenticação;
• autorização;
• roles e permissões;
• tokens, sessões e cookies de segurança;
• webhooks;
• filas;
• workers;
• integrações externas;
• configuração de infraestrutura;
• deploy;
• Docker/Compose/Kubernetes;
• DNS;
• variáveis de ambiente reais;
• segredos;
• CI/CD.

Exceção

Se a alteração de frontend exigir mudança em uma dessas áreas:

1. não faça a alteração silenciosamente;
2. explique a dependência;
3. proponha a menor mudança possível;
4. preserve compatibilidade retroativa quando viável;
5. só implemente se a tarefa autorizar.

---

4. Arquivos que devem ser carregados por tipo de tarefa

Toda tarefa em projeto existente

Leia primeiro:

• agents/00-project-analyzer.md
• agents/01-codebase-guardian.md

UI/UX ou melhoria visual

Leia:

• agents/02-ui-ux.md
• agents/03-design-system.md
• agents/04-frontend.md

Formulários, cadastro, edição, filtros ou autenticação

Leia também:

• agents/05-forms.md

Tabelas, painéis, ERP, CRM, SaaS administrativo

Leia também:

• agents/06-dashboard.md

Site institucional, landing page, página comercial

Leia também:

• agents/07-landing-page.md
• agents/10-seo.md

Mobile/responsividade

Leia:

• agents/08-responsive.md

Acessibilidade

Leia:

• agents/09-accessibility.md

Performance

Leia:

• agents/11-performance.md

Revisão final

Leia sempre ao finalizar alteração relevante:

• agents/12-visual-qa.md
• agents/13-regression-check.md

---

5. Pipeline padrão

Fase A — Descoberta

1. Ler este AGENTS.md.
2. Ler 00-project-analyzer.md.
3. Ler 01-codebase-guardian.md.
4. Inspecionar o projeto.
5. Registrar stack, arquitetura, riscos e escopo.

Fase B — Planejamento

1. Classificar a tarefa.
2. Selecionar somente os agentes necessários.
3. Identificar componentes afetados.
4. Identificar dependências e riscos de regressão.
5. Elaborar um plano mínimo de mudança.

Fase C — Implementação

1. Reutilizar padrões existentes.
2. Alterar o menor número razoável de arquivos.
3. Preservar contratos existentes.
4. Tratar estados de UI.
5. Evitar duplicação.
6. Não adicionar dependências sem justificativa.

Fase D — Validação

1. Build.
2. Typecheck.
3. Lint.
4. Testes disponíveis.
5. Navegação principal.
6. Mobile e desktop.
7. Estados loading/erro/vazio/sucesso.
8. Acessibilidade básica.
9. Console sem erros relevantes.
10. Revisão visual.
11. Checagem de regressão.

Fase E — Entrega

Explique:

• o que foi alterado;
• por que foi alterado;
• arquivos principais envolvidos;
• validações executadas;
• riscos ou limitações restantes;
• sugestões opcionais, sem misturá-las ao escopo concluído.

---

6. Seleção inteligente de agentes

Não execute todos os especialistas mecanicamente.

Exemplos:

• Ajuste de espaçamento em um componente: analyzer + guardian + frontend + visual QA.
• Página de cadastro: analyzer + guardian + UI/UX + design system + frontend + forms + responsive + accessibility + regression.
• Dashboard: analyzer + guardian + UI/UX + design system + frontend + dashboard + responsive + accessibility + performance + regression.
• Landing page: analyzer + guardian + UI/UX + design system + frontend + landing page + responsive + accessibility + SEO + performance + visual QA.

---

7. Regras de implementação

Preserve o que já existe

• Não renomeie arquivos ou componentes sem benefício claro.
• Não troque framework, biblioteca ou padrão arquitetural sem solicitação.
• Não converta JS para TS, CSS para Tailwind, Redux para Zustand etc. como efeito colateral.
• Não faça “limpeza geral” fora do escopo.

Dependências

Antes de instalar uma dependência:

1. verifique se o projeto já oferece solução equivalente;
2. verifique se a plataforma/framework tem recurso nativo;
3. avalie custo de bundle e manutenção;
4. justifique a instalação.

Componentização

Crie componente quando houver pelo menos um destes motivos:

• reutilização real;
• responsabilidade visual/funcional clara;
• redução de complexidade;
• necessidade de teste isolado;
• padronização de comportamento.

Não crie componentes microscópicos sem ganho prático.

---

8. Estados obrigatórios de interface

Sempre que aplicável, considere:

• inicial;
• carregando;
• sucesso;
• vazio;
• erro;
• sem permissão;
• indisponível;
• ação em andamento;
• ação concluída;
• confirmação antes de ação destrutiva.

Nunca exiba uma tela quebrada apenas porque uma API retornou array vazio ou falhou.

---

9. Regras de dados

• Não invente métricas reais.
• Não fabrique dados de produção.
• Não altere valores financeiros, permissões ou status de negócio para fins visuais.
• Diferencie mock, fixture e dado real.
• Respeite locale, moeda, fuso e formatação existente.
• Não exponha secrets ou tokens no frontend.

---

10. Critério de pronto

Uma alteração só pode ser considerada concluída quando:

• atende exatamente ao pedido;
• funcionalidade existente continua funcionando;
• não alterou regra de negócio indevidamente;
• desktop e mobile foram considerados;
• estados relevantes foram tratados;
• acessibilidade básica foi verificada;
• build/typecheck/lint/testes aplicáveis passam, ou falhas preexistentes foram documentadas;
• não existem erros novos óbvios no console;
• o código segue padrões do projeto;
• o resultado é sustentável para manutenção.