Communitygithub.com

frontend-admin-architecture-skill

Skill do Codex para criar projetos de arquitetura de painel administrativo frontend estáveis com React ou Vue.

O que é frontend-admin-architecture-skill?

Este skill do Codex é especializado em criar ou normalizar projetos de sistemas de gerenciamento administrativo frontend, suportando React + TypeScript e Vue 3 + TypeScript. Ele orquestra a geração de documentos essenciais como `docs/architecture.md` e `AGENTS.md`, além de criar a estrutura básica do projeto quando solicitado. O skill segue um fluxo de trabalho em cinco etapas: confirmar o escopo e o framework, ler as referências de arquitetura correspondentes, escrever a documentação do projeto, criar a estrutura de diretórios e explicar o uso. Durante o processo, ele faz perguntas críticas ao usuário sobre estilo de UI, layout, autenticação e instalação de dependências, garantindo que o projeto resultante esteja alinhado com as escolhas do desenvolvedor. Ele também distingue claramente entre frameworks React e Vue, usando referências internas para garantir que apenas os recursos corretos sejam aplicados a cada projeto, e evita sobrecarga de construção, adicionando apenas o que é explicitamente solicitado.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add 728188325/frontend-admin-architecture-skill

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Habilidade de Arquitetura de Painel Administrativo Frontend

Esta habilidade é usada para criar ou normalizar sistemas de gerenciamento administrativo frontend, suportando:

  • React + TypeScript
  • Vue 3 + TypeScript

Ela é responsável por selecionar as especificações do framework correspondente, gerar docs/architecture.md e AGENTS.md no projeto de destino e, quando solicitado pelo usuário, criar a estrutura básica do projeto.

Recursos Internos

Leia os recursos correspondentes com base no framework escolhido pelo usuário e não escreva o conteúdo do outro framework no projeto de destino.

React:

  • references/react/architecture.md
  • assets/AGENTS.react.template.md

Vue:

  • references/vue/architecture.md
  • assets/AGENTS.vue.template.md

Documentos de governança de projeto genéricos:

  • assets/docs/ai-interaction.md
  • assets/docs/karpathy-guidelines.md
  • assets/docs/ui-style.md
  • assets/docs/ui-quality.md
  • assets/docs/design-tokens.md
  • assets/docs/code-style.md
  • assets/docs/security.md
  • assets/docs/comments.md
  • assets/docs/verification.md
  • assets/docs/git-commit.md
  • assets/docs/knowledge-capture.md

Fluxo de Trabalho Padrão

Etapa 1: Confirmar Escopo

Se o usuário não fornecer o caminho do projeto, pergunte primeiro pelo caminho.

Se o usuário não especificar o framework de destino, primeiro verifique se o caminho de destino já possui um projeto:

  • Se existir um package.json, leia as seções dependencies e devDependencies.
  • Se react ou react-dom estiverem presentes, identifique como React + TypeScript.
  • Se vue ou @vitejs/plugin-vue estiverem presentes, identifique como Vue 3 + TypeScript.
  • Se package.json não existir, verifique vite.config.* em busca de pistas sobre plugins de framework.
  • Se React e Vue aparecerem juntos, ou se não for possível determinar, pergunte ao usuário.

Quando precisar perguntar, use:

Por favor, selecione o framework do projeto:
1. React + TypeScript
2. Vue 3 + TypeScript

Se o usuário não especificar se deseja "apenas gerar documentação" ou "também criar a estrutura do projeto", confirme com uma pergunta curta.

Se o usuário quiser criar ou iniciar um projeto, você deve confirmar as seguintes decisões antes de criar arquivos, executar comandos de inicialização ou instalar dependências. A menos que o usuário diga explicitamente "configuração padrão", "usar configuração padrão", "não pergunte, use o padrão" ou expressão equivalente, não interprete termos como "novo projeto", "criar projeto", "criar na área de trabalho", "continuar" como adoção da configuração padrão.

Quando faltar seleção de estilo de UI do sistema, estilo de layout, autenticação de login ou instalação de dependências, pare a execução e use uma pergunta curta para cobrir as opções ausentes. O estilo de UI do sistema deve ser perguntado primeiro, mas o usuário pode escolher "Não especificar agora"; se o usuário não selecionar ou não escrever um estilo personalizado, não presuma um estilo visual específico.

  1. Selecione o estilo de UI do sistema. O estilo de UI do sistema descreve apenas a linguagem visual, densidade de informação e tom de interação, não é equivalente ao estilo de layout; se o usuário não selecionar agora, docs/ui-style.md permanecerá como pendente:
    • Clássico e Estável: fundo claro, cor principal de baixa saturação, tabelas e formulários claros, adequado para painéis corporativos genéricos.
    • Minimalista e Limpo: mais espaçamento, bordas e sombras mais contidas, adequado para SaaS leves e painéis de gerenciamento de baixa complexidade.
    • Intensivo em Dados: tabelas compactas, alta densidade de informação, decoração fraca, adequado para operações, relatórios, BI e painéis de gerenciamento de dados.
    • Tipo Workstation SaaS: sensação mais workspace, enfatiza visão geral, atalhos rápidos e alternância entre multi-inquilinos/multi-projetos, adequado para produtos B2B.
    • Escuro Tecnológico: fundo escuro, status de dados de alto contraste, toque tecnológico moderado, adequado para sistemas de monitoramento, segurança, operações e telas grandes.
    • Financeiro Rigoroso: cores contidas, tabelas fortes, status de risco e valores claros, adequado para painéis financeiros, de liquidação e gerenciamento de risco.
    • Governamental e Empresarial Padrão: tom azul e branco, hierarquia clara, cadeias de formulários e aprovação padronizadas, adequado para sistemas governamentais, de escritório e aprovação.
    • Tipo Gerenciamento de Conteúdo: prioriza pré-visualização de ativos, operações em lote, tags de status e fluxos de revisão, adequado para CMS, conteúdo e back-office de operações de marketing.
    • Tipo Ferramenta de Eficiência: enfatiza operações rápidas, painéis divididos, amigável ao teclado e eficiência de configuração, adequado para back-Office do tipo ferramenta ou configuração.
    • Tipo Portal Leve: navegação superior, entrada de módulos clara, baixa complexidade de página, adequado para sistemas internos com poucos módulos.
    • Personalizado: o usuário descreve o estilo visual desejado, produto de referência ou requisitos de design em linguagem natural.
    • Não especificar agora: não escrever um estilo específico, manter docs/ui-style.md pendente.
  2. Selecione o estilo de layout:
    • Layout Clássico de Painel: menu lateral + barra superior + área de conteúdo + guias. Adequado para menus com muitos níveis e painéis de gerenciamento tradicionais, como layout padrão.
    • Tipo Navegação Superior: navegação principal horizontal superior + área de conteúdo. Adequado para poucos módulos, níveis rasos e back-offices leves que desejam páginas mais amplas.
    • Tipo Navegação Mista: domínio de negócio superior + menu secundário lateral esquerdo + área de conteúdo. Adequado para back-offices com múltiplos domínios de negócio, como projetos com módulos de pedidos, finanças, sistema e conteúdo coexistentes.
    • Tipo Barra Estreita de Ícones: barra estreita de ícones à esquerda + menu expandido ou painel secundário + área de conteúdo. Adequado para back-offices do tipo ferramenta e SaaS moderno que desejam economizar espaço horizontal.
    • Tipo Workstation: barra de produtos superior + alternância de organização/projeto + menu lateral esquerdo recolhível + área de conteúdo. Adequado para sistemas B2B com multi-inquilinos, multi-projetos e alternância frequente de organização.
    • Não Presumir Layout: manter apenas roteamento básico e contêineres de página. Adequado para quando o layout for decidido posteriormente pelo negócio ou design.
  3. Deve incluir autenticação de login básica? Se ativado, a página de login deve seguir o estilo de UI do sistema selecionado; se o estilo de UI do sistema não for especificado, use o estilo neutro padrão da biblioteca de componentes de UI.
  4. Deve instalar dependências e executar a verificação imediatamente?
  5. Deve usar a configuração padrão? Sem estilo de UI do sistema presumido + layout de painel clássico + autenticação de login básica + não instalar dependências imediatamente.

Somente quando o usuário adotar explicitamente a configuração padrão, use estes valores padrão:

  • Gerenciador de pacotes: pnpm.
  • Autenticação de login: inclui estrutura de token de login básica por padrão.
  • Layout: inclui layout de painel clássico por padrão.
  • Estilo de UI do sistema: não presumido por padrão; docs/ui-style.md permanece pendente, a ser preenchido por requisitos de negócios ou design posteriores.
  • Instalação de dependências: não executar pnpm install, pnpm add, pnpm dev, pnpm lint, pnpm typecheck, pnpm build por padrão, apenas escrever as declarações de dependências, arquivos de projeto e comandos subsequentes.
  • Stack padrão React: Vite, React, TypeScript, Ant Design, React Router, Axios, TanStack Query, Zustand.
  • Stack padrão Vue: Vite, Vue 3, TypeScript, Composition API, <script setup lang="ts">, Vue Router, Pinia, Axios, Element Plus, VueUse.
  • Permissões, Mock, i18n, Gráficos, Monitoramento, Implantação, Geração de Código OpenAPI: não implementado por padrão, introduzir quando necessário.

Etapa 2: Ler as Especificações Correspondentes

Antes de escrever arquivos, leia o documento de arquitetura correspondente com base no framework:

  • React: leia references/react/architecture.md
  • Vue: leia references/vue/architecture.md

Use-o como base para:

  • Stack de tecnologia
  • Estrutura de diretórios
  • Limites dos módulos
  • Limites dos componentes compartilhados
  • Regras de posicionamento de API e tipos
  • Regras de gerenciamento de estado
  • Padrões de codificação
  • Ferramentas de qualidade de engenharia
  • Estratégia de teste

Etapa 3: Escrever a Documentação do Projeto

Crie ou atualize no projeto de destino:

docs/architecture.md
docs/ai-interaction.md
docs/karpathy-guidelines.md
docs/ui-style.md
docs/ui-quality.md
docs/design-tokens.md
docs/code-style.md
docs/security.md
docs/comments.md
docs/verification.md
docs/git-commit.md
docs/knowledge-capture.md
AGENTS.md

Ao escrever docs/architecture.md, descreva apenas as especificações de arquitetura que o desenvolvimento subsequente do projeto de destino deve seguir. Não escreva o fluxo de trabalho da habilidade, as perguntas feitas ao usuário ou o processo de decisão de inicialização na documentação do projeto de destino.

Ao escrever outros docs/*.md, use os documentos de governança genéricos em assets/docs/ como base. Eles são usados para descrever interação de IA, diretrizes Karpathy, registro de estilo de UI, limites de qualidade e criatividade de UI, tokens de design, estilo de código, segurança e dados, comentários, verificação, commits Git e sedimentação de regras. Exceto docs/ui-style.md, que precisa registrar o estilo de UI do sistema explicitamente selecionado ou personalizado pelo usuário, não escreva decisões temporárias de projetos de negócios específicos.

Se o usuário selecionar ou pular capacidades opcionais como autenticação de login básica, estilo de layout, etc., o docs/architecture.md gerado deve ser consistente com a seleção real:

  • Capacidades selecionadas: mantenha as regras de arquitetura correspondentes e os arquivos esperados.
  • Capacidades ignoradas: mantenha apenas uma descrição de limite, esclarecendo que a menos que requisitos futuros os introduzam, não crie diretórios e arquivos relacionados previamente.
  • Estilo de layout: escreva apenas os diretórios de layout, responsabilidades de componentes e limites de estado do layout selecionado atualmente; não escreva todos os candidatos a layout na documentação do projeto de destino, a menos que o usuário solicite explicitamente a manutenção da comparação de layouts.

Ao escrever docs/ui-style.md:

  • O usuário seleciona um dos dez estilos de UI do sistema interno: escreva o nome do estilo, cenários de aplicação e descrição correspondente.
  • O usuário seleciona personalizado: organize as palavras do usuário em requisitos claros de estilo de UI do sistema, evitando expandir para esquemas visuais que o usuário não confirmou.
  • O usuário seleciona não especificar agora, ou não fornece descrição personalizada: mantenha o estado pendente de assets/docs/ui-style.md.
  • Não escreva todos os candidatos de estilo de UI do sistema na documentação do projeto de destino, a menos que o usuário solicite explicitamente a manutenção da comparação.
  • Se uma página de login, esqueleto de layout, home page, página de lista básica ou página de status forem criados, essas interfaces devem ser visualmente baseadas no estilo de UI do sistema atual; quando o estilo de UI do sistema não for especificado, use o estilo neutro padrão da biblioteca de componentes de UI correspondente, sem criar um tema visual adicional.

Ao escrever docs/ui-quality.md:

  • Use assets/docs/ui-quality.md como a linha de base de qualidade para saída de UI estável.
  • Esclareça que a criatividade pode ser expressa em linguagem visual, tokens, página de login, home page, estado vazio, animações leves e combinações de componentes; esqueleto de layout, guias, menus, tabelas, formulários, paginação, modais e fluxo de login devem ser estáveis e corretos.
  • Ao criar a estrutura do projeto, a página de login, esqueleto de layout, home page e páginas de lista básica devem ser implementadas de acordo com a lista de verificação de aceitação em docs/ui-quality.md.

Ao escrever AGENTS.md:

  • React: use assets/AGENTS.react.template.md.
  • Vue: use assets/AGENTS.vue.template.md.
  • AGENTS.md serve apenas como ponto de entrada de colaboração de IA em nível de projeto, listando documentos obrigatórios, prioridades, limites-chave do framework e método de tratamento de conflitos; não coloque todas as regras de volta em AGENTS.md.
  • Se o projeto de destino já tiver um AGENTS.md, não o substitua silenciosamente; leia primeiro e, em seguida, anexe prioritariamente uma seção de arquitetura de painel administrativo frontend apontando para docs/architecture.md.
  • Se precisar substituir completamente, pergunte primeiro ao usuário.
  • Se o projeto de destino já tiver especificações especializadas docs/*.md com o mesmo nome, leia o conteúdo existente primeiro; a menos que o usuário solicite explicitamente a substituição, apenas complemente documentos ausentes ou peça ao usuário para confirmar a estratégia de mesclagem.

Etapa 4: Criar Estrutura do Projeto

Crie arquivos de código somente quando o usuário solicitar a implementação ou criação da estrutura do projeto.

Execute comandos de criação com base no framework selecionado pelo usuário, não execute dois comandos simultaneamente.

A menos que o usuário solicite explicitamente a instalação imediata de dependências e execução de verificação, não execute:

pnpm install
pnpm add <package>
pnpm dev
pnpm lint
pnpm typecheck
pnpm build
pnpm test:run

Quando as dependências não estiverem instaladas, apenas modifique dependencies, devDependencies e scripts no package.json e, após a conclusão, informe ao usuário quais comandos executar manualmente na próxima etapa.

React:

pnpm create vite <project-name> --template react-ts

Vue:

pnpm create vite <project-name> --template vue-ts

Módulos de negócios React:

src/modules/<business-domain>/<business-module>/
  pages/
  components/
  api/
  hooks/
  types/
  constants/

Módulos de negócios Vue:

src/modules/<business-domain>/<business-module>/
  views/
  components/
  api/
  hooks/
  types/
  constants/

Projetos Vue usam hooks/ consistentemente para nomear o diretório de lógica combinável reutilizável, não use o diretório composables/; a implementação ainda usa Composition API, e os arquivos de hook exportam funções useXxx.

Etapa 5: Explicar Modo de Uso

Após criar a documentação ou estrutura do projeto, informe ao usuário:

Você pode chamar assim em uma nova sessão do Codex/Agent:

$frontend-admin-architecture Quero criar um novo sistema de gerenciamento empresarial Vue 3 + TypeScript, por favor inicialize o projeto conforme as especificações

Ou:

Use frontend-admin-architecture, me ajude a gerar os documentos de especificação docs/ e AGENTS.md para o projeto React atual e crie a estrutura de diretórios conforme as especificações.

Explique também:

  • Novos membros devem copiar a pasta frontend-admin-architecture para seu próprio diretório .agents/skills/.
  • Após a instalação, reinicie o Codex ou abra uma nova sessão do Codex.
  • As tarefas de desenvolvimento subsequentes devem começar com: "Por favor, leia primeiro o AGENTS.md e, de acordo com o tipo de tarefa, leia as especificações especializadas em docs/, desenvolvendo estritamente de acordo com as especificações do projeto."

Guia de Criação de Projeto

Se o usuário solicitar a criação de um projeto real:

  1. Crie o projeto usando o template Vite correspondente.
  2. Escreva ou mescle as declarações de dependências e scripts do package.json conforme o framework selecionado.
  3. Crie docs/architecture.md e documentos de especificações especializadas genéricas.
  4. Crie ou atualize AGENTS.md.
  5. Crie a estrutura de diretórios.
  6. Escreva ou mantenha docs/ui-style.md com base no estilo de UI do sistema selecionado pelo usuário e escreva docs/ui-quality.md como a linha de base de qualidade de saída de UI.
  7. Primeiro, conclua o roteamento, esqueleto de layout, menu, guias, fluxo de login, página de lista, formulário e fluxo de estado estáveis e utilizáveis, depois faça aprimoramentos de estilo visual.
  8. Adicione a estrutura mínima do aplicativo com base nas opções de layout e autenticação de login selecionadas pelo usuário; se criar uma página de login ou esqueleto de layout, eles devem respeitar o estilo de UI do sistema selecionado e docs/ui-quality.md.
  9. Configure scripts e ferramentas de engenharia.
  10. Se o usuário selecionar instalar dependências e verificar imediatamente, execute instalação, inicialização, verificação e inspeção visual do navegador.
  11. Se o usuário não selecionar instalar dependências imediatamente, no final, solicite que o usuário execute:
  • pnpm install
  • pnpm dev
  • pnpm lint
  • pnpm typecheck
  • pnpm build

Quando o usuário solicitar explicitamente a instalação imediata de dependências e verificação, execute:

pnpm install
pnpm lint
pnpm typecheck
pnpm build

Se o projeto tiver testes configurados, execute também:

pnpm test:run

Se o ambiente atual permitir a inicialização da página e inspeção do navegador, você também deve abrir a página de login, home page e páginas de lista básica para aceitação visual, verificando principalmente:

  • Menu, barra superior, guias, breadcrumbs, área de conteúdo sem sobreposição, desalinhamento e flutuação.
  • O tema permanece consistente na página de login, esqueleto de layout, tabelas, formulários, modais e tags de status.
  • Na largura de desktop principal do projeto, o texto não transborda, os botões não são comprimidos, a largura do conteúdo é razoável; quando não houver acordo no projeto, verifique prioritariamente 1440px e 1920px.
  • O console do navegador não tem erros de tempo de execução.

Se a versão específica for importante, use npm view <package> version para consultar a versão atual antes da instalação. As versões de pacotes frontend mudam rapidamente, não dependa de números de versão antigos por muito tempo.

Limites

Não construa em excesso por padrão.

A menos que o usuário solicite explicitamente, não adicione por padrão:

  • Implementação RBAC
  • Servidor Mock
  • i18n
  • Gráficos
  • SDK de monitoramento
  • Docker
  • Nginx
  • CI/CD
  • Geração de código OpenAPI

Mantenha os limites de extensão, mas mantenha o projeto inicial leve.

Habilidades Relacionadas