Customer Success Manager

Customer Success Manager

Analytics de sucesso do cliente de nível de produção com pontuação de saúde multidimensional, previsão de risco de churn e identificação de oportunidades de expansão. Três ferramentas Python CLI fornecem análise determinística e repetível usando apenas biblioteca padrão — sem dependências externas, sem chamadas de API, sem modelos de ML.

Sumário

• Requisitos de Entrada
• Formatos de Saída
• Como Usar
• Scripts
• Guias de Referência
• Templates
• Melhores Práticas
• Limitações

Requisitos de Entrada

Todos os scripts aceitam um arquivo JSON como argumento de entrada posicional. Veja assets/sample_customer_data.json para exemplos completos de schema e dados de amostra.

Calculadora de Pontuação de Saúde

Campos obrigatórios por objeto de cliente: customer_id, name, segment, arr e objetos aninhados usage (login_frequency, feature_adoption, dau_mau_ratio), engagement (support_ticket_volume, meeting_attendance, nps_score, csat_score), support (open_tickets, escalation_rate, avg_resolution_hours), relationship (executive_sponsor_engagement, multi_threading_depth, renewal_sentiment) e pontuações previous_period para análise de tendências.

Analisador de Risco de Churn

Campos obrigatórios por objeto de cliente: customer_id, name, segment, arr, contract_end_date e objetos aninhados usage_decline, engagement_drop, support_issues, relationship_signals e commercial_factors.

Pontuador de Oportunidades de Expansão

Campos obrigatórios por objeto de cliente: customer_id, name, segment, arr e objetos aninhados contract (licensed_seats, active_seats, plan_tier, available_tiers), product_usage (sinalizações de adoção e percentuais de uso por módulo) e departments (atuais e potenciais).

Formatos de Saída

Todos os scripts suportam dois formatos de saída via flag --format:

• text (padrão): Saída formatada legível por humanos para visualização no terminal
• json: Saída JSON legível por máquina para integrações e pipelines

Como Usar

Início Rápido

# Pontuação de saúde
python scripts/health_score_calculator.py assets/sample_customer_data.json
python scripts/health_score_calculator.py assets/sample_customer_data.json --format json

# Análise de risco de churn
python scripts/churn_risk_analyzer.py assets/sample_customer_data.json
python scripts/churn_risk_analyzer.py assets/sample_customer_data.json --format json

# Pontuação de oportunidades de expansão
python scripts/expansion_opportunity_scorer.py assets/sample_customer_data.json
python scripts/expansion_opportunity_scorer.py assets/sample_customer_data.json --format json

Integração de Fluxo de Trabalho

# 1. Pontuar saúde do cliente em todo o portfólio
python scripts/health_score_calculator.py customer_portfolio.json --format json > health_results.json
# Verificar: confirmar que health_results.json contém o número esperado de registros de clientes antes de continuar

# 2. Identificar contas em risco
python scripts/churn_risk_analyzer.py customer_portfolio.json --format json > risk_results.json
# Verificar: confirmar que risk_results.json não está vazio e tiers de risco estão presentes para cada cliente

# 3. Encontrar oportunidades de expansão em contas saudáveis
python scripts/expansion_opportunity_scorer.py customer_portfolio.json --format json > expansion_results.json
# Verificar: confirmar que expansion_results.json lista oportunidades classificadas por prioridade

# 4. Preparar QBR usando templates
# Referência: assets/qbr_template.md

Tratamento de erros: Se um script sair com erro, verificar que:

• O JSON de entrada corresponde ao schema obrigatório para aquele script (veja Requisitos de Entrada acima)
• Todos os campos obrigatórios estão presentes e corretamente tipados
• Python 3.7+ está sendo usado (python --version)
• Arquivos de saída de etapas anteriores não estão vazios antes de canalizar para etapas seguintes

Scripts

1. health_score_calculator.py

Propósito: Pontuação de saúde multidimensional do cliente com análise de tendências e benchmarking consciente do segmento.

Dimensões e Pesos:

Classificação:

• Verde (75-100): Saudável — cliente alcançando valor
• Amarelo (50-74): Precisa de atenção — monitorar de perto
• Vermelho (0-49): Em risco — intervenção imediata necessária

Uso:

python scripts/health_score_calculator.py customer_data.json
python scripts/health_score_calculator.py customer_data.json --format json

2. churn_risk_analyzer.py

Propósito: Identificar contas em risco com detecção de sinais comportamentais e recomendações de intervenção baseadas em tier.

Pesos de Sinais de Risco:

Tiers de Risco:

• Crítico (80-100): Escalação executiva imediata
• Alto (60-79): Intervenção urgente do CSM
• Médio (40-59): Contato proativo
• Baixo (0-39): Monitoramento padrão

Uso:

python scripts/churn_risk_analyzer.py customer_data.json
python scripts/churn_risk_analyzer.py customer_data.json --format json

3. expansion_opportunity_scorer.py

Propósito: Identificar oportunidades de upsell, cross-sell e expansão com estimativa de receita e classificação por prioridade.

Tipos de Expansão:

• Upsell: Upgrade para tier superior ou mais do produto existente
• Cross-sell: Adicionar novos módulos de produto
• Expansão: Assentos ou departamentos adicionais

Uso:

python scripts/expansion_opportunity_scorer.py customer_data.json
python scripts/expansion_opportunity_scorer.py customer_data.json --format json

Guias de Referência

Templates

Melhores Práticas

1. Combinar sinais: Usar todos os três scripts juntos para uma visão completa do cliente
2. Agir sobre tendências, não instantâneos: Um Verde em declínio é mais urgente do que um Amarelo estável
3. Calibrar limiares: Ajustar benchmarks de segmento com base no seu produto e setor conforme references/health-scoring-framework.md
4. Preparar com dados: Executar scripts antes de cada QBR e reunião executiva; referenciar references/cs-playbooks.md para orientação de intervenção

Limitações

• Sem dados em tempo real: Scripts analisam instantâneos pontuais de arquivos JSON de entrada
• Sem integração com CRM: Dados devem ser exportados manualmente do seu CRM/plataforma de CS
• Somente determinístico: Sem ML preditivo — pontuação é algorítmica com base em sinais ponderados
• Ajuste de limiar: Limiares padrão são padrões do setor mas podem precisar de calibração para o seu negócio
• Estimativas de receita: Estimativas de receita de expansão são aproximações com base em padrões de uso

Última Atualização: Fevereiro 2026 Ferramentas: 3 ferramentas Python CLI Dependências: Apenas biblioteca padrão Python 3.7+