Andy-zch/agent-skills

Mapa Lógico do Projeto

Ajuda mantenedores e IA a responder: o que mudar, onde impacta, o que não pode ser quebrado e como verificar.

Escolher o Escopo da Tarefa

• Geração Inicial: A partir de requisitos e perícia no código, gere um mapa de relacionamentos em Markdown. Quando o usuário precisar de navegação visual ou já houver HTML, gere ou mantenha também o diagrama visual.
• Atualização Incremental: Preserve IDs estáveis, atualize apenas fatos, relacionamentos, estados e diagramas alterados. Verifique referências a nós excluídos.
• Análise de Impacto: Em torno de uma mudança dada, rastreie entradas, consumidores, estados, ramos excepcionais, restrições e validações; quando o usuário pedir apenas análise, não implemente a mudança.

Priorize arquivos e IDs existentes do projeto. Para novos projetos, a saída padrão é docs/LOGIC_MAP.md; a versão visual padrão é docs/logic-map.html. Prefira nomes já existentes ou locais especificados pelo usuário.

Primeiro, Colete Evidências, Depois Construa Relacionamentos

Leia as convenções do projeto, a linha de base dos requisitos, entradas principais, páginas/workspaces, estado e armazenamento, fluxos de negócio, testes e registros de release. Percorra o código necessário ao longo das tarefas principais do usuário, sem precisar esgotar o repositório arquivo por arquivo.

Distinga claramente: promessas de requisitos, implementação real, evidências de verificação automatizada, validação de ambiente de execução e auditoria externa. Registros antigos devem ter data e escopo de evidência; verificações não executadas não podem ser descritas como aprovadas.

Foco no rastreamento:

• Se múltiplas entradas realmente compartilham a mesma cadeia de processamento e quais ignoram certos passos.
• Quem cria, mantém, consome, sobrescreve, libera os dados; se são persistidos ou saem da máquina.
• Como cancelamento, dados vazios, rejeição, estouro de limite, falha de parsing terminam cada um.
• Atualizações frequentes, lotes, limites etc. carregam invariantes específicas do projeto.

Quando documentação e código entrarem em conflito, registre ambos separadamente; não force a união para tornar o diagrama bonito. Se encontrar riscos no código, escreva como lacunas; não expanda automaticamente a tarefa para correção.

Construir um Modelo Rastreável

Leia references/model.md, adotando seus campos de nós, relacionamentos e evidências; simplifique ou ajuste com base na numeração existente do projeto.

Primeiro, escreva a definição em uma frase da tarefa principal e a cadeia principal; depois, complemente com ramos normal/excepcional, estado entre páginas, interface, restrições e validação. No diagrama, adjacência não implica relacionamento; cada aresta deve ter significado e fundamento explicáveis.

Estrutura de entrega padrão:

1. Visão Geral de Capacidades: Deixe o leitor saber primeiro o que o produto faz. Agrupe por tarefas reais do usuário; o número de subdiagramas técnicos não deve ser contado como capacidades, nem fixado nos cinco grupos deste exemplo.
2. Fluxo de Capacidade Individual: Expanda entrada, ação, processamento, estado e saída, marcando condições de ramificação.
3. Descrição do Nó e Evidências: Responsabilidade, relacionamentos diretos, localização na implementação, restrições, verificação e estado.
4. Índice de Impacto de Mudanças: Mudanças comuns mapeadas para quais nós, arquivos e verificações.

A visão geral pode omitir relacionamentos secundários, mas o modelo completo ou a descrição dos nós devem poder recuperá-los. O documento de requisitos continua sendo o árbitro dos requisitos; o mapa não deve criar uma nova linha de base de requisitos.

Entrega Visual HTML

Quando HTML for necessário, leia references/visual.md. Se precisar de referência concreta, veja references/wechat-example.html; é um exemplo de um projeto já implementado, não um fato universal ou modelo de layout fixo.

Compartilhe uma única fonte de dados entre nós e arestas semânticas. Coordenadas de visualização, roteamento e tema são gerenciados separadamente; Markdown e HTML usam os mesmos IDs. Projetos simples podem manter uma estrutura de dados pequena diretamente, sem forçar a introdução de um gerador ou biblioteca de gráficos.

Preserve a direção visual já confirmada pelo usuário. O padrão é centralizado com largura limitada, entrada pela visão geral de capacidades, navegação por fluxo individual, descrição abaixo do diagrama e temas claro e escuro. O número de nós e a forma de subdividir os diagramas são determinados pela densidade do conteúdo.

Não copie termos específicos do WeChat do exemplo, tamanhos limites, estados "por verificar" ou coordenadas manuais para outros projetos. Quando um agrupamento raiz do produto for apenas para exibição estrutural, marque-o claramente e não o trate como uma nova capacidade de negócio.

Verificação e Entrega

Conteúdo e estrutura:

• IDs únicos; extremidades das arestas existentes; cada capacidade principal tem uma entrada de detalhamento; nós excluídos não deixam referências pendentes.
• Relacionamentos de contenção, fluxo de dados, dependência, restrição e verificação têm cada um sua semântica; não os misture como ordem de execução.
• Ciclo de vida de armazenamento, saídas excepcionais, localizações de implementação e estados podem ser suportados por evidências.
• Pergunte-se uma vez sobre uma mudança concreta, por exemplo "o que a mudança de layout afeta?", o mapa deve ser capaz de rastrear os estados, consumidores e verificações relevantes.

Para a versão visual, ainda é necessário abrir o navegador e verificar:

• A visão geral exibe todas as capacidades principais ao mesmo tempo, texto claro, setas não atravessam nós ou texto.
• Abra os fluxos de capacidade um por um, verificando detalhamento, relacionamentos entre diagramas, estado selecionado e desmarcação.
• Verifique texto, nós, linhas, setas e descrições nos modos claro e escuro; capture capturas de tela.
• Verifique a integridade da visão geral no tamanho de desktop alvo; em janela estreita, mantenha legibilidade, permitindo rolagem dentro do diagrama ou divisão em subdiagramas.

Verificações estáticas de sintaxe ou estrutura não substituem a inspeção visual. Quando o navegador não estiver disponível, entregue o arquivo e liste explicitamente as verificações não concluídas; não use capturas de tela antigas para fingir o resultado atual.

Entregue links, mudanças principais nos relacionamentos, resultados reais das verificações e lacunas restantes. Salve o trabalho conforme as convenções Git do projeto; não publique sites por conta própria nem instale skills globais.