261 lines
7.4 KiB
Markdown
261 lines
7.4 KiB
Markdown
# 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.
|