En muchos equipos de desarrollo y de sistemas, la documentación sigue siendo el gran punto débil del proyecto. El código evoluciona, los entornos cambian, aparecen integraciones nuevas, se añaden variables de entorno, se tocan despliegues y, mientras tanto, la documentación se queda atrás. El resultado es conocido: onboarding lento, errores evitables, dependencia excesiva de una o dos personas y agentes de IA que arrancan con contexto incompleto o directamente erróneo.
Ahí es donde un prompt bien diseñado puede marcar una diferencia enorme. No porque sustituya al criterio técnico del equipo, sino porque permite usar herramientas como Claude Code —o asistentes similares capaces de leer repositorios y modificar archivos— como un auditor documental automatizado, con capacidad para contrastar lo que dice el proyecto con lo que realmente hace el código.
El prompt que se plantea aquí va justo a ese problema. No es un simple “resume este repo” ni un “hazme un README mejor”. Es una instrucción operativa bastante más seria: obliga al asistente a inventariar la documentación existente, analizar el código real, detectar huecos, corregir inconsistencias y generar una base documental pensada para que cualquier instancia futura de Claude arranque desde cero sin perder contexto.
Ese matiz es importante. La clave ya no es solo documentar para humanos, sino también documentar para agentes que van a trabajar dentro del proyecto. Y eso cambia bastante el enfoque.
De documentación decorativa a documentación operativa
Uno de los mayores errores en muchos repositorios es tratar la documentación como un extra. Se escribe un README inicial, quizá alguna guía suelta en docs/, y a partir de ahí el conocimiento real se desplaza al código, a Slack, a tickets antiguos o directamente a la memoria del desarrollador que más tiempo lleva en el proyecto.
El prompt que propones ataca precisamente ese problema con una estructura en cinco pasos bastante bien pensada.
Primero, obliga a hacer inventario. Eso significa leer todos los .md del proyecto, localizar documentación en raíz, .claude/, docs/ o donde exista, y cruzarla con ficheros como package.json, composer.json o .env.example. Este paso parece básico, pero en realidad ya resuelve uno de los fallos más comunes: muchos proyectos tienen documentación dispersa, duplicada o medio olvidada, y nadie tiene una visión clara de qué existe y para qué sirve.
Después llega lo más valioso: el análisis del código real. Y aquí está una de las mejores ideas del prompt. No pide repetir lo que dice la documentación, sino extraer del propio código el stack real, la estructura de carpetas, los modelos principales de base de datos, los patrones repetidos, las variables de entorno necesarias, los comandos clave, las integraciones externas y los comportamientos no obvios. Es decir, obliga al asistente a trabajar como lo haría un desarrollador que entra a un proyecto heredado y quiere entender cómo funciona de verdad.
Eso tiene muchísimo valor para sysadmins y desarrolladores, porque una parte importante de los problemas operativos nace justo de esa diferencia entre lo documentado y lo desplegable.
La parte más útil: detectar lo que falta y lo que ya no es verdad
El tercer bloque del prompt, el de detección de gaps, es probablemente el más potente desde el punto de vista práctico. Aquí el asistente tiene que comparar la documentación con el código y señalar tres tipos de problemas que suelen ser los más peligrosos:
El primero es la información importante que no está documentada. Por ejemplo, variables de entorno obligatorias, dependencias de servicios externos, jobs que solo se entienden leyendo código o pasos de despliegue que el equipo da por supuestos.
El segundo es lo que está documentado pero ya no coincide con la realidad. Este caso es aún peor, porque una documentación antigua no solo no ayuda: desinforma. Y eso en producción, en migraciones o en incidencias puede costar tiempo y dinero.
El tercero son las decisiones técnicas enterradas en el código pero nunca explicadas. Este punto es clave. Un proyecto puede funcionar perfectamente y seguir siendo difícil de mantener si nadie ha dejado por escrito por qué se eligió un patrón concreto, una arquitectura determinada o una integración específica.
El prompt también pide localizar TODOs relevantes o partes a medio hacer. Y eso convierte la auditoría documental en algo más cercano a una foto real del estado del proyecto, no a un mero ejercicio cosmético.
CLAUDE.md, arquitectura, convenciones y estado: una estructura con sentido
El cuarto paso del prompt plantea algo muy interesante: no se limita a pedir “actualiza la documentación”, sino que define una estructura documental útil para agentes y para equipos.
Primero, propone crear o actualizar un CLAUDE.md en la raíz. La idea de usar este archivo como índice ligero es bastante acertada. No se trata de meter ahí todo el conocimiento del proyecto, sino de dejar una puerta de entrada clara: stack, convenciones, estado general y referencias al resto de documentación más detallada.
Después, lleva el contenido importante a tres ficheros dentro de .claude/:
ARCHITECTURE.md, para stack completo, base de datos, relaciones, decisiones técnicas e integraciones externas.
CONVENTIONS.md, para patrones de código, nomenclatura, estructura de ficheros nuevos y antipatrones detectados.
STATUS.md, para reflejar qué está en marcha, qué está roto, qué está pendiente y cuáles son los próximos pasos conocidos.
Esta división tiene mucho sentido porque separa lo estructural, lo normativo y lo situacional. Y eso, tanto para un desarrollador nuevo como para un agente que entra a trabajar en el repo, reduce mucho la ambigüedad.
En otras palabras: el prompt no solo mejora documentación, también crea contexto persistente.
Necesito que hagas una auditoría completa de la documentación de este proyecto
y la enriquezcas para que cualquier instancia de Claude pueda arrancar desde
cero sin perder contexto.
Sigue estos pasos en orden:
## PASO 1 — Inventario
- Lee todos los ficheros .md que encuentres en el proyecto (raíz, .claude/, docs/, donde estén)
- Lee el package.json / composer.json / .env.example si existen
- Haz un listado de qué documentación existe y qué cubre cada fichero
## PASO 2 — Análisis del código
Analiza el código del proyecto y extrae:
- Stack real con versiones (no lo que diga la doc, lo que diga el código)
- Estructura de carpetas y su propósito
- Modelos de BD principales y sus relaciones clave
- Patrones de código que se repiten (cómo se crean recursos, servicios, etc.)
- Variables de entorno necesarias (nombres y propósito, sin valores)
- Comandos importantes (artisan, npm, deploy, etc.)
- Integraciones externas y cómo se usan
- Cualquier comportamiento no obvio o "gotcha" que veas en el código
## PASO 3 — Detección de gaps
Compara la documentación existente con lo que encontraste en el código y dime:
- Qué información importante NO está documentada
- Qué hay documentado que ya no corresponde con el código real
- Qué decisiones técnicas están en el código pero sin explicación
- Qué está a medio hacer o tiene TODOs relevantes
## PASO 4 — Actualización de ficheros
Basándote en los gaps detectados:
1. Si existe CLAUDE.md, actualízalo. Si no existe, créalo en la raíz.
- Debe ser un índice ligero (~150 líneas máximo)
- Stack, convenciones clave, estado actual, referencias a otros md
2. Crea o actualiza .claude/ARCHITECTURE.md con:
- Stack completo con versiones
- Estructura de BD y relaciones
- Decisiones técnicas importantes y por qué se tomaron
- Integraciones externas
3. Crea o actualiza .claude/CONVENTIONS.md con:
- Patrones de código que se usan en este proyecto
- Naming conventions
- Cómo se estructuran los ficheros nuevos
- Qué NO hacer (antipatrones detectados)
4. Crea o actualiza .claude/STATUS.md con:
- Estado actual del proyecto
- Qué está en curso / pendiente / roto
- Próximos pasos conocidos
- Decisiones pendientes
## PASO 5 — Informe final
Dame un resumen de:
- Qué ficheros creaste o modificaste
- Los 3-5 gaps más críticos que encontraste y cómo los cubriste
- Algo que no puedas saber solo leyendo el código y que debería completar yo manualmente
No me pidas confirmación entre pasos, ejecuta todo y al final dame el informe.Lenguaje del código: PHP (php)Por qué este prompt es especialmente útil para equipos técnicos
Para un medio de desarrolladores y sysadmins, lo importante no es presentar este prompt como una curiosidad, sino como una herramienta de productividad técnica bastante seria.
Bien usada, esta instrucción puede servir para:
acelerar el onboarding de nuevos perfiles;
reducir dependencia de conocimiento tribal;
preparar el proyecto para trabajar mejor con asistentes de IA;
detectar deuda documental antes de que se convierta en deuda operativa;
y convertir la documentación en una parte viva del ciclo de desarrollo.
Además, tiene otra ventaja importante: no pide confirmación entre pasos. Eso obliga al agente a recorrer todo el flujo de trabajo de principio a fin y entregar un informe final cerrado, algo mucho más útil que las interacciones fragmentadas en las que el modelo se queda a medio camino porque va pidiendo permiso a cada paso.
No convierte a Claude Code en arquitecto mágico ni resuelve por sí solo lo que el equipo no ha decidido. Pero sí lo convierte en algo muy útil: un revisor disciplinado capaz de leer, contrastar, ordenar y dejar preparado un contexto mucho más sólido para el siguiente humano o la siguiente instancia de IA que entre al proyecto.
Y en 2026, donde cada vez más equipos mezclan desarrollo, automatización, agentes y operación, eso ya no es un lujo documental. Empieza a ser una necesidad práctica.
Preguntas frecuentes
¿Este prompt sirve solo para Claude Code?
No. Puede adaptarse bastante bien a otras herramientas capaces de leer repositorios, inspeccionar código y editar archivos dentro del proyecto.
¿Qué tipo de proyectos se benefician más de este enfoque?
Sobre todo proyectos medianos o grandes, con documentación dispersa, varios mantenedores, entornos complejos o necesidad de trabajar con asistentes de IA de forma recurrente.
¿Sustituye al arquitecto o al responsable técnico del proyecto?
No. Lo que hace es acelerar inventario, contraste y redacción, pero sigue habiendo decisiones que requieren contexto de negocio, historia del equipo o prioridades que no están en el código.
¿Cada cuánto conviene lanzar una auditoría así?
Tiene sentido hacerlo al inicio de un proyecto heredado, antes de incorporar nuevos desarrolladores, antes de delegar trabajo en agentes y después de cambios importantes de arquitectura o despliegue.
