Guía completa de CLAUDE.md y .cursorrules para tu proyecto

Si usas Claude Code, Cursor o Copilot sin un archivo de instrucciones persistentes, estás perdiendo el 70% del valor de la herramienta. Es como contratar a un developer senior excelente y no darle nunca contexto del proyecto, las convenciones del equipo ni cómo está estructurado el código.

Este artículo es la guía definitiva para configurar archivos CLAUDE.md, .cursorrules y equivalentes. Vas a aprender:

• Qué son exactamente y por qué importan
• Cómo escribir uno que funcione (no genérico)
• Templates reales para Next.js, Python, Go, Rust y más
• Errores comunes que arruinan los resultados
• Cómo medir si está funcionando

Al final tendrás archivos listos para copiar a tus proyectos.

Qué son los archivos de configuración de IA#

Los asistentes de IA modernos permiten instrucciones persistentes que se aplican a cada interacción dentro de un proyecto. En lugar de explicar el contexto cada vez que pides algo, lo escribes una vez en un archivo y la IA lo lee automáticamente.

Los principales:

CLAUDE.md (Claude Code): archivo en la raíz del proyecto. Claude lo lee al inicio de cada sesión.

.cursorrules (Cursor): mismo concepto, formato más estructurado. Puedes tener .cursorrules global y reglas por carpeta.

.github/copilot-instructions.md (GitHub Copilot): instrucciones a nivel repositorio. Más limitado pero útil.

AGENTS.md (OpenCode, ChatGPT Codex, otros): estándar emergente que algunos proveedores están adoptando.

Si tu proyecto tiene los tres archivos (raro pero válido), cada herramienta lee el suyo. Idealmente, mantén un solo archivo “fuente de verdad” y los otros como enlaces simbólicos.

Por qué importan tanto#

Sin archivo de instrucciones, la IA tiene que inferir convenciones cada vez:

• ¿Usamos let o const? ¿Función arrow o normal?
• ¿La estructura de carpetas es por feature o por tipo?
• ¿Qué librería de estado usamos? ¿Zustand? ¿Redux Toolkit?
• ¿Los tests van junto al código o en __tests__/?
• ¿Usamos Tailwind o CSS Modules?

Sin contexto, la IA inventa convenciones que no son las tuyas. Después tienes que corregir cada output manualmente, y la productividad cae en picado.

Con un buen CLAUDE.md, la IA respeta tus convenciones desde el primer mensaje. La diferencia es ~3x en velocidad real, no es exageración.

Anatomía de un CLAUDE.md efectivo#

Un buen archivo de instrucciones tiene 5 secciones:

1. Contexto del proyecto#

## Project Context

This is the frontend of [Project Name], a SaaS for [audience] that
[main value proposition]. Built with Next.js 15 (App Router),
TypeScript and Tailwind CSS v4.

Current state: Production with ~10k users.
Architecture: Monolithic Next.js with PostgreSQL via Prisma.

Por qué importa: la IA toma decisiones distintas en un proyecto de 10 usuarios vs uno de 10.000. Saber si es producción vs experimental cambia cuánto riesgo es aceptable.

2. Stack tecnológico#

## Tech Stack

- Framework: Next.js 15 (App Router, no Pages Router)
- Language: TypeScript with strict mode
- Styling: Tailwind CSS v4 + Radix UI primitives
- State: Zustand for client state, React Query for server state
- Database: PostgreSQL with Prisma ORM
- Auth: Clerk
- Hosting: Vercel
- Testing: Vitest + Playwright for E2E

Crítico: especifica versiones mayores. “Next.js” no es lo mismo que “Next.js 15”. La diferencia entre Pages Router y App Router en Next.js es enorme.

3. Convenciones de código#

## Coding Conventions

### TypeScript

- Strict mode enabled (no any unless absolutely necessary)
- Prefer interface over type for object shapes
- Use generics for reusable components
- Use Zod for runtime validation

### React

- Functional components only
- Custom hooks for shared logic (file: useXxx.ts)
- Props interface named ComponentNameProps
- Export default at end of file

### Styling

- Tailwind classes inline (no @apply in CSS files)
- Use cn() utility from utils/cn.ts for conditional classes
- Component variants via cva (class-variance-authority)

### File Structure

src/
app/ - Next.js routes (App Router)
components/ - Shared components
ui/ - Base UI primitives (button, input)
features/ - Feature-specific components
lib/ - Utilities, types, configs
hooks/ - Custom React hooks
server/ - Server actions and DB queries

Clave: sé específico con ejemplos, no abstracto. “Componentes bien tipados” no significa nada. “Props interface llamada ComponentNameProps exportada” sí.

4. Lo que NO hacer#

## Do NOT

- Do not use class components or HOCs (legacy patterns)
- Do not introduce new dependencies without explicit approval
- Do not modify files in /lib/legacy/ (frozen for compatibility)
- Do not use console.log in production code (use lib/logger.ts)
- Do not write inline styles (use Tailwind)
- Do not create files in src/utils — use src/lib instead
- Do not use any unless you justify it with a comment

Esto es probablemente lo más importante del archivo. Las prohibiciones explícitas evitan que la IA tome decisiones que tendrás que revertir.

5. Workflow esperado#

## Workflow

When implementing a new feature:

1. Read existing similar features for patterns
2. Add types/interfaces first in src/lib/types/
3. Create components in src/components/features/[feature]/
4. Add tests in same folder (Component.test.tsx)
5. Update relevant types and exports
6. Run npm run typecheck before considering done

When fixing bugs:

1. Reproduce the bug first
2. Write a failing test
3. Fix the bug
4. Verify test passes
5. Look for similar issues elsewhere in codebase

Commit messages: use Conventional Commits

- feat: new feature
- fix: bug fix
- refactor: code change without behavior change
- chore: maintenance

Templates listos para usar#

Template 1: Next.js + TypeScript + Tailwind (App Router)#

# Project Instructions

## Context

This is a Next.js 15 SaaS using App Router. Production app with
real users. Code goes to main after PR review.

## Stack

- Next.js 15 (App Router)
- TypeScript strict
- Tailwind CSS v4
- shadcn/ui components
- Prisma + PostgreSQL
- React Query + Zustand
- Vitest + Playwright

## Conventions

### Components

- Functional components only
- Server Components by default, "use client" only when needed
- Props as ComponentNameProps interface
- One component per file

### Data Fetching

- Server: direct Prisma queries in Server Components
- Client: React Query + custom hooks
- Mutations: Server Actions (not API routes unless necessary)

### Styling

- Tailwind inline classes
- cn() utility for conditional
- cva for variants
- No CSS Modules

## DO NOT

- Use Pages Router (App Router only)
- Add new dependencies without approval
- Use API Routes for mutations (use Server Actions)
- Use any in TypeScript

## Workflow

1. Read similar features for patterns
2. Types first, then logic, then UI
3. Run npm run typecheck before completing
4. Conventional Commits for messages

Template 2: Python + FastAPI + PostgreSQL#

# Project Instructions

## Context

FastAPI backend serving REST API for our mobile + web frontends.
Python 3.12, async-first throughout.

## Stack

- FastAPI 0.115+
- SQLAlchemy 2.0 (async)
- Alembic migrations
- Pydantic v2 for validation
- pytest for testing
- Ruff for linting/formatting

## Conventions

### Python

- Type hints everywhere (mypy strict)
- async/await for I/O operations
- Pydantic models for request/response
- SQLAlchemy 2.0 syntax (no legacy)

### Structure

src/
api/ - FastAPI routers by domain
services/ - Business logic
repositories/ - Data access layer  
 models/ - SQLAlchemy models
schemas/ - Pydantic schemas
core/ - Config, dependencies

### Error Handling

- Custom exceptions in core/exceptions.py
- HTTPException only at API layer
- Services raise domain exceptions
- Global handler converts to HTTP responses

## DO NOT

- Use synchronous SQLAlchemy (async only)
- Put business logic in routers (use services)
- Skip type hints
- Use print() (use structlog)

## Workflow

1. Add schema in schemas/
2. Add repository methods
3. Add service logic
4. Expose via router
5. Add tests at each layer
6. Run ruff format && ruff check && mypy

Template 3: Go + Gin + PostgreSQL#

# Project Instructions

## Context

Backend API in Go 1.23. Microservice for [domain]. High throughput,
low latency requirements (<100ms p99).

## Stack

- Go 1.23
- Gin framework
- pgx (PostgreSQL driver, not database/sql)
- sqlc for type-safe queries (not ORM)
- Zerolog for logging
- testify for tests

## Conventions

### Go Idioms

- Return errors, don't panic (except main)
- Accept interfaces, return structs
- No god packages — small focused packages
- Context.Context as first arg always

### Structure

cmd/
api/ - main.go for API service
internal/
api/ - HTTP handlers
service/ - Business logic
repository/ - Data access (sqlc generated)
domain/ - Entities and interfaces
pkg/ - Public packages (rare)

### Error Handling

- errors.New / fmt.Errorf with %w for wrapping
- Sentinel errors for known cases
- HTTP layer translates to status codes

## DO NOT

- Use init() functions (initialize explicitly)
- Use global variables
- Panic outside main
- Use ORMs (sqlc only)
- Ignore errors (handle or wrap)

## Workflow

1. Define types in domain/
2. Define repository interface
3. Generate queries with sqlc
4. Implement service logic
5. Expose via handler
6. Write tests at each layer
7. Run go vet, golangci-lint, go test

Errores comunes que arruinan los resultados#

Error 1: Demasiado genérico#

❌ “Write clean code following best practices”

✅ “Functional components only, props as ComponentNameProps interface, one component per file”

La IA no sabe qué significa “clean code” para tu equipo específico. Sé concreto.

Error 2: Contradicciones internas#

❌ “Use TypeScript strict mode” + ejemplos con any en el mismo documento.

La IA va a coger señales de los ejemplos. Si dices strict pero das ejemplos sucios, harás lo sucio.

Error 3: Demasiado largo#

Si tu CLAUDE.md tiene 5.000 palabras, la IA va a saltarse cosas. Mantenlo entre 500-1.500 palabras. Si necesitas más, divide en archivos por área (/docs/backend.md, /docs/frontend.md).

Error 4: No actualizarlo#

El proyecto evoluciona, el CLAUDE.md no. En 6 meses tienes un archivo que no refleja la realidad y la IA toma decisiones basadas en información obsoleta.

Regla: revisa el archivo cada sprint. Si cambias algo fundamental (librería, patrón), actualízalo el mismo día.

Error 5: Esconder convenciones en código#

❌ Convenciones en el CLAUDE.md que no están en el código.

✅ El CLAUDE.md describe lo que ya hay en el código + lo que debería haber.

Si tu código es inconsistente pero tu CLAUDE.md describe la versión idealizada, la IA va a seguir el código (no el archivo).

Cómo saber si está funcionando#

Tres señales de que tu CLAUDE.md funciona:

1. La IA respeta convenciones sin que lo recuerdes en cada mensaje. Si tienes que decir “recuerda que usamos Zustand” cada vez, falta info en el archivo.

2. El código generado es directamente mergeable. Si tienes que arreglar imports, renombrar variables, mover archivos antes de hacer commit, faltan reglas.

3. La IA pregunta cuando hay ambigüedad real. Esto es buena señal — significa que conoce tus convenciones y solo pregunta cuando hay decisión genuina que tomar.

Si tu IA “inventa” mucho sin preguntar, falta contexto o claridad en el archivo.

Configuración avanzada: archivos por carpeta#

En Cursor puedes tener .cursorrules por carpeta. Útil para proyectos con áreas muy diferentes:

project/
├── .cursorrules              # Reglas globales
├── frontend/
│   └── .cursorrules          # Reglas específicas de frontend
├── backend/
│   └── .cursorrules          # Reglas específicas de backend
└── mobile/
    └── .cursorrules          # Reglas específicas de React Native

Cursor aplica las reglas más específicas según en qué archivo estés trabajando. Muy útil para monorepos.

Claude Code no soporta esto nativamente, pero puedes referenciar archivos desde el CLAUDE.md principal:

## Sub-projects

- /frontend: See /frontend/CONVENTIONS.md
- /backend: See /backend/CONVENTIONS.md
- /infra: See /infra/CONVENTIONS.md

Repositorio público con templates#

Mantenemos un repositorio público con templates de CLAUDE.md y .cursorrules para los stacks más comunes. Está actualizado regularmente y la comunidad contribuye:

github.com/zyntax-dev/agent-templates (próximamente)

Stacks incluidos:

• Next.js + TypeScript + Tailwind
• React + Vite + TypeScript
• Vue 3 + Pinia + TypeScript
• Python FastAPI + SQLAlchemy
• Python Django + DRF
• Go + Gin + sqlc
• Rust + Axum + sqlx
• Node.js + Express + Prisma
• Astro + MDX (este blog)

Conclusión#

Un buen archivo de configuración para IA no es opcional — es lo que separa a developers que usan IA productivamente de developers que pelean con la IA.

Empieza con uno de los templates de arriba, adáptalo a tu proyecto en una hora, y verás la diferencia desde el primer día. Es de las inversiones de tiempo con mejor ROI que puedes hacer como developer en 2026.

Y un consejo final: trata tu CLAUDE.md como cualquier otra documentación importante del proyecto. Vive en el repo, se versiona con git, se revisa en code review, se actualiza cuando algo cambia. No es un “extra” — es parte del código.

---

Si tienes preguntas sobre cómo configurar tu proyecto específico, escríbenos en redes. Y si tienes templates buenos para otros stacks, abre un PR al repo público.