Tutorial 2 How the Code Works es

Tutorial 2 · Cómo funciona el código

Meta: entender el puñado de decisiones de diseño que hacen que este proyecto sea fácil — y seguro — de cambiar con un agente de IA. No necesitas memorizar el código; necesitas el modelo mental, para poder dirigir al agente con precisión.

← Anterior: Tutorial 1 Orientación · Siguiente: Tutorial 3 Tu primera tarea con el agente

---

El mapa

lockedin-cli/
├── bin/lockedin.js      # punto de entrada — la ÚNICA parte que hace E/S
├── src/lockedin.js      # el núcleo — funciones puras que devuelven strings
├── test/
│   ├── unit.test.js     # prueba las funciones del núcleo directamente
│   └── cli.test.js      # lanza el binario real y revisa su salida
├── tools/screenshot.js  # genera los SVG que ves en docs/
└── package.json         # metadatos + el script `npm test`

Cuatro ideas lo hacen funcionar. Apréndelas y podrás pedirle al agente casi cualquier cambio con confianza.

Idea 1 — Un núcleo puro que devuelve strings

Abre src/lockedin.js. Nota que las funciones de render no imprimen — devuelven strings:

function renderConnect() {
  const names = shuffle(NAMES).slice(0, 6);
  // ...arma un arreglo de líneas...
  return out.join('\n');   // devuelve texto; no imprime nada
}

Toda la impresión real (y la lectura de tus teclas) ocurre en bin/lockedin.js. Esta separación “el núcleo devuelve datos, el borde hace E/S” es lo más importante aquí, porque una función que solo devuelve un string es trivial de probar:

const out = app.renderConnect();
assert.ok(out.includes("“Me encantaría añadirte a mi red profesional.” — enviado a "));

Sin simular una terminal, sin capturar stdout. Cuando le pides al agente que agregue una función, por esto también puede agregarle una prueba rápida y fiable.

Idea 2 — Pools de contenido

Los chistes viven en arreglos simples cerca del principio de src/lockedin.js:

const HOOKS = [
  'Opinión impopular:', 'Deja que eso cale hondo.', /* ...~25 en total... */
];
const LESSONS = [ '→ Tu red es tu patrimonio neto.', /* ... */ ];

Los generadores eligen elementos de estos pools. En v1.2.0, cada pool creció hasta ~25 variaciones y se añadió una segunda capa de pools de plantillas (como POST_REVEALS y REFLECT_TAGSETS) para que varíe la estructura de cada salida, no solo las palabras. Agregar contenido suele ser tan simple como añadir strings a un arreglo: una primera tarea perfecta para un agente.

Idea 3 — Aleatoriedad con semilla = pruebas deterministas

Salida aleatoria y pruebas automatizadas suenan incompatibles. Este proyecto resuelve el dilema con un generador de números aleatorios con semilla:

setSeed(42);
const a = generatePost();
setSeed(42);
const b = generatePost();
// a === b  → misma semilla, misma publicación

Cada elección aleatoria pasa por los helpers compartidos pick() / shuffle(), que toman de ese generador con semilla. Con LOCKEDIN_SEED=42 la CLI es totalmente reproducible. La regla de oro para cualquier cambio: la nueva aleatoriedad debe usar pick / shuffle, nunca Math.random directamente — o el determinismo (y las pruebas) se rompen. Guarda esto para el Capítulo 3.

Idea 4 — Dos capas de pruebas

• test/unit.test.js llama funciones del núcleo y verifica los strings que devuelven (rápido, preciso).
• test/cli.test.js de verdad lanza bin/lockedin.js y revisa su stdout y su código de salida (prueba que todo funciona de extremo a extremo).

Juntas son la barrera. También codifican invariantes — promesas que la app hace. Por ejemplo, una publicación siempre abre con un gancho conocido y contiene al menos tres viñetas →; la pantalla de “connect” siempre dice incalculable. Cuando un agente cambia código, estas pruebas atrapan cualquier promesa que se haya roto en silencio.

---

Por qué esto importa al trabajar con un agente

Junta las ideas y obtienes un código donde un agente puede:

1. Agregar una función como función pura que devuelve un string,
2. Agregar una prueba sin gimnasia de E/S,
3. Mantener la salida reproducible vía el RNG con semilla, y
4. Probar que no rompió nada corriendo la barrera existente.

Ese es el ciclo que correrás en el próximo capítulo.

✅ Pruébalo con tu agente

Pídele al agente que verifique tu comprensión — leyendo, no editando:

1. “Lista cada pool de contenido de la versión en inglés y cuántas entradas tiene cada uno.”
2. “Muéstrame una invariante que test/unit.test.js impone sobre generatePost y explica qué la rompería.”
3. “¿Dónde está definido el RNG con semilla y qué funciones deben usarlo en vez de Math.random? No cambies nada — solo explícalo.”

Cuando las respuestas del agente coincidan con este capítulo, estás list@ para construir.

Siguiente: Tutorial 3 Tu primera tarea con el agente