MISTAKES.md y Claude Code: convertir un error recurrente en una regla

1. MISTAKES.md frente a la transcripción de sesión

No confunda un registro de incidentes con una transcripción de terminal sin filtrar:

MISTAKES.md debe ser conciso para que Claude Code pueda ingerirlo al iniciar la sesión sin gastar demasiados tokens de contexto.

---

2. Anatomía de un registro de incidente

Cada entrada contiene cuatro campos obligatorios:

1. Incident: qué se rompió exactamente y en qué condiciones: código de error, comando y herramienta.
2. Impact: efecto posterior, como build roto, migración corrompida o suite de pruebas abortada.
3. Root Cause: fuente técnica confirmada; si no está probada, márquela explícitamente como [Hypothesis].
4. Prevention: regla o comprobación concreta que impide que vuelva a suceder.

Ejemplo de registro

ERR-014: migración PostgreSQL falló al ejecutar DROP COLUMN sin CASCADE

• Incident: Claude Code ejecutó ALTER TABLE orders DROP COLUMN customer_ref; en la migración 0042.
• Impact: el despliegue de staging falló por la vista dependiente v_active_orders.
• Root Cause: las vistas que referencian tablas base requieren recreación explícita con cascade o actualizaciones previas.
• Prevention: toda migración DDL que elimine una columna debe comprobar las vistas dependientes mediante pg_depend antes de ejecutarse.

> [!IMPORTANT]
> **Política de cero secretos:** nunca haga commit de cadenas reales de conexión a base de datos, claves privadas, tokens ni fragmentos de `.env` en `MISTAKES.md`. Administre las claves API de Claude Code mediante variables de entorno locales.

Para una configuración fiable de Claude Code con un proveedor API, use su propia clave API y siga la [guía de integración de Claude Code de BetterToken](https://docs.bettertoken.ai/ai-tools/claude-code).

---

3. Umbral de promoción: del registro a prueba o regla

No todo error tipográfico aislado merece una regla permanente. Promueva las entradas a barreras automatizadas con un umbral claro:

Incidente ocurrido
  │
  ├─> Primera vez: registrar entrada de 4 campos en MISTAKES.md
  │
  └─> Segunda vez (recurrencia):
        │
        ├─> ¿Se puede verificar mecánicamente?
        │     └─> SÍ: añadir prueba unitaria, regla ESLint o hook pre-commit
        │
        └─> NO: añadir instrucción negativa estricta en CLAUDE.md / AGENTS.md

1. Primera ocurrencia: añada un registro breve a MISTAKES.md.
2. Segunda ocurrencia: si se detecta de forma determinista, escriba una prueba o regla de linter. Las barreras automatizadas superan a los prompts de texto.
3. Comprobaciones no mecánicas: formule una regla negativa explícita en CLAUDE.md, por ejemplo «No ejecutar nunca jest sin --runInBand en CI».
4. Archivado: cuando haya un test o hook desplegado, archive o elimine la entrada de MISTAKES.md para evitar que el archivo crezca.

---

4. Verificación en la siguiente tarea

Para confirmar que funciona la nueva barrera:

1. inicie una sesión nueva de Claude Code;
2. proporcione un prompt que antes provocaba el fallo;
3. revise si el agente respeta la regla o queda detenido por el hook pre-commit;
4. si el agente elude instrucciones de texto, convierta la restricción en un wrapper de comando estricto o una comprobación automática.

Este bucle de retroalimentación convierte fallos de desarrollo aleatorios en una base de ingeniería robusta que mejora por sí misma.