teste
/
testes
Template
2
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects 1 Releases Wiki Activity
testes/.agent/instructions/CORE_INSTRUCTIONS.md

5.6 KiB
Raw Blame History

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.