Habilidad de Investigación
Stack Tecnológico: AWS CLI, Git, ripgrep, jq, curl, DevTools del navegador
Fuente: Extraído de los principios de investigación y patrones de depuración de CLAUDE.md.
Cuándo Usar Esta Habilidad
Usa la habilidad de investigación cuando:
- ✓ El mismo error persiste después de 2+ intentos de corrección
- ✓ Necesitas comprender una base de código desconocida
- ✓ Estás investigando incidentes de producción
- ✓ Estás tomando decisiones arquitectónicas
- ✓ Estás depurando interacciones complejas del sistema
- ✓ Estás aprendiendo una nueva tecnología/biblioteca
NO uses esta habilidad para:
- ✗ Primer intento de corrección (prueba primero la solución obvia)
- ✗ Problemas bien comprendidos (simplemente arréglalos)
- ✗ Incidentes críticos de tiempo (corrige primero, investiga después)
Árbol de Decisión Rápida para Investigación
¿Cuál es el problema?
├─ ¿Es la primera vez que ves este problema?
│ ├─ SÍ → Intenta la corrección obvia (iteración)
│ └─ NO → ¿El mismo error después de 2 intentos? → INVESTIGACIÓN
│
├─ ¿Incidente de producción?
│ ├─ ¿Afecta a usuarios AHORA? → Reversión/corrección rápida primero, investigar después
│ └─ ¿Análisis posterior al incidente? → Investigación profunda
│
├─ ¿Necesitas comprender la base de código?
│ ├─ ¿Función/módulo específico? → Leer código + pruebas
│ ├─ ¿Arquitectura del sistema? → Rastrear el flujo de solicitudes
│ └─ ¿Contexto histórico? → Git blame + historial de commits
│
├─ ¿Decisión tecnológica?
│ ├─ Leer documentación oficial (no publicaciones de blog)
│ ├─ Comparar alternativas (compensaciones)
│ ├─ Crear prototipo con un caso de uso real
│ └─ Documentar la decisión (ADR)
│
└─ ¿Integración de API/Biblioteca?
├─ Leer requisitos de tipo (no asumir)
├─ Verificar compatibilidad de versiones
├─ Probar un ejemplo mínimo
└─ Verificar con datos reales
Patrón de Bucle: Meta-Bucle → Inicial-Sensible
Desencadenante de Escalada:
/reflectrevela: "He intentado 3 correcciones, todas fallaron con el mismo error"- La salida de
/tracees idéntica en todos los intentos - Patrón: Atascado en un bucle de reintento (la ejecución cambia, el resultado no)
- Acción: Usa
/hypothesispara cuestionar suposiciones (cambiar a inicial-sensible)
Herramientas Utilizadas:
/observe- Observar el comportamiento del sistema (qué está fallando)/hypothesis- Generar explicaciones alternativas (¿por qué podría fallar de manera diferente a lo que pienso?)/research- Probar hipótesis sistemáticamente/validate- Verificar si la nueva comprensión es correcta/reflect- Sintetizar aprendizajes después de la investigación
Por Qué Funciona: La habilidad de investigación se ajusta naturalmente al bucle inicial-sensible: estás cuestionando suposiciones, no solo corrigiendo la ejecución.
Consulta Arquitectura del Proceso de Pensamiento - Bucles de Retroalimentación para una visión estructural.
Principios Básicos de Investigación
Principio 1: Investigar Antes de Iterar
De CLAUDE.md:
"Cuando el mismo error persiste después de 2 intentos de corrección, DEJA DE ITERAR y EMPIEZA A INVESTIGAR. Invierte 30-60 minutos en comprender la causa raíz en lugar de implementar más suposiciones."
Por Qué Es Importante:
- ❌ Iteración: Retroalimentación rápida, pero derrochadora después de 2+ intentos fallidos
- ✅ Investigación: Costo inicial, previene 3+ ciclos de implementación fallidos
Patrón:
Intento 1: Hipótesis + Implementación (8 minutos)
↓ Falló
Intento 2: Hipótesis diferente + Implementación (8 minutos)
↓ Falló
Intento 3: ❌ DETENER - No implementes otra suposición
CAMBIAR A MODO DE INVESTIGACIÓN:
- Leer especificaciones/documentación (15 minutos)
- Inspeccionar datos reales (10 minutos)
- Reproducir localmente (20 minutos)
- Identificar causa raíz (15 minutos)
↓ Total: 60 minutos de investigación
Intento 3 (con causa raíz): Implementar corrección (8 minutos)
✅ Éxito
Tiempo total: 76 minutos (vs 120+ minutos con iteración ciega)
Principio 2: Leer Fuentes Primarias
Jerarquía de Calidad de la Información:
| Tipo de Fuente | Fiabilidad | Cuándo Usar |
|---|---|---|
| Documentación Oficial | Más Alta | Primer paso para comportamiento de API, requisitos de tipo |
| Código Fuente | Muy Alta | Cuando la documentación no es clara o está incompleta |
| Issues de GitHub | Alta | Para errores conocidos, casos límite, soluciones alternativas |
| Stack Overflow | Media | Para problemas comunes, después de leer la documentación |
| Publicaciones de Blog | Baja | Para conceptos generales, no detalles de implementación |
| ChatGPT/IA | Más Baja | Solo punto de partida, siempre verificar |
Ejemplo: Integración del Sistema de Tipos
# ❌ NO HAGAS: Preguntar a ChatGPT "¿Acepta PyMySQL diccionarios para columnas JSON?"
# ChatGPT podría alucinar o dar una respuesta desactualizada
# ✅ HAZ: Leer la documentación de PyMySQL
open https://pymysql.readthedocs.io/en/latest/
# ✅ HAZ: Probar con un ejemplo mínimo
python3 << 'EOF'
import pymysql
import json
# Prueba: ¿Acepta PyMySQL un dict para columna JSON?
data = {'key': 'value'}
try:
cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
print("✅ Dict aceptado")
except TypeError as e:
print(f"❌ Dict rechazado: {e}")
# Probar con cadena JSON en su lugar
cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
print("✅ Cadena JSON aceptada")
EOF
Principio 3: Reproducir Localmente
Antes de implementar correcciones, reproduce el problema localmente.
Beneficios:
- ✅ Iteración rápida (segundos vs minutos)
- ✅ Se puede depurar con puntos de interrupción
- ✅ Sin costos en la nube
- ✅ Se pueden probar casos límite fácilmente
Patrón:
# Paso 1: Extraer el caso mínimo de fallo
# En lugar de probar toda la función Lambda...
# ❌ MALO: Implementar en AWS, revisar registros, repetir
aws lambda invoke --function-name worker --payload '{}' /tmp/response.json
# Esperar 30 segundos por los registros de CloudWatch...
# ✅ BUENO: Reproducir localmente
python3 << 'EOF'
from src.data.news_fetcher import NewsFetcher
# Mismo código exacto que Lambda
fetcher = NewsFetcher()
result = fetcher.fetch_news('NVDA19')
print(result) # Retroalimentación inmediata
EOF
Principio 4: Inspeccionar Datos Reales
No asumas la forma de los datos; verifica con ejemplos reales.
Errores Comunes:
- Asumir que la API devuelve un dict (podría devolver una lista)
- Asumir que el campo existe (podría ser nulo/estar ausente)
- Asumir el tipo (podría ser string, no int)
Patrón:
# ❌ NO HAGAS: Asumir
# "La API devuelve una lista de tickers"
# ✅ HAZ: Verificar
curl -s https://api.example.com/tickers | jq . > sample_response.json
cat sample_response.json
# Inspeccionar estructura:
# - ¿Es una lista o un dict?
# - ¿Qué campos están presentes?
# - ¿Qué tipos tienen?
# - ¿Hay valores nulos?
# - ¿Hay estructuras anidadas?
Ejemplo: Investigación de Esquema de Aurora
# Conectarse a Aurora a través del túnel SSM
aws ssm start-session \
--target i-1234567890abcdef0 \
--document-name AWS-StartPortForwardingSessionToRemoteHost \
--parameters '{"host":["aurora-endpoint"],"portNumber":["3306"],"localPortNumber":["3307"]}'
# Inspeccionar el esquema real (no asumir)
mysql -h 127.0.0.1 -P 3307 -u admin -p << 'SQL'
DESCRIBE precomputed_reports;
-- Verificar tipos de datos reales
SELECT
symbol,
report_json,
typeof(report_json) as json_type
FROM precomputed_reports
LIMIT 1 \G
-- Verificar valores nulos
SELECT COUNT(*) as total,
SUM(CASE WHEN report_json IS NULL THEN 1 ELSE 0 END) as null_count
FROM precomputed_reports;
SQL
Flujo de Trabajo de Investigación
Consulta WORKFLOW.md para un proceso de investigación detallado paso a paso.
Lista de Verificación de Investigación
Consulta INVESTIGATION-CHECKLIST.md para una lista de verificación sistemática de depuración.
Verificación de Límites
Cuándo: Al investigar sistemas distribuidos (Lambda, Aurora, S3, SQS, Step Functions)
Problema: El código parece correcto pero falla en producción debido a límites de ejecución no verificados
Preguntas críticas:
- ¿DÓNDE se ejecuta este código? (¿Lambda, EC2, local?)
- ¿QUÉ entorno requiere? (¿variables de entorno, red, permisos?)
- ¿QUÉ sistemas externos llama? (¿esquema de Aurora, bucket de S3, formato de API?)
- ¿CUÁLES son las propiedades de la entidad? (¿tiempo de espera/memoria de Lambda, límites de conexión de Aurora, uso previsto?)
- ¿CÓMO verifico el contrato? (¿configuración de Terraform, SHOW COLUMNS, prueba de acceso?)
Cinco capas de corrección:
- Sintáctica: El código compila (sintaxis de Python válida)
- Semántica: El código hace lo que afirma (lógica correcta)
- Límite: El código puede alcanzar lo que necesita (red, permisos)
- Configuración: La configuración de la entidad coincide con los requisitos del código (tiempo de espera, memoria)
- Intencional: El uso coincide con el propósito diseñado (Lambda síncrona no para trabajo asíncrono)
Cuándo aplicar:
- Errores de "el código parece correcto pero no funciona"
- Flujos de trabajo de múltiples servicios (Lambda → Aurora → S3)
- Después de 2 intentos de implementación fallidos (problemas de infraestructura)
- Antes de concluir que "el código es correcto" (verificar el contexto de ejecución)
Flujo de trabajo de verificación:
1. Identificar límites de ejecución (código → tiempo de ejecución, código → base de datos, servicio → servicio)
2. Identificar entidades físicas (QUÉ Lambda, QUÉ Aurora, QUÉ bucket de S3)
3. Verificar que la configuración coincida con los requisitos (tiempo de espera, memoria, concurrencia)
4. Verificar que la intención coincida con el uso (Lambda asíncrona no para API síncrona)
5. Avanzar a través de las capas de evidencia (código → configuración → tiempo de ejecución → verdad fundamental)
Integración con el flujo de trabajo de investigación:
- Fase 1 (Observar): Notar fallas relacionadas con límites (tiempo de espera, permiso denegado, discrepancia de esquema)
- Fase 2 (Hipótesis): Identificar qué límite podría estar siendo violado
- Fase 3 (Investigación): Aplicar la lista de verificación de verificación de límites sistemáticamente
- Fase 4 (Validar): Verificar el contrato a través de la verdad fundamental (probar la ejecución real)
Ver: Lista de Verificación de Límites de Ejecución para un flujo de trabajo de verificación completo
Principios relacionados:
- Principio #20 (Disciplina de Límites de Ejecución) - CLAUDE.md
- Principio #2 (Fortalecimiento Progresivo de la Evidencia) - Verificar a través de todas las capas
- Principio #15 (Contrato Infraestructura-Aplicación) - Sincronizar código e infraestructura
Investigaciones Arquitectónicas
Cuándo: Al elegir entre tecnologías, patrones o enfoques arquitectónicos
Problema: Las comparaciones "X vs Y" obtienen respuestas vagas de "depende" sin un análisis estructurado
Solución: Aplicar un marco de análisis de relaciones basado en OWL para una comparación sistemática
Pasos:
-
Definir los conceptos a comparar
- ¿Qué es X? (definición, ubicación, propósito, ejemplos)
- ¿Qué es Y? (definición, ubicación, propósito, ejemplos)
-
Aplicar los 4 tipos de relación:
- Parte-Todo: ¿Es uno parte del otro, o son pares?
- Complemento: ¿Manejan preocupaciones no superpuestas que funcionan juntas?
- Sustitución: ¿Puede uno reemplazar al otro? ¿Bajo qué condiciones?
- Composición: ¿Pueden ser estratificados/compuestos en un sistema de múltiples capas?
-
Documentar con ejemplos concretos
- Proporcionar escenarios reales, no teoría abstracta
- Incluir análisis de compensaciones (qué se gana vs qué se pierde)
-
Hacer recomendación basada en el análisis
- Fundamentada en el análisis de relaciones, no en la intuición
- Incluir antipatrones a evitar
Ver: Guía de Análisis de Relaciones para una metodología completa
Ejemplos de Casos de Uso:
- "¿Debería usar Redis o DynamoDB para almacenamiento en caché?" → Aplicar análisis de sustitución y composición
- "¿Cómo se relacionan la CDN y el almacenamiento en caché de la aplicación?" → Aplicar análisis de complemento y composición
- "¿Microservicios vs Monolito?" → Aplicar análisis de parte-todo y compensaciones
Escenarios Comunes de Investigación
Escenario 1: Discrepancia del Sistema de Tipos
Síntoma: Mismo error después de 2 intentos, fallo silencioso
Pasos de Investigación:
-
Leer la Documentación del Sistema Objetivo
# Documentación de PyMySQL open https://pymysql.readthedocs.io/en/latest/modules/cursors.html # Buscar: ¿Qué tipos acepta execute()? -
Probar Ejemplo Mínimo
import pymysql import json # Probar hipótesis: Dict vs cadena JSON data = {'key': 'value'} # Prueba 1: Dict try: cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,)) except TypeError as e: print(f"Dict falló: {e}") # Prueba 2: Cadena JSON cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),)) print("Cadena JSON exitosa") -
Aplicar Corrección con Confianza
# Ahora SABEMOS que json.dumps() es necesario def store_report(symbol: str, report_json: dict): cursor.execute( "INSERT INTO reports (symbol, report_json) VALUES (%s, %s)", (symbol, json.dumps(report_json)) # Convertir a cadena )
Escenario 2: Incidente de Producción
Síntoma: Usuarios reportando errores, el panel muestra un pico
Pasos de Investigación:
-
Triaje (< 5 minutos)
# Verificar recuento de errores aws logs filter-log-events \ --log-group-name /aws/lambda/worker \ --start-time $(($(date +%s) - 600))000 \ --filter-pattern "ERROR" \ --query 'length(events)' # Verificar cuándo comenzó aws cloudwatch get-metric-statistics \ --namespace AWS/Lambda \ --metric-name Errors \ --dimensions Name=FunctionName,Value=worker \ --start-time $(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%S) \ --end-time $(date -u +%Y-%m-%dT%H:%M:%S) \ --period 60 \ --statistics Sum -
Mitigación Inmediata (< 10 minutos)
# Revertir a la versión anterior CURRENT=$(aws lambda get-alias --function-name worker --name live \ --query 'FunctionVersion' --output text) PREVIOUS=$((CURRENT - 1)) aws lambda update-alias \ --function-name worker \ --name live \ --function-version $PREVIOUS echo "Reversión de v$CURRENT a v$PREVIOUS completada" -
Análisis Posterior al Incidente (30-60 minutos)
# Recopilar evidencia mkdir incident-$(date +%Y%m%d-%H%M%S) cd incident-* # Exportar registros de errores aws logs filter-log-events \ --log-group-name /aws/lambda/worker \ --start-time $INCIDENT_START \ --end-time $INCIDENT_END \ --filter-pattern "ERROR" > errors.json # Exportar métricas aws cloudwatch get-metric-statistics ... > metrics.json # Obtener diff de implementación git diff v$PREVIOUS v$CURRENT > deployment.diff # Analizar (análisis de causa raíz) # - ¿Qué cambió? # - ¿Qué falló? # - ¿Por qué falló? # - ¿Cómo prevenir?
Escenario 3: Base de Código Desconocida
Tarea: Agregar funcionalidad a un módulo que nunca has visto
Pasos de Investigación:
-
Encontrar el Punto de Entrada
# Buscar función principal rg "def main" rg "if __name__ == '__main__'" # Seguir las importaciones para mapear dependencias rg "from src" --type py -
Leer el Código Fuente
# Leer el archivo principal cat src/data/news_fetcher.py # Buscar tipos/clases clave rg "class Fetch" --type py -
Comprender las Pruebas
# Buscar archivos de prueba para el módulo rg "news_fetcher" tests/ -l cat tests/test_news_fetcher.py | head -50 -
Revisar el Historial de Git
# Ver cambios recientes git log --oneline -10 src/data/news_fetcher.py # Ver cómo cambió con el tiempo git log -p --follow src/data/news_fetcher.py | head -100 -
Ejecutar el Código con Depuración
# Agregar declaraciones de impresión para rastrear el flujo python3 -c " from src.data.news_fetcher import NewsFetcher fetcher = NewsFetcher() import pdb; pdb.set_trace() # Punto de interrupción result = fetcher.fetch_news('AAPL') print(result) "
Ejemplos de Llamadas a la API de Claude
{
"name": "majiayu000/skill-registro-datos-claude",
"description": "Investigación sistemática y análisis de causa raíz.",
"aiSummary": "Habilidad para realizar investigaciones sistemáticas y análisis de causa raíz en sistemas complejos."
}