# Cortana - Asistente de Desarrollo Basado en IA

## Introducción

Cortana es una potente herramienta de asistencia para desarrollo basada en IA que te permite interactuar con un modelo de lenguaje avanzado directamente desde tu terminal. Funciona como una interfaz de línea de comandos (CLI) para Claude, proporcionando capacidades de comprensión y generación de código, resolución de problemas, revisión de código, documentación y más.

Implementada como parte del ecosistema MRDevs Tools, Cortana aprovecha la tecnología de Claude para ofrecer un asistente programable que se integra perfectamente en tu flujo de trabajo de desarrollo.

## Instalación y Configuración

### Requisitos Previos

- MRDevs Tools instalado (ejecutar `bin/bootstrap.sh` previamente)
- Conexión a Internet
- Token de API de Anthropic válido

### Instalación Básica

```bash
# Instalar Cortana CLI
bin/claude_install.sh

# Configurar el token de API (necesario solo una vez)
bin/cortana_token.sh
```

El proceso de instalación descarga la última versión de Claude Code CLI y configura el entorno necesario. El token se encripta mediante SOPS y se almacena de forma segura en `$HOME/.cortana/cortana.sops.yaml`.

### Configuración de Alias

Para facilitar el uso, puedes configurar un alias permanente:

```bash
# Crear alias 'cortana' para el comando 'claude'
bin/cortana_alias.sh

# Habilitar el alias permanentemente
bin/cortana_enable.sh
```

Esto te permitirá usar el comando `cortana` en lugar de `claude` para todas las operaciones.

### Actualización y Desinstalación

```bash
# Actualizar Cortana a la última versión
bin/claude_install.sh --update

# Desinstalar Cortana
bin/claude_install.sh -u
```

## Uso Básico

### Iniciar una Sesión Interactiva

```bash
cortana
```

Esto inicia una sesión interactiva donde puedes conversar con Cortana directamente en la terminal.

### Realizar una Consulta Puntual

```bash
cortana "¿Cómo implementar autenticación JWT en Node.js?"
```

### Trabajar con Archivos y Proyectos

```bash
# Abrir una sesión con acceso a un archivo específico
cortana --file path/to/file.js

# Abrir una sesión en un directorio específico
cortana --dir path/to/project/

# Abrir múltiples archivos
cortana --file file1.js --file file2.js
```

### Lectura de Datos desde STDIN

```bash
cat file.js | cortana "Explica este código"
```

## Comandos y Opciones Avanzadas

### Opciones de Configuración

```bash
# Establecer un modelo específico
cortana --model claude-3-opus-20240229

# Cambiar la temperatura de generación
cortana --temperature 0.7

# Limitar la longitud máxima de respuesta
cortana --max-tokens 4000
```

### Flags Comunes

| Flag | Descripción |
|------|-------------|
| `--model` | Especifica qué modelo de Claude usar |
| `--temperature` | Controla la aleatoriedad (0.0-1.0) |
| `--file` | Incluye un archivo en el contexto |
| `--dir` | Incluye un directorio en el contexto |
| `--max-tokens` | Limita la longitud de respuesta |
| `--help` | Muestra la ayuda del comando |
| `--version` | Muestra la versión instalada |

## Casos de Uso Comunes

### Generación de Código

```bash
# Generar una función basada en una descripción
cortana "Escribe una función en Python que calcule el factorial de un número de forma recursiva"

# Implementar una característica específica
cortana --file app.js "Agrega manejo de errores a esta función"
```

### Revisión y Mejora de Código

```bash
# Revisar código existente
cortana --file script.js "Revisa este código y sugiere mejoras de rendimiento"

# Refactorizar código
cortana --file legacy.py "Refactoriza este código para hacerlo más modular y mantenible"
```

### Depuración

```bash
# Ayuda con errores
cortana --file buggy.js "Este código da el error 'TypeError: Cannot read property'. ¿Puedes identificar el problema?"

# Optimización de rendimiento
cortana --file slow.js "Este código es lento al procesar grandes conjuntos de datos. ¿Cómo puedo optimizarlo?"
```

### Documentación y Explicación

```bash
# Generar documentación para código existente
cortana --file module.js "Genera documentación JSDoc completa para este módulo"

# Explicar código complejo
cortana --file complex_algorithm.py "Explica cómo funciona este algoritmo paso a paso"
```

### Pruebas Unitarias

```bash
# Generar pruebas unitarias
cortana --file utils.js "Genera pruebas unitarias completas para estas funciones utilizando Jest"
```

## Control por Voz (Experimental)

MRDevs Tools incluye soporte experimental para interacción por voz con Cortana:

```bash
# Iniciar modo interactivo por voz
bin/claude_voice.py

# Seleccionar idioma específico
bin/claude_voice.py --language en-us

# Modo continuo (escucha hasta que digas "salir")
bin/claude_voice.py --continuous
```

## Buenas Prácticas

### Optimización de Consumo de Tokens

Para reducir el consumo de tokens y mejorar la eficiencia:

1. **Sé específico en tus consultas**
   ```bash
   # Ineficiente (consume más tokens)
   cortana "Ayúdame con JavaScript"
   
   # Eficiente (consume menos tokens)
   cortana "Explica cómo implementar debounce en JavaScript"
   ```

2. **Delimita el alcance de tu consulta**
   ```bash
   cortana "Crea una función de validación para emails. Solo incluye el código, sin explicaciones."
   ```

3. **Utiliza flags para limitar respuestas**
   ```bash
   cortana --max-tokens 1000 "Resumen conciso de patrones de diseño en Node.js"
   ```

4. **Aprovecha el contexto compartido**
   - En lugar de hacer múltiples consultas independientes, continúa una conversación para aprovechar el contexto compartido.

5. **Selecciona el modelo adecuado**
   ```bash
   # Para tareas simples y rápidas
   cortana --model claude-3-haiku-20240307 "Corrige esta sintaxis de JavaScript: fuction test(a, b { retrun a+b }"
   
   # Para tareas más complejas que requieren mayor profundidad
   cortana --model claude-3-opus-20240229 "Diseña una arquitectura de microservicios para una aplicación de e-commerce"
   ```

6. **Reutiliza resultados anteriores**
   ```bash
   # Guardar una respuesta para uso posterior
   cortana "Crea un script de backup con rsync" > backup_script.sh
   ```

7. **Usa parámetros para consultas especializadas**
   ```bash
   # Ajustar temperatura para respuestas más deterministas
   cortana --temperature 0.1 "Genera tests unitarios para esta función"
   ```

### Mejores Prácticas de Uso

1. **Proporciona Contexto Suficiente**
   - Incluye archivos relevantes con `--file` o `--dir`
   - Explica el entorno de desarrollo y las dependencias

2. **Formula Consultas Claras**
   - Usa verbos de acción: "implementa", "analiza", "optimiza", "refactoriza"
   - Especifica el formato de salida deseado

3. **Trabajo con Proyectos**
   - Usa `--dir` para incluir todo el contexto del proyecto
   - Menciona versiones específicas de frameworks/librerías

4. **Seguridad y Datos Sensibles**
   - No compartas credenciales o tokens en las consultas
   - Revisa el código generado antes de ejecutarlo

5. **Organización del Trabajo**
   - Divide problemas complejos en consultas más pequeñas
   - Usa scripts específicos para tareas recurrentes

## Scripts de Utilidad

MRDevs Tools incluye varios scripts para facilitar el uso de Cortana:

```bash
# Activar el alias 'cortana' permanentemente
bin/cortana_enable.sh

# Desactivar temporalmente el alias
bin/cortana_disable.sh

# Gestionar el token de forma segura
bin/cortana_token.sh

# Control por voz
bin/claude_voice.py
```

## Integración con el Flujo de Trabajo

### Integración con Git

```bash
# Revisar cambios antes de commit
git diff | cortana "Revisa estos cambios y sugiere mejoras"

# Analizar un Pull Request
git show | cortana "Analiza este PR y proporciona feedback"
```

### Integración con Editores

**VS Code**
Puedes configurar un atajo de teclado para enviar el texto seleccionado a Cortana:

```json
{
  "key": "ctrl+alt+c",
  "command": "workbench.action.terminal.sendSequence",
  "args": {
    "text": "cat ${relativeFile} | cortana \"Explica este código\"\n"
  }
}
```

### Automatización de Tareas

Puedes crear scripts personalizados que usen Cortana para tareas específicas:

```bash
#!/bin/bash
# Script para generar tests unitarios

if [ -z "$1" ]; then
  echo "Uso: $0 <archivo.js>"
  exit 1
fi

file=$1
test_file=$(echo $file | sed 's/\.js$/.test.js/')

cortana --file "$file" "Genera tests unitarios exhaustivos para este archivo usando Jest. Incluye mocks necesarios y pruebas para casos de error." > "$test_file"

echo "Tests generados en $test_file"
```

## Solución de Problemas

### Problemas Comunes

| Problema | Solución |
|----------|----------|
| "Error de autenticación" | Ejecuta `bin/cortana_token.sh` para actualizar tu token |
| Respuestas truncadas | Usa `--max-tokens` con un valor más alto |
| Respuestas incorrectas/irrelevantes | Proporciona más contexto y sé más específico en tu consulta |
| "No se pudo conectar al servidor" | Verifica tu conexión a Internet |

### Verificación de Estado

```bash
# Verificar que Cortana está instalada correctamente
which cortana

# Verificar la versión instalada
cortana --version

# Comprobar la configuración del token (requiere SOPS configurado)
sops --decrypt $HOME/.cortana/cortana.sops.yaml
```

## Ejemplos Prácticos

### Análisis de Rendimiento de Aplicación

```bash
cortana --dir ./my-app "Analiza este código React y sugiere optimizaciones de rendimiento. Enfócate en componentes que pueden causar rerenderizados innecesarios y cómo implementar memoización."
```

### Creación de una API RESTful

```bash
cortana "Diseña una API RESTful completa para gestionar una biblioteca con usuarios, libros y préstamos. Incluye endpoints, estructura de datos, manejo de errores y documentación OpenAPI. Organiza la respuesta en archivos separados que pueda implementar directamente."
```

### Migración de Código Legacy

```bash
cortana --file legacy-app.php "Este código PHP usa una versión antigua (5.6). Actualízalo a PHP 8.0, utilizando características modernas como tipos estrictos, propiedades tipadas, y construcciones match. Mantén la funcionalidad original."
```

## Consideraciones Éticas y Limitaciones

### Limitaciones Actuales

- Cortana puede proporcionar información imprecisa o desactualizada
- El conocimiento está limitado a la fecha de corte del modelo
- No puede ejecutar código directamente ni acceder a recursos online
- Podría generar soluciones que no se adaptan perfectamente a tu caso específico

### Uso Ético

- No uses Cortana para generar código malicioso o engañoso
- Verifica y comprende el código generado antes de implementarlo
- Cita apropiadamente cuando uses asistencia de IA en trabajos académicos o profesionales
- Respeta los términos de servicio de Anthropic

## Créditos y Reconocimientos

Cortana está basada en Claude de Anthropic, un asistente de IA de última generación. Todas las capacidades de procesamiento de lenguaje natural son proporcionadas por Claude, mientras que la interfaz CLI y las integraciones específicas para desarrollo han sido implementadas por el equipo de MRDevs Tools.

## Recursos Adicionales

- [Documentación Oficial de Claude](https://docs.anthropic.com/)
- [Guía de Prompt Engineering](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
- [Buenas Prácticas de Desarrollo con IA](https://docs.anthropic.com/claude/docs/building-with-claude)

---

Creado por Cortana Rosero One para MRDevs Tools.
Última actualización: 2025/04/07