JOURNAL /
Documentar con evidencia, no con apariencia de certeza
Un inventario no es una validación. Cómo separar hechos, inferencias y pendientes para que la documentación de un repositorio sea útil y revisable.
El documento puede estar completo y la comprobación, no
Una lista de carpetas, un diagrama de componentes y una explicación fluida pueden ayudar a orientarse. Sin embargo, ninguno de esos elementos demuestra por sí solo que una funcionalidad se haya ejecutado, que una integración responda o que una versión publicada coincida con el código revisado.
La primera regla es separar el alcance del documento del alcance de la evidencia. Un mapa del código describe lo que se ha encontrado. Una prueba aporta información sobre un comportamiento y unas condiciones concretas. La verificación de una página publicada responde a otra pregunta distinta.
Tres estados que conviene escribir
Observado: una afirmación respaldada por una fuente identificable. Puede ser una configuración leída, un contrato definido en el código o un resultado ejecutado. La referencia debe permitir que otra persona revise el mismo punto.
Inferido: una interpretación razonable a partir de varias señales. Debe quedar etiquetada como tal. Que exista un adaptador no demuestra que se haya utilizado; que exista un formulario no demuestra que el servicio de destino esté disponible.
Desconocido: una pregunta todavía abierta. Una restricción de acceso, una credencial ausente o un flujo no ejecutado no son defectos que se puedan ocultar con una frase genérica de cierre.
Usar la IA sin cederle la autoridad
Un agente puede recorrer archivos, resumir contratos y preparar documentación. El límite está en la autoridad de las fuentes y en el permiso para acceder a ellas. La documentación debe trabajar con repositorios autorizados y no transformar contenido privado en material público por comodidad.
También importa el alcance de la tarea. Documentar no equivale a refactorizar. Si la tarea consiste en explicar un sistema, modificar su comportamiento para que encaje mejor en la explicación introduce una dependencia peligrosa entre lo que se describe y lo que se cambia.
Una ficha mínima para cada flujo
Un punto de entrada, el objetivo del flujo, sus dependencias y un recorrido del comportamiento principal suelen ser más útiles que una enumeración extensa de símbolos. Después se añaden los estados de error, las restricciones de acceso y los puntos que necesitan comprobación.
Cada resultado debería indicar qué se revisó, cómo se comprobó y qué no cubre esa comprobación. Las pruebas de una función no sustituyen una revisión de navegador. Una compilación correcta no valida un contenido editorial. Un despliegue aceptado por el proveedor no demuestra que todos los enlaces públicos funcionen.
Cerrar sin inventar una conclusión
El cierre útil no necesita afirmar que todo está al cien por cien. Necesita que el siguiente lector pueda distinguir lo implementado, lo comprobado y lo pendiente, y continuar sin repetir toda la investigación.
Self-Documenting Democracy desarrolla este enfoque mediante skills de documentación para Claude Code y Codex, con ediciones independientes en inglés y español. NgAutoPilot aborda un límite relacionado: orientar el trabajo del agente según el contexto técnico y mantener la validación explícita. Sus repositorios son la referencia para el alcance actual; este artículo no los presenta como una garantía universal.