Developer Docs

1) Objetivo e Escopo

Manter documentação técnica acionável, atualizada e consistente com o comportamento real do Code Compass.

Trigger policy

• •Disparar quando o pedido mencionar README, docs/, ADRs, quickstart, runbook, exemplos de tool calls, troubleshooting ou atualização de documentação após mudança técnica.
• •Disparar quando houver divergência entre comportamento do sistema e instruções documentadas.
• •Não disparar para implementação de feature em runtime (developer-mcp-server, developer-indexer, developer-vector-db, developer-infra) sem foco documental explícito.

2) Entradas esperadas

• •Público-alvo (dev, operação, mantenedor, reviewer).
• •Escopo do documento e contexto técnico da mudança.
• •Fonte de verdade (arquivos de código, comandos reais, decisões arquiteturais).
• •Restrições de formato/idioma e nível de detalhe desejado.

3) Workflow (Discovery -> Plan -> Implement -> Validate -> Deliver)

1. •Discovery
   • •Ler arquivos de código e configs relevantes antes de editar docs.
   • •Levantar lacunas, inconsistências e comandos obsoletos.
   • •Consultar references/checklist.md para padrão de qualidade documental.
2. •Plan
   • •Definir estrutura mínima por seção (objetivo, pré-requisitos, execução, validação, troubleshooting).
   • •Priorizar clareza operacional e exemplos executáveis.
3. •Implement
   • •Atualizar documentos com linguagem direta e passos verificáveis.
   • •Incluir exemplos de tool calls MCP e paths reais quando aplicável.
   • •Registrar decisões em ADR quando houver trade-off arquitetural.
4. •Validate
   • •Verificar se comandos documentados existem e se ordem de execução é coerente.
   • •Confirmar consistência entre README, docs específicas e estrutura do repositório.
5. •Deliver
   • •Entregar plano aplicado, documentos alterados e checklist de verificação final.

4) DoD

• •Documentação responde "como rodar", "como validar" e "como debugar" sem passos implícitos críticos.
• •Comandos, paths e nomes de módulos batem com a base atual.
• •ADRs capturam contexto, decisão, trade-offs e consequências.
• •Exemplos de tool calls refletem contrato real e limites conhecidos.
• •Mudanças documentais preservam consistência de termos e convenções.

5) Guardrails

• •Não inventar comportamento não confirmado no código/configuração.
• •Não manter instruções quebradas por compatibilidade histórica; corrigir ou marcar depreciação.
• •Não ocultar pré-requisitos importantes (versões, env vars, serviços).
• •Não copiar conteúdo redundante quando referência cruzada resolve melhor.
• •Não criar scripts/ nesta skill sem necessidade determinística comprovada.
• •Localização dos arquivos: Toda documentação deve residir em docs/<projeto>/ (ex: docs/indexer/, docs/mcp-server/). Não espalhar docs soltas pelas pastas dos apps.

6) Convenções de saída

• •Sempre devolver: (1) plano editorial, (2) arquivos alterados por objetivo, (3) validações realizadas, (4) pendências abertas.
• •Sempre incluir orientação de uso: onde ler primeiro e como aplicar os exemplos.

7) Exemplos de uso (prompts)

• •"Atualize o README com quickstart real para subir Qdrant, indexar e iniciar o MCP server."
• •"Escreva um ADR justificando a escolha Node/NestJS + Python + Qdrant para o Code Compass."
• •"Crie guia de troubleshooting para falhas comuns de indexação e conexão com Qdrant."
• •"Documente exemplos de chamadas das tools search_code, open_file e list_tree."

8) Anti-exemplos (quando não usar)

• •"Implementar validação de path traversal no servidor" -> usar developer-mcp-server.
• •"Ajustar algoritmo de chunking e embeddings" -> usar developer-indexer.
• •"Modificar schema da collection e rotina de upsert" -> usar developer-vector-db.
• •"Reorganizar docker-compose e make targets" -> usar developer-infra.