IA para documentar sin odiar tu vida: comentarios, README y changelog que sí sirven

Llegas tarde al standup con la laptop medio viejita, ventilador sonando como turbo. Te preguntan qué cambió en el deploy de anoche. Abres el PR y… puro “fix stuff”, “wip”, y un comentario que dice “TODO: mejorar esto” desde 2022.

El bug no fue lo peor. Lo peor es no poder explicar qué hiciste sin volver a leer todo el diff como si fuera tarea de la uni.

La IA sí te puede sacar del hoyo con la documentación, pero solo si la usas como pair: tú pones la verdad del cambio (qué tocaste y por qué) y la IA te ayuda a dejarlo claro, consistente y fácil de mantener. Si la dejas sola, te arma un README bonito… y falso. Y en production, lo bonito no paga el rollback.

Qué te vas a llevar

• Cómo usar IA para generar comentarios útiles (cortos, con intención) desde código real.
• Cómo armar o actualizar un README que sí sirve para onboarding (incluyendo tu “yo del futuro”).
• Cómo redactar changelogs con señal (qué cambia) y contexto (por qué), sin inventos.
• Un workflow para que la doc salga dentro del PR, no tres sprints después.
• Prompts listos para copiar, y un método para cachar alucinaciones antes de que te quemen.

Contexto real: el jale y la talacha

En equipos chicos, documentar compite contra todo: cerrar el ticket, sacar release, contestar soporte y el cliente mandando audio de WhatsApp con “ya no jala”. En equipos grandes el dolor es otro: hay doc, sí, pero vive en cuatro wikis, nadie sabe cuál es la buena y siempre está desfasada del código.

La IA brilla cuando:

• Tienes cambios concretos (diff/PR/issue) y quieres convertirlos en texto entendible.
• Quieres consistencia (mismo estilo, mismas secciones) sin perder media tarde.
• Necesitas “traducir” decisiones técnicas para otra banda: soporte, QA, producto, o el sysadmin que te va a mentar la madre si no avisas del nuevo env var.

La IA falla cuando:

• No le das contexto real y te devuelve doc genérica tipo plantilla.
• Le pides “explica el repo” sin enseñarle estructura, comandos o logs.
• Le das permiso de inventar features, flags o endpoints “porque suena lógico”.

Decisión que te ahorra problemas: la IA no es la fuente de verdad. La fuente es tu repo + tus cambios + tus decisiones. La IA es el editor rápido.

Guía principal: IA como editor de doc (sin apagar el cerebro)

1) Comentarios en código: menos prosa, más intención

Un comentario bueno contesta una de estas preguntas:

• Por qué existe (tradeoff, limitación, bug histórico).
• Qué garantiza (invariante) o qué no se debe romper.
• Cómo se usa (si el uso correcto no es obvio).

Un comentario malo solo repite lo que ya dice el código.

Workflow recomendado

1. Ubica una función/módulo que:
   • tenga lógica rara,
   • toque edge cases,
   • maneje errores/timeouts,
   • o sea un workaround.
2. Pásale a la IA:
   • el snippet (mínimo viable),
   • el nombre del bug/ticket,
   • el “por qué” en una frase.
3. Pídele 3 versiones: corto, medio y “para auditoría”.
4. Tú eliges y ajustas hasta que sea cierto.

Ejemplo realista (Node/TypeScript)

Código (antes):

export async function fetchWithTimeout(url: string, ms = 5000) {
  const controller = new AbortController();
  const t = setTimeout(() => controller.abort(), ms);

  try {
    const res = await fetch(url, { signal: controller.signal });
    return res;
  } finally {
    clearTimeout(t);
  }
}

Prompt (cópialo y adapta):

Actúa como revisor senior. Escribe un comentario corto (máx 2 líneas) para el bloque de AbortController.
Contexto: en producción tuvimos sockets colgados en una VM barata; necesitamos cortar requests para no saturar.
No repitas lo obvio del código. Enfócate en el porqué y el riesgo.

Salida esperada (editada por ti):

// Cortamos requests que se quedan colgadas para evitar saturar el pool de conexiones en producción.
// Ojo: si cambias el timeout, valida impactos en endpoints lentos (reportes) y en retries.

Tradeoff de guerra: si comentas demasiado, se desactualiza y se vuelve ruido. Si comentas intención y riesgo, suele sobrevivir refactors.

2) README: el que sí ayuda en onboarding (y no es puro marketing)

Un README útil es tu manual de “primer día”:

• qué es este repo,
• cómo corre local,
• cómo corre en staging/prod,
• cómo se prueba,
• dónde viven secretos/config,
• y qué cosas muerden (gotchas).

Plantilla que sí funciona (mínima pero completa)

• Qué es (2–4 líneas)
• Stack (lenguaje, runtime, DB, colas, servicios)
• Requisitos (versiones)
• Setup local (paso a paso con comandos)
• Config (variables de entorno, ejemplos)
• Scripts útiles (test, lint, migrate, seed)
• Deploy (alto nivel, sin novela)
• Troubleshooting (3–5 broncas comunes)

Workflow con IA (sin que se invente cosas)

1. Genera el README desde fuentes reales:
   • package.json / pyproject.toml / go.mod
   • docker-compose.yml
   • .env.example
   • CI (GitHub Actions)
   • estructura de carpetas
2. Dale eso a la IA. Nada de “adivina”.
3. Pídele que marque con TODO(verify) lo que no pueda confirmar.

Prompt recomendado:

Vas a crear/actualizar el README.md usando SOLO la info que te doy.
Si algo no está explícito en los archivos, escribe 'TODO(verify): ...' en vez de inventar.
Estructura deseada: Qué es, Stack, Requisitos, Setup local, Config, Scripts, Deploy, Troubleshooting.
Archivos:
- package.json: (pega contenido)
- docker-compose.yml: (pega contenido)
- .env.example: (pega contenido)
- .github/workflows/ci.yml: (pega contenido)
- Tree del repo: (pega árbol)

Consejo práctico: si tu repo está enorme, no pegues 40 archivos de UI. Pega lo que define el setup: dependencias, scripts, compose y config. Con eso la IA puede armar un README que sí corre.

3) Changelog: que sirva para soporte, negocio y rollback

Cuando soporte te pregunta “¿qué cambió?”, no es por chismoso. Quiere saber:

• ¿se movió algo que afecta usuarios?
• ¿hay cambio de config?
• ¿hay migración?
• ¿hay riesgo y plan de rollback?

Estilo recomendado

• Formato tipo Keep a Changelog: Added, Changed, Fixed, Deprecated, Removed, Security.
• Cada entrada debe decir:
  • impacto,
  • y si aplica, acción requerida.

Workflow de changelog con IA basado en PR

Inputs reales:

• título del PR,
• descripción,
• diff resumido,
• issues relacionados,
• notas de release.

Prompt recomendado:

Redacta una entrada de CHANGELOG.md para versión 1.8.0.
Usa secciones Added/Changed/Fixed/Security.
Base tus bullets SOLO en esta info:
- PR title: ...
- PR description: ...
- Commits (resumen): ...
- Archivos tocados y cambios clave: ...
Incluye 'Acción requerida:' si hay cambios de env vars, migraciones o flags.
Tono: claro, para dev+soporte.

Ejemplo de salida (editada):

## [1.8.0] - 2026-06-27

### Changed
- El endpoint `/reports/export` ahora pagina resultados para evitar timeouts en datasets grandes.
  - Acción requerida: si consumes el endpoint directo, actualiza tu cliente para seguir `nextCursor`.

### Fixed
- Evitamos requests colgadas con timeout por defecto de 5s en integraciones externas.

### Security
- Se rotó el token de acceso a `PAYMENTS_API` y se validan scopes mínimos.

Escena muy real: deploy tarde, alguien mete hotfix directo en production “nomás para que jale” y al día siguiente nadie sabe qué se tocó. El changelog es el rastro decente para auditar y deshacer sin adivinar.

Cómo meter esto a tu workflow sin duplicar chamba

Opción A (recomendada): doc como parte del PR

Checklist del PR:

• Cambios de código
• Tests
• Docs: comentario/README/changelog (lo que aplique)

Dónde entra la IA:

• Antes de pedir review, sacas borrador de doc.
• En el review, pides feedback también sobre la doc (sí, aunque dé pena).

Esto tiene un efecto bonito: cuando alguien te pide un cambio de último minuto (“nomás muévele tantito”), la doc se actualiza en el mismo pull request, no se queda colgada.

Opción B: doc post-merge (deuda controlada)

Sirve cuando estás apagando fuego:

• Mergeas para arreglar producción.
• Abres un ticket “Docs follow-up” con link al PR.
• Le pones deadline real (mismo sprint) y responsable.

Si no hay deadline, ese ticket se vuelve fósil. Y luego viene el freelance mal cotizado a “documentar todo” en dos días… y termina siendo puro relleno.

Reglas para que la IA no te meta mentiras

• Siempre dale fuentes: diff, archivos de config, outputs de comandos.
• Oblígala a marcar incertidumbre: TODO(verify).
• Haz un smoke test humano:
  • ¿los comandos del README sí corren?
  • ¿las env vars existen?
  • ¿el changelog cuadra con el PR?

Screenshots sugeridos

• Vista de un PR donde agregas “Docs” al checklist y un comentario de release notes.
• Ejemplo de README con secciones de Setup/Config/Troubleshooting.
• Entrada de CHANGELOG con “Acción requerida” resaltada.
• Comparación: comentario malo vs comentario bueno en un snippet.

Errores comunes + solución

1) “La IA me generó un README hermoso, pero no corre nada”

Causa: le pediste “escribe un README” sin pasarle package.json, .env.example, compose, etc.
Solución: usa el prompt de “SOLO la info que te doy” + TODO(verify) y pega fuentes reales.

2) Comentarios que explican el if en vez de la intención

Causa: prompt genérico tipo “documenta este código”.
Solución: pídele “no repitas lo obvio” y apunta a “por qué existe” + “riesgo si se cambia”.

3) Changelogs que son lista de commits sin impacto

Causa: convertir git log en bullets y ya.
Solución: fuerza “impacto + acción requerida” y organiza por Added/Changed/Fixed/Security.

4) Documentación que se desactualiza al siguiente refactor

Causa: demasiadísimo detalle en lugares inestables.
Solución: el detalle a donde sí se mantiene: scripts, ejemplos de config, y gotchas que cambian poco. En código, comenta intención, no implementación.

5) Copiar prompts sin adaptar el contexto del negocio

Causa: la IA no sabe qué es crítico (pagos, facturación, privacidad).
Solución: agrega 2–3 líneas de contexto: “esto toca pagos”, “corre en un VPS con 1GB”, “usuarios con mala red”. Eso cambia por completo la calidad de la doc.

Checklist final (para que la doc no sea adorno)

• ¿El README tiene un setup local que corrí al menos una vez?
• ¿Las env vars del README existen en .env.example o están marcadas TODO(verify)?
• ¿Agregué comentarios solo donde hay intención/riesgo/limitación real?
• ¿El changelog dice impacto y acciones requeridas (migración, flags, env vars)?
• ¿La doc referencia el PR/issue cuando aplica?
• ¿Alguien más (aunque sea un compa) leyó la doc y no se atoró?

FAQ

1) ¿Qué tan seguro es pegar código a una IA?

Depende de tu política y tu setup. Si es repo privado o hay datos sensibles, usa herramientas aprobadas por tu org (enterprise) o un modelo local. Regla rápida: no pegues secretos, tokens, datos de clientes ni dumps. Para documentación normalmente basta con un diff recortado y config sanitizada.

2) ¿Qué sí vale automatizar al 80%?

Changelog por release y borrador de README a partir de archivos reales. Los comentarios en código suelen ser menos cantidad pero más calidad: automatiza el borrador, revisa más.

3) ¿Cómo evito que la IA alucine endpoints o comandos?

Cierra el scope: “solo con la info que te doy”, fuerza TODO(verify) y valida corriendo comandos reales (aunque sea con café frío y cero ganas).

4) ¿Sirve documentar en español si el repo está en inglés?

Sí. Solo define convención: README en inglés si es open source; docs internas en español si el equipo es local. Si mezclas, mantén comandos y nombres de flags tal cual para no romper el workflow.

5) ¿Qué hago si mi equipo odia escribir documentación?

Bájale la fricción: checklist en PR, plantillas y doc mínima que quite dolores reales (setup, deploy, troubleshooting). El día que soporte deja de preguntarte lo mismo en Slack/Teams, la doc se vuelve incentivo inmediato.

Siguiente episodio

Nos movemos de “IA que escribe texto” a “IA que te cuida el build”: cómo usarla para pruebas, edge cases y regresiones sin inflar tu suite hasta el infinito. Incluye prompts para generar tests que sí pegan y cómo cachar cuando la IA está overfitting a tu código.