bright-y/prototype-maintenance

Manutenção de Protótipo

Use esta skill para tornar um protótipo existente mais fácil de modificar ao longo de muitas rodadas de iteração de produto.

O objetivo não é redesenhar o produto. Preserve o comportamento atual e a direção visual, melhorando a facilidade de manutenção, a propriedade dos arquivos e a velocidade de validação.

Escopo e Entrega

• Use esta skill para iteração estrutural contínua e mapeamento de propriedade em um protótipo existente. Para divisão ou empacotamento estático pela primeira vez, use static-prototype-splitter quando disponível; não é uma dependência obrigatória.
• Uma pequena solicitação de cópia, layout ou comportamento não requer uma reformulação completa do diretório. Divida apenas as responsabilidades relevantes para a solicitação.
• Mantenha o nome do arquivo de entrada existente, framework, modelo de script e fluxo de trabalho de visualização. O layout app.html abaixo é um exemplo, não um requisito de renomeação.
• Siga as regras de autorização do usuário para substituição de arquivos, configuração, dependências, acesso à rede, servidores locais e dados armazenados. Esta skill não concede essas permissões.

Quando Acionar

Acione esta skill quando o usuário pedir para:

• Melhorar a velocidade de modificação futura do protótipo.
• Dividir JS por página, componente, campo, modal, store ou camada de dados.
• Dividir CSS por escopos: base, layout, página, componente, modal e campo.
• Separar dados mock, dados de semente (seed), esquemas e lógica de estado/store.
• Criar ou atualizar um README de manutenção do protótipo.
• Criar ou atualizar um CHANGE-MAP que mapeie futuras solicitações para arquivos.
• Continuar otimizando um protótipo interativo existente.
• Fazer uma visualização combinada e arquivos divididos permanecerem mantíveis juntos.
• Explicar onde uma futura alteração no protótipo deve ser feita.

Princípios Padrão

• Siga o idioma do usuário e a terminologia existente do protótipo.
• Leia a entrada atual e as referências de script ativas antes de editar.
• Mantenha o design visual original e a intenção de interação, a menos que o usuário peça um redesenho.
• Não reescreva tudo em um framework, a menos que explicitamente solicitado.
• Evite uma segunda implementação divergente. A visualização combinada deve carregar módulos compartilhados/divididos ou ser gerada a partir deles.
• Mantenha as mudanças focadas na facilidade de manutenção e no comportamento do produto solicitado.
• A divisão não está completa quando novos arquivos são meramente adicionados. Cada divisão também deve reduzir a responsabilidade do arquivo antigo para que futuras edições tenham um proprietário óbvio.
• Mantenha alterações não relacionadas intactas e preserve os arquivos originais de entrada e os substituídos. Foque as edições autorizadas na implementação ativa; não exclua arquivos legados ou substitua documentos protegidos sem aprovação.
• Após as alterações, verifique a sintaxe e a interação principal da visualização quando for prático.

Estrutura Recomendada

Adapte os nomes ao projeto, mas prefira esta forma para protótipos interativos estáticos:

prototype/
├── app.html
├── README-prototype.md
├── CHANGE-MAP.md
├── assets/
│   ├── css/
│   │   ├── base.css
│   │   ├── layout.css
│   │   ├── components.css
│   │   ├── modals.css
│   │   ├── fields.css
│   │   └── pages/
│   │       ├── home.css
│   │       ├── editor.css
│   │       └── fill.css
│   └── js/
│       └── app/
│           ├── core.js
│           ├── runtime.js
│           ├── pages/
│           ├── components/
│           ├── fields/
│           ├── modals/
│           ├── data/
│           ├── store/
│           └── utils/
└── pages/
    └── ...

Use nomes equivalentes quando o domínio do protótipo for diferente. O importante é a divisão de responsabilidades.

Para protótipos pequenos, uma estrutura mais plana é aceitável. Para protótipos que mudam com frequência, prefira a estrutura de diretórios acima para que cada solicitação futura seja mapeada para um arquivo pequeno.

Responsabilidades das Camadas

Camada de Entrada

Mantenha a entrada de visualização combinada atual; app.html é o nome de exemplo usado abaixo.

Deve conter:

• Moldura de dispositivo ou shell de visualização, se houver.
• Container raiz.
• Links CSS.
• Referências de script ordenadas.

Não deve conter a maioria da lógica de negócios.

Camada de Página

Use arquivos de página para renderização de página e layout específico da página:

• Página inicial/lista/pesquisa/abas.
• Página do editor/criação/edição.
• Página de preenchimento/visualização/envio/detalhes.
• Páginas de login/registro/onboarding.
• Páginas de configurações/conta.

Quando o usuário pedir para alterar o layout ou o texto de uma página, comece aqui.

Se um arquivo de página contém múltiplas subvisualizações editadas com frequência, divida-o novamente. Exemplo:

pages/home/
├── index.js
├── search.js
├── my-forms.js
└── submitted.js

Camada de Campo ou Componente

Use arquivos de campo/componente para blocos de UI repetidos:

• Rótulos de tipo de campo.
• Valores padrão de campo.
• Visualização de campo no editor.
• Controles de página de preenchimento.
• Renderizadores de upload/imagem/arquivo/rádio/checkbox/OCR/data.

Quando o usuário pedir para alterar um tipo de elemento, evite pesquisar todo o aplicativo primeiro. Comece pelos arquivos de configuração e renderização do campo.

Quando um protótipo tem muitos controles de formulário ou cartões repetidos, prefira registros (registries):

fields/
├── registry.js
├── text.js
├── image.js
├── file.js
├── options.js
└── ocr.js

Camada de Modal

Use arquivos de modal para:

• Folha de configurações de campo.
• Folha do seletor de tipo.
• Gaveta de classificação.
• Diálogos de confirmação.
• Folha de biblioteca de adicionar elemento.

Mantenha o estado do modal local quando possível e confirme os dados apenas após ações de confirmação.

Camada de Dados

Separe os dados do comportamento da store.

Use data/ para:

• Templates mock.
• Listas de indústrias/categorias.
• Definições de tipo de campo.
• Usuários demo e exemplos.
• Registros de semente (seed) e fixtures.

Use store/ para:

• Chaves de armazenamento local.
• Salvar/excluir/atualizar formulário.
• Salvar/excluir/atualizar registro de envio.
• Normalização e migrações de dados.

Não misture regras de armazenamento nos renderizadores de página, a menos que o protótipo seja muito pequeno.

Quando dados locais existentes podem já existir, preserve suas chaves e edições do usuário. Adicione apenas registros de semente ausentes por IDs estáveis e torne a semeadura idempotente; não sobrescreva registros editados, duplique itens ou redefina o armazenamento local no recarregamento. Trate migrações de esquema como uma operação separada e autorizada, com um caminho de recuperação documentado.

Camada CSS

Divida o CSS por propriedade, não apenas por tamanho:

• base.css: variáveis, reset, tipografia.
• layout.css: shell, moldura do dispositivo, container da página, primitivas de grid.
• components.css: botões, inputs, cartões, abas, chips.
• modals.css: folhas, gavetas, diálogos de confirmação, toast.
• fields.css: controles de campo e visualizações de elemento de formulário.
• pages/*.css: layout específico de página e exceções.

Se um seletor é reutilizado entre páginas, mantenha-o em components ou fields. Se é específico de uma página, mova-o para o CSS dessa página.

Camada de Mapa de Mudanças (Change Map)

Adicione CHANGE-MAP.md para protótipos que devem receber muitas rodadas de edições.

Deve mapear solicitações comuns do usuário diretamente para arquivos:

# Mapa de Mudanças

## Páginas
- Página inicial: assets/js/app/pages/home/index.js
- Página de template: assets/js/app/pages/templates/index.js
- Editor de formulário: assets/js/app/pages/editor/index.js

## Campos
- Campo de upload de imagem: assets/js/app/fields/image.js
- Campo de upload de arquivo: assets/js/app/fields/file.js
- Campos de rádio/checkbox: assets/js/app/fields/options.js

## Modais
- Modal de configurações de campo: assets/js/app/modals/field-settings.js
- Gaveta de classificação: assets/js/app/modals/sort.js

## Dados
- Dados de template: assets/js/app/data/templates.js
- Categorias de indústria: assets/js/app/data/industries.js

## Estilos
- Estilos da página de template: assets/css/pages/templates.css
- Estilos de campo: assets/css/fields.css

Mantenha CHANGE-MAP curto. É um índice de edição, não documentação do produto.

Camada de Runtime

Use arquivos de runtime para:

• Despacho de roteador/renderização.
• Delegação de eventos.
• Manipulação de gestos.
• Despacho de ações.
• Inicialização.

Se o runtime se tornar grande, divida por tipo de interação, mas mantenha um ponto de entrada claro.

README de Manutenção

Quando solicitado, adicione ou atualize README-prototype.md na raiz do protótipo.

Inclua:

• Total da visualização de entrada.
• URL de visualização local e portas reservadas, se houver.
• Mapa página-para-arquivo.
• Mapa campo/componente-para-arquivo.
• Mapa modal-para-arquivo.
• Localização da camada de dados.
• Localização da camada CSS.
• Localização do CHANGE-MAP.
• Como atualizar e validar após as alterações.
• Exemplos comuns de futuras alterações, como "alterar campo de upload de imagem" ou "alterar página de envio de formulário".

Mantenha conciso e útil. É para humanos que mantêm o protótipo, não um diário de desenvolvimento longo.

Fluxo de Trabalho

1. Inspecione os arquivos de entrada ativos.

   • Use rg --files, grep, e leituras direcionadas.
   • Confirme quais scripts são realmente carregados pela visualização combinada.
   • Não presuma que arquivos divididos existentes estão ativos.

2. Identifique a propriedade atual.

   • Renderizadores de página.
   • Renderizadores/configuração de campo.
   • Modais/gavetas.
   • Helpers de store/dados.
   • Manipuladores de runtime/eventos.

3. Divida com cuidado.

   • Prefira extração mecânica primeiro quando preservar o comportamento é importante.
   • Mantenha a ordem de carregamento dos scripts explícita em app.html.
   • Evite alterar o comportamento durante a divisão, a menos que o usuário também tenha solicitado alterações de comportamento.
   • Após extrair um módulo, remova ou reduza a responsabilidade correspondente do arquivo antigo. Não deixe dois proprietários ativos para a mesma página, componente, modal, conjunto de dados ou seletor CSS.
   • Deixe arquivos combinados legados não utilizados, em vez de excluí-los, a menos que o usuário confirme a exclusão.
   • Preserve o modelo existente de script clássico ou módulo ES. Verifique a ordem de carregamento, exportações e manipuladores de eventos inline após mover funções.
   • Torne as responsabilidades de montagem/desmontagem da visualização explícitas. Remova listeners e timers obsoletos ao sair de uma visualização para que a navegação repetida não duplique ações.

4. Divida dados quando os dados estão crescendo.

   • Mova grandes dados mock para fora dos renderizadores de página e arquivos de store.
   • Mantenha as fixtures de semente determinísticas e fáceis de examinar.
   • Mescle novos dados de semente nos dados locais existentes quando possível.
   • Se os dados são movidos para data/, faça com que os arquivos de store/estado consumam esses dados em vez de manter uma cópia ativa duplicada.

5. Divida CSS quando as mudanças visuais estão se tornando lentas.

   • Comece com base/layout/components/pages.
   • Mova seletores específicos de página para o CSS da página.
   • Mova controles reutilizáveis para o CSS de components ou fields.
   • Após mover seletores, remova seletores ativos duplicados da folha de estilo global anterior, a menos que sejam intencionalmente retidos como estilos de componente compartilhados.
   • Preserve a ordem em cascata e os breakpoints responsivos; baseie novamente os caminhos CSS url(...), fontes e importações relativos ao novo local do arquivo.

6. Atualize ou crie README e CHANGE-MAP.

   • Documente a estrutura ativa final.
   • Deixe claro qual arquivo editar para futuras solicitações comuns.
   • Inclua URL de visualização local, portas reservadas e instruções de cache-busting quando relevante.

7. Verifique.

   • Verifique recursivamente os arquivos JavaScript realmente pertencentes ao protótipo, incluindo arquivos de página/componente aninhados. Quando Python e Node já estão disponíveis, este exemplo verifica .js, .mjs e .cjs abaixo de assets/js; adapte a raiz ao projeto. Não instale runtimes apenas para executá-lo.

     python3 - <<'PY_CHECK'
     from pathlib import Path
     import subprocess
     import sys
     
     root = Path("assets/js")
     files = sorted(p for p in root.rglob("*")
                    if p.is_file() and p.suffix in {".js", ".mjs", ".cjs"}
                    and not {"node_modules", "vendor", ".git"}.intersection(p.parts))
     if not files:
         sys.exit("Nenhum arquivo JavaScript encontrado; verifique a raiz da verificação.")
     failed = False
     for path in files:
         failed |= subprocess.run(["node", "--check", str(path)]).returncode != 0
     sys.exit(1 if failed else 0)
     PY_CHECK
     

   • Para projetos com framework ou um modo de módulo diferente, use as verificações existentes do projeto. Uma verificação de sintaxe não prova o comportamento do navegador.
   • Abra a visualização combinada.
   • Compare o comportamento afetado com a linha de base, incluindo navegação para frente/trás, revisitar a visualização editada, confirmar/cancelar em modais e estado salvo após atualização, quando aplicável.
   • Verifique os erros do console do navegador quando for prático.

Regras de Granularidade de Divisão

Use estas regras para evitar tanto a subdivisão quanto a superdivisão:

• Se um arquivo é editado repetidamente para solicitações não relacionadas, divida-o.
• Se uma página contém múltiplas subvisualizações que mudam independentemente, divida as subvisualizações.
• Se dados mock ocupam mais espaço do que a lógica ao seu redor, mova-os para data/.
• Considere fields/ quando vários tipos de campos/controles mudam independentemente; não divida apenas para cumprir uma contagem.
• Considere modals/ quando diálogos ou gavetas têm necessidades separadas de estado ou manutenção.
• Se mudanças CSS exigem pesquisar uma grande folha de estilo global, divida por página e componente.
• Se um arquivo é estável e raramente editado, não o divida apenas por estética.

Ajudantes de Validação

Prefira validação simples e sem dependências para protótipos estáticos:

• Use node --check para sintaxe JS.
• Para cache-busting, substitua por um valor real, como app.html?t=20261109-153000; Date.now() digitado literalmente em uma URL é uma string fixa. Uma consulta HTML sozinha não atualiza JS/CSS em cache separadamente, então use controles de cache do navegador ou a estratégia de versionamento de ativos existente quando necessário.
• Mantenha a porta de visualização local estável quando o usuário tiver escolhido uma.
• Verifique a interação alterada no navegador após refatorações estruturais.
• Abertura direta de arquivo é aceitável para páginas estáticas compatíveis. Fragmentos buscados e módulos ES do navegador geralmente exigem HTTP; documente o modo de abertura e reutilize o servidor de visualização existente quando disponível. Iniciar um novo servidor segue as regras de autorização do usuário.

Estilo de Resposta

Ao finalizar, informe ao usuário:

• O que foi dividido ou documentado.
• O arquivo de entrada ativo.
• Os caminhos de arquivo mais importantes.
• Se README-prototype.md ou CHANGE-MAP.md foi criado ou atualizado.
• Qual verificação foi concluída.
• Quaisquer arquivos legados deixados intencionalmente.

Mantenha a resposta final curta e prática.