Tutorial 2 How the Code Works fr

Tutoriel 2 · Comment fonctionne le code

Objectif : comprendre la poignée de choix de conception qui rendent ce projet facile — et sûr — à modifier avec un agent IA. Vous n'avez pas besoin de mémoriser le code ; vous avez besoin du modèle mental, pour pouvoir diriger l'agent avec précision.

← Précédent : Tutoriel 1 Orientation · Suivant : Tutoriel 3 Votre première tâche avec l'agent

---

La carte

lockedin-cli/
├── bin/lockedin.js      # point d'entrée — la SEULE partie qui fait des E/S
├── src/lockedin.js      # le cœur — des fonctions pures qui renvoient des chaînes
├── test/
│   ├── unit.test.js     # teste directement les fonctions du cœur
│   └── cli.test.js      # lance le vrai binaire et vérifie sa sortie
├── tools/screenshot.js  # génère les SVG que vous voyez dans docs/
└── package.json         # métadonnées + le script `npm test`

Quatre idées le font fonctionner. Apprenez-les et vous pourrez demander à l'agent presque n'importe quel changement en toute confiance.

Idée 1 — Un cœur pur qui renvoie des chaînes

Ouvrez src/lockedin.js. Remarquez que les fonctions de rendu n'impriment pas — elles renvoient des chaînes :

function renderConnect() {
  const names = shuffle(NAMES).slice(0, 6);
  // ...construit un tableau de lignes...
  return out.join('\n');   // renvoie du texte ; n'imprime rien
}

Toute l'impression réelle (et la lecture de vos frappes) se fait dans bin/lockedin.js. Cette séparation « le cœur renvoie des données, la bordure fait les E/S » est la chose la plus importante ici, car une fonction qui se contente de renvoyer une chaîne est triviale à tester :

const out = app.renderConnect();
assert.ok(out.includes("« J’aimerais vous ajouter à mon réseau professionnel. » — envoyé à "));

Pas de terminal à simuler, pas de stdout à capturer. Quand vous demandez à l'agent d'ajouter une fonctionnalité, c'est pourquoi il peut aussi lui ajouter un test rapide et fiable.

Idée 2 — Les pools de contenu

Les blagues vivent dans de simples tableaux près du haut de src/lockedin.js :

const HOOKS = [ 'Opinion impopulaire :', 'Laissez ça infuser.', /* ...~25 au total... */ ];
const LESSONS = [ '→ Votre réseau, c’est votre valeur nette.', /* ... */ ];

Les générateurs puisent dans ces pools. Dans v1.2.0, chaque pool est passé à ~25 variations, et une deuxième couche de pools de gabarits a été ajoutée (des choses comme POST_REVEALS et REFLECT_TAGSETS) pour que la structure de chaque sortie varie, pas seulement les mots. Ajouter du contenu est souvent aussi simple qu'ajouter des chaînes à un tableau — une première tâche parfaite à confier à un agent.

Idée 3 — Aléatoire à graine = tests déterministes

Une sortie aléatoire et des tests automatisés semblent incompatibles. Ce projet résout la quadrature du cercle avec un générateur de nombres aléatoires initialisable par graine :

setSeed(42);
const a = generatePost();
setSeed(42);
const b = generatePost();
// a === b  → même graine, même post

Chaque choix aléatoire passe par les helpers partagés pick() / shuffle(), qui tirent de ce générateur à graine. Définissez LOCKEDIN_SEED=42 et la CLI est entièrement reproductible. La règle d'or pour tout changement : tout nouvel aléatoire doit utiliser pick / shuffle, jamais Math.random directement — sinon le déterminisme (et les tests) se cassent. Gardez cela sous le coude ; vous le rappellerez à l'agent au Chapitre 3.

Idée 4 — Deux couches de tests

• test/unit.test.js appelle les fonctions du cœur et fait des assertions sur les chaînes qu'elles renvoient (rapide, précis).
• test/cli.test.js lance réellement bin/lockedin.js et vérifie son vrai stdout et son code de sortie (prouve que l'ensemble fonctionne de bout en bout).

Ensemble, elles forment la barrière. Elles encodent aussi des invariants — des promesses que fait l'appli. Par exemple, un post s'ouvre toujours sur un hook connu et contient toujours au moins trois leçons → ; l'écran « connect » affiche toujours incalculable. Quand un agent modifie le code, ces tests attrapent tout ce qui a rompu une promesse en silence.

---

Pourquoi cela compte pour travailler avec un agent

Réunissez les quatre idées et vous obtenez un code où un agent peut :

1. Ajouter une fonctionnalité sous forme de fonction pure qui renvoie une chaîne,
2. Ajouter un test pour elle sans aucune gymnastique d'E/S,
3. Garder la sortie reproductible via le RNG à graine, et
4. Prouver qu'il n'a rien cassé en lançant la barrière existante.

C'est la boucle que vous exécuterez au prochain chapitre.

✅ Essayez avec votre agent

Demandez à votre agent de vérifier votre compréhension — en lisant, pas en éditant :

1. « Liste chaque pool de contenu dans src/lockedin.js et combien d'entrées chacun contient. »
2. « Montre-moi un invariant que test/unit.test.js impose sur generatePost, et explique ce qui le casserait. »
3. « Où le RNG à graine est-il défini, et quelles fonctions doivent l'utiliser au lieu de Math.random ? Ne change rien — explique seulement. »

Quand les réponses de l'agent correspondent à ce chapitre, vous êtes prêt·e à construire.

Suivant : Tutoriel 3 Votre première tâche avec l'agent