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 o más intentos de corrección
- ✓ Necesitas entender un código base desconocido
- ✓ Investigas incidentes de producción
- ✓ Tomas decisiones arquitectónicas
- ✓ Depuras interacciones complejas del sistema
- ✓ Aprendes una nueva tecnología o 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 (primero corrige, luego investiga)
Árbol de Decisión Rápido de Investigación
¿Cuál es el problema?
├─ ¿Es la primera vez que ves este problema?
│ ├─ SÍ → Prueba la solución obvia (iteración)
│ └─ NO → ¿Mismo error después de 2 intentos? → INVESTIGAR
│
├─ ¿Incidente de producción?
│ ├─ ¿Afecta a usuarios AHORA? → Reversión/corrección urgente primero, investiga después
│ └─ ¿Análisis post-incidente? → Investigación profunda
│
├─ ¿Necesitas entender el código base?
│ ├─ ¿Función/módulo específico? → Lee código + pruebas
│ ├─ ¿Arquitectura del sistema? → Traza el flujo de solicitudes
│ └─ ¿Contexto histórico? → Git blame + historial de commits
│
├─ ¿Decisión tecnológica?
│ ├─ Lee la documentación oficial (no publicaciones de blog)
│ ├─ Compara alternativas (compensaciones)
│ ├─ Crea un prototipo con un caso de uso real
│ └─ Documenta la decisión (ADR)
│
└─ ¿Integración de API/biblioteca?
├─ Lee los requisitos de tipo (no supongas)
├─ Verifica la compatibilidad de versiones
├─ Prueba un ejemplo mínimo
└─ Verifica con datos reales
Patrón de Bucle: Meta-Loop → Initial-Sensitive
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 reintentos (la ejecución cambia, el resultado no)
- Acción: Usa
/hypothesispara cuestionar suposiciones (cambia a initial-sensitive)
Herramientas Utilizadas:
/observe- Observa el comportamiento del sistema (qué está fallando)/hypothesis- Genera explicaciones alternativas (¿por qué podría fallar de manera diferente a lo que creo?)/research- Prueba hipótesis sistemáticamente/validate- Verifica si el nuevo entendimiento es correcto/reflect- Sintetiza lo aprendido después de la investigación
Por Qué Funciona: La habilidad de investigación encaja naturalmente con el bucle initial-sensitive—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 Fundamentales de Investigación
Principio 1: Investiga 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 entender 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 + Implementar (8 minutos)
↓ Falló
Intento 2: Hipótesis diferente + Implementar (8 minutos)
↓ Falló
Intento 3: ❌ DETENTE - No implementes otra suposición
CAMBIA A MODO DE INVESTIGACIÓN:
- Lee especificaciones/documentación (15 minutos)
- Inspecciona datos reales (10 minutos)
- Reproduce localmente (20 minutos)
- Identifica la causa raíz (15 minutos)
↓ Total: 60 minutos de investigación
Intento 3 (con causa raíz): Implementa la corrección (8 minutos)
✅ Éxito
Tiempo total: 76 minutos (vs 120+ minutos con iteración a ciegas)
Principio 2: Lee Fuentes Primarias
Jerarquía de Calidad de la Información:
| Tipo de Fuente | Fiabilidad | Cuándo Usar |
|---|---|---|
| Documentación Oficial | Más Alta | Primera parada 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 como punto de partida, siempre verifica |
Ejemplo: Integración de Sistema de Tipos
# ❌ NO HAGAS: Preguntar a ChatGPT "¿Acepta PyMySQL diccionarios para columnas JSON?"
# ChatGPT podría alucinar o dar una respuesta desactualizada
# ✅ HAZ: Lee la documentación de PyMySQL
open https://pymysql.readthedocs.io/en/latest/
# ✅ HAZ: Prueba con un ejemplo mínimo
python3 << 'EOF'
import pymysql
import json
# Prueba: ¿Acepta PyMySQL un diccionario para columna JSON?
data = {'key': 'value'}
try:
cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
print("✅ Diccionario aceptado")
except TypeError as e:
print(f"❌ Diccionario rechazado: {e}")
# Prueba 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: Reproduce 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 de nube
- ✅ Se pueden probar casos límite fácilmente
Patrón:
# Paso 1: Extrae el caso de fallo mínimo
# En lugar de probar toda la función Lambda...
# ❌ MAL: Implementar en AWS, revisar registros, repetir
aws lambda invoke --function-name worker --payload '{}' /tmp/response.json
# Espera 30 segundos por los registros de CloudWatch...
# ✅ BIEN: Reproduce 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: Inspecciona Datos Reales
No asumas la forma de los datos—verifica con ejemplos reales.
Errores Comunes:
- Suponer que la API devuelve un diccionario (podría devolver una lista)
- Suponer que un campo existe (podría ser nulo/estar ausente)
- Suponer el tipo (podría ser cadena, no entero)
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
# Inspecciona la estructura:
# - ¿Es una lista o un diccionario?
# - ¿Qué campos están presentes?
# - ¿Qué tipos son?
# - ¿Hay valores nulos?
# - ¿Hay estructuras anidadas?
Ejemplo: Investigación de Esquema de Aurora
# Conectar a Aurora a través de túnel SSM
aws ssm start-session \
--target i-1234567890abcdef0 \
--document-name AWS-StartPortForwardingSessionToRemoteHost \
--parameters '{"host":["aurora-endpoint"],"portNumber":["3306"],"localPortNumber":["3307"]}'
# Inspecciona el esquema real (no asumas)
mysql -h 127.0.0.1 -P 3307 -u admin -p << 'SQL'
DESCRIBE precomputed_reports;
-- Verifica los tipos de datos reales
SELECT
symbol,
report_json,
typeof(report_json) as json_type
FROM precomputed_reports
LIMIT 1 \G
-- Verifica si hay 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 detallado paso a paso de investigación.
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 las entidades? (¿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, acceso de prueba?)
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 con 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 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 fallos relacionados con límites (tiempo de espera, permiso denegado, discrepancia de esquema)
- Fase 2 (Hipótesis): Identificar qué límite podría estar violado
- Fase 3 (Investigación): Aplicar la lista 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 completo de verificación
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: ¿Uno es 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: ¿Se pueden combinar/componer 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 una recomendación basada en el análisis
- Basada 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 el almacenamiento en caché?" → Aplicar análisis de sustitución y composición
- "¿Cómo se relacionan la CDN y el almacenamiento en caché de aplicaciones?" → Aplicar análisis de complemento y composición
- "¿Microservicios vs Monolito?" → Aplicar análisis parte-todo y de compensaciones
Escenarios Comunes de Investigación
Escenario 1: Discrepancia en el 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 un Ejemplo Mínimo
import pymysql import json # Probar hipótesis: Diccionario vs cadena JSON data = {'key': 'value'} # Prueba 1: Diccionario try: cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,)) except TypeError as e: print(f"Diccionario falló: {e}") # Prueba 2: Cadena JSON cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),)) print("Cadena JSON tuvo éxito") -
Aplicar la 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 empezó 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 ACTUAL=$(aws lambda get-alias --function-name worker --name live \ --query 'FunctionVersion' --output text) ANTERIOR=$((ACTUAL - 1)) aws lambda update-alias \ --function-name worker \ --name live \ --function-version $ANTERIOR echo "Reversión de v$ACTUAL a v$ANTERIOR completada" -
Análisis Post-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 $INICIO_INCIDENTE \ --end-time $FIN_INCIDENTE \ --filter-pattern "ERROR" > errors.json # Exportar métricas aws cloudwatch get-metric-statistics ... > metrics.json # Obtener diff de implementación git diff v$ANTERIOR v$ACTUAL > deployment.diff # Analizar (análisis de causa raíz) # - ¿Qué cambió? # - ¿Qué falló? # - ¿Por qué falló? # - ¿Cómo prevenirlo?
Escenario 3: Código Base Desconocido
Tarea: Agregar una función a un módulo que nunca has visto
Pasos de Investigación:
- Encontrar el Punto de Entrada
# Buscar la función main rg "def main"
[truncado para traducción]
---
## Aprendizajes Clave
1. **Investiga antes de iterar**: Después de 2 intentos fallidos, cambia al modo de investigación.
2. **Lee fuentes primarias**: Confía en la documentación oficial y el código fuente sobre la información generada por IA.
3. **Reproduce localmente**: Evita implementar en la nube hasta que entiendas el problema.
4. **Inspecciona datos reales**: No asumas la forma de los datos—verifica con ejemplos reales.
5. **Verifica los límites**: En sistemas distribuidos, los errores a menudo provienen de límites de ejecución no verificados, no de la lógica del código.
6. **Usa un análisis estructurado**: Para decisiones arquitectónicas, aplica marcos de análisis de relaciones en lugar de argumentos intuitivos.