# developer-vector-db

> Planejar e implementar mudanças na camada vetorial Qdrant (collections, distance metric, vector size, payload filters, upsert/delete e migração de schema); usar quando o pedido tocar modelagem ou operação de vetor e não usar para lógica do indexador, handlers MCP, infra geral 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-vector-db:20260208232228

---

---
name: developer-vector-db
description: Planejar e implementar mudanças na camada vetorial Qdrant (collections, distance metric, vector size, payload filters, upsert/delete e migração de schema); usar quando o pedido tocar modelagem ou operação de vetor e não usar para lógica do indexador, handlers MCP, infra geral ou documentação.
---

# Developer Vector DB

## 1) Objetivo e Escopo
Projetar e manter o armazenamento vetorial em Qdrant com schema claro, filtros eficientes e operações seguras de evolução.

### Trigger policy
- Disparar quando o pedido mencionar Qdrant, collection, métrica de distância, tamanho de vetor, filtros por payload, upsert/delete, snapshots, migração de schema ou versionamento de pontos.
- Disparar quando houver ajuste em contrato de payload que impacta busca semântica e filtros.
- Não disparar para lógica de chunking/embedding (`developer-indexer`), handlers MCP (`developer-mcp-server`), bootstrap docker/env (`developer-infra`) ou documentação (`developer-docs`).

## 2) Entradas esperadas
- Nome da collection e objetivo da mudança.
- `vector_size`, `distance metric`, índices de payload e filtros necessários.
- Estratégia de versionamento/migração de schema e compatibilidade.
- Política de retenção, delete lógico/físico e rollback.

## 3) Workflow (Discovery -> Plan -> Implement -> Validate -> Deliver)
1. Discovery
   - Mapear configuração atual de collection e contratos de payload consumidos.
   - Levantar consultas e filtros críticos para performance e precisão.
   - Consultar `references/checklist.md` para garantir segurança de migração.
2. Plan
   - Definir plano de migração (in-place, shadow collection ou backfill) com rollback.
   - Explicitar impacto em indexador e servidor MCP.
3. Implement
   - Aplicar ajustes de schema e operações de upsert/delete de forma idempotente.
   - Preservar compatibilidade dos campos de payload usados por filtros existentes.
4. Validate
   - Validar queries com filtros representativos e checar precisão mínima esperada.
   - Validar rotina de delete/versionamento para evitar pontos órfãos ou inconsistentes.
5. Deliver
   - Entregar plano executado, mudanças por arquivo/config, comandos de validação e riscos.

## 4) DoD
- Collection final documenta `vector_size`, `distance metric` e índices de payload.
- Migração tem plano de rollback e não perde rastreabilidade dos pontos.
- Upsert e delete são idempotentes para reprocessamentos.
- Filtros por payload relevantes funcionam com cobertura mínima de casos.
- Versionamento evita mistura de schemas incompatíveis na mesma consulta.

## 5) Guardrails
- Não remover collection produtiva sem backup/snapshot e aprovação explícita.
- Não alterar `vector_size`/métrica sem migrar dados existentes de forma segura.
- Não quebrar filtros existentes ao renomear campos de payload sem compat layer.
- Não executar limpeza destrutiva sem critério observável e reversível.
- Não criar `scripts/` nesta skill sem necessidade determinística comprovada.

## 6) Convenções de saída
- Sempre devolver: (1) plano de migração, (2) mudanças aplicadas, (3) comandos de validação, (4) risco residual.
- Sempre explicitar impacto em compatibilidade de payload e queries.

## 7) Exemplos de uso (prompts)
- "Ajuste a collection `code_chunks` para suportar novos filtros por `branch` e `language`."
- "Proponha migração segura ao trocar `distance` para `Cosine` mantendo rollback."
- "Implemente versionamento de pontos para evitar conflito entre schemas antigos e novos."
- "Reveja política de deletes para remover chunks obsoletos sem perder histórico útil."

## 8) Anti-exemplos (quando não usar)
- "Melhorar chunking AST de arquivos Python" -> usar `developer-indexer`.
- "Alterar tool MCP para retornar mais campos" -> usar `developer-mcp-server`.
- "Configurar make targets e compose local" -> usar `developer-infra`.
- "Atualizar ADR explicando a escolha do Qdrant" -> usar `developer-docs`.