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.mdassets/AGENTS.react.template.md
Vue:
references/vue/architecture.mdassets/AGENTS.vue.template.md
Documentos de governança de projeto genéricos:
assets/docs/ai-interaction.mdassets/docs/karpathy-guidelines.mdassets/docs/ui-style.mdassets/docs/ui-quality.mdassets/docs/design-tokens.mdassets/docs/code-style.mdassets/docs/security.mdassets/docs/comments.mdassets/docs/verification.mdassets/docs/git-commit.mdassets/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çõesdependenciesedevDependencies. - Se
reactoureact-domestiverem presentes, identifique como React + TypeScript. - Se
vueou@vitejs/plugin-vueestiverem presentes, identifique como Vue 3 + TypeScript. - Se
package.jsonnão existir, verifiquevite.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.
- 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.mdpermanecerá 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.mdpendente.
- 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.
- 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.
- Deve instalar dependências e executar a verificação imediatamente?
- 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.mdpermanece 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 buildpor 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.mdcomo 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.mdserve 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 emAGENTS.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 paradocs/architecture.md. - Se precisar substituir completamente, pergunte primeiro ao usuário.
- Se o projeto de destino já tiver especificações especializadas
docs/*.mdcom 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-architecturepara 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:
- Crie o projeto usando o template Vite correspondente.
- Escreva ou mescle as declarações de dependências e scripts do
package.jsonconforme o framework selecionado. - Crie
docs/architecture.mde documentos de especificações especializadas genéricas. - Crie ou atualize
AGENTS.md. - Crie a estrutura de diretórios.
- Escreva ou mantenha
docs/ui-style.mdcom base no estilo de UI do sistema selecionado pelo usuário e escrevadocs/ui-quality.mdcomo a linha de base de qualidade de saída de UI. - 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.
- 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. - Configure scripts e ferramentas de engenharia.
- Se o usuário selecionar instalar dependências e verificar imediatamente, execute instalação, inicialização, verificação e inspeção visual do navegador.
- Se o usuário não selecionar instalar dependências imediatamente, no final, solicite que o usuário execute:
pnpm installpnpm devpnpm lintpnpm typecheckpnpm 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.