La mejor explicación de tu código está enterrada en un registry de chat

Pasaste cuarenta y cinco minutos con Claude diseñando un circuito de reintento. Explicaste los modos de falla, rechazaste el backoff exponencial porque oculta la presión en cascada, te decidiste por el rate limiting de token bucket con jitter, y generaste una implementación funcional. La explicación fue clara, el razonamiento fue sólido, y el código realmente pasó las pruebas.

Luego cerraste la pestaña.

Dos semanas después un compañero pregunta por qué la lógica de reintento usa jitter en lugar de backoff exponencial. Abres una nueva sesión de Claude y reconstruyes el argumento de memoria. La nueva explicación es cercana, pero no idéntica. Has creado una segunda tradición oral ligeramente diferente. Ninguna es encontrable por búsqueda. Ninguna es revisable en un pull request. Ambas desaparecerán cuando dejes la empresa.

Esto no es un problema de herramientas. Es un error de categoría. Tratamos las conversaciones con LLM como borradores privados cuando en realidad son lo más cercano a la programación literaria que la mayoría de los ingenieros han experimentado.

Lo que Knuth quiso decir, y por qué los LLM lo entregaron accidentalmente

Donald Knuth definió la programación literaria en 1984 como el acto de escribir programas como obras de literatura. El código y la documentación se tejen juntos en una sola narrativa. El lector sigue el razonamiento del autor, ve las alternativas consideradas, y entiende por qué existe la forma final.

Durante cuarenta años, la programación literaria permaneció como una práctica de nicho. Herramientas como WEB y CWEB requerían disciplina. La mayoría de los desarrolladores escribieron código en un archivo y documentación en otro, y los dos se desviaron inmediatamente.

Una conversación con un LLM es programación literaria por accidente. Planteas el problema en prosa. El modelo hace preguntas aclaratorias. Refinas restricciones. Propone código. Rechazas la propuesta y explicas por qué. Lo revisa. El artefacto final no es solo el bloque de código. Es todo el hilo: los enfoques descartados, los trade-offs, las suposiciones del dominio.

El problema es que el medio es efímero. Las interfaces de chat están diseñadas para la finalización de tareas, no para la preservación del conocimiento. Una vez que la sesión termina, la narrativa queda congelada en ámbar, no buscable, no versionada, y propiedad de un proveedor.

Por qué los registries de chat superan a la documentación tradicional para decisiones complejas

La documentación tradicional describe el estado final. Responde “qué.” Un buen registry de chat responde “por qué,” que es la pregunta más difícil y la que se pudre más rápido.

Considera un registry típico de decisión de arquitectura. Podría decir: “Elegimos PostgreSQL sobre DynamoDB para el servicio de inventario debido a los requisitos de consistencia fuerte.” Eso es una conclusión. No te dice nada sobre las queries que fueron demasiado lentas, el lag de replicación que fue aceptable, o el vendor lock-in que se debatió y descartó.

Un hilo de Claude contiene todo eso. Contiene las iteraciones de esquema que fallaron, los planes de query que te sorprendieron, y el momento en que te diste cuenta de que el index compuesto tenía que cubrir el filtro de estado. Es un registry de decisión con contexto completo.

La trampa es que el contexto está atrapado en un formato conversacional. Desplazarse por un hilo de cien turnos para encontrar la única idea sobre diseño de indexes es miserable. El conocimiento está ahí, pero no es accesible.

Los tres modos de falla de chat-como-docs

Tratar los registries de chat sin procesar como documentación falla de maneras predecibles. Cada modo de falla tiene una solución, pero tienes que ser intencional.

Hallucination drift. Claude inventa APIs, cita papers inexistentes, y propone con confianza diseños que ignoran tus restricciones reales. Un registry de chat preservado como documentación preserva las alucinaciones junto con la sabiduría. Si no marcas qué partes fueron verificadas y cuáles fueron especulativas, el siguiente lector trata todo como evangelio.

Narrative sprawl. Una buena conversación divaga. Exploras callejones sin salida, te distraes con casos límite, y retrocedes. Esa divagación es valiosa para la comprensión, pero es terrible para la referencia. Un nuevo ingeniero que necesita la política de reintento no necesita leer la desviación de veinte minutos hacia el control de congestión TCP.

Vendor lock-in. Tu documentación vive en la base de datos de Anthropic, detrás de su interfaz de búsqueda, sujeta a su política de retención. Si la cuenta caduca o la interfaz cambia, tus docs desaparecen. Documentación que no puedes grepear no es documentación.

Cómo extraer un documento durable de un chat efímero

La solución es tratar el chat como un primer borrador, no como un artefacto final. Extraes, verificas y publicas. El flujo de trabajo es simple y toma unos diez minutos por decisión significativa.

Paso uno: tag los turnos. Durante la conversación, marca las decisiones clave. Uso una convención simple. Cuando Claude produce un bloque de código que pretendo conservar, respondo con KEEP: <one-line reason>. Cuando propone algo que rechazo, respondo con REJECT: <reason>. Estas tags hacen la checkout trivial.

Paso dos: extrae a markdown. Después de la sesión, copia el hilo en un archivo markdown y elimina el ruido. Quita los saludos, los polyfills de “déjame pensar,” y los turnos donde ambos estaban confundidos. Conserva la declaración del problema, las alternativas consideradas, la decisión final y el código verificado. El resultado debe leerse como una nota técnica, no como una transcripción.

Aquí hay un script que automatiza la checkout si usas la API de Claude o exportas tu conversación como JSON:

#!/usr/bin/env python3
"""
Extract a readable technical note from a Claude conversation export.
Expects Anthropic's conversation JSON format.
"""

import json
import argparse
from pathlib import Path


def extract_note(conversation_path: Path, output_path: Path) -> None:
    with open(conversation_path) as f:
        data = json.load(f)

    turns = data.get("chat_messages", [])
    lines = []

    for turn in turns:
        sender = turn.get("sender", "unknown")
        text = turn.get("text", "").strip()

        if not text:
            continue

        # Skip pleasantries and meta-turns
        if any(phrase in text.lower() for phrase in [
            "hello", "how can i help", "you're welcome", "glad i could help"
        ]):
            continue

        if sender == "human":
            lines.append(f"**Q:** {text}\n")
        else:
            lines.append(f"**A:** {text}\n")

    with open(output_path, "w") as f:
        f.write("# Technical Note: Extracted from Claude Session\n\n")
        f.write("\n".join(lines))


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--input", type=Path, required=True)
    parser.add_argument("--output", type=Path, required=True)
    args = parser.parse_args()
    extract_note(args.input, args.output)

Paso tres: verifica cada bloque de código. Ejecuta el código extraído. Si no compila o pasa las pruebas, corrígelo en el markdown y anota la corrección. El documento extraído debe ser una fuente de verdad, no una transcripción de una conversación que pudo haber contenido errores.

Paso cuatro: haz commit al repository. Guarda el markdown en docs/decisions/ o docs/notes/ junto al código que describe. Dale un nombre de archivo significativo: retry-circuit-jitter-over-exponential.md, no claude-chat-july-19.md. Agrégalo al mismo pull request que el cambio de código, o abre un PR de tracing inmediatamente. Si la documentación no está bajo control de versiones, no existe.

Cuándo funciona y cuándo no

Este enfoque sobresale para decisiones complejas y ambiguas donde el razonamiento importa tanto como el resultado. El diseño de circuitos, las estrategias de migration de esquema, las políticas de versioning de API y los trade-offs de rendimiento son todos buenos candidatos.

No funciona para documentación de referencia. Un registry de chat sobre cómo autenticarse con la API interna es un sustituto terrible para una especificación OpenAPI estructurada y un ejemplo de cURL. Usa la herramienta correcta para el trabajo.

Tampoco funciona sin curaduría. Volcar registries de chat sin procesar en una wiki no es documentación. Es acumulación. Los diez minutos de checkout y edición no son negociables. Si los omites, produces basura buscable.

Un punto de partida práctico

No necesitas una herramienta nueva. Necesitas un hábito.

La próxima vez que tengas una sesión larga y productiva con Claude sobre una decisión de diseño no trivial, exporta el hilo antes de cerrar la pestaña. Dedica diez minutos a editarlo en una nota markdown que responda tres preguntas: ¿Qué problema estábamos resolviendo? ¿Qué alternativas consideramos y rechazamos? ¿En qué nos decidimos y por qué?

Haz commit de esa nota en tu repo. Enlázala desde el comentario de código sobre la función que describe. El próximo ingeniero que toque ese código te lo agradecerá, y no necesitará abrir Claude para reconstruir tu razonamiento.

Tu chat con Claude puede convertirse en documentación. Solo necesita que lo trates como código: extraído, verificado, versioning y mantenido.