GPT Codex を使って TypeScript 型パズルゲームを作ってみた
作ったもの
今回は、TypeScript の型を学べるパズル形式の Web アプリを作成しました。クイズ形式で型定義の正解を導き出すことで、型への理解を深めることができます。
使用した技術スタックは、Next.js、Monaco Editor、TypeScript、ESLint に加えて、GPT Codex（ChatGPT Pro）と Cursor です。実装は主に Codex に支援してもらいながら、プロジェクトの初期設計から UI 実装、型ロジックの確認までを進めました。
実際の画面は、Monaco Editor を使ってエディタ上で型を記述し、正しい型に修正できれば「正解」になるという構成です。
GitHub
後述する AGENTS.md は Codex 活用において非常に重要な情報です。上記リポジトリ内の
AGENTS.mdをぜひ参考にしてください。
アプリを作った背景
React や Next.js を用いた開発では、型の修正や補完に時間を取られることが多く、「本当にこの型で合っているのか？」と不安になる場面がよくあります。
特に TypeScript の経験が浅い場合や、複雑なジェネリクスや条件付き型を使っている場面では、any に逃げたくなる誘惑に駆られることもしばしばあります。そういった「よくない妥協」を減らすために、自分自身の学習も兼ねて、型に特化したパズルゲームを作ってみようと思ったのがこのプロジェクトの発端です。
実際のところ、実装のほとんどは GPT Codex に助けられながら進めていますが、「自分専用の教材を作る」という意味でも非常に意義のある体験になりました。
Codex を使ってよかったこと
Codex を使ってみて特に驚いたのは、「テストコードを作って」と依頼するだけで、プロジェクト内のコード構造を理解した上で、適切なユニットテストを素早く生成してくれる点です。
また、複数の開発タスクを並行して進められるのが大きな魅力でした。GitHub Issue にタスクを登録しておけば、必要な内容をチャットで Codex に投げるだけで、PRの作成まで自動的に進めてくれます。生成完了時には通知が届き、あとはレビューするだけという流れが実現できます。
※iPhoneに ChatGPT アプリを入れておくと、生成中の進行状況や完了通知も受け取れて非常に便利です。
つまずいた点・難しかったこと
主な課題
- Codex では
npm installやnpxが実行できない - ESLint や vitest の設定は生成できるが、実行はできない
- CI 環境との連携は Codex 単体では難しい
Codex では npm install や npx が実行できない
Codex の実行環境はインターネットに接続されておらず、パッケージの取得や外部コマンドの実行はできません。最初はこれを知らず、依存解決に失敗して原因調査に時間を取られました。
ESLint や vitest の設定は生成できるが、実行はできない
Codex は .eslintrc.js や vitest.config.ts といった設定ファイルの生成には対応していますが、eslint . や vitest run といった実行までは行えません。テストや Lint を「書く」ことは得意でも、「通るかどうかの検証」は開発者が行う必要があります。
CI 環境との連携は Codex 単体では難しい
GitHub Actions などの CI 設定も Codex によって生成できますが、動作確認やトラブル対応などはすべて手動で行う必要があります。Codex を完全に任せるのではなく、あくまで補助として使うのが現実的です。
AGENTS.md が果たす役割
こうした制約をふまえて、Codex に「何ができて何ができないのか」を明示的に伝えることが非常に重要だと感じました。特に、npm install や vitest run のようなコマンドは実行できない一方で、設定ファイルの生成やコードのリファクタには強いという特性があります。
そこで私は、Codex 向けに「どこまでを任せてよいのか」を明文化した AGENTS.md をプロジェクトルートに配置しました。
このファイルには、以下のようなガイドラインを記載しています：
- Codex は
npm installやnpxを実行しないこと - テストやビルドは「構成ファイルの出力」までに留めること
- ESLint のルール（例:
no-unused-vars,no-explicit-any）を遵守すること - PR のタイトル形式やコミットメッセージのルールを守ること
このように「Codex に任せる範囲」を明文化することで、出力コードの品質を安定させることができ、PRのレビューや統合もスムーズに進められるようになりました。
特に複数の開発タスクを Codex に並行して割り振る場合、AGENTS.md によって「文脈を持たないCodex」でも一貫性のある成果物を出してくれるというメリットが得られます。
Codex を活用する場合は、コードだけでなく「Codexに与えるドキュメント」も同じくらい重要です。
結論と今後の展望
Codex はコード生成や設計支援において非常に優れており、特に GitHub 上のプロジェクト構成がある程度整っている状態では、非常に強力なツールになります。
ただし初期フェーズ、特に以下のような状況では人間の介入が不可欠です：
- プロジェクトの 0→1 の環境構築
- CI の統合や本番向けのチューニング
- ランタイムの検証やパッケージの整合性確認
したがって、アイディアをすぐに形にしたい場合は、テンプレートプロジェクトを先に用意し、その上に Codex を導入するスタイルが現時点では最も効率的です。
今後は Codex をさらに活用して、レビューアシスタントのような存在として機能させたり、設定ファイルの整備、PR テンプレートの自動化など、開発体験そのものの向上につなげていきたいと考えています。
Discussion