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

Al trabajar con Claude Code en repositorios complejos, el agente inevitablemente encuentra peculiaridades poco evidentes: definiciones TypeScript obsoletas, dependencias de ejecución ocultas o comportamientos específicos del bundler. Corregir el mismo error repetidamente en el chat desperdicia contexto y tiempo. En cambio, volcar transcripciones de sesión de varias páginas en las instrucciones llena el prompt y reduce la atención del modelo.

Un patrón práctico es mantener un MISTAKES.md ligero en la raíz del repositorio. Solo registra incidentes reproducibles, causas verificadas y acciones preventivas. Más tarde, estos se promueven a pruebas del proyecto, reglas de linter y configuración persistente.

---

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:

Dimensión	Transcripción de sesión	Registro de incidentes MISTAKES.md
Volumen	Miles de líneas de llamadas de herramientas y pasos intermedios	5–10 líneas estructuradas por incidente
Propósito	Depuración y auditoría de una ejecución	Base de referencia para evitar recurrencias
Manejo de secretos	Puede capturar variables de entorno o tokens sin procesar	Estrictamente prohibido: cero credenciales o secretos
Duración	Artefacto efímero	Documentación persistente hasta automatizar

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.

---

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.