novel-jp/learn-ac-iterate

/learn-ac-iterate — イテレーティブな対話（05-02）

1回で完璧を目指さず、段階的に精度を上げるイテレーティブな対話パターンを体験する演習です。

所要時間: 約 60 分 前提: /learn-ac-evaluate（05-01）完了済み スキル対応: AI Collaboration（AI との協働）

---

Step 1: 導入

「1回の指示で完璧なコードを求めるのは非効率です。

プロの開発者が AI と協働する場合、
『骨格 → 詳細追加 → テスト → リファクタ』の 4 段階で進めるのがベストプラクティスです。

各段階で出力を確認し、方向修正をかけることで、
最終的な品質は 1 回指示よりも圧倒的に高くなります。

このスキルでは、4 段階イテレーションを実践し、
1 回指示との品質差を体感します。」

---

Step 2: 学習環境の準備

受講者の作業ディレクトリに learn-workspace/ がなければ作成する:

mkdir -p learn-workspace && cd learn-workspace && git init

git init を実行したとき Reinitialized existing Git repository と表示されても問題ありません。既に初期化済みのディレクトリで再実行しただけです。

ProjSight タスクの開始

演習用タスクを ProjSight に登録し、作業を開始する:

1. list_deliverables(projectId) で紐づけ先の成果物を確認する
2. upsert_task(projectId, title: "05-02 イテレーティブな対話", deliverableId, description) でタスクを作成する
3. start_work(taskId) で作業を開始する（返却される activePhase があれば phaseId に設定）

以降、taskId をメモしておく（Step 5 の完了時に使用する）。

---

Step 3: 4 段階イテレーション実践

お題: 「シンプルな TODO リスト CLI ツール」

以下の 4 Phase を順番に進める。各 Phase で AI に指示を出し、前の Phase の出力を踏まえて次の指示を書く。

Phase 1: 骨格（データ構造とインターフェースだけ）

「TODO リスト CLI ツールのデータ構造とインターフェース（関数シグネチャ）だけを定義してください。
実装は空でかまいません。」

• 出力を learn-workspace/todo-cli.ts に保存

確認ポイント — 以下の観点でレビューする:

| チェック観点 | 確認すること | | -------------------------- | ------------------------------------------------------------------------------------------ | | ID の型 | number か string（UUID）か？ — 複数デバイスでの衝突リスクを考慮すると string が安全 | | 必須フィールドの過不足 | id, title, completed, createdAt は最低限必要。不要なフィールドが混入していないか | | 関数シグネチャの網羅性 | CRUD（追加・一覧・完了・削除）が揃っているか | | 永続化方式 | Phase 2 で JSON ファイル保存を指示するが、インターフェースが特定の永続化に依存していないか |

受講者に「この構造で良いか？上の観点で気になる点はあるか？」を確認する。必要に応じて方向修正を指示する。

方向修正の具体例: もし AI が id: number（連番）で定義した場合、「UUID（string）の方が衝突しにくく拡張性が高いので id: string に変更してください」と指示する。これがイテレーションの核心 — 問題を早期に発見し、次の Phase に進む前に修正する。

Phase 1 完了後、変更をコミットする:

cd learn-workspace && git add . && git commit -m "Phase 1: データ構造とインターフェース定義"

Phase 2: 詳細追加（各関数の実装）

「Phase 1 で定義した各関数を実装してください。
データの永続化はファイル（JSON）で行ってください。」

設計通りに実装されたか確認する方法:

cd learn-workspace && git diff HEAD

このコマンドで Phase 1 からの差分が表示される。以下の観点で確認する:

| チェック観点 | 確認すること | | ------------------------ | ------------------------------------------------------------ | | 関数シグネチャの一致 | Phase 1 で定義したインターフェースが変更されていないか | | 永続化の実装 | JSON ファイルの読み書きが正しく行われているか | | エッジケース | ファイルが存在しない初回起動時の処理があるか | | 副作用 | Phase 1 になかった関数やフィールドが勝手に追加されていないか |

受講者に「diff を見て、想定と違う部分はあるか？」を確認する。

Phase 2 完了後、変更をコミットする:

cd learn-workspace && git add . && git commit -m "Phase 2: 各関数の実装（JSON永続化）"

Phase 3: テスト追加

「Phase 2 の実装に対するユニットテストを追加してください。
正常系・異常系・境界値をカバーしてください。」

• テストを learn-workspace/todo-cli.test.ts に保存

テストを実行して結果を確認する:

cd learn-workspace && npx tsx --test todo-cli.test.ts

tsx がインストールされていない場合は npx tsx --test で自動ダウンロードされる。Node.js 組み込みのテストランナー（node:test）を使用する。

• テストがすべて通ることを確認する
• テストの網羅性を確認（正常系・異常系・境界値がカバーされているか）
• 受講者に「テストで足りない観点はあるか？」を確認

Phase 3 完了後、変更をコミットする:

cd learn-workspace && git add . && git commit -m "Phase 3: ユニットテスト追加"

Phase 4: リファクタ（エラーハンドリング、型安全性）

「Phase 2-3 のコードをリファクタリングしてください。
エラーハンドリングの強化、型安全性の向上、コードの整理を行ってください。」

• 最終的なコード品質を評価
• テストを再実行して、リファクタで既存テストが壊れていないことを確認する:

cd learn-workspace && npx tsx --test todo-cli.test.ts

Phase 4 完了後、変更をコミットする:

cd learn-workspace && git add . && git commit -m "Phase 4: リファクタリング（エラーハンドリング・型安全性強化）"

---

Step 4: 1 回指示との比較

同じお題を 1 行の指示 で生成させる:

「TODO リスト CLI ツールを作ってください。」

生成されたコードを learn-workspace/todo-cli-oneliner.ts に保存し、4 段階の結果と比較する。

以下のテーブルを自分で埋めてみてください。 各観点で 4 段階イテレーションと 1 回指示の結果を比較し、気づいたことを記入する:

| 比較観点 | 4 段階イテレーション | 1 回指示 | | ---------------------- | -------------------- | -------- | | データ構造の設計 | | | | エラーハンドリング | | | | テスト | | | | 型安全性 | | | | 方向修正の余地 | | |

受講者にテーブルを埋めてもらった後、「どちらの品質が高いか？なぜそう言えるか？」を考えてもらう。

ヒント: 「テストがあるかないか」だけでなく、「設計段階で自分が意図を確認できたか」「途中で軌道修正できたか」にも注目する。

---

Step 5: 振り返り

「イテレーティブな対話の利点は明確です:

- 途中で方向修正できる — 最終形まで走ってから直すより遥かに効率的
- 各段階の品質を確認できる — 問題を早期に発見・修正できる
- AI の出力を理解しながら進められる — ブラックボックスにならない
- 変更履歴が残る — git log で設計の意図を追跡できる

4 段階テンプレート:
1. 骨格（構造とインターフェース）
2. 詳細（実装）
3. テスト（検証）
4. リファクタ（品質向上）

次にタスクを始めるとき、Phase 1（骨格）から試してみましょう。
最初は面倒に感じても、Phase 2 以降で手戻りが大幅に減ることを実感できるはずです。

次の /learn-ac-debug では、AI と一緒にデバッグする方法を学びます。」

受講者のタスクを complete_work(taskId) で完了にする。