Plano de modernização de aplicações

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Objetivo

​

Princípios

• Preserve a arquitetura atual, a menos que um limite esteja comprovadamente causando retrabalho, custo de desempenho ou bugs visíveis ao usuário.
• Prefira o menor patch correto para cada problema, depois repita.
• Separe correções obrigatórias de polimentos opcionais para que mantenedores possam entregar trabalho de alto valor sem esperar por decisões subjetivas.
• Mantenha o comportamento voltado a Plugin documentado e compatível com versões anteriores.
• Verifique o comportamento publicado, os contratos de dependência e os testes antes de afirmar que uma regressão foi corrigida.
• Melhore primeiro o caminho principal do usuário: onboarding, autenticação, chat, configuração de provedor, gerenciamento de Plugin e diagnósticos.

​

Fase 1: Auditoria de linha de base

• Identifique os principais fluxos de trabalho do usuário e as superfícies de código responsáveis por eles.
• Liste recursos mortos, configurações duplicadas, estados de erro pouco claros e caminhos de renderização caros.
• Capture os comandos de validação atuais para cada superfície.
• Marque problemas como obrigatórios, recomendados ou opcionais.
• Documente bloqueadores conhecidos que precisam de revisão de proprietário, especialmente mudanças de API, segurança, release e contrato de Plugin.

• Uma lista de problemas com referências de arquivo relativas à raiz do repo.
• Cada problema tem severidade, superfície proprietária, impacto esperado ao usuário e um caminho de validação proposto.
• Nenhum item especulativo de limpeza é misturado às correções obrigatórias.

​

Fase 2: Limpeza de produto e UX

• Ajuste o texto de onboarding e estados vazios em torno de autenticação de modelo, status do Gateway e configuração de Plugin.
• Remova ou desabilite recursos mortos quando nenhuma ação for possível.
• Mantenha ações importantes visíveis em larguras responsivas, em vez de escondê-las atrás de suposições frágeis de layout.
• Consolide linguagem de status repetida para que erros tenham uma única fonte de verdade.
• Adicione divulgação progressiva para configurações avançadas, mantendo a configuração principal rápida.

• Caminho feliz manual para configuração de primeira execução e inicialização de usuário existente.
• Testes focados para qualquer lógica de roteamento, persistência de configuração ou derivação de status.
• Capturas de tela do navegador para superfícies responsivas alteradas.

​

Fase 3: Ajuste da arquitetura de frontend

• Mova transformações repetidas de estado de UI para helpers tipados e estreitos.
• Mantenha separadas as responsabilidades de busca de dados, persistência e apresentação.
• Prefira hooks, stores e padrões de componentes existentes a novas abstrações.
• Divida componentes grandes demais apenas quando isso reduzir acoplamento ou esclarecer testes.
• Evite introduzir estado global amplo para interações locais de painel.

• Não altere comportamento público como efeito colateral de divisão de arquivos.
• Mantenha intacto o comportamento de acessibilidade para menus, diálogos, abas e navegação por teclado.
• Verifique se estados de carregamento, vazio, erro e otimistas ainda renderizam.

​

Fase 4: Desempenho e confiabilidade

• Meça custos de inicialização, transição de rota, listas grandes e transcrições de chat.
• Substitua dados derivados caros e repetidos por seletores memoizados ou helpers em cache quando o profiling comprovar valor.
• Reduza varreduras evitáveis de rede ou sistema de arquivos em caminhos quentes.
• Mantenha ordenação determinística para entradas de prompt, registro, arquivo, Plugin e rede antes da construção do payload do modelo.
• Adicione testes leves de regressão para helpers quentes e limites de contrato.

• Cada mudança de desempenho registra linha de base, impacto esperado, impacto real e lacuna restante.
• Nenhum patch de desempenho é entregue somente por intuição quando medição barata está disponível.

​

Fase 5: Endurecimento de tipos, contratos e testes

• Substitua strings soltas em runtime por uniões discriminadas ou listas fechadas de códigos.
• Valide entradas externas com helpers de schema existentes ou zod.
• Adicione testes de contrato em torno de manifestos de Plugin, catálogos de provedores, mensagens de protocolo do Gateway e comportamento de migração de configuração.
• Mantenha caminhos de compatibilidade em fluxos de doctor ou reparo, em vez de migrações ocultas em tempo de inicialização.
• Evite acoplamento apenas de teste a detalhes internos de Plugin; use fachadas do SDK e barrels documentados.

• pnpm check:changed
• Testes direcionados para cada limite alterado.
• pnpm build quando limites lazy, empacotamento ou superfícies publicadas mudarem.

​

Fase 6: Documentação e prontidão para release

• Atualize a documentação com mudanças de comportamento, API, configuração, onboarding ou Plugin.
• Adicione entradas de changelog somente para mudanças visíveis ao usuário.
• Mantenha a terminologia de Plugin voltada ao usuário; use nomes internos de pacote somente quando necessário para contribuidores.
• Confirme que as instruções de release e instalação ainda correspondem à superfície atual de comandos.

• Documentação relevante é atualizada na mesma branch das mudanças de comportamento.
• Verificações de documentação gerada ou drift de API passam quando tocadas.
• O handoff nomeia qualquer validação ignorada e por que ela foi ignorada.

​

Primeira fatia recomendada

• Audite superfícies de configuração de primeira execução, prontidão de autenticação de provedor, status do Gateway e configuração de Plugin.
• Remova ações mortas e esclareça estados de falha.
• Adicione ou atualize testes focados para derivação de status e persistência de configuração.
• Execute pnpm check:changed.

​

Atualização da skill de frontend

# Frontend Delivery Standards

Use this skill when implementing or reviewing user-facing React, Next.js,
desktop webview, or app UI work.

## Operating rules

- Start from the existing product workflow and code conventions.
- Prefer the smallest correct patch that improves the current user path.
- Separate required fixes from optional polish in the handoff.
- Do not build marketing pages when the request is for an application surface.
- Keep actions visible and usable across supported viewport sizes.
- Remove dead affordances instead of leaving controls that cannot act.
- Preserve loading, empty, error, success, and permission states.
- Use existing design-system components, hooks, stores, and icons before adding
  new primitives.

## Implementation checklist

1. Identify the primary user task and the component or route that owns it.
2. Read the local component patterns before editing.
3. Patch the narrowest surface that solves the issue.
4. Add responsive constraints for fixed-format controls, toolbars, grids, and
   counters so text and hover states cannot resize the layout unexpectedly.
5. Keep data loading, state derivation, and rendering responsibilities clear.
6. Add tests when logic, persistence, routing, permissions, or shared helpers
   change.
7. Verify the main happy path and the most relevant edge case.

## Visual quality gates

- Text must fit inside its container on mobile and desktop.
- Toolbars may wrap, but controls must remain reachable.
- Buttons should use familiar icons when the icon is clearer than text.
- Cards should be used for repeated items, modals, and framed tools, not for
  every page section.
- Avoid one-note color palettes and decorative backgrounds that compete with
  operational content.
- Dense product surfaces should optimize for scanning, comparison, and repeated
  use.

## Handoff format

Report:

- What changed.
- What user behavior changed.
- Required validation that passed.
- Any validation skipped and the concrete reason.
- Optional follow-up work, clearly separated from required fixes.