Skip to content

plugin-troubleshooting.md

Latest commit

 

History

History
480 lines (348 loc) · 10.9 KB

plugin-troubleshooting.md

File metadata and controls

480 lines (348 loc) · 10.9 KB

English | 한국어 | 中文 | 日本語 | Español | Português

Guía de Resolución de Problemas de CodingBuddy

Soluciones a problemas comunes al usar el Plugin de CodingBuddy para Claude Code.

Problemas de Instalación

El Plugin No Aparece en Claude Code

Síntoma: Después de la instalación, claude plugin list no muestra codingbuddy.

Soluciones:

  1. Verificar que la instalación se completó

    # Comprobar si existen los archivos del plugin
ls ~/.claude/plugins/codingbuddy/

  2. Reinstalar el plugin

    claude plugin uninstall codingbuddy@jeremydev87
claude plugin install codingbuddy@jeremydev87

  3. Verificar la versión de Claude Code

    claude --version
# El sistema de plugins requiere Claude Code 1.0+

  4. Reiniciar Claude Code

    # Salga de Claude Code completamente y reinicie
claude

La Instalación de npm Falla

Síntoma: npm install -g codingbuddy-claude-plugin falla con errores.

Soluciones:

  1. Errores de permisos (EACCES)

    # Opción A: Use un gestor de versiones de Node
# Instale nvm, luego:
nvm install --lts
npm install -g codingbuddy-claude-plugin

# Opción B: Corregir prefijo de npm
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g codingbuddy-claude-plugin

  2. Errores de red

    # Verificar registro de npm
npm config get registry
# Debe ser https://registry.npmjs.org/

# Intentar con registro detallado
npm install -g codingbuddy-claude-plugin --verbose

  3. Versión de Node muy antigua

    node --version
# Requiere Node.js 18+
# Actualice Node.js si es necesario

Problemas del Marketplace

Error "Invalid marketplace schema"

Síntoma: claude marketplace add falla con:

✘ Failed to add marketplace: Invalid marketplace schema from URL: : Invalid input: expected object, received string

Causa: Usando formato de URL en lugar del formato de repositorio de GitHub.

Solución:

# Incorrecto (formato URL - obsoleto)
claude marketplace add https://jeremydev87.github.io/codingbuddy

# Correcto (formato de repositorio GitHub)
claude marketplace add JeremyDev87/codingbuddy

Migración desde Formato URL

Si anteriormente agregó el marketplace usando el formato URL:

# 1. Eliminar marketplace antiguo
claude marketplace remove https://jeremydev87.github.io/codingbuddy

# 2. Agregar con formato correcto
claude marketplace add JeremyDev87/codingbuddy

# 3. Reinstalar el plugin
claude plugin install codingbuddy@jeremydev87

Marketplace No Encontrado

Síntoma: claude marketplace add JeremyDev87/codingbuddy falla con "not found"

Soluciones:

  1. Verificar ortografía y mayúsculas/minúsculas

    • Nombre de usuario GitHub: JeremyDev87 (distingue mayúsculas)
    • Repositorio: codingbuddy

  2. Verificar conectividad de red

    curl -I https://github.com/JeremyDev87/codingbuddy

  3. Actualizar Claude Code

    npm update -g @anthropic-ai/claude-code

Problemas de Conexión MCP

El Servidor MCP No Conecta

Síntoma: Los comandos de flujo de trabajo (PLAN, ACT, EVAL) no se activan correctamente, no se muestra el agente.

Diagnóstico:

# Verificar si el CLI de codingbuddy está instalado
which codingbuddy
codingbuddy --version

# Verificar configuración MCP
cat ~/.claude/settings.json | grep -A5 codingbuddy

Soluciones:

  1. Instalar el servidor MCP

    npm install -g codingbuddy

  2. Agregar configuración MCP

    Edite ~/.claude/settings.json:

    {
  "mcpServers": {
    "codingbuddy": {
      "command": "codingbuddy",
      "args": []
    }
  }
}

  3. Reiniciar Claude Code

    # Salga y reinicie
claude

Las Herramientas MCP No Están Disponibles

Síntoma: El comando /mcp no muestra las herramientas de CodingBuddy.

Soluciones:

  1. Verificar que el servidor MCP está ejecutándose

    # En una terminal separada, ejecute:
codingbuddy
# Debe iniciarse sin errores

  2. Verificar que PATH incluye codingbuddy

    echo $PATH
which codingbuddy
# Si no se encuentra, agregue al PATH

  3. Verificar conflictos de servidores MCP

    cat ~/.claude/settings.json
# Asegúrese de que no hay entradas duplicadas para codingbuddy

"Command not found: codingbuddy"

Síntoma: MCP intenta ejecutar codingbuddy pero no se encuentra.

Soluciones:

  1. Agregar el directorio bin global de npm al PATH

    # Para npm
export PATH="$(npm config get prefix)/bin:$PATH"

# Para yarn
export PATH="$(yarn global bin):$PATH"

  2. Usar ruta absoluta en configuración MCP

    {
  "mcpServers": {
    "codingbuddy": {
      "command": "/usr/local/bin/codingbuddy",
      "args": []
    }
  }
}

Problemas de Flujo de Trabajo

Las Palabras Clave PLAN/ACT/EVAL No Se Reconocen

Síntoma: Escribir "PLAN implement X" no activa el modo de flujo de trabajo.

Soluciones:

  1. Verificar que la palabra clave está al inicio del mensaje

    # Correcto
PLAN implement user login

# Incorrecto - palabra clave no al inicio
Can you PLAN implement user login

  2. Usar mayúsculas o palabras clave localizadas

    PLAN ...
계획 ...  (Coreano)
計画 ...  (Japonés)
PLANIFICAR ... (Español)

  3. Verificar que MCP está conectado

    • Escriba /mcp para ver herramientas disponibles
    • Debe mostrar la herramienta parse_mode

El Contexto No Se Persiste

Síntoma: El modo ACT no recuerda las decisiones de PLAN.

Soluciones:

  1. Verificar que existe el archivo de contexto

    cat docs/codingbuddy/context.md

  2. Asegurar que PLAN se completó correctamente

    • El modo PLAN crea el archivo de contexto
    • Si se interrumpió, reinicie con PLAN

  3. Verificar permisos de archivo

    ls -la docs/codingbuddy/
# Asegure permisos de escritura

El Modo AUTO No Se Detiene

Síntoma: El modo AUTO sigue iterando incluso cuando los problemas están corregidos.

Soluciones:

  1. Verificar límite de iteraciones

    • El límite por defecto es 5 iteraciones
    • AUTO se detiene cuando Critical=0 Y High=0

  2. Revisar hallazgos de EVAL

    • Algunos problemas pueden ser recurrentes
    • Aborde la causa raíz, no los síntomas

  3. Intervención manual

    • Escriba cualquier mensaje para interrumpir AUTO
    • Revise los hallazgos, luego reinicie si es necesario

Problemas de Rendimiento

Tiempos de Respuesta Lentos

Síntoma: Claude tarda mucho tiempo en responder en los modos de flujo de trabajo.

Soluciones:

  1. Simplificar la tarea

    • Divida tareas complejas en partes más pequeñas
    • Use PLAN para una funcionalidad a la vez

  2. Reducir agentes especialistas

    • Configure menos especialistas en codingbuddy.config.json
    module.exports = {
  specialists: ['security-specialist']  // Solo los esenciales
};

  3. Verificar tamaño del contexto

    • Archivos de contexto grandes ralentizan el procesamiento
    • Inicie un nuevo PLAN para nuevas funcionalidades

Alto Uso de Tokens

Síntoma: Alcanzando límites de contexto rápidamente.

Soluciones:

  1. Usar prompts enfocados

    # Mejor
PLAN add email validation to registration

# Menos eficiente
PLAN review the entire auth module and add validation

  2. Dejar que el contexto se compacte naturalmente

    • Claude Code resume automáticamente el contexto antiguo
    • No repita manualmente el contexto anterior

Problemas de Configuración

La Configuración del Proyecto No Se Carga

Síntoma: La configuración de codingbuddy.config.json no se aplica.

Soluciones:

  1. Verificar ubicación del archivo

    • Debe estar en la raíz del proyecto
    • Nombrado exactamente codingbuddy.config.json

  2. Verificar sintaxis

    node -e "console.log(require('./codingbuddy.config.json'))"

  3. Verificar formato de exportación

    // Correcto
module.exports = { language: 'es' };

// Incorrecto
export default { language: 'es' };

Respuestas en Idioma Incorrecto

Síntoma: Claude responde en el idioma incorrecto.

Soluciones:

  1. Establecer idioma en configuración

    // codingbuddy.config.json
module.exports = {
  language: 'es'  // 'en', 'ko', 'ja', 'zh', 'es'
};

  2. Usar variable de entorno

    export CODINGBUDDY_LANGUAGE=es

  3. Usar palabras clave localizadas

    • Comience con español: PLANIFICAR implementar login de usuario
    • Claude responderá en español

Modo de Depuración

Habilitar Registro Detallado

Para depuración detallada:

# Ejecutar servidor MCP con salida de depuración
CODINGBUDDY_DEBUG=true codingbuddy

Verificar Comunicación MCP

# En Claude Code, verificar estado MCP
/mcp

# Debe mostrar:
# - Estado del servidor codingbuddy
# - Herramientas disponibles
# - Último error si hay alguno

Revisar Documento de Contexto

# Verificar qué contexto está persistido
cat docs/codingbuddy/context.md

# Buscar:
# - Decisiones previas de PLAN
# - Progreso de ACT
# - Hallazgos de EVAL

Obtener Ayuda

Reportar Problemas

  1. Issues de GitHub: github.com/JeremyDev87/codingbuddy/issues

  2. Incluir en el reporte:

    • Versión de Claude Code (claude --version)
    • Versión del plugin (de plugin.json)
    • Versión del servidor MCP (codingbuddy --version)
    • Pasos para reproducir
    • Mensajes de error

Consultar Documentación

Lista de Verificación de Diagnóstico Rápido

[ ] Node.js 18+ instalado
[ ] Claude Code 1.0+ instalado
[ ] Plugin visible en `claude plugin list`
[ ] Servidor MCP instalado (`which codingbuddy`)
[ ] Configuración MCP en settings.json
[ ] Puede ver herramientas con `/mcp`
[ ] Palabra clave PLAN activa el modo
[ ] Archivo de contexto creado después de PLAN

🤖 Este documento fue traducido con asistencia de IA. Si encuentras errores o sugerencias de mejora, por favor repórtalos en GitHub Issues.