grill-with-docs

grill-with-docs es un Skill de código abierto desarrollado por Matt Pocock dentro de su colección de herramientas para ingeniería de software. Está diseñado como un sistema de entrevista continua + documentación para proyectos de desarrollo.

Su definición oficial es sencilla: entrevistar al desarrollador sobre un plan o diseño hasta que ambas partes tengan la misma comprensión del problema, mientras los términos importantes y las decisiones clave quedan registrados dentro del repositorio.

Es un Skill que requiere activación manual: solo se ejecuta cuando el desarrollador introduce /grill-with-docs. El agente no decide utilizarlo por sí mismo.

Su objetivo principal es solucionar uno de los problemas más frecuentes del AI Coding: la diferencia entre lo que el desarrollador cree que ha explicado y lo que realmente ha entendido el agente.

Por eso resulta especialmente interesante durante las primeras etapas de desarrollo, cuando el plan todavía es ambiguo o los conceptos del dominio aún no están bien definidos.

La diferencia fundamental frente a un simple prompt del tipo «hazme algunas preguntas antes de programar» es que grill-with-docs mantiene el estado de lo aprendido.

Otros Skills de interrogación dejan la información dentro de la conversación. grill-with-docs, en cambio, convierte parte de ese conocimiento en activos permanentes del proyecto: los términos se incorporan a CONTEXT.md y las decisiones importantes se documentan mediante ADR.

¿Por qué AI Coding necesita algo así?

Imagina una situación habitual. Le dices a un agente de IA:

«Ayúdame a añadir un sistema de permisos para usuarios».

Un agente puede empezar a modificar el código inmediatamente. Pero antes habría que responder muchas preguntas:

¿Qué significa exactamente «permiso» en este proyecto? ¿Qué relación existe entre permisos y roles? ¿Qué operaciones necesitan autorización? ¿El control se realiza a nivel de recurso o de funcionalidad? ¿Qué conceptos similares existen ya en el código? ¿Qué decisiones arquitectónicas se han tomado anteriormente? ¿Qué elecciones serán difíciles de modificar después?

Matt Pocock resume este problema en el README del proyecto citando una idea de The Pragmatic Programmer: nadie sabe exactamente lo que quiere.

Desde esta perspectiva, uno de los principales puntos débiles del AI Coding no es necesariamente la capacidad de programar, sino la comunicación entre la persona y el agente.

Sin embargo, hay una condición importante que puede pasar desapercibida: grill-with-docs presupone que ya existe un repositorio y que ese repositorio contiene, o debería contener, conceptos de dominio definidos.

Si estás empezando un proyecto completamente nuevo y todavía no existe código ni un modelo de dominio previo, una de las principales ventajas de grill-with-docs —comparar las nuevas decisiones con el modelo existente— pierde buena parte de su referencia.

¿Cómo funciona realmente grill-with-docs?

Su funcionamiento puede resumirse en un ciclo:

pregunta → respuesta → revisión del código → aclaración de términos → decisión → actualización de CONTEXT.md o ADR → siguiente decisión

Hay varios mecanismos especialmente importantes.

Una pregunta cada vez, con una respuesta recomendada

No se trata simplemente de hacer preguntas una detrás de otra. El proceso intenta recorrer un árbol de decisiones de diseño.

La respuesta a una pregunta se convierte en la premisa de la siguiente. Al plantear una sola cuestión cada vez, el sistema evita avanzar sobre decisiones que todavía no están resueltas o formular preguntas cuya relevancia podría desaparecer después.

Si el código puede responder, el agente no debería preguntarte

Esta es una de las diferencias importantes frente a grill-me.

grill-me se centra en la conversación y realiza preguntas al desarrollador. grill-with-docs, en cambio, puede inspeccionar primero el repositorio y utilizar la información existente.

Solo debería preguntarte aquello que el código no puede resolver por sí mismo.

Esto reduce preguntas innecesarias y, sobre todo, evita que el desarrollador tenga que explicar algo que ya está documentado en el proyecto.

Los términos se documentan en cuanto quedan resueltos

Una de las reglas centrales del Skill es que un término no se guarda al final de toda la entrevista.

Cuando un concepto queda definido, se incorpora inmediatamente a CONTEXT.md.

Esto es importante porque convierte el vocabulario compartido en una fuente de contexto que otros agentes pueden consultar posteriormente.

No todas las decisiones merecen un ADR

grill-with-docs también intenta evitar que el repositorio termine lleno de documentos irrelevantes.

Una decisión solo debería convertirse en ADR cuando sea realmente difícil de revertir y difícil de entender sin conocer el motivo original.

Por ejemplo, elegir event sourcing frente a CRUD o adoptar aislamiento multi-tenant en lugar de utilizar una tabla compartida son decisiones que pueden justificar este nivel de documentación.

Es principalmente una capa de entrada

Otro detalle importante es que grill-with-docs no contiene por sí mismo toda la lógica.

Funciona como una capa que utiliza otros Skills, principalmente grilling, encargado de la entrevista, y domain-modeling, encargado de la documentación.

Por tanto, instalar únicamente grill-with-docs no es suficiente para reproducir todo el flujo.

¿Qué valor aporta realmente CONTEXT.md?

El problema que intenta resolver CONTEXT.md es bastante concreto: cuando un nuevo AI Agent entra en un proyecto, tiene que descubrir desde cero el vocabulario interno del sistema.

Sin una terminología compartida, una idea que podría expresarse con una palabra termina necesitando una explicación de varias frases.

Matt Pocock utiliza en el repositorio un ejemplo bastante claro:

Antes: «Hay un problema cuando una lección dentro de una sección de un curso se vuelve “real”, es decir, cuando recibe una ubicación dentro del sistema de archivos».

Después: «Hay un problema con la cascada de materialización».

La diferencia muestra el verdadero valor de CONTEXT.md: no se limita a almacenar conocimiento; comprime el contexto necesario para entender el proyecto.

Cuando los conceptos están unificados, también resulta más fácil mantener una nomenclatura coherente en variables, funciones y archivos. El repositorio se vuelve más fácil de navegar para el agente y este puede gastar menos tokens intentando reconstruir qué significa cada término.

Pero existe un riesgo importante: CONTEXT.md puede quedarse obsoleto.

Si el modelo de dominio cambia y el documento no se actualiza, lo que originalmente servía para reducir malentendidos puede terminar provocándolos.

El propio Matt Pocock reconoce que este problema es una de las principales fuentes de complicaciones del sistema. Al tratarse de un archivo real del repositorio, puede no existir cuando el agente espera encontrarlo o puede divergir cuando varias personas lo modifican simultáneamente.

¿Realmente hacen falta los ADR?

El principal objetivo de un ADR, o Architecture Decision Record, es conservar algo que normalmente queda oculto en la cabeza de los desarrolladores: por qué se tomó una determinada decisión.

grill-with-docs es bastante conservador a la hora de generar ADR. Una decisión tiene que superar varios filtros antes de convertirse en documentación permanente.

Esa moderación tiene sentido. Si cada pequeña decisión terminara convertida en un ADR, el repositorio se llenaría rápidamente de documentos que nadie leería.

Lo que realmente merece conservarse son las decisiones difíciles de revertir y cuyo motivo no resulta evidente al mirar el código.

Y aquí aparece una diferencia interesante: los ADR pueden ser incluso más valiosos para un AI Agent que para un desarrollador humano.

Una persona que hereda un proyecto puede preguntar a un compañero, revisar el historial de commits o incluso reconstruir la intención a partir del código.

Un agente de IA no dispone de ese contexto social. Su principal fuente de información son los archivos del proyecto.

Un ADR bien escrito puede ser, por tanto, la única forma de que el agente entienda por qué una arquitectura determinada funciona de esa manera.

Experiencia de uso real

Los comentarios de la comunidad muestran opiniones bastante divididas.

Algunos usuarios aseguran haber pasado varias sesiones de medio día respondiendo cerca de un centenar de preguntas y consumiendo casi la mitad de su cuota.

Otros, después de varios días, consideran que los documentos generados aportan poco valor práctico.

También existen evaluaciones positivas. Algunos usuarios destacan que /grill-with-docs obliga al agente a consultar la documentación real antes de escribir código y lo consideran una capa de disciplina especialmente útil después de haber sufrido repetidamente alucinaciones de APIs.

Pero también hay una crítica importante: estos patrones pueden parecer, en esencia, una colección de prompts muy bien diseñados para herramientas como Claude Code. Desde esta perspectiva, la popularidad del proyecto reflejaría en parte el tamaño de la audiencia de Matt Pocock y no necesariamente una revolución tecnológica.

Estas opiniones apuntan a una conclusión importante: el valor de grill-with-docs depende mucho del proyecto.

Si el dominio tiene conceptos complejos, existen decisiones difíciles de revertir y varios agentes van a trabajar sobre el mismo código durante meses, documentar el contexto puede aportar un valor considerable.

Si el proyecto ya tiene una terminología clara y una documentación madura, el beneficio marginal puede ser mucho menor.

¿Realmente consigue que la IA escriba mejor código?

Aquí conviene separar dos problemas.

Lo que sí puede mejorar:

• comprensión de requisitos;
• modelado del dominio;
• coherencia terminológica;
• documentación de decisiones arquitectónicas;
• comprensión del contexto por parte de agentes posteriores.

Lo que no puede garantizar:

• que el código sea correcto;
• que la arquitectura sea necesariamente buena;
• que las pruebas sean suficientes;
• que el agente no introduzca errores.

Este es probablemente el punto más importante de todo el análisis:

entender correctamente el problema no equivale a saber programarlo correctamente.

grill-with-docs mantiene una relación complementaria con TDD, los tests, el análisis estático y el Code Review. No los sustituye.

• grill-with-docs intenta garantizar que estamos construyendo lo correcto.
• TDD y los tests ayudan a comprobar que lo construido funciona.
• Code Review ayuda a verificar que la implementación tiene una calidad aceptable.

Un comentario de usuario resume bien el problema: cuando se entrega un proyecto antiguo a una IA y la complejidad del negocio aumenta, el agente puede generar errores constantemente, hasta convertir el proyecto en una especie de caja negra difícil de revisar.

Es decir, incluso con una buena alineación de requisitos, las limitaciones del propio agente de programación siguen existiendo.

¿Qué diferencia hay frente a un prompt normal?

Prompt tradicional

Un prompt del tipo «hazme algunas preguntas antes de escribir código» normalmente:

• no tiene un árbol de decisiones estructurado;
• no inspecciona necesariamente el repositorio;
• no crea una terminología compartida;
• no conserva los resultados como activos del proyecto;
• obliga a repetir parte del proceso en futuras conversaciones.

grill-with-docs

grill-with-docs, en cambio:

• profundiza progresivamente siguiendo decisiones de diseño;
• inspecciona el código existente antes de preguntar;
• registra los términos resueltos en CONTEXT.md;
• convierte decisiones importantes en ADR;
• deja el conocimiento dentro del repositorio para que otros agentes puedan reutilizarlo.

Por eso, grill-with-docs no es simplemente un «prompt avanzado», sino un flujo de trabajo de ingeniería.

La diferencia principal no está en hacer preguntas más inteligentes, sino en qué queda después de responderlas.

Frente a utilizar directamente un AI Coding Agent

Un flujo típico sin este tipo de Skill sería:

requisitos → comprensión de la IA → implementación → pruebas → descubrimiento de problemas → modificaciones → retrabajo

Con grill-with-docs, el proceso puede convertirse en:

grill-with-docs → to-spec → to-tickets → implement → code-review

El segundo flujo es claramente más largo. Pero un proceso más largo no significa automáticamente un proceso más profesional.

La pregunta correcta es cuándo merece la pena añadir ese coste.

Tiene sentido cuando el coste de corregir un malentendido es mucho mayor que el coste de aclarar los requisitos antes de programar.

Por el contrario, si una funcionalidad realmente puede implementarse en diez minutos y dedicar treinta minutos a la entrevista no aporta información relevante, el proceso se convierte en una pérdida de tiempo.

¿Para qué proyectos merece la pena?

Muy recomendable

• repositorios medianos y grandes ya existentes;
• sistemas con lógica de negocio compleja;
• proyectos desarrollados durante mucho tiempo por varios agentes;
• dominios con muchos conceptos específicos;
• equipos con varios desarrolladores;
• proyectos que tendrán mantenimiento durante años.

Probablemente innecesario

• scripts sencillos;
• herramientas de un solo uso;
• proyectos de unas pocas decenas de líneas;
• prototipos rápidos;
• funcionalidades cuya implementación ya está completamente definida.

Un criterio práctico sería exigir dos condiciones simultáneas:

1. El repositorio debe contener suficientes conceptos de dominio que necesiten una terminología común.
2. El coste de interpretar mal una decisión debe ser suficientemente alto.

Un sistema de permisos o una plataforma de pagos son buenos ejemplos de situaciones en las que un error conceptual puede resultar mucho más costoso que dedicar tiempo adicional a la fase de definición.

Coste de uso

Consumo de tokens

Algunos usuarios han informado de un consumo cercano a la mitad de su cuota durante el proceso.

El proyecto ha conseguido reducir el coste de tokens mediante la extracción de código compartido, con una reducción oficial del 63 %, pero el gasto sigue siendo considerable.

Coste de tiempo

Una sesión típica de grilling puede durar desde varias decenas de minutos hasta varias horas, dependiendo de la complejidad del proyecto y del número de decisiones pendientes.

Mantenimiento de documentación

CONTEXT.md necesita mantenerse actualizado y los ADR se acumulan con el tiempo.

Si el equipo no incorpora la actualización de documentación a su flujo normal de trabajo, estos archivos pueden quedar obsoletos rápidamente.

La pregunta clave

Si una funcionalidad realmente puede desarrollarse en diez minutos, ¿merece la pena dedicar tiempo a hacer grilling antes?

En muchos casos, no.

Pero existe una condición importante: esos diez minutos tienen que ser reales.

Si la aparente simplicidad es solo una ilusión y detrás de la funcionalidad existen decisiones de arquitectura, dependencias o reglas de negocio que todavía no están claras, hacer grilling puede ahorrar mucho más tiempo del que consume.

Ventajas

• Obliga a alinear los requisitos antes de escribir código.
• Reduce las decisiones arbitrarias tomadas por el agente.
• Crea una terminología compartida a nivel de proyecto.
• Evita repetir la misma explicación en cada conversación.
• Convierte decisiones importantes del chat en activos permanentes del repositorio.
• Permite que futuros agentes comprendan más rápidamente el contexto.
• Utiliza un árbol de decisiones estructurado en lugar de depender de preguntas improvisadas.

Desventajas y limitaciones

• El proceso inicial se alarga considerablemente: no es ideal cuando la prioridad absoluta es la velocidad.
• Consume bastantes tokens: los usuarios sensibles al coste deben valorar si el beneficio compensa el gasto.
• Puede resultar excesivo para tareas sencillas: una tarea de diez minutos podría acabar requiriendo treinta minutos de preparación.
• La documentación puede quedar obsoleta: CONTEXT.md y los ADR pierden valor si no se mantienen sincronizados con el código.
• Los errores de comprensión del agente siguen siendo posibles: si la IA interpreta mal el repositorio, puede llegar a conclusiones incorrectas.
• Requiere participación activa del usuario: respuestas poco cuidadas producen decisiones poco fiables.
• El comportamiento puede variar entre agentes: distintos AI Coding Agents pueden interpretar y ejecutar el Skill de manera diferente.
• No funciona de forma completamente independiente: es una capa de entrada que depende de grilling y domain-modeling.
• La recomendación del propio autor ha evolucionado: Matt Pocock ha reducido la prioridad de grill-me como punto de entrada para coding y actualmente recomienda un flujo basado en domain-model → to-prd → to-issues → tdd.

Valoración final

Puntuación: 3,5/5,0

Criterio	Puntuación
---	---:
Alineación de requisitos	4,5/5
Mejora de la calidad del diseño	3,5/5
Ayuda práctica para AI Coding	3,5/5
Valor a largo plazo	4,0/5
Facilidad de uso	3,0/5
Coste de tiempo	2,5/5
Coste de tokens	2,5/5
Ámbito de aplicación	3,0/5
Compatibilidad con otros flujos	4,0/5

Entonces, ¿qué es realmente grill-with-docs?

Es una herramienta de alineación de requisitos mediante interrogación con estado.

No es simplemente un prompt más sofisticado. Su principal aportación es convertir el proceso de alineación entre desarrollador y agente en información persistente dentro del propio proyecto.

¿Qué problema de AI Coding intenta solucionar?

El problema de tener una idea todavía ambigua en la cabeza del desarrollador mientras el agente no dispone de suficiente contexto para ejecutarla correctamente.

No soluciona directamente la falta de capacidad de programación de la IA.

¿Tienen valor CONTEXT.md y los ADR?

Sí, pero solo si se mantienen actualizados.

Si se abandonan, pueden convertirse en una fuente adicional de errores. Si se mantienen correctamente, constituyen algunos de los activos no relacionados directamente con el código más valiosos de un proyecto.

El código explica qué hace el sistema. CONTEXT.md y los ADR ayudan a explicar por qué funciona de esa manera y si desarrolladores y agentes están hablando realmente de los mismos conceptos.

¿Puede reducir el retrabajo en AI Coding?

Sí, pero principalmente el retrabajo provocado por malentendidos de requisitos y contexto.

No elimina el retrabajo provocado por código incorrecto. Para eso siguen siendo necesarios TDD, tests y Code Review.

¿Cuándo merece la pena?

Cuando se cumplen simultáneamente estas dos condiciones:

1. El proyecto contiene suficientes conceptos de dominio que necesitan una terminología común.
2. El coste de interpretar mal una decisión es elevado.

¿Cuándo no hace falta?

En scripts sencillos, herramientas de un solo uso, prototipos rápidos o tareas cuya implementación ya está completamente definida.

¿Debería un desarrollador normal empezar directamente con grill-with-docs?

No necesariamente.

Puede ser más razonable empezar con un flujo de grilling más sencillo. Si con el tiempo descubres que en cada nueva conversación tienes que volver a explicar el contexto del proyecto o que la terminología interna genera errores frecuentes, entonces grill-with-docs empieza a tener mucho más sentido.

Conclusión

grill-with-docs merece la pena, pero no para todos los proyectos.

Es especialmente útil en repositorios medianos y grandes que van a mantenerse durante mucho tiempo, sobre todo cuando contienen una lógica de negocio compleja y las decisiones equivocadas son caras de revertir.

Su valor no consiste en hacer que la IA sea más inteligente, sino en conseguir que la IA y el desarrollador estén pensando en el mismo problema.

En un sistema complejo, esa diferencia puede ahorrar una cantidad considerable de retrabajo.

En un CRUD sencillo que puede resolverse en unos minutos, probablemente solo añade fricción.