Cómo escribir un blog técnico con IA: investigación, validación de código y revisión humana

Un artículo técnico contiene tres bloques de código, pero ninguno se ha ejecutado. Los lectores los copian, obtienen errores y descubren que el problema no era la redacción: los hechos y el código nunca pasaron un control.

Un borrador de IA puede parecer completo mientras adivina versiones, argumentos y formatos de salida. Un proyecto declara "type": "module" en package.json, pero el ejemplo usa require directamente. Otro texto afirma que GitHub Actions ofrece «2.000 minutos al mes» sin explicar que esa cifra corresponde a la cuota de un plan concreto para repositorios privados.

Escribir un blog técnico no consiste en entregar un tema a un modelo y pulir el resultado. Primero se reúnen fuentes y evidencias ejecutables, luego la IA organiza la explicación y finalmente una persona revisa los hechos, el código y el estilo. El flujo siguiente asigna un control y un responsable a cada etapa para mantener afirmaciones correctas, ejemplos ejecutables y conclusiones reproducibles.

Investigar antes de pedir un borrador a la IA

Qué debe investigarse y qué puede redactar la IA

La primera decisión separa los hechos que deben venir de fuentes externas de las partes que el modelo puede organizar.

Tres categorías facilitan esa separación.

Las versiones, los campos de API modificados, los límites documentados, los precios o cuotas y la configuración de seguridad se investigan antes. Un error puede romper el proyecto de un lector o generar un costo inesperado. La documentación actual de Next.js usa, por ejemplo, la clave turbopack, mientras que las versiones 13.0.0 a 15.2.x utilizaban experimental.turbo. Escribir solo «configura Turbopack» sin indicar la versión puede llevar a copiar una configuración incompatible.

La IA puede redactar conceptos generales, uso de frameworks, buenas prácticas y errores comunes, pero una persona debe verificarlos. Una explicación sobre React hooks puede sonar correcta; el número de reglas, las convenciones y las diferencias de versión se comparan con la documentación oficial.

La estructura, la edición de estilo y el formato sí pueden dejarse a la IA. Reformular una explicación o reunir párrafos relacionados normalmente no requiere otra investigación.

Comparación:

Tipo de investigación	Contenido típico	Fuerza del control	Etapa
Investigar primero	Versiones, campos de API, precios o cuotas, seguridad	Alta: extraer de documentación oficial y marcar [VERIFY]	Preparar durante la planificación y revisar el día de redacción
Borrador de IA + revisión	Conceptos generales, frameworks, buenas prácticas	Media: comparar el borrador con documentación oficial	Redactar y verificar durante la revisión
Organización por IA	Estructura, estilo, formato	Baja: normalmente no requiere más investigación	Etapa de borrador

Árbol de decisión:

Aparece contenido de tipo X
  ↓
¿Implica una versión, API, precio o seguridad?
  ├─ Sí → Extraer de documentación oficial, marcar [VERIFY] y revisar el día de redacción
  └─ No → ¿Implica una regla técnica o buena práctica?
      ├─ Sí → Dejar que la IA redacte y contrastar con documentación oficial durante la revisión
      └─ No → Dejar que la IA organice la explicación

Cómo transferir la investigación al proceso de redacción

Al terminar la investigación, los resultados se guardan en un formato que la etapa de redacción pueda usar directamente.

De research.md se extraen las fuentes de alta confianza, especialmente documentación oficial marcada como high: las recomendaciones de Google Search Central, el ejemplo de CI para Node.js de GitHub y la documentación de Astro Content Collections.

Los hechos cambiantes reciben [VERIFY], por ejemplo: «La cuota incluida de GitHub Actions para repositorios privados depende del plan de la cuenta [VERIFY]» o «Comprobar si la versión objetivo de Node sigue teniendo soporte [VERIFY]».

Las fichas de fuentes, salidas de comandos y resultados de revisión se guardan en source_cards y risk_notes:

{
  "source_cards": [
    {
      "url": "https://developers.google.com/search/docs/fundamentals/creating-helpful-content",
      "type": "official/docs",
      "confidence": "high",
      "usable_info": "El contenido debe aportar información original y una explicación completa, no depender principalmente de automatización masiva"
    }
  ],
  "risk_notes": [
    {
      "fact": "Cuota incluida de GitHub Actions",
      "status": "[VERIFY]",
      "check_date": "2026-06-24",
      "source": "https://docs.github.com/en/billing/managing-billing-for-github-actions"
    }
  ]
}

Con este traspaso, la redacción no repite toda la investigación. Solo vuelve a comprobar los datos variables señalados.

Los ejemplos de código deben ejecutarse, no solo parecer correctos

Cuatro situaciones de validación

Los ejemplos técnicos suelen parecer razonables y fallar en un proyecto real. Cuando un lector copia el código y encuentra un error, el artículo pierde credibilidad.

La validación se divide en cuatro situaciones.

La ejecución local cubre comandos de instalación, configuraciones y scripts pequeños como npm install, git clone o un cambio de configuración. Se ejecutan localmente y se conserva la salida.

Las pruebas CI cubren builds, tests y dependencias de entorno, por ejemplo npm ci, npm run build y npm test en GitHub Actions. La CI permite repetir el entorno.

El control de versiones cubre Node, dependencias y versiones de API, como .nvmrc, package.json y cambios de endpoint. Se registra la versión y se explican las diferencias. La coherencia de entorno cubre desarrollo, producción y CI: variables, imágenes Docker y sistemas operativos. Hay que indicar dónde se ejecutó.

Las cuatro situaciones:

Situación	Contenido típico	Método	Evidencia necesaria
Ejecución local	Instalación, configuración	Ejecutar localmente	Salida o captura
Prueba CI	Build y tests	GitHub Actions u otra CI	Log de CI o resultado del build
Control de versión	Node o dependencias	Comando de versión	Salida de node --version y nota
Coherencia de entorno	Variables, Docker	Probar varios entornos o identificar el probado	Entorno y condiciones

Cómo registrar evidencias de ejecución

Cada ejemplo necesita una evidencia. «Se ejecutó correctamente» no basta. Los comandos y salidas siguientes solo muestran el formato de un registro; no son resultados reutilizables. Deben reemplazarse por las versiones y logs reales del proyecto.

Ejemplo para CI de Node.js:

# Entorno local: macOS + Node 18.20.0 LTS
$ node --version
v18.20.0

# Entorno CI: GitHub Actions
$ npm ci
added 245 packages in 12s

$ npm run build
✓ Built in 1.23s

$ npm test
✓ 12 tests passed

Un ejemplo correcto incluye salida de texto o captura, versión y resultado relevante.

Un ejemplo incorrecto solo dice «funciona» y no muestra la salida.

El código se coloca en fenced code blocks con un lenguaje como bash o typescript. Una salida larga se pliega o se limita a las líneas importantes. En varios pasos se indica local, CI o Docker. Los controles de versión conservan la salida de node --version o npm --version.

Ejemplo:

# Entorno de ejecución: macOS + Node 18.20.0
$ npm install
added 124 packages in 8s

$ node --version
v18.20.0

Si la salida del build es larga, se muestra la parte útil:

$ npm run build
✓ Built in 1.23s
  ├─ dist/index.html
  ├─ dist/assets/index.js
  └─ dist/assets/index.css

GitHub explica los fenced code blocks y el resaltado de sintaxis en Creating and highlighting code blocks. Un artículo técnico debe conservar código copiable y verificable, no disfrazarlo como prosa.

La revisión humana comprueba hechos, código y estructura

Revisión de hechos: rastrear versiones, parámetros y precios

La revisión humana no es solo edición de estilo. Comprueba hechos, código y estructura. Si solo se corrigen palabras, se pasan por alto versiones erróneas, parámetros inválidos y conclusiones que no coinciden con el código.

La clave es la trazabilidad. Cada versión, campo de API, parámetro, valor de configuración, precio o cuota y fecha de publicación se compara con documentación oficial o una ejecución real.

Tabla:

Elemento	Método	Señal de fallo	Evidencia válida
Versión	Comparar con release o documentación oficial	Versión inexistente o función mal descrita	Enlace oficial y node --version
Parámetro	Comparar con documentación CLI oficial	Parámetro ausente o formato incorrecto	Enlace oficial y salida real
Campo de API	Comparar con documentación de API	Campo ausente o tipo erróneo	Enlace oficial y solicitud real
Precio o cuota	Comparar con página oficial	Precio incorrecto o condición público/privado ausente	Enlace oficial y condiciones
Fecha de lanzamiento	Comparar con anuncio oficial	Fecha o evento erróneo	Enlace al anuncio

Ejemplo incorrecto:

El proyecto declara "type": "module" en package.json, pero el ejemplo usa require de CommonJS directamente sin cambiar a .cjs ni explicar el límite entre módulos.

Otro ejemplo incorrecto:

El texto afirma que GitHub Actions solo ofrece «2.000 minutos gratuitos al mes», pero no indica que los runners GitHub-hosted estándar son gratuitos en repositorios públicos y que la cuota de los privados depende del plan.

Redacción más precisa:

«Node 18 admite ES modules y CommonJS. .mjs, .cjs y el campo type de package.json determinan cómo se interpreta un archivo. Este registro usa Node 18.20.0 y conserva la salida de node --version».

«A 26 de julio de 2026, los runners GitHub-hosted estándar son gratuitos para repositorios públicos. Los privados reciben minutos según el plan, por ejemplo 2.000 con GitHub Free y 3.000 con GitHub Pro (fuente: GitHub Actions billing)».

Revisión de código: ejecución, salida y entorno

La revisión responde tres preguntas: ¿funciona el comando?, ¿la salida respalda el texto? y ¿el entorno está claro?

Elemento	Método	Señal de fallo	Evidencia válida
Comando ejecutable	Probar localmente o en CI	Error o dependencia ausente	Log o captura
Salida coherente	Comparar salida y texto	La salida contradice el artículo	Texto y registro coinciden
Entorno identificado	Revisar nota de entorno	Falta Node u OS	Node 18.20.0 + macOS
Versión de dependencia	Revisar package.json	No coincide con el texto	package.json o salida de versión

Ejemplo incorrecto:

El texto anuncia tres archivos, pero npm run build muestra cinco.

El texto dice «funcionó localmente», pero el ejemplo depende de Docker y no lo menciona.

Ejemplo correcto:

El texto y el log coinciden: «npm run build generó index.html, index.js e index.css».

El entorno es explícito: «Probado en macOS con Node 18.20.0. Linux o Windows puede requerir cambios de ruta».

Revisión de estructura y estilo: H2/H3, enlaces y residuos de IA

Esta revisión compara H2/H3 con la estructura aprobada, comprueba enlaces internos y elimina frases genéricas de IA.

Elemento	Método	Señal de fallo	Resultado válido
Coherencia H2/H3	Comparar con outline.md	Falta o sobra una sección	Registrar el motivo del cambio
Enlaces internos	Comparar con el plan	Falta un enlace o el ancla engaña	Añadir el enlace con texto descriptivo
Frases de IA	Comparar con anti-ai-words.json	Promesa vacía o atribución vaga	Sustituir por un hecho o eliminar

El archivo anti-ai-words.json del sitio agrupa expresiones que deben evitarse. Las promesas vacías, atribuciones vagas y exageraciones se sustituyen o eliminan.

Un mal inicio se limita a declarar una tendencia.

«Este artículo ofrece un análisis completo» también es una promesa vacía.

Un inicio mejor va a la decisión: «Al redactar contenido técnico con IA, primero hay que decidir qué hechos provienen de fuentes externas».

Una promesa verificable sería: «Este flujo coloca un control en investigación, validación y revisión».

Cerrar el proceso con QA antes de publicar

Lista de QA previa a la publicación

Un borrador terminado aún no está listo para publicar. El último control revisa marcadores, evidencias de código, fuentes, estructura, enlaces internos, residuos de IA e imágenes.

Elemento	Comprobación	Condición de aprobación	Respuesta al fallo
Marcadores resueltos	Buscar [VERIFY]	No queda ninguno abierto	Volver a investigación
Ejemplos validados	Comparar con logs	Cada ejemplo tiene evidencia	Volver a validación
Hechos rastreables	Comparar con fichas	Cada hecho importante tiene fuente o condición	Añadir fuente o borrar afirmación
Estructura coherente	Comparar con outline.md	H2/H3 coincide o el cambio se explica	Actualizar el registro
Enlaces colocados	Comparar con el plan	Enlaces y anclas correctos	Añadir enlace o corregir plan
Residuos eliminados	Comparar con anti-ai-words.json	No hay relleno genérico	Reescribir o borrar
Imágenes disponibles	Comparar inventario y rutas Markdown	Todos los archivos existen	Subir imagen o corregir ruta

Estados:

Aprobado: el artículo puede avanzar.

Pendiente: una fuente o afirmación necesita revisión.

Fallido: vuelve a la etapa responsable.

Cada elemento se comprueba por separado y se marca en cuanto aparece un problema. El estado «listo para publicar» solo se asigna cuando todo pasa.

Devolver un fallo a la etapa responsable

Un error de QA regresa a la etapa que lo causó. No se omite.

Un error factual vuelve a investigación: se añade una fuente oficial, se elimina una afirmación sin respaldo o se revisa un dato cambiante.

Un error de código vuelve a validación: se ejecuta de nuevo, se guarda la salida, se corrige el ejemplo y se identifica el entorno.

Una diferencia de estructura exige actualizar el registro o explicar qué H2/H3 cambió y por qué.

Un enlace interno ausente vuelve al plan. Se busca el artículo real en el inventario y se usa un ancla descriptiva.

Los residuos de IA vuelven a edición. Se sustituyen por información concreta; si la frase sigue siendo vaga, se reescribe por completo.

Ejemplo:

QA detecta que una cuota de GitHub Actions no indica la condición público/privado
  ↓
Marcar como fallo
  ↓
Volver a investigación
  ↓
Añadir la fuente oficial de facturación y las condiciones
  ↓
Ejecutar QA de nuevo

La ruta de retorno hace visible la responsabilidad. La persona que revisa al final no debe heredar un cambio sin explicación.

Siete señales de que el artículo se aleja de los hechos

Las siete señales

La desviación factual se acumula. Estas señales ayudan a detectarla antes de publicar.

Señal 1: afirmación sin fuente. El texto dice «última versión», «recomendación oficial» o «buena práctica» sin enlace. Por ejemplo, afirma que una clave Turbopack funciona en todas las versiones de Next.js sin citar documentación.

Señal 2: código no ejecutado. No existe salida ni log, solo «funciona».

Señal 3: versión o parámetro mal clasificado. La versión puede existir, pero su rama o soporte es incorrecto; parámetros y endpoints también cambian. Node 20.1.0 fue Current, no LTS.

Señal 4: el entorno no coincide. La evidencia nombra un entorno, pero el comportamiento se comprobó en otro.

Señal 5: la conclusión no es reproducible. Se afirma una mejora sin método, datos ni pasos.

Señal 6: enlace interno roto. El artículo apunta a /posts/ai/ai-xxx, pero la ruta no existe.

Señal 7: una frase vaga oculta la falta de evidencia. «Análisis completo» sustituye a una fuente o resultado.

Ejemplos:

Señal	Mal ejemplo	Problema
Sin fuente	«Esta clave Turbopack funciona en todas las versiones de Next.js»	Sin documentación oficial
Código no ejecutado	«Ejecuta npm install; funciona»	Sin evidencia
Versión incorrecta	«Node 20.1.0 LTS»	20.1.0 fue Current
Entorno incoherente	Se registra un entorno antiguo y se valida en otro	Versión y entorno no coinciden
Conclusión no reproducible	«El rendimiento mejora mucho»	Sin método ni datos
Enlace roto	Enlace a /posts/ai/ai-xxx	Ruta inexistente
Residuo de IA	«Análisis completo de redacción con IA»	Promesa vaga

Cuando aparece una señal, se marca [VERIFY] y vuelve a la etapa responsable.

Una afirmación sin fuente vuelve a investigación, el código no ejecutado a validación y una versión errónea al release oficial. Un entorno incoherente exige condiciones correctas o eliminar la afirmación. Una conclusión no reproducible necesita método, datos y pasos o se borra. Un enlace roto se cambia por una ruta real. Una frase vaga se concreta o elimina.

La devolución debe ser inmediata. De lo contrario, varias incertidumbres pequeñas forman un artículo imposible de rastrear.

Escribir con honestidad sin un entorno completo

Tres formas honestas

A veces falta un servicio de pago, un clúster complejo, un sistema operativo o hardware concreto. No se debe inventar evidencia. Hay tres alternativas.

Primera: indicar condiciones y límites. Se nombra la versión probada y las diferencias posibles, o que solo se probó el plan gratuito. Ejemplo: «El ejemplo solo se validó con Node 18.20.0; otras versiones pueden variar».

Segunda: ofrecer una validación alternativa. Puede ser una reproducción mínima, datos Mock o un issue oficial. Ejemplo: «No había un clúster Kubernetes disponible; solo se ofrece una reproducción mínima que aún debe probarse en un clúster real».

Tercera: admitir lo no verificado. Se escribe «Esta conclusión de rendimiento no se reprodujo en el entorno actual» o se elimina la afirmación.

Comparación:

Situación	Redacción engañosa	Redacción honesta
Diferencia de versión	«Todas las versiones lo admiten»	«Validado con Node 18.20.0; otras versiones pueden variar»
Diferencia de entorno	«Funcionó localmente»	«Probado en macOS con Node 18.20.0; Linux, Windows u otra versión pueden requerir ajustes»
Servicio de pago	«Es gratis»	«Solo se probó el plan gratuito; las funciones de pago pueden variar»
Afirmación no verificada	«El rendimiento mejora mucho»	«El entorno actual no reprodujo esta conclusión de rendimiento»

Ejemplos válidos:

«La prueba utilizó el plan gratuito de Cloudflare Workers, que actualmente incluye 100.000 solicitudes diarias. Las condiciones de pago pueden variar; revisa la página oficial de precios».

«No había un clúster Kubernetes disponible. La reproducción mínima aún debe probarse en un clúster real con sus límites de Pod y configuración de red».

«No hay una medición de un proyecto grande, así que no se afirma nada sobre el rendimiento de build de Turbopack. Mide una línea base y una comparación en tu proyecto».

Ejemplos inválidos:

«Cloudflare Workers es gratis». Falta la cuota.

«Funciona en cualquier entorno». Falta el entorno.

«El rendimiento mejora mucho». Faltan método y datos.

Google Search Central recomienda información original, explicaciones completas y análisis útil en Creating helpful, reliable, people-first content. Explicar una limitación no reduce el estándar: separa lo verificado de lo que aún requiere una prueba.

Cuándo publicar y cuándo revisar el borrador

Árbol de decisión de publicación

La decisión no depende del número de palabras ni de una apariencia terminada, sino de que pasen investigación, validación, revisión y QA.

Investigación: si están todas las fuentes fiables y los datos variables marcados, se pasa a validar. Si falta una fuente central, se investiga.

Validación: si todos los ejemplos funcionan, se pasa a revisión. Los ejemplos fallidos se corrigen o eliminan. Los no verificables explican sus límites o se retiran.

Revisión humana: si los hechos son rastreables, se pasa a QA. Una afirmación sin fuente se documenta o elimina. Un cambio de estructura explicado puede avanzar; una desviación sin explicar vuelve a planificación.

QA previa: si todo pasa, el artículo avanza. Un punto pendiente se revisa y un fallo vuelve a su etapa.

Un artículo avanza cuando la investigación y la actualización están completas, el código tiene evidencias, la revisión confirma hechos y estructura, se elimina el relleno de IA y la QA pasa.

Si falta una fuente, registro, enlace interno o limpieza de estilo, aún queda trabajo.

Una versión, parámetro, precio u otro hecho central erróneo, una conclusión principal irreproducible o una estructura fuera del objetivo sin explicación exigen revisión.

Cada etapa tiene un control. El fallo vuelve a su causa y no llega a publicación.

Prioridad:

Primero se corrigen o eliminan los errores factuales. Después los errores de código que un lector podría copiar. La estructura y los enlaces tienen menor prioridad, pero se resuelven antes de publicar.

Lecturas relacionadas

Para dar contexto del proyecto a la IA, consulta cómo usar CLAUDE.md para evitar código incorrecto. Para empaquetar redacción y revisión como pasos reutilizables, revisa los flujos con Claude Code Skills.

También existe un flujo de redacción con IA para contenido general. Ese texto prioriza la velocidad; este prioriza los hechos técnicos, la evidencia de ejecución y los controles de publicación. Ambos pueden combinarse.