El 21 de abril de 2026, freeCodeCamp publicó mi tutorial sobre cómo construir un Knowledge Graph automático con JSON-LD y PHP. Un artículo técnico de 3,000 palabras con seis pasos de implementación, código de producción y consultas a base de datos. Cada línea de PHP fue escrita con Claude como coding partner. Y cada línea pasó por una revisión editorial humana antes de publicarse.

El proceso de llegar del borrador a la publicación cambió cómo pienso sobre escribir código con IA. No porque el código estuviera mal. Porque el proceso de defender cada función ante una editora me obligó a entender lo que había construido a un nivel que construirlo nunca logró.

La brecha entre construir y explicar

Cuando construyo funcionalidades para shinobis.com, el flujo es rápido. Describo lo que necesito a Claude. Claude escribe el PHP. Lo pruebo. Si funciona, se publica. Si no, describo el problema y Claude lo corrige. En seis meses construí un blog trilingüe con automatización de JSON-LD, negociación de contenido, un radar de IA, imágenes de identidad generativa y dos herramientas públicas. Todo en PHP vanilla con hosting compartido.

Pero construir y explicar son habilidades diferentes. Cuando empecé a escribir el tutorial para freeCodeCamp, me di cuenta de que podía describir lo que cada función hacía a nivel general. No podía explicar por qué lo hacía de esa manera. ¿Por qué el sistema usa un array @graph en vez de objetos anidados? ¿Por qué el publisher es una Organization en vez de una Person? ¿Por qué la detección de entidades usa strpos en vez de un patrón regex?

Claude había tomado esas decisiones durante la implementación. Yo las había aceptado porque el resultado funcionaba. Escribir el tutorial me obligó a interrogar cada decisión. Algunas eran correctas por razones que no había considerado. Algunas necesitaban cambiar.

Lo que eliminé del borrador de Claude

El primer borrador incluía secciones que Claude sugirió y que inicialmente mantuve. Una tabla comparativa de formatos JSON-LD en cinco plataformas CMS. Una sección sobre jerarquías de vocabulario de Schema.org. Una discusión sobre RDFa versus Microdata versus JSON-LD.

Todo técnicamente correcto. Todo irrelevante para el tutorial. El lector que abre un artículo de freeCodeCamp titulado "Cómo construir un Knowledge Graph automático" no necesita una lección de historia sobre formatos de datos estructurados. Necesita el código. La tabla comparativa era el tipo de contenido que la IA genera para llenar espacio: completo, bien organizado e innecesario.

Eliminar esas secciones cortó 800 palabras e hizo el tutorial más conciso. Cada párrafo que sobrevivió tenía que responder una pregunta: ¿esto ayuda al lector a implementar el sistema? Si la respuesta era no, se iba.

Lo que agregué que Claude no sugirió

Tres cosas entraron al artículo final que no estaban en el borrador generado por IA.

Primero, la sección sobre lo que aprendí después de tres meses en producción. Claude no puede escribir esa sección porque Claude no tiene tres meses de datos de producción. El insight de que agregar la propiedad abstract tuvo impacto inmediato en el procesamiento por LLMs, que citation junto con relatedLink señala relaciones de conocimiento de forma diferente, que definir el publisher como Organization aumenta las señales de confianza. Eso vino de observar comportamiento real en un blog real durante tiempo real.

Segundo, los diagramas. El artículo incluye cuatro diagramas que muestran la arquitectura del pipeline, la diferencia entre JSON-LD estático y basado en grafos, las conexiones de entidades del @graph, y el output anotado. Claude no sugirió ayudas visuales. Los agregué porque diez años de diseño UX me enseñaron que los conceptos técnicos se entienden más rápido cuando puedes ver la estructura, no solo leer sobre ella.

Tercero, la metodología de testing. El borrador original terminaba con la implementación. Agregué una sección sobre validar el output con Google Rich Results Test y auditar el schema con modelos de IA. La recomendación de pegar tu JSON-LD en ChatGPT y pedir un puntaje vino de mi propio proceso. Lo hice, obtuve 8.7, hice mejoras, obtuve 9.1. Ese antes y después es contenido non-commodity. Nadie más tiene esa progresión específica porque nadie más corrió esa auditoría específica en ese schema específico.

El proceso editorial

freeCodeCamp tiene revisores editoriales. Mi artículo fue asignado a Abbey. La revisión no fue un sello de goma. Cuestionó afirmaciones técnicas. Pidió clarificación sobre la diferencia entre about y mentions en JSON-LD. Señaló una sección donde la explicación asumía conocimiento que el lector podría no tener.

Cada comentario editorial me obligó a volver al código y verificar. No verificar que funcionara. Verificar que pudiera explicar por qué funcionaba. Hay una diferencia. Ejecutar una función y ver un output correcto prueba que el código es funcional. Explicarle a otra persona por qué la función está estructurada de esa manera prueba que lo entiendes.

Tres de las preguntas de Abbey me llevaron a descubrir cosas sobre mi propia implementación que no había notado. Los flags de json_encode (JSON_UNESCAPED_SLASHES y JSON_UNESCAPED_UNICODE) estaban en el código porque Claude los puso ahí. Nunca los cuestioné. Cuando Abbey preguntó por qué importaban, probé qué pasa sin ellos. Un título en español con tilde rompía todo el bloque JSON-LD silenciosamente. Una URL con barra diagonal se escapaba en una cadena ilegible. Esos flags no eran decoración. Estaban previniendo bugs reales en un blog trilingüe. Entendí mi propio código mejor porque alguien me pidió que lo explicara.

La línea entre usar IA y entender código

Existe una versión de esta historia donde pego el output de Claude en un formulario de freeCodeCamp y espero aprobación. Esa versión es rechazada. No porque el código esté mal sino porque la explicación es superficial. Los tutoriales generados por IA tienen una textura específica: información correcta organizada en un patrón predecible sin insight personal, sin datos de producción, y sin evidencia de que el autor haya ejecutado el código fuera de un sandbox.

La versión que se publicó es diferente porque hice el trabajo que la IA no puede hacer. Corrí el sistema en producción durante tres meses. Observé cómo diferentes modelos de IA respondieron al schema. Hice cambios basados en feedback real. Eliminé secciones que eran técnicamente correctas pero editorialmente incorrectas. Agregué secciones que vinieron de la experiencia, no de prompting.

Usar IA para escribir código no es lo mismo que entender código. Pero usar IA para escribir código y luego ser obligado a explicar cada línea a un editor humano cierra esa brecha más rápido que cualquier otra cosa que haya intentado. El proceso editorial no fue un filtro. Fue un acelerador de aprendizaje.

Lo que cambió después de publicar

El artículo está activo desde el 21 de abril. Tres cosas medibles pasaron.

Primero, el backlink de freeCodeCamp. Su autoridad de dominio está entre las más altas del espacio de publicaciones técnicas. Para un blog con un domain rating de 3.2, un solo enlace dofollow de freeCodeCamp vale más que docenas de enlaces de sitios más pequeños.

Segundo, el comentario que me sorprendió. Alguien preguntó "Could you share the source code?" Todo el código fuente está en el tutorial, paso a paso. Pero el lector quería un solo archivo que pudiera soltar en un proyecto. Eso me dijo algo sobre cómo los developers consumen tutoriales: leen la explicación para decidir si vale la pena implementar, y luego quieren el código completo en un solo lugar.

Tercero, y esto es lo que más me importa: dejé de pensar en mí como un diseñador que usa IA para codear. Empecé a pensar en mí como alguien que construye software con IA y entiende lo que se construye. La distinción no es semántica. Cambia lo que estoy dispuesto a publicar, lo que cuestiono antes de desplegar, y cómo explico mi trabajo a otros.

Lo que le diría a alguien que quiere publicar con IA

No publiques output de IA. Publica tu comprensión del output de IA. La diferencia es todo.

Lee cada función. No para buscar errores de sintaxis. Para verificar si puedes explicar la decisión que representa. Si no puedes explicar por qué una función usa strpos en vez de preg_match, no entiendes el código lo suficiente para publicar un tutorial sobre él.

Elimina las secciones que la IA agrega para ser exhaustiva. La IA llena espacio porque la completitud es su modo por defecto. Tu trabajo es cortar todo lo que no sirva al lector.

Agrega lo que solo tú puedes agregar. Datos de producción. Números de antes y después. Decisiones que tomaste y por qué. Errores que atrapaste. Las cosas que hacen tu tutorial diferente de cualquier otro tutorial sobre el mismo tema. La IA no puede fabricar experiencia.

Y encuentra un editor. No un editor de IA. Un humano que te haga preguntas que aún no puedes responder. Esas preguntas son donde ocurre el aprendizaje.

El tutorial está activo en freeCodeCamp: How to Build an Automatic Knowledge Graph for Your Blog with PHP and JSON-LD.