3. Proyecto base
Construye la base del proyecto
Construye la práctica mínima, ubica sus archivos y distingue código, dependencias y control de versiones.
Qué aprenderás
- Crear una práctica sin depender de un repositorio público.
- Entender los scripts de desarrollo y compilación.
- Localizar entrada, acción y selección del modelo.
- Distinguir archivos versionados, dependencias y configuración local.
- Reservar una carpeta para los próximos patrones.
Índice de esta lección
Paso 1
Define el proyecto y sus scripts
Crea package.json dentro de tu carpeta de práctica y copia este contenido. Después ejecuta npm install en la terminal. Hemos conservado las versiones declaradas por la base de estudio y reducido los proveedores al que usaremos.
dev ejecuta src/main.ts una vez con tsx. watch vuelve a ejecutarlo al cambiar archivos. build compila con TypeScript y start ejecuta la salida de dist. El proyecto del curso tiene más adaptadores; esta práctica solo necesita ai y @ai-sdk/groq.
{ "name": "agentic-patterns-practica", "private": true, "type": "module", "scripts": { "build": "tsc", "start": "node --env-file=.env dist/main.js", "dev": "tsx --env-file=.env src/main.ts", "watch": "tsx watch --env-file=.env src/main.ts" }, "dependencies": { "ai": "7.0.59", "@ai-sdk/groq": "4.0.27" }, "devDependencies": { "@types/node": "26.2.0", "tsx": "4.23.12", "typescript": "7.0.2" }}Qué deberías observar
npm install instala las dependencias. Aún no ejecutes dev: primero falta crear los archivos de las próximas lecciones.
Paso 2
Configura cómo se compila TypeScript
Crea tsconfig.json junto a package.json. src contiene los archivos que editas y dist recibe el JavaScript compilado.
La base usa módulos ESM con type: module y resolución Node16. Por eso los imports internos escritos en TypeScript terminan en .js: apuntan a la forma que tendrán los archivos al compilar.
Declaramos types: ["node"] para que TypeScript reconozca los globales de Node.js, como process, usados en el manejo de errores.
{ "compilerOptions": { "target": "ES2022", "module": "Node16", "moduleResolution": "Node16", "rootDir": "src", "outDir": "dist", "strict": true, "skipLibCheck": true, "types": [ "node" ] }, "include": [ "src/**/*.ts" ]}Qué deberías observar
La configuración incluye src/**/*.ts, activa strict y define dist como salida.
Paso 3
Dibuja el recorrido antes de ejecutar
Crea las carpetas src/actions y src/helpers. Las siguientes lecciones aportan el contenido de cada archivo; este mapa muestra cómo se conectan.
main.ts decide qué práctica ejecutar. La acción hace la llamada. selected-model.ts concentra el proveedor elegido para poder cambiarlo sin editar cada acción.
agentic-patterns-practica/├── package.json├── tsconfig.json├── .env└── src/ ├── main.ts ├── actions/get-message-model.ts └── helpers/selected-model.ts main.ts → acción → modelo → proveedorQué deberías observar
Puedes ubicar dónde cambiar la práctica y dónde cambiar el proveedor.
Paso 4
Reconoce las ayudas del proyecto de estudio
La base disponible también incluye helpers/index.ts para reexportar utilidades, string-colors.ts para colorear la consola y create-tracer.ts para observar pasos.
Los colores son presentación. Una traza registra lo que la ejecución expone; no es una prueba de corrección ni una ventana completa al razonamiento del modelo. En esta práctica utilizaremos console.log normal para mantener los ejemplos independientes.
helpers/index.ts → reexporta utilidadeshelpers/string-colors.ts → presentación en consolahelpers/create-tracer.ts → observación de pasosactions/get-message-model.ts → llamada, traza y erroresQué deberías observar
Distingues las piezas necesarias para conectar un modelo de las ayudas para estudiar su ejecución.
Paso 5
Ubica configuración, dependencias y documentación
package.json declara scripts y dependencias. package-lock.json registra las versiones resueltas: en esta práctica lo conservamos para reproducir la instalación. node_modules contiene los paquetes instalados y dist la salida de build; no son las carpetas donde escribes los ejercicios.
README.md explica cómo arrancar. .env contiene la configuración local; .env.example es la plantilla pública vacía. La base original llama a esa plantilla .env.template: identifica cuál existe antes de copiarla, sin sobrescribir tu .env.
La carpeta opcional .agents/skills guarda instrucciones para asistentes de programación. skills-lock.json registra información de las skills instaladas. Estas ayudas no se ejecutan como parte de la llamada al modelo y no son necesarias para completar la práctica mínima.
package.json → scripts y dependenciaspackage-lock.json → versiones resueltasnode_modules/ → dependencias instaladastsconfig.json → compilación y tipadoREADME.md → instrucciones de uso.env → configuración local.env.example → plantilla pública vacía.gitignore → archivos que Git debe ignorar.agents/skills/ → ayuda opcional para asistentesskills-lock.json → registro de skillssrc/ → código que editasdist/ → resultado de compilarQué deberías observar
Puedes explicar qué se edita, qué se genera y qué archivo sirve de plantilla sin confundirlo con la credencial real.
Paso 6
Entiende qué guarda Git y dónde está el repositorio
Una carpeta de apuntes puede existir sin ser un repositorio. .git contiene el historial y la configuración de Git y normalmente está oculto en Finder. .gitignore es un archivo de reglas; su presencia no crea un repositorio ni significa que todo esté publicado.
Comprueba desde tu carpeta si Git encuentra una raíz y un remoto. Si la práctica viene de un repositorio anidado, estos comandos pueden mostrar esa raíz y su origen, que no tienen por qué coincidir con el repositorio de la tutoría.
El repositorio del curso es My-free-time/patrones-diseno-agentico. Sus apuntes y su práctica acompañan tutorials/patrones-diseno-agentico.json, el archivo que consume el portafolio. Añadir un Markdown no modifica automáticamente las lecciones: hay que adaptar el JSON y publicar ese cambio.
git rev-parse --show-toplevelgit status --shortgit remote -vQué deberías observar
Identificas la raíz y el remoto reales. Si Git responde que no hay repositorio, sabes que esa carpeta aún es solo un directorio local.
Paso 7
Reserva el espacio para los próximos patrones
La base incluye src/patterns/.gitkeep. Git versiona archivos; .gitkeep es un nombre convencional para conservar una carpeta inicialmente vacía, no una instrucción especial de Git.
Cada patrón tendrá su propio subdirectorio en src/patterns. main.ts seleccionará la práctica que quieras ejecutar y selected-model.ts seguirá concentrando el proveedor. Esta sección prepara la estructura; aún no implementa Tool Use ni ReAct.
Las tres acciones de conexión tienen objetivos diferentes: getMessageFromModel comprueba la llamada, getMessageFromModelWithTrace añade observación y getMessageFromModelFailSafe orienta el diagnóstico. El helper de colores solo cambia la presentación en consola.
src/├── main.ts├── actions/│ └── get-message-model.ts├── helpers/│ ├── selected-model.ts│ ├── string-colors.ts│ ├── create-tracer.ts│ └── index.ts└── patterns/ └── .gitkeep main → práctica elegida → modelo compartido → proveedorQué deberías observar
Sabes dónde colocar futuros patrones y distingues la prueba básica, la traza y el diagnóstico.
Ahora te toca
Prueba la idea por tu cuenta
Explica dónde harías cada cambio: ejecutar una práctica diferente, elegir otro modelo y ajustar la carpeta de salida.
Necesito una pista
Sigue las responsabilidades del mapa: entrada, proveedor y compilación.
Comparar con una solución
Selecciona la práctica en src/main.ts; cambia el modelo en src/helpers/selected-model.ts; cambia outDir en tsconfig.json. Mantén esos motivos separados.
Antes de seguir
Comprueba lo que aprendiste
No es una nota. Es una pausa para comprobar que la idea quedó clara.
¿Terminaste la práctica?
Haz el ejercicio y comprueba tus respuestas antes de marcar la lección como completada.