# developer-indexer

> Planejar e implementar mudanças no indexador Python (chunking, embeddings, indexação full/incremental, IDs de chunk e payload rico); usar quando o pedido tocar `apps/indexer` ou pipeline RAG de ingestão e não usar para handlers MCP, schema Qdrant, infra ou documentação.

- Author: Junior Martins
- Repository: juniormartinxo/code-compass
- Version: 20260208232228
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-09
- Source: https://github.com/juniormartinxo/code-compass
- Web: https://mule.run/skillshub/@@juniormartinxo/code-compass~developer-indexer:20260208232228

---

---
name: developer-indexer
description: Planejar e implementar mudanças no indexador Python (chunking, embeddings, indexação full/incremental, IDs de chunk e payload rico); usar quando o pedido tocar `apps/indexer` ou pipeline RAG de ingestão e não usar para handlers MCP, schema Qdrant, infra ou documentação.
---

# Developer Indexer

## 1) Objetivo e Escopo
Evoluir o pipeline de ingestão e indexação para manter alta qualidade semântica, custo previsível e consistência entre full e incremental.

### Trigger policy
- Disparar quando o pedido mencionar `apps/indexer`, chunking, embeddings, ingestão de arquivos, full/incremental, tratamento de arquivos grandes ou exclusões de diretórios.
- Disparar quando houver alteração em ID de chunk, payload de metadados, estratégia de deduplicação ou rerank pré-indexação.
- Não disparar para contratos de tools MCP (`developer-mcp-server`), modelagem da collection Qdrant (`developer-vector-db`), bootstrap de ambiente (`developer-infra`) ou escrita de documentação (`developer-docs`).

## 2) Entradas esperadas
- Escopo de indexação (repositórios, pastas, branch/commit, modo full ou incremental).
- Parâmetros de chunking (`CHUNK_MAX_TOKENS`, `CHUNK_OVERLAP_TOKENS`, heurística/AST).
- Provider/modelo de embedding e limites de custo/latência.
- Regras de exclusão (ex.: `node_modules`, `dist`, `build`, `.git`, binários).

## 3) Workflow (Discovery -> Plan -> Implement -> Validate -> Deliver)
1. Discovery
   - Mapear fluxo atual em `code_compass/index`, `chunking`, `embeddings` e `storage`.
   - Confirmar como o ID de chunk é composto e onde ocorre deduplicação.
   - Consultar `references/checklist.md` para critérios de consistência e performance.
2. Plan
   - Definir plano com impacto em qualidade de recuperação, custo de embedding e compatibilidade de payload.
   - Diferenciar claramente comportamento full vs incremental.
3. Implement
   - Aplicar mudança mínima por etapa (scan -> chunk -> embed -> upsert).
   - Garantir IDs determinísticos para evitar duplicidade em reindexações.
   - Preservar payload rico (`repo`, `branch`, `commit`, `path`, `language`, `startLine`, `endLine`).
4. Validate
   - Executar testes e smoke tests da indexação (principalmente incremental idempotente).
   - Validar exclusões obrigatórias e tratamento de arquivos grandes sem explodir memória.
5. Deliver
   - Entregar plano executado, mudanças por arquivo, comandos usados e limitações conhecidas.

## 4) DoD
- Full e incremental produzem estado consistente para o mesmo commit alvo.
- IDs de chunk são determinísticos e estáveis sob reexecução.
- Diretórios bloqueados não entram no índice.
- Payload contém metadados suficientes para rastreabilidade e filtros.
- Fluxo trata arquivos grandes e tipos não suportados com fallback explícito.

## 5) Guardrails
- Não indexar segredos, artefatos binários ou diretórios de build/cache.
- Não alterar formato de ID de chunk sem plano de migração e limpeza.
- Não acoplar lógica de negócio a provider específico sem fallback/configuração.
- Não aumentar custo de embedding sem justificar ganho de qualidade.
- Não criar `scripts/` nesta skill sem necessidade determinística comprovada.

## 6) Convenções de saída
- Sempre devolver: (1) plano, (2) alterações, (3) comandos de validação, (4) impacto em qualidade/custo.
- Sempre declarar se houve mudança em ID, payload ou política de exclusão.

## 7) Exemplos de uso (prompts)
- "No indexador Python, implemente chunking AST para TypeScript com fallback heurístico."
- "Ajuste a indexação incremental para atualizar apenas arquivos alterados no commit atual."
- "Crie IDs de chunk estáveis e evite duplicação ao reindexar a mesma branch."
- "Melhore o tratamento de arquivos grandes sem estourar memória durante a ingestão."

## 8) Anti-exemplos (quando não usar)
- "Adicionar validação de input em uma tool MCP" -> usar `developer-mcp-server`.
- "Mudar vector size da collection Qdrant" -> usar `developer-vector-db`.
- "Configurar docker-compose para subir tudo local" -> usar `developer-infra`.
- "Escrever seção de troubleshooting no README" -> usar `developer-docs`.