# developer-docs

> Planejar e manter documentação técnica do projeto (README, quickstart, ADRs, docs internas, exemplos de tool calls e troubleshooting) alinhada ao código; usar quando o pedido exigir clareza documental e não usar para implementar lógica de runtime ou infraestrutura.

- 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-docs:20260208232228

---

---
name: developer-docs
description: Planejar e manter documentação técnica do projeto (README, quickstart, ADRs, docs internas, exemplos de tool calls e troubleshooting) alinhada ao código; usar quando o pedido exigir clareza documental e não usar para implementar lógica de runtime ou infraestrutura.
---

# 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.

## 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`.