Cómo documentar un workflow de IA

Por qué documentar

Un workflow no documentado solo existe en la cabeza de quien lo creó. En cuanto esa persona no está disponible, el sistema se convierte en una caja negra. Nadie sabe por qué hace lo que hace, cómo cambiarlo ni cómo depurarlo.

Documentar no es burocracia. Es la diferencia entre un sistema que crece y uno que se abandona.

Qué debe incluir la documentación

1. Resumen ejecutivo (para que cualquiera entienda en 2 minutos)

Nombre del workflow: [Nombre]
Objetivo: [Qué hace en una frase]
Input: [Qué datos o eventos lo disparan]
Output: [Qué produce]
Frecuencia: [Cuándo se ejecuta]
Responsable: [Quién lo mantiene]
Última actualización: [Fecha]

2. Diagrama del flujo

Un diagrama visual es imprescindible. Muestra:

• El evento o trigger que inicia el workflow
• Cada paso en orden
• Las decisiones (condicionales)
• Las herramientas y APIs que intervienen
• El output final

No necesitas herramientas sofisticadas. Un diagrama en Mermaid, Excalidraw o incluso en papel sirve.

3. Descripción de cada paso

Para cada paso del workflow:

## Paso N: [Nombre descriptivo]

**Qué hace**: descripción clara en 1-3 frases
**Input**: qué datos recibe
**Output**: qué produce
**Herramientas usadas**: [lista]
**Errores posibles**: qué puede fallar y cómo se maneja
**Tiempo estimado**: cuánto tarda normalmente

4. Prompts y configuración

Si hay LLMs involucrados, documenta:

• El system prompt completo (o referencia al archivo)
• La versión del modelo usada
• Los parámetros de temperatura y tokens
• La razón de cada decisión de configuración

5. Dependencias externas

• APIs externas y sus endpoints
• Credenciales necesarias (solo referencia, nunca los valores)
• Servicios de terceros y sus límites de rate
• Bases de datos o almacenamiento

6. Casos de prueba

Documenta los casos que validan que el workflow funciona:

## Caso de prueba 1: [Nombre]
Input: [ejemplo]
Output esperado: [ejemplo]
Resultado actual: ✅ / ❌
Notas: [observaciones]

7. Historial de cambios

## Changelog
- 2026-05: v1.0 — Versión inicial
- 2026-06: v1.1 — Añadido paso de validación
- 2026-07: v2.0 — Refactorizado para usar RAG

Plantilla mínima viable

Si no tienes tiempo para documentar todo, este mínimo es suficiente para empezar:

# [Nombre del workflow]

**Qué hace**: [1 frase]
**Cuándo se ejecuta**: [trigger]
**Output**: [qué produce]

## Pasos
1. [Paso 1]
2. [Paso 2]
3. [Paso 3]

## Herramientas
- [Herramienta 1]: [para qué se usa]
- [Herramienta 2]: [para qué se usa]

## Si algo falla
- [Error común 1]: [cómo resolverlo]
- [Error común 2]: [cómo resolverlo]

## Responsable
[Nombre] — [contacto]

Dónde guardar la documentación

La documentación vive junto al código del workflow. En el mismo repositorio, en la misma carpeta, actualizada en el mismo commit que los cambios.

Documentación separada del código es documentación que siempre está desactualizada.

---

Siguiente: Glosario básico de IA para empresas y creadores