121 lines
5.6 KiB
Markdown
121 lines
5.6 KiB
Markdown
# Instruções Base para IA – Projetos React
|
||
|
||
Instruções genéricas de desenvolvimento React, etapas de workflow e uso de agentes. **Contexto específico do projeto** (objetivo, URLs, ambientes) está em **`.agent/project/PROJECT_CONTEXT.md`** — consulte-o sempre que necessário.
|
||
|
||
---
|
||
|
||
## Regra primordial – Ambiente obrigatório
|
||
|
||
- Todo ajuste deve ser feito em um **ambiente** explícito (ex.: `financeiro-cnab`, `rh`, `gr`, `prafrot`).
|
||
- **Se o ambiente não for informado**: **Pergunte** em qual ambiente a alteração será feita **antes** de realizar qualquer mudança. Isso evita erros e mantém o isolamento entre módulos.
|
||
|
||
---
|
||
|
||
## Etapas de Desenvolvimento
|
||
|
||
### Etapa 1 – Construção e validação lógica
|
||
|
||
1. **Estudo**: Pesquise a fundo o que foi solicitado (materiais extras + código a ser alterado). Use os **agentes** (e o orquestrador) para aumentar a precisão (ex.: `BrowserValidationAgent`, `DataIntegrityAgent` para formulários/APIs).
|
||
2. **Implementação**: Desenvolva o solicitado seguindo os padrões desta base e do projeto.
|
||
3. **Testes pesados**: Valide que o código funciona em termos lógicos:
|
||
- Build sobe sem erros (`npm run build`).
|
||
- Nenhum componente com erros (lint, tipos se houver).
|
||
- Use agentes para testes automatizados (ex.: `AgentOrchestrator.validateBuild`, `validateComponent`).
|
||
|
||
### Etapa 2 – Validação visual e usabilidade
|
||
|
||
1. **Condição**: Pergunte ao usuário se as implementações já estão em ambiente de desenvolvimento.
|
||
2. **Se sim**: Solicite **URL** e **acesso** (credenciais) para testes reais.
|
||
3. **Ações**: Execute testes de usabilidade no que foi construído (fluxos, formulários, respostas da API). Use agentes (ex.: `BrowserValidationAgent`, `UIAdaptationAgent`) conforme os respectivos `*.md` em `.agent/agents/`.
|
||
|
||
---
|
||
|
||
## Uso de agentes
|
||
|
||
- Sempre que relevante, **leia os `.md` em `.agent/agents/`** e, se alguma **condicional** de um agente se aplicar à tarefa, **utilize esse agente** (ou o orquestrador) no fluxo.
|
||
- O **Documentation Agent** deve ser chamado **toda vez que algo for feito no projeto**, além de quando o usuário solicitar, para manter a documentação atualizada.
|
||
|
||
---
|
||
|
||
## Contexto técnico essencial
|
||
|
||
### Arquitetura
|
||
|
||
- **Framework**: React 18+ com Vite.
|
||
- **Linguagem**: JavaScript (ES6+).
|
||
- **Estilização**: Tailwind CSS (mobile-first, design system atômico).
|
||
- **UI**: Shadcn UI (Radix UI + Lucide).
|
||
- **Arquitetura**: Modular (encapsulamento por features).
|
||
- **Estado**: Zustand (global) + React Context (por módulo).
|
||
- **Padrão**: Domain-Driven Feature Folders em `src/features/`.
|
||
|
||
### Estrutura de pastas
|
||
|
||
```
|
||
src/
|
||
├── components/
|
||
│ ├── ui/ # Shadcn (NUNCA editar manualmente)
|
||
│ └── shared/ # Componentes transversais (StatCard, PageHeader, etc.)
|
||
├── features/ # Domínios de negócio (uma pasta por feature)
|
||
├── hooks/ # Hooks globais (useTheme, useAuth, etc.)
|
||
├── services/ # Integrações com API (Axios / React Query)
|
||
└── utils/ # Formatadores e validadores
|
||
```
|
||
|
||
### Padrões de desenvolvimento
|
||
|
||
1. **Componentes funcionais** (obrigatório): use apenas componentes funcionais.
|
||
2. **Hooks para lógica**: extraia lógica de negócio em hooks (`useX`).
|
||
3. **JSDoc**: use JSDoc para documentar tipos e contratos quando fizer sentido.
|
||
|
||
### Ambientes e isolamento
|
||
|
||
- **Ambiente**: ecossistema isolado (ex.: Financeiro, RH, Frota) com Sidebar, Header e conjunto de telas.
|
||
- **Isolamento**: ao ajustar um ambiente, **nunca** altere componentes internos de outro.
|
||
- **Componentes**: os específicos de um ambiente ficam em `src/features/[ambiente]/components/`.
|
||
- **Shared**: use `src/components/shared` apenas para elementos realmente universais. Se uma mudança no shared puder quebrar outro ambiente, use cópia local ou variantes/props.
|
||
|
||
### Padrão dual-version (componentes complexos)
|
||
|
||
```
|
||
src/features/[feature]/components/[NomeComponente]/
|
||
├── index.js # Entry point (exporta produção por padrão)
|
||
├── [Componente].jsx # Produção (limpo, funcional)
|
||
└── [Componente].debug.jsx # Debug (wrapper com controles e mocks)
|
||
```
|
||
|
||
### Camada de dados (Axios)
|
||
|
||
- Use a instância em `src/services/api.js`.
|
||
- Cada feature tem seu `[feature]Service.js` encapsulando chamadas à API.
|
||
- Faça o mapeamento dos dados da API nos Services; os componentes não devem conhecer a estrutura bruta.
|
||
- Use `try/catch`, interceptores para 401 e erros globais, e feedback via Toasts/alertas.
|
||
|
||
### Performance
|
||
|
||
- Code splitting com `React.lazy()` e `Suspense` nas rotas principais.
|
||
- `useMemo` e `useCallback` em componentes pesados (tabelas, gráficos).
|
||
- Minimize dependências pesadas; prefira Shadcn e soluções nativas.
|
||
- Ícones vetoriais (Lucide) e imagens otimizadas.
|
||
|
||
### O que nunca fazer
|
||
|
||
1. Importar componentes privados de um ambiente em outro.
|
||
2. Criar lógica de negócio global específica de um único módulo.
|
||
3. Ignorar o bundle size ao adicionar dependências.
|
||
4. Criar componentes com mais de 200 linhas.
|
||
|
||
### Sempre fazer
|
||
|
||
1. Verificar componentes existentes no Shadcn antes de criar novos.
|
||
2. Encapsular lógica em `features/`.
|
||
3. Usar `index.js` por feature para expor apenas o necessário (Public API).
|
||
4. Isolar o ambiente em desenvolvimento.
|
||
5. Comentar em português quando explicar isolamento ou regras importantes.
|
||
6. Validar performance após mudanças grandes.
|
||
7. Usar Tailwind para estilização.
|
||
|
||
---
|
||
|
||
**IMPORTANTE**: Esta base é a referência para padrões de código. O contexto do projeto (URLs, credenciais, documentação por ambiente) está em **`.agent/project/PROJECT_CONTEXT.md`**.
|