Buenas prácticas para la estructura de proyectos en Claude Code

Cuando trabajas con Claude Code, organizar bien tus proyectos marca una gran diferencia. Claude funciona mejor cuando tiene un contexto claro, una estructura consistente e instrucciones explícitas.

A continuación encontrarás 5 principios fundamentales que deberías seguir para crear una excelente estructura de proyecto:

1. Coloca CLAUDE.md en la raíz

CLAUDE.md es un archivo fundamental para proporcionar a Claude Code contexto específico sobre tu proyecto. Funciona como una guía de incorporación para que la IA entienda los requisitos de tu proyecto y tu base de código.

Claude lee automáticamente el archivo CLAUDE.md al iniciar.

Este es un ejemplo de lo que puedes incluir en este archivo:

# Descripción general del proyecto
Breve descripción del proyecto.

# Arquitectura
Explicación de los componentes principales.

# Stack tecnológico
Next.js
TypeScript
ShadCN UI
Tailwind

# Convenciones de código
- Usar el modo estricto de TypeScript
- Preferir componentes funcionales
- Evitar exportaciones por defecto

# Estructura de carpetas
Explicación de los directorios.

# Comandos
npm run dev
npm run build

# Reglas importantes
Requisitos de rendimiento
Requisitos de accesibilidad
Estrategia de testing

El archivo debería colocarse en la carpeta raíz de tu proyecto:

my-project/
├── CLAUDE.md
├── package.json
├── src/
├── docs/
└── scripts/

Nota rápida: si ya tienes una base de código existente en tu proyecto, no tienes que empezar desde cero al crear CLAUDE.md.

En su lugar, puedes escribir el comando /init en Claude Code y este generará un primer borrador del archivo:

/init

2. Divide las instrucciones grandes de CLAUDE.md en archivos importados

El archivo CLAUDE.md puede crecer rápidamente.

Como Claude Code lee este archivo constantemente y su contenido se añade al contexto, no es recomendable tener archivos demasiado grandes.

Como regla general, si notas que el archivo supera aproximadamente las 200 líneas de texto, deberías dividirlo en varios archivos.

Claude Code permite realizar importaciones dentro de CLAUDE.md:

@path/to/import.md

Solo necesitas proporcionar el contexto necesario para indicar cuándo Claude debería utilizar cada archivo importado.

Así podría verse un archivo CLAUDE.md actualizado utilizando importaciones:

# CLAUDE.md

# Arquitectura
Para consultar la arquitectura del proyecto, revisa:
@claude/architecture.md

# Convenciones de código
Para consultar las convenciones de código, revisa:
@claude/coding_conventions.md

# Guías de interfaz
Para consultar las guías de interfaz, revisa:
@claude/ui_guidelines.md

Y dentro del directorio del proyecto, la estructura de archivos sería:

CLAUDE.md

claude/
    architecture.md
    coding_conventions.md
    ui_guidelines.md

Esta estructura resulta útil tanto para ti como para la IA porque:

• Es más fácil de mantener cuando quieres modificar algo.
• Permite una carga de contexto más rápida para Claude.
• Los archivos pueden reutilizarse entre diferentes proyectos, especialmente en proyectos de desarrollo web.

3. Añade una carpeta /docs para proporcionar contexto

Si quieres ayudar a Claude a comprender mejor tu proyecto y sus particularidades, es recomendable añadir una carpeta docs/.

Claude entiende especialmente bien la documentación escrita en formato Markdown.

Por ejemplo, puedes añadir información sobre funcionalidades que planeas incorporar a tu producto durante el trimestre o sobre las llamadas actuales a la API que ofrece tu producto.

docs/
    project_roadmap.md
    api.md

Después puedes pedirle a Claude que consulte esa documentación cuando implemente una funcionalidad concreta.

Por ejemplo, si quieres crear un sistema de comprobación del estado de tu servicio web:

Lee docs/api.md e implementa nuestro monitor de estado del servicio disponible mediante llamadas a la API.

De esta manera, Claude puede trabajar utilizando como referencia la documentación específica de tu proyecto.

4. Añade una carpeta /workflows para los flujos de trabajo

Si quieres que Claude siga un flujo de trabajo específico al realizar determinadas tareas, deberías guardar esos procesos en un directorio dedicado.

Por ejemplo, en un proyecto de desarrollo web puedes utilizar una estructura como esta:

claude/
    workflows/
        build-new-component.md
        code-refactoring.md
        write-auto-tests.md
        migrate-db.md

Así podría verse el workflow build-new-component.md.

Ten en cuenta que este es únicamente un ejemplo y que un flujo de trabajo real puede ser mucho más complejo:

# build-component.md

Cuando se te pida crear un nuevo componente para un servicio web,
créalo siguiendo estos requisitos:

- TypeScript
- ShadCN UI
- Accesible
- Mobile-first
- Estilos con Tailwind

Después puedes ejecutarlo con una instrucción como esta:

Sigue claude/prompts/build-component.md para crear una tarjeta para el dashboard.

Una de las ventajas de esta estructura es que puedes activar un flujo de trabajo desde otro.

Por ejemplo, si Claude crea un nuevo componente siguiendo build-new-component.md, puedes indicarle desde ese mismo archivo que también genere pruebas automáticas para validar el nuevo código.

El archivo podría verse así:

# build-component.md

Cuando se te pida crear un nuevo componente para un servicio web,
créalo siguiendo estos requisitos:

- TypeScript
- ShadCN UI
- Accesible
- Mobile-first
- Estilos con Tailwind

Asegúrate también de escribir pruebas automáticas para este componente
siguiendo las instrucciones de:

@workflows/write-auto-tests.md

De esta manera puedes crear flujos de trabajo compuestos y reutilizables.

5. Utiliza una carpeta /tools para las tareas de servicio de Claude

Una de las grandes ventajas de Claude Code es que puede escribir scripts de servicio específicos para agilizar determinados flujos de trabajo.

Por ejemplo, si le pides que organice una migración de base de datos definida en migrate-db.md, Claude probablemente escribirá un script en Python encargado de ejecutar parte de esas acciones.

Mi recomendación es guardar todos estos scripts de servicio dentro de una única carpeta llamada /tools.

tools/
    migrate-db.py
    seed-data.py
    export-data.py

Nota rápida: quizás te preguntes por qué utilizar /tools en lugar de /scripts.

Si estás trabajando en un proyecto de desarrollo web, normalmente el término scripts se asocia con scripts de frontend o backend utilizados directamente por el servicio.

Por eso prefiero utilizar el nombre /tools para las herramientas auxiliares que utilizamos durante el desarrollo.

Esto ayuda a reducir confusiones cuando diferentes personas del equipo revisan la estructura del proyecto.

Una estructura de proyecto bien organizada no solo hace que el código sea más sencillo de mantener.

También permite que Claude Code tenga un contexto más claro, entienda mejor las reglas del proyecto y siga flujos de trabajo de una forma mucho más consistente.

Gracias por leer Código en Casa.
Si esto te a ayudado y te sumo algo Dale un 👏 , compártelo con tu red o dejame un comentario para saber tu opinión.