Los agentes de código están cambiando la forma en que escribimos software. Herramientas como Cursor, Claude Code, Windsurf y GitHub Copilot pueden generar código, refactorizar archivos y hasta ejecutar comandos por nosotros. Pero hay un problema que todos enfrentamos al empezar a usarlos en proyectos reales: el agente no conoce tu proyecto.
Le das una instrucción y te devuelve código que usa una librería que no tienes instalada. Te sugiere una estructura de carpetas que no sigue tu convención. Te escribe tests con un framework que no usas. O peor aún, modifica archivos críticos sin considerar las dependencias.
La solución no es dejar de usar agentes — es configurarlos correctamente. Y para eso existen dos herramientas fundamentales: Cursor Rules y CLAUDE.md.
El problema: agentes genéricos, proyectos específicos
Los modelos de lenguaje como Claude y GPT-4 son entrenados con código público de todo internet. Conocen React, Django, FastAPI, Tailwind — pero no saben que tu proyecto usa Express con EJS, que prefieres pnpm sobre npm, que tus commits siguen Conventional Commits, o que tienes una carpeta lib/ donde va toda la lógica de negocio.
Sin configuración, cada interacción con un agente es una lotería. A veces acierta, a veces escribe código que no funciona con el resto del sistema. Y cada vez que corriges al agente —“no uses axios, usa fetch nativo”— estás perdiendo el tiempo que la IA debería ahorrarte.
La solución: archivos de contexto para tu proyecto
Tanto Cursor Rules como CLAUDE.md resuelven el mismo problema fundamental: darle contexto permanente al agente sobre tu proyecto. Pero lo hacen de maneras ligeramente distintas.
Cursor Rules
Cursor Rules es un sistema de configuración que le dice a Cursor (y a otros editores con IA) cómo comportarse en tu proyecto. Funciona con archivos .cursorrules que puedes poner en la raíz de tu proyecto o en subdirectorios.
Un archivo .cursorrules típico incluye:
- Stack técnico: qué frameworks, librerías y versiones usas
- Convenciones de código: estilo de imports, naming, estructura de archivos
- Reglas de comportamiento: cómo debe responder el agente, qué evitar
- Contexto del proyecto: propósito, arquitectura, decisiones técnicas
Eres un asistente experto en desarrollo web con Astro 6 y Tailwind CSS.
Reglas:
- Usa TypeScript siempre, no JavaScript plano
- Prefiere componentes .astro sobre .tsx cuando no haya interactividad
- Los estilos van con @apply en Tailwind, no CSS modules
- Los imports usan el alias @/ para src/
- No generes archivos fuera de src/ sin preguntar primeroCLAUDE.md
CLAUDE.md (conocido también como .claude.md o CLAUDE.md en la raíz del proyecto) es un archivo de configuración que usa específicamente Claude Code (de Anthropic) y que otros agentes como Cursor también respetan.
El formato es similar pero tiene convenciones propias:
# Proyecto: DojoFullStack Blog
## Stack
- Astro 6 + Tailwind CSS
- Python 3.13 para pipelines
- AWS S3 + CloudFront para deploy
## Comandos
- Build: cd blog && npm run build
- Dev: cd blog && npm run dev
- Deploy: python3 pipeline/deployer.py
- Tests: npm run test
## Convenciones
- Los artículos van en blog/src/content/blog/
- Frontmatter YAML obligatorio con title, description, pubDate, tags
- Las imágenes OG se generan con generate_og_images.py
- No usar APIs externas para traducción de artículosLa principal ventaja de CLAUDE.md es que también incluye comandos. El agente sabe exactamente qué comandos ejecutar para build, test, lint o deploy sin que tengas que decírselo cada vez.
Implementación: cómo configurarlo paso a paso
1. Audita tu proyecto
Antes de escribir cualquier regla, haz un inventario rápido:
- ¿Qué lenguaje y versión? (Python 3.11, Node 20, TypeScript 5.5)
- ¿Qué framework? (Astro, Next.js, FastAPI, Express)
- ¿Qué gestor de paquetes? (npm, pnpm, yarn, uv, pip)
- ¿Qué linter/formatter? (ESLint, Prettier, Ruff, Black)
- ¿Qué estructura de carpetas? (src/, lib/, modules/, features/)
- ¿Qué convenciones de estilo? (imports absolutos, PascalCase componentes, camelCase variables)
2. Crea el archivo de reglas
Para Cursor: Crea .cursorrules en la raíz del proyecto.
Para Claude Code: Crea CLAUDE.md en la raíz del proyecto.
Para ambos: Crea ambos. No hay conflicto — Cursor lee .cursorrules primero, y Claude Code busca CLAUDE.md. Si usas ambos editores, duplicar la configuración es el camino seguro.
3. Sé específico
Cuanto más específicas sean tus reglas, mejores resultados obtendrás. Algunos ejemplos de reglas que marcan la diferencia:
| Regla genérica | Regla específica |
|---|---|
| ”Usa buenas prácticas" | "Las funciones async tienen type hints con tipos concretos, no Any" |
| "Sigue el estilo del proyecto" | "Los componentes React son arrow functions con export default, no function declarations" |
| "Optimiza el código" | "Prefiere for...of sobre .forEach() — 2x más rápido en V8” |
4. Incluye ejemplos
Los agentes entienden mejor con ejemplos. Si tu proyecto tiene un patrón específico, incluye un fragmento de código como referencia:
Ejemplo de endpoint válido:
```typescript
export async function GET({ request }: APIContext): Promise<APIRoute> {
const data = await request.json();
return new Response(JSON.stringify({ ok: true }), { status: 200 });
}
## Resultados: qué cambia cuando configuras bien tu agente
Después de implementar Cursor Rules y CLAUDE.md en proyectos reales, los resultados son notables:
- **Menos correcciones**: el agente acierta en el 80-90% de los casos desde el primer intento
- **Comandos automáticos**: "build and deploy" ejecuta los pasos correctos sin recordárselos
- **Código consistente**: sigue las convenciones del proyecto sin necesidad de revisión constante
- **Menos contexto perdido**: al cambiar de sesión, el agente recuerda las reglas del proyecto
En el blog de DojoFullStack, por ejemplo, el CLAUDE.md le dice al agente exactamente cómo generar artículos, qué frontmatter usar, qué comandos ejecutar para el build y cómo hacer deploy. Sin ese archivo, cada interacción empieza desde cero.
## Mejores prácticas adicionales
- **Reglas por carpeta**: Cursor soporta `.cursorrules` en subdirectorios. Si tienes un frontend y un backend en el mismo repo, puedes tener reglas diferentes para cada uno.
- **Actualiza las reglas**: cuando migres de versión o cambies de framework, actualiza los archivos de configuración. Un CLAUDE.md desactualizado es peor que no tenerlo.
- **Compártelo en el equipo**: incluye `.cursorrules` y `CLAUDE.md` en el control de versiones. Todo el equipo se beneficia de la misma configuración.
- **Combínalo con prompts**: las reglas son configuración global, pero puedes complementarlas con instrucciones específicas en cada interacción.
## Conclusión
Los agentes de código son tan buenos como el contexto que les damos. Un agente sin configuración es como un desarrollador nuevo que llega al proyecto sin onboarding: va a cometer errores, va a preguntar cosas obvias y va a producir código que no encaja.
Cursor Rules y CLAUDE.md son el onboarding que tu agente necesita. Invertir 15 minutos en escribirlos correctamente te ahorrará horas de correcciones y te permitirá aprovechar al máximo lo que los agentes de código pueden hacer hoy.
La diferencia entre un agente que molesta y uno que multiplica tu productividad está en la configuración. Y esa configuración empieza con un archivo de texto en la raíz de tu proyecto.
*Sigue explorando estos temas en el blog de DojoFullStack. Tenemos guías prácticas sobre agentes de código, automatización de pipelines y desarrollo de software moderno que te ayudarán a mantenerte al día.*