Documentar para que la IA te entienda: el nuevo idioma del desarrollo

El código ya no habla solo.

En la era de la inteligencia artificial, cada línea necesita un traductor, y ese traductor es la documentación.

Durante años muchos desarrolladores repitieron el mantra: “el código bien escrito se explica por sí solo”. Hoy, con copilotos y modelos de lenguaje integrados en nuestros flujos de trabajo, esa idea se desmorona. La documentación técnica —esa parte siempre postergada, la cenicienta del desarrollo— se ha vuelto el punto de anclaje entre el conocimiento humano y el artificial.

Sin ella, la IA adivina; con ella, razona.

El contexto como oxígeno de la IA

Un modelo de lenguaje no lee la mente del equipo. No conoce tus decisiones, tus excepciones ni tus convenciones internas. Solo puede actuar sobre el contexto que le das.

Sourcegraph lo resumía así: “sin contexto, un LLM solo da respuestas genéricas; con contexto, entiende tu código, tu arquitectura y tus prácticas” (sourcegraph.com).

La documentación es precisamente ese contexto. Es el aire que respira la IA para no asfixiarse en conjeturas. Un asistente de IA se parece a un desarrollador recién incorporado: si no le das documentación, improvisará. Si se la das, será útil desde el primer día.

Estudios de Swimm (swimm.io) muestran que la calidad del código sugerido por una IA crece en proporción directa a la calidad del contexto aportado. Un ejemplo simple: sin información previa, un modelo propone una función incompleta; con solo añadir el lenguaje y la estructura esperada, acierta casi por completo.

La conclusión es obvia: si la IA es el copiloto, la documentación es el mapa.

Documentar bien: ahora es cuestión de rendimiento

Ya no se documenta “por cortesía” ni “para el siguiente”. Se documenta para que humanos y máquinas puedan colaborar.

Y Markdown es el terreno común donde ambos entienden el mensaje.

1. Estructura clara

Usa encabezados jerárquicos (#, ##, ###).

Ayudan a la IA tanto como al lector humano a entender el contexto de cada bloque. Un texto plano y sin secciones es un laberinto sin señales.

Separar secciones como Instalación, Uso, API o Contribución evita confusiones y mejora la interpretación.

2. Listas para pensar ordenado

Las listas guían la atención. Una IA las interpreta como pasos o requisitos, no como frases sueltas.

## Instalación del proyecto

1. Clona este repositorio.

2. Ejecuta `npm install`.

3. Configura las variables de entorno según `config/README.md`.

3. Ejemplos de código

Nada explica mejor que un ejemplo.

Los fragmentos rodeados de triple backtick ``` no solo ayudan al humano; le dan a la IA pistas sobre sintaxis, estructura y relaciones.

# Inicialización y uso de la clase Cliente

cliente = Cliente(nombre="Acme", creditos=100)

cliente.procesar_pedido("1234")

4. Markdown limpio y consistente

Evita adornos y estructuras raras. Markdown es valioso por su simplicidad.

Cuanto más uniforme sea el formato, más fácilmente una IA reconocerá patrones y entenderá tu documentación.

5. Actualiza siempre

El contexto obsoleto es veneno: Garbage In, Garbage Out.

Una documentación desactualizada no solo confunde a los humanos: induce a la IA a generar código erróneo.

Mantenerla al día ya no es opcional, es parte del desarrollo.

La arquitectura del conocimiento

No basta con documentar funciones. Hay que ofrecer una visión completa.

Piensa en la documentación como un mapa de la mente del proyecto, no como una lista de tareas.

README o visión general

Responde tres preguntas:

¿Qué es el proyecto? ¿Para quién existe? ¿Qué resuelve?

Ejemplo:

Contoso Companions — Plataforma web para agencias de adopción de mascotas que gestiona animales, ubicaciones y eventos, permitiendo a adoptantes buscar y enviar solicitudes.

Un LLM (o un nuevo colaborador) entenderá al instante el dominio del problema.

Stack y dependencias

Enumera tecnologías clave:

## Tecnologías y herramientas

**Backend:** Python 3.11 con Django 4 (PostgreSQL)  

**Frontend:** React 18 + TypeScript  

**Infraestructura:** Docker en AWS  

**Testing:** Pytest y Cypress

Así la IA sabrá el entorno en que se mueve.

Evitará, por ejemplo, sugerir código Node.js para un backend Django.

Guías de estilo y convenciones

Son las reglas de la casa.

Si usas TypeScript estricto o sigues PEP8, escríbelo.

Un modelo bien informado podrá ajustar su estilo automáticamente.

Estructura del proyecto

Incluye un mapa de carpetas y módulos clave:

## Estructura

- /api/ → backend

  - /models/ → modelos de datos

  - /routes/ → endpoints REST

- /web/ → frontend

  - /components/

  - /pages/

- /scripts/ → automatización

- /docs/ → manuales y ADRs

Esta visión evita duplicaciones y ayuda a la IA a identificar piezas existentes.

Recursos internos

Incluye scripts útiles o decisiones de arquitectura (ADR).

Si el roadmap menciona “migrar a GraphQL en el próximo trimestre”, una IA con acceso a esa nota no sugerirá soluciones contrarias a ese plan.

Cómo escribir para humanos y para máquinas

Documentar para humanos ya era difícil; hacerlo también para IA exige precisión.

Un texto LLM-friendly es claro, contextual y estructurado.

Lenguaje sin ambigüedades

Evita la jerga y define términos de negocio.

No digas “servicio externo”: di “servicio externo Stripe API para pagos”.

La IA no interpreta insinuaciones; necesita definiciones.

Secciones autónomas

Cada documento debe ser comprensible por sí mismo.

Un modelo puede leer solo un archivo sin saber del resto.

Introduce siempre el contexto mínimo al inicio.

Formato con intención

Usa negritas para conceptos clave y citas para advertencias:

> **Importante:** mantener actualizado el archivo .env antes del despliegue.

Ejemplos y anti-ejemplos

Documentar lo que no debe hacerse es igual de útil.

Una nota como “No usar

para validar entrada” puede evitar que la IA repita errores conocidos.

En resumen: escribe para que una IA te entienda como si fuera un desarrollador más.

Del mismo modo que optimizamos texto para SEO, optimizamos ahora documentación para LLM: formato limpio, contexto explícito, estructura consistente.

“El código se explica solo”… hasta que la IA lo lee

La vieja excusa ya no sirve.

El código limpio sigue siendo importante, pero no basta.

Los copilotos no heredan la intuición del equipo: no estuvieron en tus reuniones ni conocen tus decisiones implícitas. Cada vez que los usas, comienzan desde cero.

Documentar es el equivalente al onboarding que nunca termina.

Si omites contexto, la IA tropieza.

Si lo detallas, acelera.

Tres verdades incómodas

Sin documentación, tu IA es un mono con teclado.

1. No puede colaborar si no entiende el entorno.

El código necesita un traductor.

1. La documentación explica la intención que el código no puede expresar.

El conocimiento tácito se pierde.

1. Si no está escrito, no existe para la IA.

La disciplina de documentar beneficia también a los humanos.

La IA, en realidad, nos obliga a adoptar las buenas prácticas que siempre pospusimos.

Cuando falta documentación, la IA tropieza

Algunos casos lo ilustran con claridad:

1. Reinventar la rueda.

Una función útil existe, pero no está documentada.

La IA la ignora y propone crear otra. Resultado: código duplicado.

2. Supuestos ocultos.

El sistema guarda montos en centavos, pero nadie lo dice.

Copilot calcula totales en euros y multiplica errores.

Un simple comentario lo habría evitado.

3. Librerías personalizadas.

El proyecto usa una autenticación propia.

La IA, sin saberlo, sugiere OAuth estándar.

Si el README lo mencionara, no erraría el enfoque.

4. Legado sin contexto.

Una función antigua persiste por requerimiento de un cliente.

La IA la marca como “muerta” y propone eliminarla.

Una nota explicativa la habría salvado.

Cada fallo de este tipo apunta al mismo culpable: falta de contexto.

Y cada error es una oportunidad para documentar mejor.

Documento “AGENTS.md” : guía para tus copilotos IA

En un proyecto donde colaboran desarrolladores humanos y asistentes basados en modelos de lenguaje, el fichero AGENTS.md deja de ser una curiosidad y se convierte en un punto de partida obligatorio. Piénsalo como un “README para el agente”: el archivo donde explicitas cómo debe comportarse, qué convenciones seguir, dónde está lo más importante.

¿Qué hace?

• Indica la estructura del proyecto (carpetas clave, módulos principales) para que el agente se oriente rápido.
• Define las convenciones de código, estilos, reglas de test, workflows (pull-request, linters…) para que el agente genere contribuciones que casen con tu base existente.
• Señala los comandos que ejecutar, los límites del entorno, los supuestos de negocio que están fuera del código. Esto evita que el agente improvise lo que no debe o genere duplicados.

¿Por qué lo necesitas?

Porque al igual que sucede con cualquier desarrollador nuevo que entra al equipo, el agente IA no trae tu historia, ni tus convenciones, ni lo que se quedó en la pizarra del lunes. Sin AGENTS.md, el modelo opera con lo que “recuerda” de su entrenamiento o lo que deduce del código, y eso suele bastar para partes comunes, pero no para los matices de tu proyecto. Con AGENTS.md le das ese contexto que hace la diferencia.

En una analogía: si la documentación principal es el mapa de la ciudad, el AGENTS.md es la señalética que le dice al agente “por aquí, y no por allá”.

¿Dónde encontrar ejemplos y cómo implementarlo?

La especificación del archivo está abierta y accesible en el repositorio de OpenAI.

Además, hay una colección de plantillas y casos reales en herramientas como “Agents.md Examples” que muestran cómo diferentes proyectos plantean ese archivo.

Un ejemplo mínimo podría comenzar así:

# AGENTS.md

## Estructura del proyecto

- /src/ – código fuente principal

- /tests/ – pruebas unitarias y de integración

- /docs/ – documentación adicional

## Convenciones de código

- JavaScript/TypeScript: strict-types, PascalCase para clases

- Variables en snake_case en scripts de automatización

## Comandos frecuentes

- `npm test` → Ejecutar todos los tests

- `npm run lint` → Verificar estilo y errores

- `docker-compose up --build` → Levantar entorno local

Y así sucesivamente.

Buenas prácticas al escribirlo

• Sitúalo en la raíz del repositorio (o en subdirectorios específicos si tienes módulos separados) para que el agente lo encuentre sin buscar.
• No lo conviertas en un documento interminable: el agente no necesita leer “toda” la historia, sino las piezas que le permiten tomar buenas decisiones.
• Asegúrate de que esté actualizado: cualquier cambio en la estructura del proyecto, en los comandos de build o en los estándares de código, debe reflejarse aquí para que el agente siga alineado con tu equipo.

Escribir para tus futuros lectores (humanos y artificiales)

En la era de los copilotos, la documentación dejó de ser un apéndice.

Ahora es la infraestructura invisible que sostiene el desarrollo moderno.

Documentar no es burocracia: es construir una memoria compartida.

Permite que humanos y máquinas trabajen sobre la misma base de conocimiento.

El código por sí solo no basta; necesita su narración adjunta.

Cuando documentas bien, no solo mejoras la colaboración y el mantenimiento: preparas tu proyecto para un futuro donde la IA será parte activa del equipo.

Y si queremos que colabore con sentido, primero debemos enseñarle a entendernos.

La documentación es, al fin y al cabo, el lenguaje común entre la creatividad humana y la inteligencia artificial.

Nuestro nuevo idioma técnico.