Si has trabajado en Drupal en algún momento en un proyecto medio (más de 2 módulos custom y un tema custom), esto te sonará:
"Buf ni me acuerdo que hacía este módulo ni que campo se usan aquí. Si modifico algo aquí igual me cargo el sitio entero...."
Lo lógico para evitar estos problemas es la misma, Documentación !!! qué ocurre, que los desarrolladores no destacamos por hacer documentación... jeje y después nos pasa esto!
Para intentar resolverlo, he estado trabajado en crear una skill de IA dedicada a documentar proyectos Drupal. Creo que tengo ya algo funcional (lo estoy usando actualmente) y quiero compartir mi enfoque.
¿Porqué documentar con IA?
No se trata solo de "tener documentación bonita". Yo diría que tengo 2 razones principales:
- Documentación técnica del proyecto: El principal objetivo es tener una documentación fiable de qué hace cada módulo custom, qué contiene el tema, y cómo está modelado el contenido. Esta docu le sirve tanto al propio equipo de desarrollo, como a cualquier otro desarrollador que se incorpore.
- Retroalimentar a la IA con contexto real y técnico: Esto creo que es lo más importante. Cualquier IA (Claude Code, Gemini, etc..) trabaja mucho mejor cuando tiene acceso a documentación estructurada del propio proyecto, en lugar de tener que investigar la arquitectura leyendo archivo por archivo cada vez. Cuanto más precisa y específica sea esa documentación, mejor es el rendimiento de la IA a la hora de proponer cambios, detectar dependencias o evitar romper flujos.
¿Cuál es mi enfoque de la Skill?
La skill la he planteado como una secuencia de varias faces. En cada fase de la documentación, me centro en una parte se documenta de forma independiente:
- Documentación de cada módulo custom, siempre de forma independiente:
Cada módulo custom del proyecto se documenta por separado: qué hooks implementa, qué servicios expone, qué entidades o campos define, y qué responsabilidad de negocio cubre. De esta formaa creo es más fácil de mantener, y también más fácil de cargar como contexto cuando la IA solo necesita trabajar sobre uno de ellos. - Documentación del tema custom, de forma independiente
Igual que los módulos custom: preprocess, plantillas Twig sobrescritas, librerías de assets, y cualquier lógica de presentación relevante. - Documentación de la estructura de la base de datos: tipos de contenido y taxonomías
Aquí intento documentar el Modelo de Datos orientado a Drupal: tipos de contenido, campos, vocabularios de taxonomía y relaciones entre ellos. De esta forma apoyo el contexto/documentación de los módulos custom y temas con datos "reales" (porque tenemos nombres reales de tipos de contenidos, campos, etc...) - Relaciones entre módulos y flujos de trabajo
Con las tres documentaciones anteriores ya generadas, el último paso consiste en cruzarlas: identificar qué módulos custom interactúan entre sí y a partir de ahí intentar describir los flujos de trabajo que el proyecto está implementando.
A simple vista parece que estoy "perdiendo" el potencial de la IA porque estoy "secuenciado" o limitando lo que puede hacer pero yo creo que es al contrario porque:
- Cada documento al ser independiente, se puede utilizar por separado. Puedes regenerar solo la documentación de un módulo concreto tras un cambio, sin tener que rehacer todo el proyecto.
- La fase final de relaciones y flujos de trabajo depende de que las anteriores existan. Sin la documentación de módulos, tema y modelo de datos ya generada, no hay con qué cruzar información para detectar los flujos reales y puede ser que la IA empiece a alucinar...
¿ Cual es el resultado de mi skill?
Básicamente me expone la documentación organizada dentro de un módulo custom (normalmente el principal o más importante). Con esta documentación que genero puedo:
- Consultar la documentación de forma "tradicional" (qué hacía esto¿?).
- Usar la IA con un contexto "cerrado" solamente a lo que quiero solucionar
- Puedo gestionar mejor la docu, actualizando solo lo que necesito sin tocar el resto de componentes
