Tutorial 2 How the Code Works ja

チュートリアル2 · コードのしくみ

ゴール: このプロジェクトがAIエージェントにとって変更しやすく、そして安全で あるための、いくつかの設計判断を理解すること。コードを暗記する必要はありません。 エージェントに正確な指示を出すための「地図」を頭に入れるのが目的です。

← 前へ: チュートリアル1 オリエンテーション · 次へ: チュートリアル3 はじめてのエージェントタスク

---

全体像

lockedin-cli/
├── bin/lockedin.js      # エントリポイント — 入出力を行う唯一の場所
├── src/lockedin.js      # コア — 文字列を返すだけの純粋関数
├── test/
│   ├── unit.test.js     # コアの関数を直接テストする
│   └── cli.test.js      # 実際のバイナリを起動し、出力を検証する
├── tools/screenshot.js  # docs/ にあるSVGを生成する
└── package.json         # メタデータと `npm test` スクリプト

このプロジェクトを支えているのは4つの考え方です。これさえ押さえれば、 たいていの変更は自信を持ってエージェントに頼めます。

考え方1 — 文字列を返すだけの、純粋なコア

src/lockedin.js を開いてみてください。描画（render）系の関数は 出力しません。文字列を返すだけです。

function renderConnect() {
  const names = shuffle(NAMES).slice(0, 6);
  // ...行の配列を組み立てて...
  return out.join('\n');   // テキストを返す。何も出力しない
}

実際の出力（およびキー入力の読み取り）は、すべて bin/lockedin.js で行われます。 この「コアはデータを返し、端っこがI/Oを担当する」という分離が、ここでいちばん 重要な点です。というのも、文字列を返すだけの関数はテストが非常に簡単だからです。

const out = app.renderConnect();
assert.ok(out.includes("「私のプロのネットワークに加えたいです。」— 送信先："));

ターミナルのモックも、標準出力のキャプチャも要りません。エージェントに機能追加を 頼んだとき、実装と一緒に速くて安定したテストまで書けるのは、この設計のおかげです。

考え方2 — コンテンツプール

ジョークの中身は、src/lockedin.js の先頭付近にある素朴な配列に入っています。

const HOOKS = [ '不人気な意見ですが：', 'この言葉を、心に染み込ませてください。', /* ...全部で約25個... */ ];
const LESSONS = [ '→ あなたの人脈こそが、あなたの純資産。', /* ... */ ];

ジェネレータは、このプールから要素を選びます。v1.2.0 で各プールは約25種類まで 増え、さらにテンプレート用のプール（POST_REVEALS や REFLECT_TAGSETS など） という2層目が追加されました。これにより、言葉だけでなく出力の構造そのものが 変化します。コンテンツの追加は配列に文字列を足すだけで済むことも多く、 エージェントに任せる最初のタスクとして最適です。

考え方3 — シード付きの乱数 = 決定的なテスト

ランダムな出力と自動テストは、一見すると両立しません。このプロジェクトは シードを指定できる乱数生成器でその矛盾を解消しています。

setSeed(42);
const a = generatePost();
setSeed(42);
const b = generatePost();
// a === b  → 同じシードなら、同じ投稿

ランダムな選択はすべて、共有ヘルパーの pick() / shuffle() を経由し、 このシード付き生成器から値を取ります。LOCKEDIN_SEED=42 を設定すれば、 CLIの出力は完全に再現可能になります。変更を加えるときの鉄則は、新しい乱数も 必ず pick / shuffle を使い、Math.random を直接呼ばないこと。 これを破ると決定性が壊れ、テストも落ちます。第3章でエージェントに念を押す場面が あるので、覚えておいてください。

考え方4 — 2層のテスト

• test/unit.test.js はコアの関数を呼び、返ってきた文字列を検証します （速くて、狙いが正確）。
• test/cli.test.js は実際に bin/lockedin.js を起動し、本物の標準出力と 終了コードを確認します（全体が通しで動くことの証明）。

この2つが揃って「ゲート」になります。さらにこれらは、アプリが守ると約束した 不変条件を記録したものでもあります。たとえば、投稿は必ず既知のフックで始まり、 → で始まる教訓を必ず3つ以上含む。connectの画面には必ず incalculable が出る。 エージェントがコードを変更したとき、こっそり壊れた約束をこのテストが捕まえます。

---

これがエージェントとの作業にどう効くのか

4つの考え方を組み合わせると、エージェントは次のように動けます。

1. 文字列を返す純粋関数として、機能を追加する
2. I/Oの小細工なしに、そのテストを追加する
3. シード付き乱数によって、出力を再現可能に保つ
4. 既存のゲートを実行して、何も壊していないことを証明する

次の章では、まさにこのループを回します。

✅ エージェントと試してみよう

理解の確認をエージェントに手伝ってもらいましょう。読むだけで、編集はさせません。

1. 「src/lockedin.js にあるコンテンツプールをすべて列挙し、それぞれ何件 入っているか教えてください。」
2. 「test/unit.test.js が generatePost について強制している不変条件を1つ挙げ、 何をすればそれが壊れるか説明してください。」
3. 「シード付き乱数はどこで定義されていますか？ Math.random の代わりに それを使わなければならない関数はどれですか？ 何も変更せず、説明だけしてください。」

エージェントの答えがこの章の内容と一致したら、作る準備は完了です。

次へ: チュートリアル3 はじめてのエージェントタスク