Módulo 1: Solo 3% Confía — Por Qué y Qué Hacer

Confianza Calibrada

Descripción de la cápsula

Ya conoces el problema (solo 3% confía) y los dos extremos peligrosos (aceptar todo vs rechazar todo). Ahora toca el punto medio. Confianza calibrada es la postura profesional que te permite usar AI coding tools con máxima productividad y mínimo riesgo. No es una fórmula mágica — es un principio: tu nivel de confianza debe ajustarse al tipo de tarea, al impacto de un error, y a tu capacidad de verificar el resultado.

En esta cápsula vas a entender qué es confianza calibrada, cómo funciona en la práctica, y por qué es el skill más importante para trabajar con AI-generated code. Piensa en esto como aprender a conducir: no frenas en cada esquina (rechazar todo) ni ignoras los semáforos (aceptar todo). Conduces con atención proporcional al contexto.

Qué Es Confianza Calibrada

Definición

Confianza calibrada es el proceso de ajustar tu nivel de confianza en código AI-generated basándote en factores objetivos, no en intuición o hábito.

Los factores son:

Confianza = f(
    tipo_de_tarea,      → ¿Qué tipo de código es?
    impacto_de_error,    → ¿Qué pasa si hay un bug?
    verificabilidad,     → ¿Puedo verificarlo fácilmente?
    familiaridad,        → ¿Conozco bien este dominio?
    complejidad           → ¿Qué tan complejo es el código?
)

No necesitas calcular una fórmula. Necesitas hacerte estas preguntas antes de aceptar o rechazar output.

El principio core

Invierte tiempo de revisión proporcional al riesgo. No proporcional a la cantidad de código.

Un endpoint de 100 líneas que solo hace CRUD puede requerir 3 minutos de revisión. Una función de 10 líneas que valida permisos puede requerir 15 minutos. El riesgo determina la revisión, no el tamaño.

Los 5 Factores de Calibración

Factor 1: Tipo de tarea

No todas las tareas son iguales. AI es consistentemente buena en algunas y consistentemente impredecible en otras:

AI es consistentemente BUENA en:
├── Boilerplate y setup
├── CRUD básico
├── Formateo y transformaciones de datos simples
├── Documentación y README
├── Configuración estándar (Docker, CI/CD)
└── Código que sigue patrones bien establecidos

AI es IMPREDECIBLE en:
├── Lógica de negocio específica
├── Seguridad y autenticación
├── Optimización de performance
├── Regex complejos
├── Código que depende de context que no le diste
└── Edge cases y error handling exhaustivo

AI es consistentemente MALA en:
├── Código que requiere entender state global del sistema
├── Integración con APIs que cambian frecuentemente
├── Debugging de issues que requieren reproducir en runtime
└── Decisiones de arquitectura a nivel sistema

Factor 2: Impacto de error

Pregúntate: "Si este código tiene un bug, ¿qué pasa?"

Impacto BAJO:
- Error en documentación → Se corrige fácil
- Bug en script de setup → Alguien reporta, se arregla
- Mal formateo → Cosmético

Impacto MEDIO:
- Bug en endpoint → Respuesta incorrecta al cliente
- Edge case no manejado → Crash en runtime para ciertos inputs
- Test incorrecto → Falsa confianza en calidad

Impacto ALTO:
- Security hole → Breach de datos
- Lógica de negocio incorrecta → Pérdida financiera
- Corrupción de datos → Irreversible
- Compliance failure → Legal

Factor 3: Verificabilidad

¿Qué tan fácil es verificar que el código es correcto?

FÁCIL de verificar:
- Código con output visible (print, return)
- Funciones puras (mismo input → mismo output)
- CRUD con datos de prueba
- Código con tests existentes

DIFÍCIL de verificar:
- Side effects (modifica base de datos, envía emails)
- Race conditions (solo aparecen bajo carga)
- Security (necesitas pensar como atacante)
- Lógica de negocio (necesitas entender el dominio)

Factor 4: Familiaridad

¿Qué tan bien conoces este dominio?

Si CONOCES el dominio:
- Puedes detectar errores sutiles rápidamente
- Tu revisión es más eficiente
- Puedes confiar más en tu review rápido
→ Calibra hacia arriba (más confianza si tu review es OK)

Si NO conoces el dominio:
- Errores sutiles pueden pasar desapercibidos
- Tu revisión es menos confiable
- Necesitas más tiempo y herramientas
→ Calibra hacia abajo (menos confianza, más verificación)

Factor 5: Complejidad

¿Qué tan complejo es el código generado?

BAJA complejidad:
- Flujo lineal (paso 1 → paso 2 → paso 3)
- Pocas dependencias
- Sin state management
→ Alta confianza, revisión rápida

ALTA complejidad:
- Múltiples branches y condiciones
- Dependencias cruzadas entre módulos
- State management complejo
- Concurrencia o async
→ Baja confianza, revisión exhaustiva

La Tabla de Calibración

Combinando los 5 factores, así se ve la calibración en la práctica:

Escenario	Confianza	Tiempo de revisión	Qué revisar
Generar README.md	90%	1-2 min	Que la info sea correcta
Boilerplate de proyecto	85%	2-3 min	Versiones de dependencias
CRUD endpoint	70%	5-8 min	Validaciones, error handling
Función de utilidad	65%	5-10 min	Edge cases, naming
Query SQL complejo	40%	10-15 min	Lógica del query, injection
Lógica de negocio	30%	15-20 min	Que haga lo que el negocio necesita
Auth / JWT	15%	20-30 min	Todo: tokens, expiración, secrets, roles
Validación de pagos	10%	30+ min	Cada línea + tests + compliance
Regex para validación	20%	15-20 min	Probar con inputs edge case
Tests generados por AI	50%	10-15 min	Que testen lo correcto, no solo que pasen

Cómo leer la tabla

Confianza 90%: Acepta casi siempre. Revisión visual de 1-2 minutos.
Confianza 50-70%: Revisa las partes importantes. 5-15 minutos.
Confianza 10-30%: No confíes. Lee cada línea, verifica contra documentación, escribe tests.

Confianza Calibrada en Acción

Ejemplo práctico: Generando una API

Imagina que le pides a Claude Code que genere una API de gestión de tareas. El output incluye:

# Claude Code generó esto
from fastapi import FastAPI, HTTPException, Depends
from pydantic import BaseModel, Field
from typing import Optional, List
from datetime import datetime
import uuid

app = FastAPI(title="Task Manager API")

tasks_db: dict = {}

class TaskCreate(BaseModel):
    title: str = Field(..., min_length=1, max_length=200)
    description: Optional[str] = None
    priority: str = Field(default="medium")

class Task(TaskCreate):
    id: str
    created_at: datetime
    completed: bool = False

@app.post("/tasks", response_model=Task)
async def create_task(task: TaskCreate):
    task_id = str(uuid.uuid4())
    new_task = Task(
        id=task_id,
        created_at=datetime.now(),
        **task.model_dump()
    )
    tasks_db[task_id] = new_task
    return new_task

@app.get("/tasks", response_model=List[Task])
async def list_tasks(completed: Optional[bool] = None):
    tasks = list(tasks_db.values())
    if completed is not None:
        tasks = [t for t in tasks if t.completed == completed]
    return tasks

@app.get("/tasks/{task_id}", response_model=Task)
async def get_task(task_id: str):
    if task_id not in tasks_db:
        raise HTTPException(status_code=404, detail="Task not found")
    return tasks_db[task_id]

@app.put("/tasks/{task_id}/complete")
async def complete_task(task_id: str):
    if task_id not in tasks_db:
        raise HTTPException(status_code=404, detail="Task not found")
    tasks_db[task_id].completed = True
    return tasks_db[task_id]

@app.delete("/tasks/{task_id}")
async def delete_task(task_id: str):
    if task_id not in tasks_db:
        raise HTTPException(status_code=404, detail="Task not found")
    del tasks_db[task_id]
    return {"message": "Task deleted"}

Aplicando confianza calibrada

Paso 1: ¿Qué tipo de código es?

CRUD endpoint → Confianza base: 70%
No hay auth ni security → No hay factores de riesgo crítico

Paso 2: ¿Cuál es el impacto de un error?

Es un task manager, no un sistema financiero → Impacto medio
No maneja datos sensibles → No hay riesgo de compliance

Paso 3: ¿Qué verifico? Con 70% de confianza, reviso las partes de riesgo:

✅ Verificar rápidamente:
- Imports correctos → Sí, todos existen
- Modelos Pydantic → Field con validación, bien
- UUID para IDs → Correcto

⚠️ Verificar con atención:
- Validación de priority → Solo "medium" como default,
  pero acepta cualquier string. ¿Debería ser un Enum?
  → Depende de requisitos. Si necesitas valores fijos, 
  cambia a Enum.

- Error handling → Tiene 404 para task no encontrado.
  Falta manejar otros errores (e.g., qué pasa si el body
  es malformado).
  → Pydantic maneja validación del body automáticamente.
  OK para un CRUD básico.

- Delete sin soft-delete → Borra permanentemente.
  → ¿Es lo que quieres? Para un task manager básico, OK.
  Para producción, quizá soft-delete.

❌ No necesito verificar:
- Sintaxis (el linter lo hace)
- Estilo de código (es consistente)
- Nombre de variables (claros y descriptivos)

Paso 4: Decisión

Acepto el código con un cambio: agregar Enum para priority
Tiempo total: ~5 minutos de revisión + 2 minutos de cambio = 7 minutos

Eso es confianza calibrada. No revisaste línea por línea. No aceptaste sin mirar. Revisaste lo que importaba para el tipo de tarea.

Anti-Patrones de Calibración

Anti-patrón 1: Calibración estática

❌ "Mi regla es: reviso 50% de todo el código AI"

→ 50% de un README es demasiado
→ 50% de auth code es muy poco
→ La calibración debe variar por tarea

Anti-patrón 2: Calibración por volumen

❌ "Si son pocas líneas, confío. Si son muchas, reviso."

→ 3 líneas de SQL injection son peores que 300 líneas de CRUD
→ El riesgo no correlaciona con el tamaño

Anti-patrón 3: Calibración por experiencia previa única

❌ "Claude Code generó un bug en auth una vez, 
    ahora no confío en nada que genere"

→ Un error en auth no invalida su capacidad para CRUD
→ Calibra por tipo de tarea, no por recuerdos aislados

Anti-patrón 4: Calibración por presión social

❌ "Mi lead dice que siempre revise todo, 
    así que reviso cada import statement"

→ Revisar cada import es desperdicio
→ Tu lead probablemente quiere que revises lo importante
→ Muéstrale tu tabla de calibración

Troubleshooting

Problema 1: "No sé cómo evaluar el riesgo de una tarea"

Causa: Falta de experiencia clasificando tareas por impacto. Solución: Hazte una pregunta simple: "Si este código tiene un bug y llega a producción, ¿a quién llaman a las 3 AM?" Si la respuesta es "a nadie, lo arreglamos mañana" → bajo riesgo. Si es "al equipo de seguridad" → alto riesgo.

Problema 2: "Mi tabla de calibración no cubre mi caso específico"

Causa: La tabla es un punto de partida, no una enciclopedia. Solución: Usa los 5 factores directamente. Evalúa: (1) tipo de tarea, (2) impacto, (3) verificabilidad, (4) tu familiaridad, (5) complejidad. La combinación te da un rango de confianza razonable.

Problema 3: "Calibro bien pero mi equipo no, y sus bugs me afectan"

Causa: Problema de equipo, no individual. Solución: Comparte tu tabla de calibración con el equipo. En la Guía 7 (Git Workflows) verás cómo integrar esto en el flujo de code review del equipo.

Ejercicios

Ejercicio 1: Asignar confianza (Fácil)

Para cada tarea, asigna un % de confianza y justifica con los 5 factores:

Generar un script que lee un CSV y lo convierte a JSON
Crear una función de autenticación con OAuth2
Escribir docstrings para 10 funciones existentes
Implementar un rate limiter custom

Ver solución

CSV a JSON → 75% confianza.
- Tipo: transformación de datos (AI es buena)
- Impacto: bajo (no es security, no es business-critical)
- Verificabilidad: alta (ejecutas y ves el output)
- Revisar: que maneje archivos vacíos, encoding, y tipos de datos
OAuth2 auth → 15% confianza.
- Tipo: seguridad (AI es impredecible)
- Impacto: crítico (breach si está mal)
- Verificabilidad: difícil (necesitas pensar como atacante)
- Revisar: CADA línea, token handling, secret management, scopes
Docstrings → 85% confianza.
- Tipo: documentación (AI es buena)
- Impacto: bajo (error en docs no causa bugs)
- Verificabilidad: alta (lees y verificas)
- Revisar: que las descripciones sean correctas, no engañosas
Rate limiter → 30% confianza.
- Tipo: infraestructura con edge cases (AI es impredecible)
- Impacto: alto (mal rate limiting = DoS o falsos positivos)
- Verificabilidad: difícil (necesitas probar bajo carga)
- Revisar: algoritmo, edge cases (qué pasa si el clock salta), storage

Ejercicio 2: Calibrar un output real (Medio)

Claude Code genera esta función. Aplica los 5 factores y decide: ¿aceptas, editas, o rechazas?

def calculate_discount(price: float, user_type: str, quantity: int) -> float:
    if user_type == "premium":
        discount = 0.20
    elif user_type == "regular":
        discount = 0.10
    else:
        discount = 0.0
    
    if quantity > 100:
        discount += 0.05
    elif quantity > 50:
        discount += 0.03
    
    final_price = price * (1 - discount)
    return round(final_price, 2)

Ver solución

Análisis con los 5 factores:

Tipo: Lógica de negocio (pricing) → Confianza base baja (30-40%)
Impacto: Alto (error = cobrar de más o de menos) → Baja confianza
Verificabilidad: Media (puedes probar con inputs conocidos)
Familiaridad: Depende de ti — ¿conoces las reglas de descuento de tu negocio?
Complejidad: Baja (if/else lineal)

Problemas detectados:

¿Los porcentajes son correctos? Solo tú lo sabes (lógica de negocio)
¿Qué pasa con price negativo? No valida
¿Qué pasa con quantity negativo? No valida
¿user_type debería ser un Enum? Acepta cualquier string
¿El descuento puede superar 25%? No hay cap máximo
¿Qué pasa si price es 0? Funciona pero ¿tiene sentido?

Decisión: Editar. La estructura está bien (acepto ~70% del código). Pero necesito:

Verificar los porcentajes contra las reglas de negocio reales
Agregar validación de inputs (precio/cantidad negativos)
Considerar un cap máximo de descuento
Usar Enum para user_type

Ejercicio 3: Crear tu tabla personalizada (Medio)

Piensa en tu trabajo actual (o un proyecto personal). Lista 8 tipos de tareas que sueles pedirle a AI y asigna confianza a cada una basándote en los 5 factores.

Ver solución

No hay respuesta única — depende de tu contexto. Pero tu tabla debería:

✅ Tener al menos 3 niveles de confianza diferentes (no todo en 50%)
✅ Las tareas de security/auth deberían estar en el rango 10-25%
✅ Boilerplate y documentación deberían estar en 75-90%
✅ Lógica de negocio debería estar en 25-40%
✅ Cada entrada debería tener una columna de "qué revisar"

Ejemplo para un developer backend:

Tarea	Confianza	Qué revisar
Docker compose	85%	Versiones, ports
API endpoints	65%	Validaciones, error handling
Database queries	45%	SQL correctness, N+1, injection
Auth middleware	15%	Todo
Business rules	30%	Contra los requisitos
Tests	55%	Que testen lo correcto
Config files	80%	Valores por defecto
Error messages	75%	Que no expongan info sensible

Ejercicio 4: Caso de estudio (Difícil)

Un equipo tiene esta política: "Todo código AI debe pasar code review por otro developer antes de merge." ¿Es una buena política? Argumenta pros y contras usando el concepto de confianza calibrada.

Ver solución

Pros:

Doble verificación reduce riesgo de bugs en producción
Distribuye el conocimiento del código (no solo el autor lo entiende)
Consistente — no depende del criterio individual de cada developer
Descubre problemas que el autor no vio (fresh eyes)

Contras (desde confianza calibrada):

Aplica el mismo proceso a todo — un PR de README pasa el mismo review que un PR de auth
Bottleneck: si el reviewer está ocupado, la PR espera (aunque sea boilerplate)
Falsa seguridad: si el reviewer tampoco calibra, revisa superficialmente todo
No incentiva al autor a revisar bien — "el reviewer lo va a ver"
Costoso: 2 personas revisan lo que 1 persona podría calibrar correctamente

Política mejorada con calibración:

PRs de bajo riesgo (boilerplate, config, docs): auto-merge con checklist
PRs de medio riesgo (CRUD, features): review por 1 developer
PRs de alto riesgo (auth, payments, data migration): review por 2 developers + tests requeridos

Conclusión: La política no es mala, pero le falta calibración. Un code review obligatorio para TODO el código trata todo como igualmente riesgoso — exactamente el anti-patrón de calibración estática.

Resumen

En esta cápsula aprendiste:

Confianza calibrada es ajustar tu nivel de confianza basándote en factores objetivos, no en hábito
Los 5 factores de calibración: tipo de tarea, impacto de error, verificabilidad, familiaridad, complejidad
El principio core: invierte tiempo de revisión proporcional al riesgo, no al volumen de código
La tabla de calibración te da un punto de partida concreto para cada tipo de tarea
Los anti-patrones a evitar: calibración estática, por volumen, por experiencia aislada, por presión social
Confianza calibrada no es un cálculo — es un hábito de pensamiento que desarrollas con práctica

Próxima cápsula: Tu Primer Framework de Verificación — el framework concreto que vas a usar mañana.

Recursos Adicionales

Thinking, Fast and Slow — Daniel Kahneman - Base teórica de calibración y sesgos cognitivos
Google Engineering Practices — Code Review - Cómo Google calibra code review por tipo de cambio
Anthropic — Claude Code Documentation - Recomendaciones oficiales para trabajar con output de Claude Code
OWASP — Code Review Guide - Framework de code review con foco en seguridad
Linus Torvalds on Code Review - Filosofía de code review del creador de Linux
Risk-Based Testing Approach - Principios de testing basado en riesgo aplicables a code review

Debugging & Code Review with Claude Code — Módulo 1, Cápsula 04 Claude Code Agentic Development Path — Guía #6 de 11

← AnteriorDos Extremos Peligrosos Siguiente →Tu Primer Framework de Verificación