Has pasado horas creando un README atractivo con badges, capturas y frases ingeniosas. Se ve genial en GitHub pero al pegarlo en Claude o ChatGPT para pedir ayuda el asistente genera importaciones que no existen y componentes inventados. El problema no es la IA sino cómo estructuras la información para máquinas. Aquí tienes cómo escribir README que funcionen tanto para humanos como para asistentes IA.

Por qué tu README actual falla con IA: la mayoría están optimizados para humanos que navegan GitHub; contienen texto de marketing, elementos visuales como badges y GIFs, explicaciones narrativas e instrucciones de instalación para múltiples plataformas. Los asistentes IA no necesitan eso, necesitan datos estructurados y predecibles que puedan convertir en contexto de trabajo. Frases como Blazingly fast React framework no aportan arquitectura real. En cambio, una lista clara de props o dependencias permite generar código preciso.

Bloque Quick Context para asistentes IA: este es tu atajo más importante. Incluye un bloque al inicio con la pila y convenciones principales. Ejemplo de bloque Quick Context para pegarle a la IA en una petición: Quick Context para asistentes IA: Stack: React 18; TypeScript 5.3; Tailwind CSS 3.4; Package Manager: pnpm; Node Version: 20+; Entry Point: src/main.tsx; Patrón de componentes: componentes funcionales con hooks; State Management: Zustand; Estilo: clases Tailwind, sin CSS modules

Con este bloque la IA ya sabe usar hooks, aplicar Tailwind y emplear pnpm sin adivinar. Sin él la IA hará preguntas o acertará por casualidad.

Diagrama de arquitectura en ASCII en lugar de imágenes: las imágenes no las 'ven' bien los LLM; proporcionar una estructura en texto indica exactamente dónde poner archivos. Ejemplo en una sola línea: src/ +-- components/ # Reusable UI components ¦ +-- ui/ # Primitives (Button, Input, Card) ¦ +-- features/ # Feature-specific components +-- hooks/ # Custom React hooks +-- lib/ # Utilities +-- stores/ # Zustand stores +-- types/ # TS types

Interfaces clave: la IA necesita contratos, no descripciones en prosa. Muestra interfaces reales en TypeScript. Ejemplo sin ambigüedades: enum Role { admin, user, guest } interface User { id: string; email: string; role: Role; createdAt: Date; } interface ApiResponse <T> { data: T; error: string | null; status: number; } Cuando la IA ve estos tipos usa nombres correctos, respeta restricciones y maneja opcionales bien.

Patrones de componente con ejemplos concretos: documenta patrones con código real y claro. Ejemplo de convención y componente: Convención: exportar la interfaz de props desde el mismo archivo; export default para el componente; exports nombrados para utilidades; hooks co-localizados si son de uso único. Ejemplo: export interface ButtonProps { variant: primary | secondary | ghost; size: sm | md | lg; disabled?: boolean; onClick?: () => void; children: React.ReactNode; } export default function Button({ variant, size, ...props }: ButtonProps) { /* implementación */ }

Aliases de importación para detener adivinanzas de rutas: documenta tus alias de módulos para evitar imports erroneos. Ejemplo: Alias @/ significa src/; @/components/ significa src/components/; @/lib/ significa src/lib/ Así la IA generará import { Button } from @/components/ui/Button en vez de rutas relativas incorrectas.

Dependencias críticas: lista los paquetes que la IA debe conocer y su propósito. Ejemplo: @tanstack/react-query para fetch con useQuery y useMutation; zustand para state management; zod para validación de esquemas; date-fns para manipulación de fechas

Operaciones comunes como pasos numerados: documenta flujos en pasos claros para que la IA los siga. Ejemplos: Agregar un nuevo componente: 1 Crear archivo en src/components/ui o src/components/features 2 Exportar interfaz de props 3 Usar export default para el componente 4 Añadir a src/components/index.ts barrel. Añadir un endpoint API: 1 Definir tipos en src/types/api.ts 2 Crear hook en src/hooks/use[Resource].ts 3 Usar react-query

Prueba real: antes y después. Con un README tradicional la IA suele sugerir rutas relativas incorrectas, clases CSS cuando usas Tailwind o manipular datos sin react-query. Con un README optimizado la IA acierta imports alias, convenciones de estilo y hooks existentes, reduciendo correcciones manuales.

Archivo LLM_CONTEXT.md para proyectos grandes: crear un archivo dedicado con metadatos y reglas evita repetir en cada petición. Incluye nombre del proyecto, tipo de app, lenguaje principal, y una sección de anti patrones que indique qué no hacer, por ejemplo evitar CSS modules, evitar componentes de clase, o evitar determinados patrones de export.

Lista de verificación para un README listo para IA: Quick Context con stack y patrones; Interfaces TypeScript para modelos centrales; Aliases de import documentados; Estructura de carpetas en ASCII; Lista de dependencias con casos de uso; Patrones de componente con ejemplos; Operaciones comunes como pasos; Sección de anti patrones

Herramientas que ayudan a generar contexto: LogicStamp para autogenerar contexto desde proyectos React/TypeScript; TypeDoc para documentación de TS; documentation.js para JSDoc a markdown

Conclusión y sobre Q2BSTUDIO: el mejor README sirve a dos audiencias, humanos y asistentes IA. Añadiendo un bloque Quick Context, mostrando interfaces reales y documentando patrones conviertes tu README en un prompt práctico. En Q2BSTUDIO somos una empresa de desarrollo de software y aplicaciones a medida con especialización en inteligencia artificial, ciberseguridad y servicios cloud. Ofrecemos soluciones de software a medida y aplicaciones a medida adaptadas a la realidad de cada cliente, además de servicios cloud aws y azure y servicios inteligencia de negocio. Si buscas impulsar la adopción de ia para empresas o desarrollar agentes IA integrados en tus sistemas puedes conocer nuestras soluciones de inteligencia artificial en servicios de inteligencia artificial y nuestros desarrollos de aplicaciones a medida en desarrollo de aplicaciones y software multicanal. Integrando buenas prácticas de documentación mejorarás la efectividad de asistentes como Claude y ChatGPT y optimizarás tiempos de desarrollo en áreas como ciberseguridad, power bi y automatización de procesos.

Qué incluir en tus READMEs para contexto IA: comparte plantillas y ejemplos en tu equipo y en la comunidad. En Q2BSTUDIO ayudamos a crear documentación técnica que funciona para humanos y para modelos de lenguaje, potenciando proyectos de software a medida, inteligencia artificial, ciberseguridad y servicios cloud.