devs/docs/cortana.md

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

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

# 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

# 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

cortana

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

Realizar una Consulta Puntual

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

Trabajar con Archivos y Proyectos

# 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

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

Comandos y Opciones Avanzadas

Opciones de Configuración

# 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

# 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

# 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

# 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

# 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

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

# 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

   # 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

   cortana "Crea una función de validación para emails. Solo incluye el código, sin explicaciones."
   

3. Utiliza flags para limitar respuestas

   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

   # 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

   # Guardar una respuesta para uso posterior
   cortana "Crea un script de backup con rsync" > backup_script.sh
   

7. Usa parámetros para consultas especializadas

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

# 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

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

{
  "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:

#!/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

# 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

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

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

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

Archivo CLAUDE.md de Configuración

El archivo CLAUDE.md es una poderosa herramienta para personalizar y controlar el comportamiento de Cortana en proyectos específicos. Este archivo de configuración, cuando se coloca en la raíz de un proyecto, permite establecer parámetros, directrices y comportamientos personalizados que Cortana seguirá automáticamente al trabajar en ese proyecto.

Funcionalidades Básicas

Estructura Fundamental

Un archivo CLAUDE.md básico tiene la siguiente estructura:

# Instrucciones para Cortana

## Contexto del Proyecto
Este es un proyecto de [tipo de proyecto] que utiliza [tecnologías principales].

## Directrices
- Seguir el estilo de código establecido
- Documentar todas las funciones nuevas
- Mantener compatibilidad con [versión específica]

Información del Proyecto

Puedes incluir información esencial sobre el proyecto que Cortana debe conocer:

## Información del Proyecto
- **Nombre**: MyAwesomeProject
- **Tecnologías**: React, TypeScript, Express
- **Versión**: 2.3.4
- **Patrones de Diseño**: MVVM, Factory, Singleton

Convenciones de Código

Define las convenciones de código específicas del proyecto:

## Convenciones de Código
- Usar camelCase para variables y funciones
- Usar PascalCase para clases y componentes
- Incluir tipos explícitos en TypeScript
- Limitar líneas a 80 caracteres
- Usar async/await en lugar de Promises.then()

Funcionalidades Avanzadas

Reglas de Generación de Código

Puedes especificar reglas detalladas para la generación de código:

## Reglas para Generación de Código

### React Components
- Usar componentes funcionales con hooks
- Implementar prop-types o TypeScript interfaces
- Seguir patrón de presentación/contenedor

### Tests
- Crear tests unitarios con Jest
- Nombrar archivos de test como `*.test.ts`
- Implementar al menos un test por función pública

Variables y Constantes de Proyecto

Define variables o constantes específicas del proyecto:

## Variables de Proyecto
- BASE_API_URL=https://api.example.com/v2
- MAX_RETRIES=3
- LOG_LEVEL=debug
- FEATURE_FLAGS={ "newUI": true, "analytics": false }

Comandos Personalizados

Configura comandos personalizados para tareas comunes:

## Comandos
- build: npm run build
- test: npm test
- lint: eslint src/**/*.js
- deploy: ./scripts/deploy.sh

Parametrización Avanzada

Control de Modo de Interacción

Puedes controlar cómo debe comportarse Cortana en diferentes situaciones:

## Configuración de Interacción
- mode: expert        # Activa el modo experto con respuestas técnicas detalladas
- verbosity: concise  # Respuestas concisas (opciones: verbose, concise, minimal)
- think-aloud: true   # Muestra el proceso de razonamiento
- code-focus: true    # Prioriza la generación de código sobre explicaciones

Configuración de Modelos y Parámetros

Define configuraciones específicas para los modelos utilizados:

## Configuración de Modelo
- default-model: claude-3-opus-20240229
- fallback-model: claude-3-sonnet-20240229
- temperature: 0.3    # Para respuestas más deterministas
- top-p: 0.95         # Control sobre diversidad de tokens
- max-tokens-per-response: 4000

Plantillas de Respuesta

Configura plantillas para tipos específicos de respuestas:

## Plantillas de Respuesta

### Plantilla de Documentación
```js
/**
 * @function $NAME
 * @description $DESCRIPTION
 * @param {$PARAM_TYPE} $PARAM_NAME - $PARAM_DESCRIPTION
 * @returns {$RETURN_TYPE} $RETURN_DESCRIPTION
 * @example
 * $EXAMPLE_CODE
 */

Plantilla de Commit

$TYPE($SCOPE): $SHORT_DESCRIPTION

$DETAILED_DESCRIPTION

Issue: #$ISSUE_NUMBER

#### Integración con Herramientas

Especifica cómo integrar Cortana con otras herramientas del proyecto:

```markdown
## Integraciones
- git: true                  # Acceso al historial Git
- npm: true                  # Acceso a comandos npm
- linters: ["eslint", "prettier"]
- ci: ["github-actions"]
- package-manager: "yarn"

Matriz de Decisiones

Define matrices de decisión para guiar las recomendaciones:

## Matrices de Decisión

### Selección de Biblioteca Estado
| Caso de Uso | Recomendación |
|-------------|---------------|
| App pequeña | useState/useReducer |
| App mediana | Context API |
| App compleja | Redux Toolkit |
| App con muchos estados asíncronos | React Query + Context |

### Estrategia de Estilo
| Escenario | Recomendación |
|-----------|---------------|
| Componentes simples | CSS Modules |
| Componentes complejos | Styled Components |
| Design System | Chakra UI o MUI |

Implementación y Casos de Uso

Implementación por Proyecto

Puedes tener diferentes archivos CLAUDE.md para diferentes proyectos:

~/
├── proyecto-react/
│   └── CLAUDE.md  # Configuración específica para React
├── proyecto-python/
│   └── CLAUDE.md  # Configuración específica para Python

Implementación para Equipos

Para equipos de desarrollo, puedes estandarizar el archivo CLAUDE.md para mantener consistencia:

# Crear un CLAUDE.md estándar para el equipo
cat > template-CLAUDE.md << EOF
# Instrucciones para Cortana
...
EOF

# Instalarlo en un nuevo proyecto
cp template-CLAUDE.md ~/nuevo-proyecto/CLAUDE.md

Casos de Uso Especializados

Para Desarrollo de Microservicios:

## Contexto: Microservicios
- Servicio actual: inventory-service
- Protocolos: gRPC interno, REST externo
- Debe mantener API contratos en ./proto/
- Registro de servicios: Consul
- Comunicación asíncrona: Kafka

Para Ciencia de Datos:

## Contexto: Análisis de Datos
- Formato de datos: principalmente DataFrames pandas
- Visualización preferida: Seaborn, Plotly
- Métricas a reportar: precisión, recall, F1
- Conjuntos de datos en: ./data/processed/
- Notebooks en: ./notebooks/

Consejos para un CLAUDE.md Efectivo

1. Mantén la especificidad: Cuanto más específicas sean tus instrucciones, mejores serán los resultados.
2. Estructura con claridad: Usa encabezados y listas para organizar la información.
3. Evoluciona gradualmente: Actualiza el archivo a medida que el proyecto evoluciona.
4. Incluye ejemplos: Proporciona ejemplos específicos de lo que consideras código "bueno" y "malo".
5. Versionamiento: Mantén el archivo CLAUDE.md en control de versiones junto con el código.

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
• Guía de Prompt Engineering
• Buenas Prácticas de Desarrollo con IA

---

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