Gerador de Guias de Integração para Wikis

Gere quatro documentos de integração personalizados para cada público-alvo na pasta “onboarding/”, cada um fornecendo a um participante diferente exatamente as informações de que ele precisa.

Resolução do repositório de origem (É PRECISO FAZER ISSO PRIMEIRO)

Antes de gerar qualquer guia, você DEVE determinar o contexto do repositório de origem:

1. Verifique se há um git remote: execute o comando ` git remote get-url origin ` para detectar se existe um remote
2. Pergunte ao usuário: “Este é um repositório apenas local ou você tem uma URL de repositório de origem (por exemplo, GitHub, Azure DevOps)?”
   • URL remota fornecida → salve como REPO_URL, use citações com link: [arquivo:linha](REPO_URL/blob/BRANCH/arquivo#Llinha)
   • Apenas local → use citações locais: (caminho_do_arquivo:número_da_linha)
3. Determine o branch padrão: execute ` git rev-parse --abbrev-ref HEAD`
4. NÃO prossiga até que o contexto do repositório de origem esteja resolvido

Quando ativar

• O usuário solicita documentos de integração ou guias de introdução
• O usuário executa o comando /deep-wiki:onboard
• O usuário deseja ajudar novos membros da equipe a entender uma base de código

Estrutura de saída

Gere uma pasta `onboarding/ ` com estes arquivos:

onboarding/
├── index.md                    # Central de integração — links para todos os 4 guias com descrições do público-alvo
├── contributor-guide.md        # Para novos colaboradores (presume conhecimento prévio em Python ou JS)
├── staff-engineer-guide.md     # Para engenheiros de equipe/principais
├── executive-guide.md          # Para líderes de engenharia no nível de vice-presidente/diretor
└── product-manager-guide.md    # Para gerentes de produto e partes interessadas não ligadas à engenharia

index.md — Central de integração

Uma página inicial com:

• Resumo do projeto em um parágrafo
• Tabela de seleção de guias:

Detecção de idioma

Analise o repositório em busca de arquivos de compilação para determinar a linguagem principal dos exemplos de código:

• package.json / tsconfig.json → TypeScript/JavaScript
• *.csproj / *.sln → C# / .NET
• Cargo.toml → Rust
• pyproject.toml / setup.py / requirements.txt → Python
• go.mod → Go
• pom.xml / build.gradle → Java

Guia 1: Guia do colaborador

Arquivo: onboarding/contributor-guide.md Público-alvo: Engenheiros que estão ingressando no projeto. Pressupõe proficiência em Python ou JavaScript e experiência geral em engenharia de software. Extensão: 1.000–2.500 linhas. Progressivo — cada seção se baseia na anterior.

Seções obrigatórias

Parte I: Fundamentos (pule se o repositório usar Python ou JS)

1. {Linguagem principal} para engenheiros de Python/JS — Tabelas de comparação de sintaxe, modelo assíncrono, coleções, sistema de tipos, gerenciamento de pacotes. Código concreto lado a lado, NÃO descrições abstratas.
2. Fundamentos do {Framework Principal} — Comparação com frameworks equivalentes em Python/JS (por exemplo, FastAPI, Express). Pipeline de solicitações, roteamento, injeção de dependências (DI), configuração.

Parte II: Esta base de código 3. O que este projeto faz — apresentação resumida em 2 a 3 frases 4. Estrutura do projeto — árvore de diretórios anotada (o que fica onde e por quê). Inclua uma visão geral da arquitetura em gráfico TB. 5. Conceitos centrais — Terminologia específica do domínio explicada com exemplos de código. Use um diagrama ER para o modelo de dados. 6. Ciclo de vida da solicitação — diagrama de sequência (com numeração automática) traçando uma solicitação típica de ponta a ponta. 7. Padrões-chave — Modelos do tipo “Se você quiser adicionar X, siga este padrão” com código real

Parte III: Começando a trabalhar 8. Pré-requisitos e configuração — Tabela: Ferramenta, Versão, Comando de instalação. Passo a passo com o resultado esperado em cada etapa. 9. Sua primeira tarefa — Orientação completa sobre como adicionar um recurso simples 10. Fluxo de trabalho de desenvolvimento — Estratégia de ramificação, convenções de commit, processo de PR. Use diagrama de fluxo. 11. Executando testes — Todos os testes, arquivo único, teste único, comandos de cobertura 12. Guia de depuração — Tabela de problemas comuns: sintoma, causa, correção 13. Armadilhas comuns — Erros que todo novo colaborador comete e como evitá-los

Anexos

• Glossário (mais de 40 termos)
• Referência de arquivos importantes — Tabela: caminho, finalidade, por que é importante, fonte
• Cartão de referência rápida — Folha de referência com os comandos e padrões mais usados

Regras

• Todos os exemplos de código no idioma principal detectado
• Todos os comandos devem poder ser copiados e colados com a saída esperada
• Mínimo de 5 diagramas Mermaid (arquitetura, ER, sequência, fluxograma, estado)
• Use o Mermaid para diagramas de fluxo de trabalho (cores do modo escuro) — adicione bloco de comentário após cada um
• Baseie todas as afirmações em código real — cite usando o formato de link

Guia 2: Guia do Engenheiro Sênior

Arquivo: onboarding/staff-engineer-guide.md Público-alvo: Engenheiros de equipe/principais que precisam entender o “porquê” por trás de cada decisão. Possuem profunda experiência em sistemas, mas podem não conhecer a linguagem deste repositório. Extensão: 800–1200 linhas. Denso, opinativo, arquitetônico.

Seções obrigatórias

1. Resumo executivo — O que é o sistema em um parágrafo conciso. O que ele controla versus o que delega.
2. A Visão Arquitetônica Central — O ÚNICO conceito mais importante. Inclua pseudocódigo em uma linguagem DIFERENTE daquela do repositório.
3. Arquitetura do Sistema — Gráfico completo do Mermaid com diagrama TB. Destaque o “coração” do sistema.
4. Modelo de domínio — Diagrama erDiagram do Mermaid das entidades centrais. Tabela de invariantes de dados: Entidade, Invariável, Imposta por, Origem.
5. Principais abstrações e interfaces — Diagrama de classes (classDiagram) mostrando as abstrações que suportam a carga.
6. Ciclo de Vida da Solicitação — sequenceDiagram (com numeração automática) mostrando uma solicitação típica, desde a entrada até a resposta.
7. Transições de estado — stateDiagram-v2 para entidades com estados de ciclo de vida significativos.
8. Registro de decisões — Tabela: Decisão, Alternativas consideradas, Justificativa, Fonte.
9. Fundamentação das Dependências — Tabela: Dependência, Finalidade, O que Substituiu, Fonte.
10. Fluxo de dados e estado — Como os dados se movem pelo sistema. Tabela comparativa de armazenamento.
11. Modos de falha e tratamento de erros — fluxograma dos caminhos de propagação de erros.
12. Características de desempenho — gargalos, limites de escalabilidade, caminhos mais utilizados.
13. Modelo de segurança — Autenticação, autorização, limites de confiança, sensibilidade dos dados.
14. Estratégia de testes — O que é testado, o que não é, filosofia de testes.
15. Dívida técnica conhecida — Tabela: Problema, nível de risco, arquivos afetados, fonte.
16. Onde aprofundar — Ordem recomendada de leitura dos arquivos-fonte, links para seções da wiki.

Regras

• Use pseudocódigo em uma linguagem diferente para explicar conceitos
• Use tabelas comparativas para mapear conceitos desconhecidos (por exemplo, Tarefa a = Awaitable[T])
• Texto denso com tabelas, NÃO listas de marcadores superficiais
• Cada afirmação deve ser respaldada por uma referência com link
• Mínimo de 5 diagramas Mermaid (arquitetura, ER, classe, sequência, estado, fluxograma)
• Cada diagrama seguido por bloco de comentários
• Use tabelas de forma intensiva — decisões, dependências e dívida devem TODAS ser apresentadas em tabelas com colunas de fonte
• Concentre-se no PORQUÊ das decisões tomadas, não apenas no O QUE existe

Guia 3: Guia Executivo

Arquivo: onboarding/executive-guide.md Público-alvo: vice-presidente/diretor de engenharia. Precisa de uma visão geral das capacidades, avaliação de riscos e contexto de investimento — NÃO de detalhes no nível do código. Extensão: 400–800 linhas. Estratégico, conciso e orientado para a tomada de decisões.

Seções obrigatórias

1. Visão geral do sistema — O que ele faz, quem o utiliza, valor comercial em 2 a 3 frases
2. Mapa de Capacidades — Tabela: Capacidade, Status (Implementado/Parcial/Planejado), Maturidade, Dependências. O que o sistema pode e não pode fazer atualmente.
3. Visão geral da arquitetura — Gráfico Mermaid de alto nível (diagrama LR ). Serviços, armazenamentos de dados, integrações externas — SEM detalhes internos de código. Foco nas unidades de implantação e nos limites das equipes.
4. Topologia da equipe — Qual equipe/pessoa é responsável por quais componentes. Tabela: Componente, Responsável, Criticidade, Fator de Risco.
5. Tese de investimento em tecnologia — Por que essas tecnologias foram escolhidas. Tabela: Tecnologia, Finalidade, Alternativas consideradas, Nível de risco.
6. Avaliação de riscos — Tabela: Risco, Probabilidade, Impacto, Mitigação, Responsável. Abranger confiabilidade, segurança, escalabilidade e conformidade.
7. Modelo de Custo e Escalabilidade — Como os custos variam de acordo com o uso. Quais são os gargalos. Quando será necessário o próximo investimento em escalabilidade.
8. Mapa de dependências — gráfico em TB mostrando dependências externas críticas. Tabela: Dependência, Tipo (Serviço/Biblioteca/Plataforma), Risco em caso de indisponibilidade.
9. Métricas-chave e observabilidade — O que é medido, quais painéis existem, cobertura de alertas. Tabela: Métrica, valor atual, meta, fonte.
10. Alinhamento do roteiro — Fluxos de trabalho de engenharia mapeados às prioridades de negócios. O que está em andamento, o que está planejado, o que está bloqueado.
11. Resumo da dívida técnica — Os 5 principais itens de dívida com impacto nos negócios. Tabela: Problema, Impacto nos negócios, Esforço para corrigir, Prioridade.
12. Recomendações — 3 a 5 recomendações práticas para o próximo trimestre, priorizadas por impacto.

Regras

• NENHUM trecho de código — este guia é para líderes de engenharia, não para programadores
• Diagramas no nível de serviço/equipe, não no nível de classe/função
• Toda afirmação deve ser respaldada por evidências — cite seções da wiki, documentos de arquitetura ou arquivos-fonte
• Mínimo de 3 diagramas Mermaid (visão geral da arquitetura, mapa de dependências, capacidades/roteiro)
• Tabelas para cada conclusão estruturada — esse público lê tabelas, não textos narrativos
• Linguagem de negócios — traduza conceitos técnicos em impacto (confiabilidade, velocidade, custo, risco)

Guia 4: Guia do Gerente de Produto

Arquivo: onboarding/product-manager-guide.md Público-alvo: gerentes de produto e partes interessadas não ligadas à engenharia. Precisam entender o que o sistema faz, o que é possível e onde estão os limites — NÃO como ele é construído. Extensão: 400–800 linhas. Centrado no usuário, focado em recursos e ciente das restrições.

Seções obrigatórias

1. O que este sistema faz — Apresentação resumida de 2 a 3 frases em linguagem acessível ao usuário (sem jargões)
2. Mapa da jornada do usuário — Gráfico Mermaid LR ou diagrama de jornada mostrando os principais fluxos de usuários pelo sistema
3. Mapa de Capacidades dos Recursos — Tabela: Recurso, Status (Ativo/Beta/Planejado/Impossível), Comportamento Percebido pelo Usuário, Limitações. Mapa abrangente do que está implementado e do que não está.
4. Modelo de dados (visão do produto) — Diagrama erDiagram simplificado no Mermaid mostrando as entidades com as quais os usuários interagem. Explique em termos de negócios (por exemplo, “Um projeto tem muitos documentos”, e não “relação FK”).
5. Configuração e sinalizadores de recursos — Tabela: Sinalizador/Configuração, O que controla, Padrão, Quem pode alterá-lo. O que pode ser ativado ou desativado sem trabalho de engenharia.
6. Recursos da API — Quais integrações são possíveis. Tabela: Recurso, Endpoint/Método, Autenticação, Limites de taxa. Escrito para parceiros de integração, não para desenvolvedores.
7. Desempenho e SLAs — Tempos de resposta, limites de taxa de transferência, metas de disponibilidade. Tabela: Operação, Latência esperada, Limite de taxa de transferência, SLA atual.
8. Limitações e restrições conhecidas — Lista honesta do que o sistema não consegue fazer ou faz mal. Tabela: Limitação, Impacto no usuário, Solução alternativa, Correção planejada.
9. Dados e privacidade — Quais dados são coletados, onde são armazenados, políticas de retenção, status de conformidade. Tabela: Tipo de dados, local de armazenamento, retenção, conformidade.
10. Glossário — Termos da área explicados em linguagem simples (sem jargão de engenharia)
11. Perguntas frequentes — Mais de 10 perguntas comuns que um gerente de produto faria, respondidas de forma concisa

Regras

• ZERO jargão de engenharia — nada de “middleware”, “injeção de dependência”, “ORM”. Use linguagem simples.
• Enquadramento centrado no usuário — descreva tudo em termos do que os usuários vivenciam, não de como o código funciona
• Mínimo de 3 diagramas Mermaid (jornada do usuário, modelo de dados, mapa de recursos/visão geral das capacidades)
• Tabelas para cada conclusão estruturada — os gerentes de produto analisam tabelas, não textos descritivos
• Se for necessário mencionar um conceito técnico, explique-o em uma frase (por exemplo: “Flags de recursos — opções que nos permitem ativar ou desativar recursos sem precisar implantar código”)
• Toda afirmação deve ser fundamentada em evidências — cite seções da wiki ou arquivos-fonte para verificação

Regras para diagramas Mermaid (TODOS os guias)

TODOS os diagramas devem usar cores do modo escuro:

• Preenchimento dos nós: #2d333b, bordas: #6d5dfc, texto: #e6edf3
• Fundos de subgráficos: #161b22, bordas: #30363d
• Linhas: #8b949e
• Se estiver usando diretivas de estilo inline, utilize preenchimentos escuros com ,color:#e6edf3
• NÃO use
em rótulos do Mermaid (use
ou quebras de linha)

Validação

Após gerar cada guia, verifique:

• Se todos os caminhos de arquivo mencionados realmente existem no repositório
• Todos os nomes de classes/métodos estejam corretos (não sejam inventados)
• Os diagramas do Mermaid sejam renderizados (sem erros de sintaxe)
• Não há tags semelhantes a HTML (genéricas como List) fora das cercas de código — envolva-as em crases
• Cada guia seja adequado ao seu público-alvo — sem código nos guias para Executivos/Gerentes de Projeto