Una Estructura de Proyecto Ideal para Desarrollar con IA

Actualmente muchas personas están utilizando herramientas de inteligencia artificial para desarrollar software. Sin embargo, a medida que los proyectos crecen, comienzan a aparecer muchos elementos nuevos: skills, documentación, scripts, archivos de contexto, memoria del proyecto, etc.

Si todo esto no se organiza correctamente, el proyecto puede terminar lleno de archivos dispersos que no aportan valor real.

En este artículo veremos una estructura de proyecto simple pero muy poderosa, que puedes aplicar en proyectos frontend, backend o fullstack, y que además ayuda a que las herramientas de IA comprendan mejor el contexto del proyecto.

Aunque el ejemplo utiliza Claude Code, estas ideas pueden aplicarse con cualquier herramienta basada en agentes o asistentes de programación.

La estructura del proyecto

Una estructura típica podría verse así:

my-project/
│
├── CLAUDE.md
├── README.md
│
├── docs/
│   ├── architecture.md
│   ├── decisions/
│   └── runbooks/
│
├── .claude/
│   ├── settings.json
│   ├── hooks/
│   └── skills/
│
├── tools/
│   ├── scripts/
│   └── prompts/
│
└── src/

Cada parte cumple un propósito específico.

1. src/: el código fuente del proyecto

Esta carpeta es la más conocida.

Aquí se encuentra el código principal de la aplicación, ya sea:

• frontend
• backend
• APIs
• lógica de negocio

Es el núcleo del proyecto.

2. README.md: presentación del proyecto

Este archivo normalmente ya existe si el proyecto está en GitHub.

Sirve para explicar:

• qué hace el proyecto
• cómo ejecutarlo
• cómo instalar dependencias
• cómo contribuir

Es principalmente para humanos.

3. CLAUDE.md: el contexto del proyecto para la IA

Este archivo es uno de los más importantes cuando trabajas con herramientas de IA.

Contiene un resumen del proyecto que la IA cargará cada vez que interactúes con ella.

Normalmente incluye:

• stack tecnológico
• descripción del proyecto
• estructura del código
• modelos de datos
• reglas de desarrollo
• convenciones del proyecto

Muchas herramientas permiten generar este archivo automáticamente con comandos como:

/init

Este comando analiza el proyecto y crea un resumen inicial. Luego puedes modificarlo manualmente para mejorar el contexto.

4. docs/: documentación del proyecto

Esta carpeta guarda la documentación técnica.

Una estructura común es:

docs/
 ├ architecture.md
 ├ decisions/
 └ runbooks/

Aquí es donde realmente puedes aprovechar la IA para generar documentación útil.

architecture.md

Describe la arquitectura del sistema.

Puede incluir:

• stack tecnológico
• diagramas
• modelos de datos
• estructura de directorios
• APIs
• patrones de diseño
• infraestructura

Lo ideal es dividir la arquitectura en múltiples archivos para facilitar la navegación.

decisions/

Esta carpeta guarda decisiones de arquitectura.

Responde a preguntas como:

• ¿Por qué usamos una base de datos relacional?
• ¿Por qué usamos Next.js?
• ¿Por qué usamos JWT para autenticación?

Ejemplo:

docs/decisions/
001-use-nextjs.md
002-use-prisma.md
003-use-jwt-auth.md

Esto crea un historial técnico del proyecto que también puede consultar la IA.

runbooks/

Aquí se documenta cómo ejecutar procesos del proyecto.

Ejemplos:

• cómo hacer deploy
• cómo ejecutar migraciones
• cómo auditar el sistema
• cómo levantar el entorno de desarrollo

Ejemplo:

docs/runbooks/
deploy.md
database-migration.md
security-audit.md

Si decisions responde por qué, runbooks responde cómo hacerlo.

5. .claude/: configuración del agente

Esta carpeta contiene configuraciones específicas para Claude Code o agentes similares.

.claude/
 ├ settings.json
 ├ hooks/
 └ skills/

skills/

Los skills permiten crear comandos reutilizables para la IA.

Ejemplo:

.claude/skills/
build/
review/
testing/
deploy/

Un ejemplo simple:

name: build
description: construir la aplicación

1. Ejecutar npm run build
2. Revisar errores
3. Si falla, corregir errores

Luego puedes ejecutarlo con:

/build

Esto evita repetir instrucciones largas.

6. tools/: herramientas del proyecto

Aquí se guardan utilidades reutilizables.

tools/
 ├ scripts/
 └ prompts/

scripts/

Scripts que automatizan tareas.

Ejemplos:

• crear usuarios
• generar datos de prueba
• ejecutar migraciones
• limpiar base de datos

prompts/

Aquí puedes guardar instrucciones reutilizables para IA.

Aunque muchas veces se reemplazan con skills, también puede servir para prompts largos reutilizables.

7. Hooks

Los hooks permiten ejecutar acciones cuando ocurre algo.

Por ejemplo:

• cuando la IA termina una tarea
• cuando se ejecuta un comando
• cuando se genera código

Se pueden usar para:

• enviar notificaciones a Telegram
• enviar mensajes a Slack
• ejecutar scripts automáticos

8. Documentación viva

La documentación no debe quedar abandonada.

Debe actualizarse a medida que el proyecto evoluciona. La IA puede ayudarte a mantenerla actualizada.

9. Uso en proyectos grandes

En proyectos más complejos puedes tener contexto por módulo.

Ejemplo:

src/api/CLAUDE.md
src/frontend/CLAUDE.md

Esto permite que la IA tenga contexto específico para cada parte del sistema.

Conclusión

Esta estructura mejora significativamente el desarrollo asistido por IA.

Beneficios:

• mejor organización del proyecto
• contexto claro para la IA
• automatización de tareas repetitivas
• documentación útil y mantenible
• flujos de desarrollo más rápidos

A medida que el proyecto crezca, puedes extender esta estructura con más herramientas, scripts y documentación.