Abre Claude Code en un proyecto nuevo y empieza a darle instrucciones. Funcionará. Obtendrás código, sugerencias, refactorizaciones. Pero observa con atención y notarás algo: Claude está haciendo suposiciones por todas partes. Sobre la estructura de tus carpetas. Tus convenciones de pruebas. Tus patrones preferidos de manejo de errores. Cómo nombras las cosas. Dónde va cada cosa.
Es como incorporar a un desarrollador nuevo y saltarse las primeras dos semanas de contexto. Producirá código, pero no se sentirá como tu código.
Eso es lo que resuelve CLAUDE.md. Es un archivo markdown en la raíz de tu proyecto que le da a Claude Code un contexto persistente sobre cómo funciona tu base de código, qué te importa y cómo quieres que se hagan las cosas. Lo hemos venido refinando en Baur Software a lo largo de docenas de proyectos, y a estas alturas lo consideramos tan esencial como un .gitignore. Ese no lo omitirías. Este tampoco.
Qué hace realmente CLAUDE.md
Cuando Claude Code inicia una sesión, lee CLAUDE.md antes de hacer cualquier otra cosa. Piénsalo como un prompt de sistema que vive en tu repositorio. Todo lo que hay en ese archivo moldea cómo Claude interpreta tus solicitudes, genera código y toma decisiones cuando no has sido explícito.
Sin él, Claude recurre a las buenas prácticas generales. Lo cual suena bien hasta que "las buenas prácticas generales" significan que reestructura tu componente con un patrón que tu equipo no ha acordado, o escribe pruebas usando un framework que no usas, o coloca un nuevo archivo de utilidades en un lugar que no tiene ningún sentido en tu proyecto.
Con un buen CLAUDE.md, Claude llega el primer día conociendo ya las reglas de la casa.
Qué incluir en uno bueno
Después de meses de iteración, hemos descubierto que un CLAUDE.md eficaz cubre cinco áreas. No necesitas escribir una novela para cada una, pero omitir cualquiera de ellas genera fricción.
1. Descripción general del proyecto
Unas pocas frases que describan qué es este proyecto, para quién es y qué hace. Esto suena obvio, pero evita que Claude haga suposiciones erróneas sobre el alcance y la intención.
## Project Overview This is a Next.js 14 SaaS platform for managing construction project bids. Users are general contractors and subcontractors. The app handles bid creation, document management, and team collaboration. We prioritize reliability and clear UX over cutting-edge features.
Esa última frase importa más de lo que crees. Le indica a Claude que tome decisiones conservadoras en lugar de recurrir a la API más nueva o a la abstracción más ingeniosa.
2. Stack tecnológico y arquitectura
Enumera tu stack de forma explícita. No asumas que Claude lo deducirá de tu package.json. Sé específico con las versiones cuando importen, y señala cualquier decisión de arquitectura que no sea obvia a partir de la estructura de archivos.
## Tech Stack - Next.js 14 (App Router) - TypeScript (strict mode) - Tailwind CSS - Prisma ORM with PostgreSQL - NextAuth.js for authentication - Zustand for client-side state - Vitest + React Testing Library for tests ## Architecture Notes - All API routes live in app/api/ and follow RESTful conventions - Database queries go through service files in lib/services/, never called directly from components or API routes - We use server components by default, client components only when interactivity requires it
La sección de notas de arquitectura es donde más tiempo te ahorras. Sin ella, Claude esparcirá llamadas a la base de datos donde le parezca conveniente. Con ella, Claude sigue tus patrones desde la primera línea de código.
3. Estilo de código y convenciones
Aquí es donde la mayoría de los equipos se detiene (si es que escriben un CLAUDE.md), pero en realidad es la tercera prioridad, no la primera. El estilo importa menos que la arquitectura, pero aun así vale la pena documentarlo.
## Code Conventions - Use named exports, not default exports (except for pages/layouts) - Prefer early returns over nested conditionals - Error messages should be user-friendly, log technical details separately - Component files use PascalCase, utility files use camelCase - Keep components under 150 lines. If it's longer, break it up. - Use absolute imports with the @/ alias
Sé exigente aquí. Cuanto más específico seas, menos tiempo pasarás reformateando la salida de Claude para que coincida con tus preferencias.
4. Reglas de flujo de trabajo
Esta es la sección que la mayoría de la gente se salta por completo, y es una de las más valiosas. Dile a Claude cómo quieres que trabaje, no solo qué quieres que produzca.
## Workflow - Always check for existing similar implementations before creating new utilities or components - When modifying existing files, preserve the current patterns even if you'd do it differently from scratch - Run the linter before considering any task complete - If a change touches more than 3 files, outline the plan before writing code - Never delete or rename existing API endpoints without flagging it
Ese cuarto punto por sí solo nos ha salvado de que Claude se lance a maratones de refactorización de múltiples archivos cuando le pedimos una pequeña adición de funcionalidad. Establecer límites sobre el alcance es tan importante como establecer convenciones sobre el estilo.
5. Trampas conocidas y contexto
Todo proyecto tiene minas. Cosas que parecen errores pero no lo son, decisiones heredadas que tienen que quedarse por ahora, áreas donde el enfoque obvio es el equivocado. Documéntalas.
## Important Context - The billing module (lib/services/billing.ts) integrates with a legacy API that requires XML payloads. Do not attempt to modernize this without discussion. - User permissions are checked at the API route level, not in components. Don't add client-side permission gates. - The "projects" table has a soft-delete pattern. Always filter by deleted_at IS NULL unless explicitly querying archived projects. - Tests in __tests__/integration/ require a running database. Unit tests should never touch the database.
Esta sección es puro conocimiento institucional. El tipo de cosas que a un desarrollador humano le toma semanas asimilar. Claude puede asimilarlo en milisegundos, pero solo si lo dejas por escrito.
Nuestra plantilla
Este es el esqueleto con el que empezamos en cada proyecto nuevo en Baur Software. Rellenamos cada sección durante la configuración del proyecto y la actualizamos a medida que la base de código evoluciona.
# CLAUDE.md ## Project Overview [What this project is, who it's for, what matters most] ## Tech Stack [Frameworks, languages, key libraries with versions] ## Architecture [Folder structure philosophy, data flow patterns, key decisions] ## Code Conventions [Naming, formatting, component patterns, import style] ## Workflow Rules [How Claude should approach tasks, scope boundaries, process] ## Important Context [Landmines, legacy decisions, things that look wrong but aren't] ## Testing [Test framework, what to test, where tests live, how to run them] ## Environment [Environment variables, local setup quirks, deployment notes]
Lo mantenemos bajo control de versiones y lo tratamos como documentación viva. Cuando alguien del equipo toma una decisión de arquitectura, se añade al CLAUDE.md ese mismo día. Cuando Claude hace algo inesperado, averiguamos qué contexto faltaba y lo agregamos.
Errores comunes
Escribir una novela. CLAUDE.md debe poder leerse de un vistazo. Si tiene más de 500 líneas, probablemente estés incluyendo cosas que corresponden a la documentación real o a los comentarios del código. Mantenlo centrado en decisiones y patrones, no en explicaciones de cómo funciona tu framework.
Ser demasiado vago. "Escribe código limpio" no significa nada. "Usa retornos tempranos, mantén las funciones por debajo de 30 líneas y prefiere la composición sobre la herencia" lo significa todo.
Configurarlo y olvidarlo. Tu base de código cambia. Tu CLAUDE.md debería cambiar con ella. Revisamos el nuestro al inicio de cada sprint y actualizamos todo lo que se haya desviado.
No incluir reglas de flujo de trabajo. Las convenciones de estilo son la parte fácil. El valor real está en decirle a Claude cómo pensar sobre tu proyecto, como cuándo preguntar antes de actuar, cómo delimitar el alcance de los cambios y dónde tener cuidado.
El efecto compuesto
Un buen CLAUDE.md no solo te ahorra tiempo en una tarea. Se acumula. Cada interacción que Claude tiene con tu base de código mejora un poco porque el contexto está ahí desde el principio. Dejas de corregir los mismos errores. Dejas de reformatear los mismos patrones. Dejas de explicar las mismas decisiones de arquitectura.
A lo largo de semanas y meses, eso se traduce en una diferencia significativa en la velocidad. Y lo que es más importante, el código que Claude produce realmente parece pertenecer a tu proyecto.
Hemos venido refinando este enfoque en cada proyecto que tomamos en Baur Software, y se ha convertido en una de las primeras cosas que configuramos. Antes de la primera funcionalidad, antes del primer componente, escribimos el CLAUDE.md. Todo lo que sigue es mejor gracias a ello.
Esta publicación forma parte de nuestra serie sobre cómo construir de forma eficaz con IA en Baur Software. Anteriormente cubrimos por qué importa tu configuración de programación con IA, AWS Bedrock y Claude Code como tu capa de infraestructura y cómo escribir prompts que realmente funcionan. Si tu proyecto asistido por IA se está volviendo lo bastante complejo como para que las buenas herramientas ya no basten y necesites una buena arquitectura, nos encantaría hablar.