AgentSkillsCN

developer-vector-db

Git最佳实践参考——常规提交、分支命名、PR标准

SKILL.md
--- frontmatter
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.