04 · ⭐ El orden del proyecto (y por qué importa tanto)

Este es el módulo más importante de toda la guía. Un proyecto ordenado no es cosmética: es lo que hace que la IA se equivoque menos, entienda mejor lo que quieres y trabaje más rápido. Vamos con calma y con el porqué de cada cosa.

¿Por qué el orden importa de verdad?

Cuando le pides algo a Claude, él mira los archivos y carpetas de tu proyecto para entender el contexto. Si todo está desordenado, revuelto o con nombres confusos, la IA "adivina" más y acierta menos. Un proyecto ordenado le da tres regalos:

• Menos errores: Claude encuentra rápido lo que necesita y no confunde un archivo con otro.
• Mejor contexto: los nombres claros y las carpetas por tema le dicen qué es cada cosa sin tener que abrir todo.
• Trabajo más veloz: menos idas y vueltas, menos "¿te refieres a este archivo o a este otro?".

Esto vale para la terminal (que se ubica en una carpeta a la vez), para VS Code (que muestra el árbol de archivos a la izquierda) y para Cursor (otro editor con IA, muy parecido a VS Code). En los tres, el orden es la diferencia entre pelear con la herramienta y fluir con ella.

Las extensiones de archivo, una por una

La extensión son las letras después del punto en el nombre de un archivo (informe.html). Le dicen al computador —y a la IA— qué tipo de archivo es. Estas son las que verás:

El archivo .env: donde viven los secretos

Una API key (o token) es como la llave de tu casa: le da a un programa acceso a un servicio a tu nombre. Si alguien la consigue, puede gastar tu dinero o entrar a tus cuentas. Por eso hay una regla sagrada:

El .env es un archivo de texto con una línea por secreto, en formato CLAVE=valor:

# Ejemplo de archivo .env (estos valores son inventados)
OPENAI_API_KEY=TU_API_KEY_AQUI
N8N_API_KEY=TU_API_KEY_AQUI
GOOGLE_MAPS_KEY=TU_API_KEY_AQUI

Luego, en el código o en las instrucciones, se hace referencia al nombre de la variable (OPENAI_API_KEY), nunca al valor real. Así, si compartes tu proyecto, compartes el "hueco" pero no la llave.

El .gitignore: el guardián del .env

Cuando respaldas tu proyecto en internet (con GitHub, módulo 07), todo se sube… excepto lo que esté listado en .gitignore. Por eso, la primera línea de tu .gitignore siempre debe ser .env:

# .gitignore — qué NO subir nunca a internet
.env
*.key
tmp/
node_modules/

El archivo CLAUDE.md: el manual que la IA lee siempre

CLAUDE.md es un archivo especial que Claude lee automáticamente cada vez que trabaja en tu proyecto. Es tu forma de darle instrucciones permanentes sin repetirlas en cada mensaje. Piénsalo como el manual de la casa que le dejas a quien cuida tu oficina.

Puedes crearlo tú, o pedirle a Claude que lo genere con el comando /init: él mira tu proyecto y arma un primer borrador que luego ajustas.

Las carpetas especiales: .claude/ y skills/

• .claude/ — una carpeta oculta donde Claude Code guarda su configuración, tus agentes y ajustes del proyecto. Normalmente no la tocas a mano; existe para que la IA "recuerde" cómo trabajar contigo.
• skills/ (dentro de .claude/) — aquí viven las skills, esas instrucciones especializadas que veremos en el módulo 05. Cada skill es una subcarpeta con sus propias indicaciones.

Plantilla óptima (lista para copiar)

Esta es una estructura sana para empezar cualquier proyecto administrativo. Puedes pedirle a Claude: "créame esta estructura de carpetas y archivos vacíos" y pegarle esto:

Mi Oficina IA/
├── CLAUDE.md          ← el manual permanente para la IA
├── .env               ← tus secretos (NUNCA se sube)
├── .gitignore         ← lista lo que no se sube (primera línea: .env)
├── documentos/        ← informes, cartas, propuestas (.html, .md)
├── planillas/         ← datos y hojas de cálculo (.csv, .xlsx)
├── scripts/           ← automatizaciones que la IA escriba (.py, .ps1)
└── tmp/               ← borradores y temporales (se limpia seguido)

Crea la siguiente estructura en esta carpeta:
- Un CLAUDE.md con los datos de mi negocio: soy [rubro] en
  [ciudad], me dedico a [qué haces]. Responde siempre en
  español de Chile, tono cercano y profesional.
- Un .gitignore cuya primera línea sea .env
- Un .env vacío con un comentario que diga dónde van las claves
- Las subcarpetas: documentos, planillas, scripts, tmp

Créalo en ese orden y explícame para qué sirve cada cosa.

El orden de creación (y por qué ese orden y no otro)

1. Primero la carpeta raíz Es el "contenedor" de todo. En VS Code: Archivo → Abrir carpeta. Sin raíz, no hay dónde poner lo demás. Además, la terminal y Claude "se paran" dentro de esta carpeta: es su punto de referencia.
2. Luego el CLAUDE.md Se crea temprano porque es lo primero que la IA lee. Si ya está desde el inicio, todo lo que Claude haga después respetará tus reglas. Crearlo al final sería como escribir el manual cuando la obra ya está construida.
3. Enseguida .env + .gitignore (juntos) Antes de manejar cualquier secreto, deben existir el lugar seguro (.env) y su guardián (.gitignore). Nunca al revés: si guardas un secreto antes de tener el .gitignore, corres el riesgo de subirlo por error.
4. Después las subcarpetas por tipo documentos/, planillas/, scripts/, tmp/. Separar por tipo de contenido le da a la IA un mapa claro de dónde va cada resultado. Créalas antes de empezar a trabajar, no cuando ya tengas archivos sueltos que reordenar.
5. Recién ahí tu primer archivo de trabajo Con la casa ordenada, pides tu primera tarea real y el resultado cae en la carpeta correcta desde el minuto uno. Orden primero, trabajo después.

Lo que te llevas de este módulo

• Un proyecto ordenado hace que la IA cometa menos errores y trabaje más rápido.
• Cada extensión tiene su rol: .md notas, .env secretos, .html páginas, .json datos, .py/.ps1 scripts, .gitignore el guardián.
• Los secretos van solo en .env, protegido por .gitignore. Nunca en el código.
• El CLAUDE.md es el manual permanente; se crea temprano. El orden de creación va de lo general a lo particular, seguridad antes que datos.