BIGboss248/nextjs-wordpress

Memória de Código & Inteligência em Grafos (codebase-memory)

Esta habilidade define os padrões de engenharia, procedimentos operacionais e contratos de uso de ferramentas para explorar, pesquisar e entender código usando o grafo de conhecimento codebase-memory MCP.

---

Invariante Central: O Protocolo de Índice Primeiro

[!CRITICAL] INVARIANTE DE ÍNDICE PRIMEIRO: A reindexação automática em segundo plano está permanentemente desabilitada (auto_watch = false) neste workspace para evitar sobrecarga de disco, sobrecarga de serialização zstd e lentidão do sistema durante a edição ativa de arquivos.

Consequentemente, o agente DEVE SEMPRE verificar a atualidade do índice ou acionar uma reindexação sob demanda (index_repository) antes de executar buscas no grafo de conhecimento do código.

Sempre que você for encarregado de encontrar um símbolo, entender um módulo, investigar um bug ou preparar uma refatoração, execute a Portaria de Índice Primeiro antes de fazer chamadas de busca.

---

Hierarquia de Ferramentas: Grafo Primeiro, Grep Depois

Ao descobrir, navegar ou revisar código, siga estritamente esta hierarquia de precedência:

flowchart TD
    Tarefa[Tarefa de Descoberta / Investigação de Código] --> Frescura{Índice Fresco?}
    Frescura -->|Não / Desconhecido / Após Edições| Sinc[index_repository modo: 'fast' ou 'moderate']
    Frescura -->|Sim| Estratégia{Tipo de Consulta}
    Sinc --> Estratégia

    Estratégia -->|Símbolo / Função / Interface| BuscaGrafo[search_graph BM25 ou semantic_query]
    Estratégia -->|Chamadores / Chamados / Dependências| RastrearCaminho[trace_path callers / callees]
    Estratégia -->|Raio de Impacto de Mudanças| DetectarMudancas[detect_changes diff para conjunto de impacto]
    Estratégia -->|Código Fonte Exato| ObterTrecho[get_code_snippet linhas precisas]
    Estratégia -->|Camadas do Sistema e Módulos Centrais| ObterArq[get_architecture nós de alta centralidade]
    Estratégia -->|Strings Literais / Não Código / Assets| FallbackGrep[search_code ou run_command grep]

1. search_graph > grep textual: Busca estrutural ranqueada BM25 com divisão camelCase, boosting de rótulos (Funções +10, Rotas +8, Interfaces +5) e embeddings vetoriais.
2. trace_path > navegação manual de arquivos: Resolução instantânea de grafos de chamadores e chamados em vários saltos.
3. get_code_snippet > view_file em arquivos grandes: Recupera a declaração e o corpo exatos de um símbolo com linhas de início/fim e contagens de chamadores sem aumentar o contexto do agente.
4. detect_changes > inspeção manual de diff: Mapeia diffs do git (since: "HEAD~1", base_branch: "main") diretamente para seu raio de impacto transitivo.
5. Fallback Grep: Use search_code ou run_command (git grep, rg) APENAS para:
   • Texto literal em markdown (.md), config (.json) ou folhas de estilo (.css).
   • Intervalos de linhas explicitamente sinalizados sob parse_partial em index_status.
   • Arquivos excluídos por design via .cbmignore.

---

Fluxo de Trabalho Operacional Padrão

Etapa 1: Portaria de Sincronização do Índice (Primeira Ação Obrigatória)

Antes de emitir consultas de busca, determine o nome do projeto e garanta que o grafo reflita as edições recentes do sistema de arquivos.

1. Identificar o Nome do Projeto: Chame list_projects se o identificador do projeto for desconhecido:

   {
     "ServerName": "codebase-memory",
     "ToolName": "list_projects",
     "Arguments": {}
   }
   

   (Neste workspace, o nome de projeto derivado é "D-Scripts-aminwebsite").

2. Verificar Status ou Atualizar Índice: Se arquivos foram criados ou modificados durante a sessão, chame index_repository:

   {
     "ServerName": "codebase-memory",
     "ToolName": "index_repository",
     "Arguments": {
       "repo_path": "d:/Scripts/aminwebsite",
       "mode": "fast"
     }
   }
   

   • Seleção de Modo:
     • mode: "fast": Parse incremental, arquivos filtrados, sem embeddings vetoriais semânticos. Rápido e leve para desenvolvimento ativo.
     • mode: "moderate": Parse incremental + embeddings de similaridade vetorial para ponte conceitual em linguagem natural.
   • Inspeção de Cobertura: Verifique a resposta para:
     • parse_partial: Arquivos onde determinados intervalos de linhas tiveram erros de parse.
     • skipped: Arquivos completamente ignorados (por exemplo, binários ou muito grandes).

---

Etapa 2: Descoberta de Símbolos e Estruturas (search_graph)

Encontre funções, interfaces, tipos, componentes e definições de rotas.

{
  "ServerName": "codebase-memory",
  "ToolName": "search_graph",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "query": "LocaleSwitcher"
  }
}

• Descoberta em Linguagem Natural: Use query para busca por palavra-chave / BM25 (ex.: "theme toggle transition", "locale routing").
• Padrão de Nome Exato: Use name_pattern para filtragem por regex (ex.: ".*Provider.*", ".*Skeleton.*").
• Busca Conceitual Semântica: Use semantic_query: ["i18n", "language", "switch"] (requer array de strings) para preencher lacunas de vocabulário.
• Lidando com Truncamento (has_more): Se a resposta retornar "has_more": true, faça paginação adicionando "offset": <current_offset + limit>.

---

Etapa 3: Rastreamento de Relacionamentos e Raio de Impacto

Nunca modifique uma função ou interface sem inspecionar seus dependentes.

1. Rastrear Chamadores e Chamados (trace_path):

   {
     "ServerName": "codebase-memory",
     "ToolName": "trace_path",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "function_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.handleSelectLocale",
       "direction": "both",
       "depth": 3
     }
   }
   

   • direction: "inbound": Identifica todos os chamadores que dependem desta função (raio de impacto).
   • direction: "outbound": Identifica funções downstream chamadas por este símbolo.
   • direction: "both": Cadeia de chamadas bidirecional completa.

2. Mapear Conjunto de Impacto de Diff Git (detect_changes): Antes de commitar ou finalizar alterações, avalie o raio de impacto:

   {
     "ServerName": "codebase-memory",
     "ToolName": "detect_changes",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "base_branch": "main",
       "scope": "impact"
     }
   }
   

---

Etapa 4: Recuperação Cirúrgica de Código (get_code_snippet)

Em vez de consumir contexto visualizando arquivos inteiros com view_file, recupere implementações exatas de símbolos:

{
  "ServerName": "codebase-memory",
  "ToolName": "get_code_snippet",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "qualified_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.LocaleSwitcher"
  }
}

A resposta inclui:

• start_line e end_line exatos
• Código fonte limpo do símbolo
• Contagens diretas de chamadores e chamados

---

Etapa 5: Exploração de Arquitetura de Alto Nível (get_architecture)

Ao se orientar em um novo subsistema ou entender a topologia do sistema:

{
  "ServerName": "codebase-memory",
  "ToolName": "get_architecture",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "aspects": ["layers", "hub_nodes"]
  }
}

Identifica os principais componentes de hub arquitetural, dependências centrais e hierarquia de camadas.

---

Matriz de Referência de Ferramentas MCP Lazy

Capacidade	Ferramenta	Parâmetros Obrigatórios	Parâmetros Opcionais Principais
Verificar Status	index_status	project	N/A
Acionar Indexação	index_repository	repo_path	mode ("fast", "moderate", "full"), persistence
Listar Projetos	list_projects	Nenhum	N/A
Buscar Símbolos	search_graph	project	query, name_pattern, semantic_query, limit, offset
Rastrear Cadeia de Chamadas	trace_path	project, function_name	direction ("inbound", "outbound", "both"), depth, mode
Recuperar Código Fonte	get_code_snippet	project, qualified_name	include_neighbors
Raio de Impacto	detect_changes	project	base_branch, since, scope ("impact", "files"), depth
Arquitetura	get_architecture	project	aspects (["hub_nodes"], ["layers"], ["all"])
Texto Literal	search_code	project, query	file_pattern, case_sensitive, limit

---

Guardrails e Antipadrões Comuns

Antipadrão	Padrão Operacional Correto
Pesquisar sem verificar a atualidade do índice	Sempre chame index_repository(mode: "fast") ou verifique com index_status primeiro, pois o auto_watch em segundo plano está desabilitado.
Usar grep para encontrar definições de função	Chame search_graph com o nome do símbolo; ele retorna nomes qualificados, caminhos de arquivo exatos, intervalos de linhas e contagens de chamadores.
Ler 1000 linhas de um arquivo para ver 1 função	Chame get_code_snippet com o qualified_name do símbolo.
Ler manualmente cada arquivo para encontrar chamadores	Chame trace_path com direction: "inbound".
Assumir que o grafo está 100% completo	O grafo funciona com base no melhor esforço. Se index_status listar arquivos sob parse_partial, use grep textual para esses intervalos de linhas sinalizados.
Ativar auto_watch	Nunca ative auto_watch; mantenha-o false para preservar o desempenho máximo durante o desenvolvimento interativo.