Cómo empezar un proyecto con IA

Guía práctica para construir proyectos asistidos por IA: desde los archivos de contexto hasta el flujo de trabajo diario. Aprende a crear un AGENTS.md, un DESIGN.md y a dirigir a la IA como si fuera tu mejor desarrollador junior.

La diferencia entre una IA que te ahorra tiempo y una que te da dolor de cabeza está en cómo le comunicas lo que quieres. Igual que un desarrollador humano necesita contexto —saber en qué proyecto trabaja, qué librerías usas, qué convenciones sigues— la IA también lo necesita.

Este tutorial te enseña a crear los archivos de contexto que toda IA respeta, a definir un sistema de diseño que se mantenga consistente y a establecer un flujo de trabajo que maximice la productividad.

¿Por qué los archivos de contexto?

Cada vez que hablas con una IA (Claude, GPT, OpenCode, Cursor), empiezas con una pizarra en blanco. La IA no sabe qué stack usas, si prefieres camelCase o snake_case, ni qué colores tiene tu marca.

Los archivos de contexto (CLAUDE.md, AGENTS.md) solucionan esto: son instrucciones persistentes que la IA lee al inicio de cada sesión. Una vez escritos, no tienes que repetir las mismas explicaciones cada vez.

Paso 1: El archivo de reglas (AGENTS.md / CLAUDE.md)

Este es el archivo más importante. Define cómo quieres que la IA trabaje: qué stack usas, qué patrones sigues, qué no debe hacer.

Estructura recomendada

1. Encabezado del proyecto — nombre, descripción, propósito
2. Stack tecnológico — frameworks, librerías, versiones
3. Estructura de carpetas — rutas clave, dónde está cada cosa
4. Reglas globales — normas que el asistente debe seguir siempre
5. Decisiones de arquitectura — por qué se eligió una solución sobre otra
6. Módulos implementados — qué está hecho y cómo se organiza

Ejemplo real

# Portfolio — AI Context

## Stack
- Frontend: Next.js 16 (pages-router), React, TypeScript, TailwindCSS, HeroUI
- Backend: Node.js, Express, TypeScript
- Database: Supabase (PostgreSQL + Auth)

## Reglas globales (OBLIGATORIO)
1. Cambios mínimos — solo patches, nunca reescribir archivos completos
2. Reutilizar primero — buscar existente antes de crear
3. TypeScript estricto — sin `any` salvo casos justificados
4. API formato: { success, data, error } — usar ok() en controllers
5. Sin confirm() — confirmaciones inline con estado React
6. Sin comentarios obvios — solo el WHY no-obvio

Buenas prácticas para las reglas

• Sin confirm(), usar estado React para confirmaciones inline
• Preferir server actions sobre API routes en Next.js
• Todos los archivos nuevos incluir TypeScript estricto
• Las queries a BD usar siempre supabaseAdmin (bypass RLS)
• Los colores siempre desde variables CSS, nunca valores hardcodeados
• Los mensajes de error en español, el código en inglés
• Las migraciones de BD en archivos SQL separados, no en código

Cómo actualizarlo

El AGENTS.md no es estático. Cada vez que la IA hace algo que no te gusta —un patrón incorrecto, una librería que no usa— añade una regla. Con el tiempo, el archivo crece y la IA se vuelve más precisa.

Paso 2: El sistema de diseño (DESIGN.md)

Si tu proyecto tiene interfaz de usuario, necesitas un DESIGN.md. Este archivo unifica la paleta de colores, tipografía, espaciado y componentes para que la IA genere código visualmente coherente.

Qué debe incluir

• Colores — primario, secundario, fondo, texto, estados (hover, active, disabled), modo oscuro
• Tipografía — fuentes, tamaños, pesos, jerarquía (h1, h2, body, small)
• Espaciado — escala (4, 8, 12, 16, 24, 32, 48, 64), márgenes, paddings
• Bordes y sombras — radios, elevaciones, colores de borde
• Componentes — botones, inputs, cards, modales con sus variantes
• Iconos — estilo (outline, solid), tamaño estándar, librería

Ejemplo de DESIGN.md

# Design System

## Colores
- primary: #8B5CF6 (Violet)
- secondary: #06B6D4 (Cyan)
- background: #FAFAFA (light) / #0A0A0A (dark)
- text: #1D1D1F (light) / #F5F5F7 (dark)
- muted: #6E6E73 (light) / #86868B (dark)
- success: #10B981, warning: #F59E0B, error: #EF4444

## Tipografía
- Font: Inter, sistema sans-serif
- h1: 36px bold, h2: 24px bold, h3: 18px semibold
- body: 14px regular, small: 12px, caption: 11px

## Espaciado
- Escala: 2, 4, 8, 12, 16, 24, 32, 48, 64
- Cards: p-4/p-6, gap entre secciones: 24px

## Bordes
- radius: 8px (sm), 12px (md), 16px (lg), 24px (xl)
- border color: black/8 (light), white/8 (dark)

## Componentes
- Button: filled (primary), outline (secondary), ghost (tertiary)
- Input: border-0 bg-black/5 rounded-xl p-3
- Card: rounded-2xl border p-4 bg-white dark:bg-[#111116]

Relación entre DESIGN.md y los componentes

El DESIGN.md no reemplaza a Tailwind o a tu framework de UI. Es una capa de abstracción que le dice a la IA qué decisiones de diseño tomar. Si usas Tailwind, las reglas serían algo como: "usar bg-violet-500 para primary, text-zinc-900 dark:text-zinc-100 para texto".

Si cambias de opinión sobre un color más tarde, actualizas el DESIGN.md y le pides a la IA que aplique el cambio en todos los componentes.

Paso 3: Archivos complementarios

Dependiendo del tamaño de tu proyecto, puedes añadir más archivos de contexto. Aquí los más útiles. Haz clic en cada uno para ver los detalles:

Paso 4: Cómo hablarle a la IA

Los archivos de contexto son el qué, pero necesitas también el cómo. La forma en que le pides cosas a la IA determina la calidad del resultado.

Principios básicos

• Sé específico — "Añade un botón de guardar" ← "Añade un botón de guardar en la esquina superior derecha del formulario, color primary, icono de check, que se deshabilite mientras se envía"
• Una cosa a la vez — Las IAs funcionan mejor con tareas atómicas. "Crea el formulario de login" es mejor que "Haz toda la app"
• Da contexto — "Crea un componente TarjetaProducto que reciba title, price, image y onClick. Sigue el diseño de las cards existentes en components/ui/"
• Corrige y refina — Si la IA genera algo incorrecto, dímelo. "El botón debería ser outline, no primary" — la IA aprende de cada corrección
• Usa referencias — "Mira el archivo components/Layout.tsx y haz algo similar para la página de dashboard"

Qué evitar

• Tareas abiertas — "Haz que la app se vea mejor" no da ninguna dirección útil
• Instrucciones contradictorias — "Sé creativo pero sigue las reglas al pie de la letra" confunde a la IA
• Cambiar de tema continuamente — Cada nuevo tema resetea parcialmente el contexto. Termina una tarea antes de empezar otra
• Asumir que recuerda — La IA no tiene memoria entre sesiones. Todo lo que necesita saber debe estar en los archivos de contexto o en el mensaje actual

Paso 5: Flujo de trabajo diario

Con los archivos de contexto en su sitio, el flujo de trabajo se vuelve predecible:

1. Abrir el proyecto — la IA lee AGENTS.md y DESIGN.md automáticamente
2. Dar una tarea concreta — "Crea el componente Navbar en components/layout/"
3. Revisar el resultado — la IA genera el código, tú lo revisas
4. Corregir si es necesario — "Cambia el color del hover a primary-600"
5. Actualizar el estado — marca la tarea como completada en MEMORY.md
6. Repetir — siguiente tarea

Gestión del contexto

Cada sesión de IA tiene un límite de tokens (normalmente 100k–200k). Si trabajas en un proyecto grande, el contexto se llena rápido. Estrategias para gestionarlo:

• Divide el trabajo en sesiones temáticas — una sesión para backend, otra para frontend
• Mantén un MEMORY.md — resumen del estado actual para que la IA se ponga al día rápido
• Usa el AGENTS.md para lo estable — solo reglas que no cambian. Lo volátil (tareas pendientes) va en MEMORY.md
• Prioriza — Si el contexto se llena, pide a la IA que se centre en lo más importante y descarte lo accesorio

Ejemplo completo: proyecto real

Este mismo portfolio donde estás leyendo este tutorial usa el sistema que acabo de describir. Tiene:

• CLAUDE.md — stack, reglas globales, estructura de carpetas, módulos implementados
• AGENTS.md — memorias que la IA carga según la tarea (backend, frontend, base de datos, auth...)
• Design system — definido en TailwindCSS con tokens consistentes y modo oscuro
• Archivos de estado — project-state.md con tareas completadas y pendientes

Cada vez que empiezo una nueva sesión con la IA, ella ya sabe qué stack uso, cómo estructuro el código y qué colores tiene la marca. No tengo que repetir nada.

Resumen

• Crea un AGENTS.md o CLAUDE.md con las reglas y stack del proyecto
• Crea un DESIGN.md con los tokens de diseño (colores, tipografía, espacios, componentes)
• Añade archivos complementarios según el tamaño del proyecto (MEMORY.md, ARCHITECTURE.md, API.md)
• Sé específico en tus instrucciones: una tarea concreta, contexto suficiente, referencias a archivos existentes
• Actualiza los archivos de contexto constantemente — cada regla nueva evita errores futuros
• Divide el trabajo en sesiones temáticas y gestiona el límite de tokens