Claude Code para la deriva de la documentación: mantener los docs alineados

Qué es la deriva de la documentación (y por qué sigue ocurriendo)

La deriva de la documentación es la separación gradual entre lo que dicen tus docs y lo que hace realmente tu código. Empieza como desajustes pequeños y luego se convierte en la confusión de “juramos que esto funcionaba el mes pasado”.

En un equipo real, la deriva se ve así: el README dice que puedes ejecutar un servicio con un comando, pero ahora se requiere una variable de entorno nueva. La documentación de la API muestra un endpoint con un campo renombrado. Un runbook indica al on-call que reinicie "worker-a", pero el proceso ahora está dividido en dos servicios.

La deriva ocurre incluso con buenas intenciones porque el software cambia más rápido que los hábitos de documentación. La gente publica correcciones con presión, copia ejemplos antiguos o asume que alguien más actualizará los docs luego. También crece cuando hay demasiados lugares que parecen la “fuente de la verdad”: archivos README, referencias de API, páginas internas de wiki, tickets y conocimiento tribal.

Los costos son concretos:

• El onboarding se rompe (los nuevos pierden días por problemas de configuración).
• Los despliegues fallan (los pasos no coinciden con la configuración actual).
• La carga de soporte sube (los usuarios siguen instrucciones desactualizadas).
• Los incidentes se alargan (los runbooks envían a los respondedores por el camino equivocado).

Pulir la redacción no arregla la deriva si los hechos son incorrectos. Lo que ayuda es tratar la documentación como algo que puedes verificar: compárala con el código actual, las configs y las salidas reales, y resalta las contradicciones donde el doc promete un comportamiento que el código ya no tiene.

Dónde aparece la deriva: README, docs de la API y runbooks

La deriva suele aparecer en documentos que la gente trata como "referencia rápida". Se actualizan una vez y luego el código sigue moviéndose. Empieza por estos tres porque contienen promesas concretas que puedes comprobar.

README: el primer lugar donde los usuarios sienten el dolor

Los README se desincronizan cuando cambian los comandos cotidianos. Se añade un flag nuevo, se elimina uno antiguo o una variable de entorno se renombra, pero la sección de setup sigue mostrando la realidad anterior. Los nuevos compañeros copian y pegan instrucciones, encuentran errores y asumen que el proyecto está roto.

La peor versión es “casi correcto”. Una variable de entorno faltante puede hacer perder más tiempo que un README totalmente desactualizado, porque la gente sigue intentando pequeñas variaciones en lugar de cuestionar el doc.

Docs de la API: formas desajustadas y ejemplos engañosos

La documentación de la API deriva cuando cambian campos de request o response. Incluso cambios pequeños (claves renombradas, defaults distintos, headers nuevos obligatorios) pueden romper clientes. A menudo la lista de endpoints está correcta mientras los ejemplos están mal, y eso es exactamente lo que los usuarios copian.

Señales típicas:

• Los payloads de ejemplo incluyen campos que el servidor ya no acepta.
• Las muestras de respuesta muestran formatos de error o códigos de estado antiguos.
• Las tablas de parámetros indican campos opcionales que ahora son obligatorios.
• Las notas de autenticación mencionan headers o scopes que ya no funcionan.
• Las reglas de paginación, ordenamiento o filtrado no coinciden con la realidad.

Runbooks: deriva silenciosa que provoca incidentes ruidosos

Los runbooks derivan cuando cambian los pasos de despliegue, rollback u operación. Un comando desactualizado, un nombre de servicio equivocado o un prerrequisito ausente puede convertir una reparación rutinaria en downtime.

También pueden ser "exactos pero incompletos": los pasos todavía funcionan, pero omiten una migración nueva, un clear de cache o el toggle de un feature flag. Ahí es cuando los respondedores siguen el runbook perfectamente y aun así se sorprenden.

Cómo usar Claude Code: diffs y señalización de contradicciones

Claude Code para la deriva de la documentación funciona mejor cuando tratas los docs como código: propone un parche pequeño y revisable y explica por qué. En vez de pedir que "actualice el README", pídelo para que genere un diff contra archivos específicos. Los revisores obtienen un antes/después claro y pueden detectar cambios no deseados rápidamente.

Un buen chequeo de deriva produce dos cosas:

1. Un diff mínimo
2. Un informe de contradicciones que sea claro y específico: "El doc dice X, el repo muestra Y."

Pide evidencia, no opiniones

Cuando redactes el prompt, exige pruebas desde el repo: rutas de archivos y detalles como rutas, valores de configuración o tests que demuestren el comportamiento actual.

Aquí tienes un patrón de prompt que mantiene todo anclado:

\nCheck these docs for drift: README.md, docs/api.md, runbooks/deploy.md.\nCompare them to the current repo.\nOutput:\n1) Contradictions list (doc claim -\u003e repo evidence with file path and line range)\n2) Unified diffs for the smallest safe edits\nRules: do not rewrite sections that are still accurate.\n

Si Claude dice "la API usa /v2", que lo respalde apuntando al router, la especificación OpenAPI o un test de integración. Si no puede encontrar evidencia, debe decirlo.

Delimita el alcance antes de editar

La deriva suele comenzar con un cambio de código que afecta silenciosamente múltiples docs. Pide a Claude que primero alcance el impacto: qué cambió, dónde cambió, qué docs probablemente se rompen y qué acciones de usuario se ven afectadas.

Ejemplo: renombras una variable de entorno de API_KEY a SERVICE_TOKEN. Un informe útil encuentra cada lugar donde aparece el nombre antiguo (setup del README, ejemplos de API, sección de secrets del runbook), y luego genera un diff ajustado que actualiza solo esas líneas y cualquier comando de ejemplo que ahora fallaría.

Configura un flujo de trabajo simple antes de pedir nada

Si apuntas un modelo a "todos los docs" sin reglas, a menudo obtendrás prosa reescrita que sigue conteniendo hechos erróneos. Un flujo de trabajo simple mantiene los cambios pequeños, repetibles y fáciles de revisar.

Comienza con un conjunto de docs: el README, la referencia de la API o un runbook que la gente realmente use. Arreglar un área de extremo a extremo te enseña qué señales confiar antes de escalar.

Decide qué cuenta como fuente de la verdad

Escribe, en palabras sencillas, de dónde deben venir los hechos para ese conjunto de docs.

• Para un README: la salida de ayuda del CLI y una app de ejemplo que funcione.
• Para docs de API: definiciones del router más tests de integración.
• Para runbooks: la config de despliegue y las alertas que disparan el procedimiento.

Una vez nombradas esas fuentes, los prompts se vuelven más precisos: "Compara el README con la salida actual del CLI y los defaults de config, luego genera un parche."

Elige una salida que los revisores validen rápido

Acordad un formato de salida antes de que alguien ejecute la primera comprobación. Mezclar formatos hace más difícil ver qué cambió y por qué.

Un conjunto de reglas simple:

• Requiere un diff para cada cambio de doc, más una razón en una frase.
• Permite una lista corta de contradicciones solo cuando la herramienta no puede proponer redacción de forma segura.
• Mantén los diffs limitados a un archivo por cambio cuando sea posible.
• Trata los ejemplos que fallan (comandos, requests, fragmentos de código) como prioridad sobre la redacción general.

Un hábito práctico: añade una nota pequeña a cada PR de docs como "Source of truth checked: routes + tests" para que los revisores sepan qué se comparó. Eso convierte las actualizaciones de docs de "se ve bien" a "verificado contra algo real".

Paso a paso: mantener los docs alineados con el código en cada cambio

Trata cada cambio de código como una pequeña investigación de docs. La idea es detectar contradicciones temprano y producir un parche mínimo que los revisores puedan confiar.

Empieza por elegir los archivos exactos a comprobar y una pregunta de deriva clara. Por ejemplo: "¿Cambiamos variables de entorno, flags del CLI, rutas HTTP o códigos de error que los docs aún mencionan?" Ser específico evita que el modelo reescriba secciones enteras.

A continuación, pide a Claude Code que extraiga hechos duros del código primero. Pídele que liste solo elementos concretos: comandos que los usuarios ejecutan, endpoints y métodos, campos de request y response, claves de configuración, variables de entorno requeridas y pasos operativos referenciados por scripts o configs. Si algo no aparece en el código, debe decir "not found" en lugar de adivinar.

Luego solicita una tabla de comparación simple: afirmación del doc, lo que muestra el código y un estado (match, mismatch, missing, unclear). Eso mantiene la discusión centrada.

Después pide un diff unificado con ediciones mínimas. Indícale que cambie solo las líneas necesarias para resolver los desajustes, que mantenga el estilo existente del doc y que evite añadir promesas que no estén respaldadas por código.

Termina con un resumen corto para el revisor: qué cambió, por qué cambió y qué revisar (por ejemplo, una variable de entorno renombrada o un header requerido nuevo).

Docs de API: una manera práctica de verificar endpoints y ejemplos

La documentación de la API deriva cuando el código cambia silenciosamente: una ruta se renombra, un campo pasa a ser obligatorio o la forma de un error cambia. El resultado son integraciones rotas y tiempo perdido en debugging.

Con Claude Code para la deriva de docs, la tarea es probar lo que hace la API desde el repo y luego señalar las discrepancias en los docs. Pídele que extraiga un inventario desde el routing y los handlers (paths, métodos, modelos de request y response) y que lo compare con lo que afirma la referencia de la API.

Concéntrate en lo que la gente realmente copia y pega: comandos curl, headers, payloads de ejemplo, códigos de estado y nombres de campos. En un mismo prompt, haz que compruebe:

• Requisitos de auth (headers, tipo de token, endpoints públicos)
• Parámetros de paginación y defaults
• Códigos de error y formato JSON
• Comportamiento de versionado (v1 vs v2)
• Si los ejemplos coinciden con las reglas de validación actuales

Cuando encuentre un desajuste, solo acepta diffs que puedan citar evidencia del código (la definición exacta de la ruta, comportamiento del handler o el esquema). Eso mantiene los parches pequeños y revisables.

Ejemplo: el código ahora devuelve 201 en POST /widgets y añade un campo name obligatorio. La documentación sigue mostrando 200 y omite name. Una buena salida señala ambas contradicciones y actualiza solo el status y el JSON de ejemplo de ese endpoint, dejando el resto intacto.

Runbooks: reducir las interrupciones causadas por procedimientos obsoletos

Los runbooks fallan de la manera más cara: parecen completos, pero los pasos ya no coinciden con lo que hace el sistema hoy. Un cambio pequeño como renombrar una variable de entorno o añadir un nuevo comando de deploy puede alargar un incidente porque los respondedores siguen instrucciones que no funcionan.

Trata el runbook como código: pide un diff contra el repo actual y exige señalamiento de contradicciones. Compáralo con lo que el sistema usa hoy: scripts, defaults de config y tu tooling actual.

Concéntrate en los puntos de fallo que más provocan thrash durante incidentes:

• ¿Los comandos listados coinciden con los scripts y flags actuales?
• ¿Los valores de config “por defecto” coinciden con lo que la app trae ahora?
• ¿Las variables de entorno y secrets requeridos están referenciados por el código y la config de despliegue?
• ¿Los pasos de deploy y rollback coinciden con tu tooling de releases y naming actual?
• ¿Los valores “conocidos buenos” (puertos, regiones, timeouts) siguen siendo correctos?

Añade también prechecks rápidos y salidas esperadas para que los respondedores puedan saber si van por el buen camino. "Verificar que funciona" no es suficiente; incluye la señal exacta que esperas (una línea de status, una cadena de versión o la respuesta de un health check).

Si construyes y despliegas apps en plataformas como Koder.ai, esto importa aún más porque los snapshots y el rollback solo son útiles cuando el runbook nombra la acción correcta y refleja la vía de recuperación actual.

Errores comunes que empeoran la deriva

La forma más rápida de crear deriva en la documentación es tratar los docs como "buena prosa" en vez de un conjunto de afirmaciones que deben coincidir con el código.

Errores que silenciosamente rompen la alineación

Un tropiezo común es pedir una reescritura primero. Cuando omites la comprobación de contradicciones, puedes acabar con una redacción más suave que sigue describiendo el comportamiento equivocado. Empieza siempre preguntando qué afirma el doc, qué hace el código y dónde discrepan.

Otro error es dejar que el modelo adivine. Si un comportamiento no es visible en código, tests o configs, trátalo como desconocido. “Probablemente” es cómo se inventan promesas en README y los runbooks se convierten en ficción.

Estos problemas aparecen mucho en las actualizaciones diarias:

• Actualizar una sección pero dejar ejemplos, mensajes de error y casos límite intactos
• Renombrar un concepto en un sitio (README) pero no en docs de API, claves de config o runbooks
• Arreglar descripciones de endpoints pero olvidar muestras de request y response
• Cambiar comportamiento pero no actualizar valores por defecto o notas de limitaciones
• Mergear edits de docs sin una breve nota de “por qué cambió” en el resumen del diff

Un ejemplo pequeño

Un handler cambia de devolver 401 a 403 por tokens expirados, y el nombre del header pasa de X-Token a Authorization. Si solo reescribes la sección de auth, podrías pasar por alto que el ejemplo de la API sigue mostrando el header antiguo y el runbook sigue diciendo al on-call que mire picos de 401.

Cuando generes diffs, añade una línea de decisión corta como: "Los fallos de auth ahora devuelven 403 para distinguir credenciales inválidas de las ausentes." Eso evita que la siguiente persona vuelva a "arreglar" los docs a comportamiento antiguo.

Lista rápida antes de hacer merge en los docs

Trata cada actualización de docs como una pequeña auditoría. El objetivo es menos sorpresas cuando alguien siga las instrucciones la semana siguiente.

Cinco comprobaciones que atrapan la mayoría de derivaciones

Antes de hacer merge, escanea el README, los docs de la API y el runbook por afirmaciones concretas y verifícalas una a una:

• Resalta cada afirmación con un comando, endpoint, clave de config, variable de entorno, puerto o payload de ejemplo.
• Para cada afirmación, anota el archivo exacto que lo prueba (source, config, esquema, migración, test o salida de ayuda del CLI). Si no encuentras prueba rápido, márcalo como desconocido en vez de adivinar.
• Pide un diff mínimo solo donde exista evidencia. Si una afirmación es desconocida, el cambio debería convertirse en una pregunta o un TODO, no en una declaración segura.
• Revisa los ejemplos: ¿las entradas siguen coincidiendo con lo que el código acepta hoy (nombres de parámetros, campos obligatorios, headers, valores por defecto)? Los ejemplos largos atraen deriva.
• Para runbooks, confirma que los pasos cubren fallos probables, rollback seguro y cómo verificar la recuperación.

Una regla rápida para pararlo todo

Si encuentras dos o más afirmaciones desconocidas en el mismo documento, pausa el merge. Añade evidencia (rutas de archivos y nombres de funciones) o reduce el doc a lo que sea cierto.

Escenario de ejemplo: un cambio de feature, tres docs con deriva

Un equipo pequeño actualiza la auth: en vez de enviar una API key en X-API-Key, los clientes ahora envían un token de corta duración en Authorization: Bearer <token>. El código se publica, los tests pasan y el equipo sigue adelante.

Dos días después, un desarrollador nuevo sigue el README. Aún dice "set X-API-Key in your environment" y muestra un ejemplo curl con el header antiguo. No logra ejecutar en local y asume que el servicio está caído.

Al mismo tiempo, los docs de la API están desactualizados. Describen el header antiguo y todavía muestran un campo de respuesta llamado user_id, aunque la API ahora devuelve userId. No hay nada malo con la redacción, pero contradice el código, así que los lectores copian lo incorrecto.

Entonces ocurre un incidente. El on-call sigue el paso del runbook "rotate the API key and restart workers". Eso no ayuda porque el problema real es la verificación de tokens tras un cambio de config. El runbook los lleva en la dirección equivocada durante 20 minutos.

Ahí es donde Claude Code para la deriva de documentación es útil cuando produce diffs y llamadas de contradicción, no una reescritura completa. Puedes pedirle que compare el middleware de auth y los handlers de rutas contra fragmentos del README, ejemplos de la API y pasos del runbook, y luego proponga parches mínimos:

- Header: X-API-Key: \u003ckey\u003e
+ Header: Authorization: Bearer \u003ctoken\u003e

- { "user_id": "..." }
+ { "userId": "..." }

Lo importante es que marque las discordancias, señale los lugares exactos y solo cambie lo que el repo demuestra que está desactualizado.

Próximos pasos: convertir los chequeos de deriva en una rutina

La documentación se mantiene precisa cuando comprobarla es aburrido y repetible. Elige una cadencia que coincida con el riesgo de tus cambios. Para código de rápido movimiento, hazlo en cada PR. Para servicios estables, una revisión semanal y una comprobación previa a release suele ser suficiente.

Trata la deriva de docs como un fallo de test, no como una tarea de redacción. Usa Claude Code para la deriva de documentación para generar un diff pequeño y una lista corta de contradicciones, y luego arregla lo mínimo que haga que los docs vuelvan a ser ciertos.

Una rutina que se mantiene ligera:

• Por PR: ejecuta un chequeo de deriva en los archivos que el cambio pueda afectar (README, docs de API, runbooks).
• Guarda el resumen del diff en la descripción del PR o en las notas de revisión para que los revisores vean qué cambió y por qué.
• Prefiere ediciones pequeñas que puedas revertir fácilmente a reescrituras grandes.
• Antes de releases: vuelve a comprobar todo lo que los usuarios vayan a copiar y pegar (ejemplos curl, variables de entorno, pasos de despliegue).
• Semanal: toma uno o dos runbooks antiguos y confirma que aún coinciden con los comandos y dashboards de hoy.

Haz que esos resúmenes de diff sean fáciles de encontrar más adelante. Una nota corta como "Docs updated to match new /v2 endpoint, removed deprecated header, updated example response" ayuda cuando alguien pregunta meses después por qué cambió un doc.

Aplica la mentalidad de "snapshots y rollback" también a los docs. Si una instrucción es incierta, cambiala en un solo lugar, verifícala rápido y luego copia la versión confirmada a otros sitios.

Si construyes rápido, puede ayudar generar la app y una primera versión de sus docs juntos en Koder.ai (koder.ai), luego exportar el código fuente y mantener los cambios revisables en tu flujo normal. El objetivo no es una prosa perfecta. Es mantener lo que la gente hace (comandos, endpoints, pasos) alineado con lo que realmente hace el código.