Los programadores documentarán para Claude, pero no para los demás
Por qué la gente “documenta para Claude”
- Los desarrolladores ven un beneficio inmediato y tangible: mejores resultados de la IA cuando aportan contexto centrado, especificaciones y archivos CLAUDE.md.
- Claude “lee” todo de manera fiable; los compañeros de trabajo, a menudo no. Esto hace que el retorno de inversión de escribir para una IA parezca mucho mayor.
- La documentación para Claude se evalúa solo por el contenido informativo, no por la calidad de la prosa, así que la gente está dispuesta a volcar notas toscas, dictados y texto desordenado que les daría vergüenza compartir con humanos.
- Algunos sostienen que los desarrolladores no están documentando para Claude, sino para sí mismos y para cualquier usuario de Claude; la IA simplemente garantiza por fin un lector atento.
Uso de la documentación por humanos frente a IA
- Muchos cuentan años escribiendo documentación cuidadosa que sus colegas ignoraban, y luego les hacían las mismas preguntas de todos modos.
- Algunos equipos intentan imponer una cultura de “leer primero la documentación” (preguntando dónde miró alguien, vinculando los hábitos de documentación a las evaluaciones), pero informan de resultados mixtos.
- Varios señalan que la mayoría de los usuarios no lee el texto en pantalla en absoluto; muchas empresas son “culturas orales”.
- Se elogia a la IA por poder leer conjuntos de documentación grandes y desordenados, cruzar PRs, tickets y páginas de wiki, y adaptar las explicaciones al nivel de comprensión actual de una persona.
Calidad, deriva y mantenimiento
- Una queja recurrente: CLAUDE.md y la documentación generada por IA se quedan obsoletos rápidamente y pueden engañar a futuras sesiones de IA, llegando incluso a alucinar clases y arquitecturas eliminadas.
- Algunos responden borrando esos archivos; otros añaden agentes para mantener un pequeño conjunto de documentos vivos (visión general, flujos clave) y descartan planes efímeros.
- La documentación en línea (por ejemplo, estilo jsdoc) y la extracción de documentación en tiempo de compilación se citan como formas de mantener alineados el código y la documentación.
- Una heurística: si un LLM no puede derivar respuestas correctas de tu documentación, entonces probablemente la propia documentación es poco clara o incorrecta.
Nuevos flujos de trabajo y herramientas
- La gente describe “skills” y agentes personalizados: revisores de código en paralelo, generadores infinitos de issues, agentes de documentación que detectan deriva y resúmenes de repositorio mantenidos mediante Claude.
- Las especificaciones, los documentos de diseño y los documentos de decisión se están volviendo centrales, tanto para alinear equipos como para impulsar agentes; algunos prevén que los formatos de especificación evolucionen hasta convertirse en “lenguajes de programación” de facto para la IA.
Entusiasmo frente a escepticismo
- Los entusiastas informan de aumentos de productividad de 4 a 8 veces y de un renacimiento de las especificaciones y la documentación de arquitectura ahora que mejoran directamente la velocidad de implementación.
- Los escépticos advierten que la salida de los LLM es no determinista, parcialmente incorrecta, prolija y puede fomentar una colaboración antisocial mediada por IA.
- Existe la preocupación de que enormes montones de documentación generada por IA sean ilegibles, queden obsoletos rápidamente y, en última instancia, sean desechables.