Programadores documentan para Claude, no para humanos

En Hacker News, un hilo revela una práctica extendida: los desarrolladores dedican tiempo a redactar archivos CLAUDE.md —instrucciones detalladas para que Claude Code entienda el proyecto— mientras la documentación para sus compañeros humanos se queda obsoleta o nunca se escribe. La IA se ha convertido en el lector prioritario.

Por qué importa

Cuando documentas para una máquina, optimizas para claridad sintáctica y cobertura de casos de uso. El resultado: Claude puede ejecutar tareas complejas sin preguntar. Pero el humano que llega nuevo al equipo se encuentra con un repositorio mudo, porque lo que se escribió fue pensado para un agente, no para una persona.

El intercambio es sutil: ganas eficiencia inmediata con la IA, pero pierdes la memoria colectiva del equipo. Si mañana cambias de herramienta o el modelo se vuelve incompatible, te quedas sin documentación y sin código legible. Es un riesgo silencioso.

Qué dice el contexto

• Un desarrollador en HN confiesa que reemplazó sus CLAUDE.md genéricos por archivos skill.md específicos, pensando que el agente ya "hace todo lo que quiero documentar cada vez". La documentación humana quedó fuera.
• Dan Harper recomienda en LinkedIn una regla simple: "Si lo explicaste dos veces, documéntalo. Si a nadie le importará en 3 meses, sáltatelo." Pero esta regla se aplica cada vez más solo a la IA.
• En el mismo hilo, otro usuario nota que "la mayoría de productos de IA para no programadores no han despegado"; Anthropic se enfocó en desarrolladores y funcionó. El resultado: los programadores son los primeros en adoptar, pero también los primeros en sufrir las consecuencias.
• Un paquete de 55 prompts para Claude incluye 15 solo para documentación —pero orientados a que la IA genere docs para humanos, no a que los humanos documenten para otros humanos.
• Lenny's Newsletter reporta que Claude Code se usa para sintetizar llamadas con clientes y mantener supuestos actualizados, pero el output se queda en el ecosistema de la IA, no en una wiki compartida.

Lo que puedes hacer