Aprende a usar Claude Code para detectar y corregir la deriva de la documentación: mantén README, docs de API y runbooks alineados con el código generando diffs y señalando contradicciones.
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:
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.
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.
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.
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 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.
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:
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.
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.
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.
Escribe, en palabras sencillas, de dónde deben venir los hechos para ese conjunto de docs.
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."
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:
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".
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).
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:
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.
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:
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.
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.
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:
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.
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.
Antes de hacer merge, escanea el README, los docs de la API y el runbook por afirmaciones concretas y verifícalas una a una:
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.
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.
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:
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.
La deriva de la documentación es cuando tus docs dejan de coincidir con lo que hace realmente el código. Normalmente comienza con cambios pequeños (una variable de entorno renombrada, un campo ahora requerido, un código de estado distinto) que nunca se reflejan en el README, los ejemplos de la API o los runbooks.
Porque el código cambia bajo presión y la documentación no recibe la misma disciplina.
Causas comunes:
Empieza por los documentos que la gente realmente ejecuta, no por los que son “agradables de tener”. Un orden práctico es:
Arreglar esos primero elimina los fallos de mayor costo.
Porque un texto más pulido puede seguir siendo incorrecto. La deriva se trata principalmente de afirmaciones incorrectas.
Un enfoque mejor es tratar la documentación como declaraciones verificables: “ejecuta este comando”, “llama este endpoint”, “define esta variable”, y luego verificar esas afirmaciones contra el repo actual, las configuraciones y salidas reales.
Pide dos salidas:
Además, exige: si no puede encontrar evidencia en el repo, debe decir “not found” en lugar de adivinar.
Porque los diffs permiten que los revisores validen rápidamente. Un diff muestra exactamente qué cambió y desalienta reescrituras “útiles” que introducen nuevas promesas.
Un buen predeterminado es: un archivo por diff cuando sea posible, y cada cambio lleva una frase que explique la razón ligada a la evidencia del repo.
Exige que cite pruebas.
Reglas prácticas:
Revisa las partes que la gente copia y pega:
Si la lista de endpoints está correcta pero los ejemplos están mal, los usuarios igual fallan—por eso los ejemplos son alta prioridad.
Los runbooks derivan cuando la realidad operacional cambia.
Controles de alto impacto:
Si los respondedores no pueden verificar el progreso, perderán tiempo durante los incidentes.
Usa una regla simple de “fuente de la verdad” por tipo de doc:
Luego incorpóralo al flujo: ejecuta chequeos de deriva en los docs afectados por PR y mantén los cambios pequeños y revisables.