# 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`**.