OpenAI Codex CLI × TypeScript開発ガイド｜型安全なコード生成からリファクタリングまで

「TypeScriptの型定義を書くのに時間がかかりすぎる」「APIレスポンスの型を手動で書くのが面倒」「既存のJavaScriptコードをTypeScriptに移行したいが工数が読めない」——TypeScript開発におけるこれらの悩みは、多くのエンジニアに共通するものです。

OpenAI Codex CLIを使えば、TypeScriptの型定義生成・型安全なコードへのリファクタリング・APIスキーマからの型自動生成まで、一連の開発作業を大幅に効率化できます。本記事では、現場で即使える実践テクニックをプロンプト例付きで解説します。

Codex CLIがTypeScript開発に強い理由

OpenAI Codex CLIは、ファイルシステムへのアクセスとコマンド実行権限を持つため、TypeScriptプロジェクト全体を把握した上でコードを生成・修正できます。単なるコード補完ツールとは異なり、tsconfig.jsonの設定やnode_modulesの型定義も参照しながら最適なコードを提案します。

TypeScript開発での主な活用シーン

活用シーン	Codex CLIの強み	手動作業との比較
型定義の生成	APIレスポンスから自動推論	手動で数十〜数百行
ジェネリクスの実装	型パラメータを適切に制約	試行錯誤が多い
JS→TS移行	ファイル単位で自動変換	1ファイル数十分
Zodスキーマ	型と同時にバリデーション生成	二重定義が発生しがち
テスト型定義	モック・スタブの型も自動	手動で型合わせ

---

プロジェクト設定の最適化

Codex CLIを最大限活用するために、まずプロジェクトの基盤を整えましょう。

AGENTS.mdでTypeScriptルールを定義

Codex CLIはAGENTS.md（またはプロジェクトルートの設定ファイル）を読み込んで動作を調整します。TypeScriptプロジェクト向けに以下の設定を記述しましょう。

# TypeScript開発ルール

## 基本方針
- strict: true を前提としたコードを書く
- any型は原則禁止（unknown + 型ガードで対応）
- as による型アサーションは最小限に
- satisfies演算子を積極的に使う

## 命名規則
- 型/インターフェース: PascalCase（例: UserProfile）
- 型パラメータ: T, K, V（または意味のある名前 TItem, KKey）
- Enum: PascalCase + PascalCaseメンバー

## インポート
- type-only importを使う（import type { Foo } from ...）
- barrel exportは使わない（パフォーマンスに悪影響）

tsconfig.jsonの推奨設定

プロンプト: 2026年のベストプラクティスに基づいた
Next.js 15プロジェクト用のtsconfig.jsonを生成してください。
strictモードに加えて、追加の型安全オプションも含めてください。

Codex CLIが生成する推奨設定：

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "forceConsistentCasingInFileNames": true,
    "verbatimModuleSyntax": true,
    "moduleResolution": "bundler",
    "module": "esnext",
    "target": "es2022",
    "lib": ["dom", "dom.iterable", "esnext"],
    "jsx": "preserve",
    "incremental": true,
    "skipLibCheck": true
  }
}

---

型定義の自動生成テクニック

APIレスポンスからの型生成

実際のAPIレスポンスJSONから、TypeScript型定義を自動生成するのはCodex CLIの得意分野です。

プロンプト: 以下のAPIレスポンスJSONからTypeScript型定義を生成してください。
- ネストしたオブジェクトは個別のインターフェースに分離
- nullableフィールドはオプショナルではなく null ユニオンで表現
- 日付文字列はブランド型で定義
- コメントで各フィールドの意味を記述

Codex CLIの出力例：

/** ISO 8601日付文字列のブランド型 */
type DateString = string & { readonly __brand: 'DateString' };

/** SES案件のAPI応答型 */
interface SesProject {
  /** 案件ID */
  id: string;
  /** 案件タイトル */
  title: string;
  /** 月額単価（万円） */
  unitPrice: number;
  /** 案件の詳細説明 */
  description: string | null;
  /** 必須スキル一覧 */
  requiredSkills: Skill[];
  /** 勤務地情報 */
  location: Location;
  /** 案件開始日 */
  startDate: DateString;
  /** 作成日時 */
  createdAt: DateString;
}

interface Skill {
  /** スキルID */
  id: string;
  /** スキル名 */
  name: string;
  /** 必要経験年数 */
  requiredYears: number;
  /** 必須/歓迎 */
  level: 'required' | 'preferred';
}

interface Location {
  /** 都道府県 */
  prefecture: string;
  /** 最寄り駅 */
  nearestStation: string | null;
  /** リモートワーク可否 */
  remotePolicy: 'full' | 'partial' | 'none';
}

OpenAPIスキーマからの一括型生成

プロンプト: このOpenAPI 3.0仕様書から、
全エンドポイントのリクエスト/レスポンス型を生成してください。
zodスキーマも同時に生成し、ランタイムバリデーションも対応してください。

Codex CLIはOpenAPIのスキーマ定義を読み込み、TypeScript型とZodスキーマを同時に生成できます。これにより「型定義とバリデーションの二重管理」問題が解消されます。

---

ジェネリクスとユーティリティ型の活用

実践的なジェネリクスの実装

TypeScriptのジェネリクスは強力ですが、複雑になりがちです。Codex CLIを使えば、型パラメータの制約を適切に設定したコードが得られます。

プロンプト: ページネーション付きAPIレスポンスのジェネリック型を作成してください。
カーソルベースとオフセットベースの両方に対応し、
データ取得関数のジェネリック版も実装してください。

/** ページネーション付きレスポンスの基本型 */
interface PaginatedResponse<T> {
  data: T[];
  pagination: CursorPagination | OffsetPagination;
  total: number;
}

interface CursorPagination {
  type: 'cursor';
  nextCursor: string | null;
  prevCursor: string | null;
}

interface OffsetPagination {
  type: 'offset';
  page: number;
  perPage: number;
  totalPages: number;
}

/** ジェネリックなデータ取得関数 */
async function fetchPaginated<T>(
  endpoint: string,
  params: PaginationParams,
  decoder: (raw: unknown) => T
): Promise<PaginatedResponse<T>> {
  const response = await fetch(
    `${API_BASE}${endpoint}?${new URLSearchParams(
      Object.entries(params).map(([k, v]) => [k, String(v)])
    )}`
  );

  if (!response.ok) {
    throw new ApiError(response.status, await response.text());
  }

  const json: unknown = await response.json();
  // zodスキーマでバリデーション後にデコード
  return paginatedResponseSchema(decoder).parse(json);
}

条件型（Conditional Types）の生成

プロンプト: HTTPメソッドに応じてリクエストボディの型を
切り替える条件型を実装してください。
GETとDELETEはボディなし、POSTとPUTはボディ必須としてください。

type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';

type RequestBody<M extends HttpMethod> =
  M extends 'GET' | 'DELETE'
    ? never
    : M extends 'POST' | 'PUT'
      ? Record<string, unknown>
      : never;

type RequestConfig<M extends HttpMethod> = {
  method: M;
  url: string;
  headers?: Record<string, string>;
} & (RequestBody<M> extends never
  ? { body?: never }
  : { body: RequestBody<M> });

---

JavaScript → TypeScript移行の自動化

既存のJavaScriptプロジェクトをTypeScriptに移行するのは、Codex CLIが最も威力を発揮するシーンの一つです。

段階的な移行戦略

プロンプト: src/utils/api-client.js をTypeScriptに変換してください。
- any型は使わず、適切な型定義を推論して付与
- 既存の動作を変えない
- JSDocコメントがあればそれを型情報のヒントとして使用

Codex CLIはJSDocの型アノテーション（@param, @returnsなど）を読み取り、TypeScriptの型定義に変換できます。JSDocで型情報が記述されている既存プロジェクトなら、移行の精度が格段に上がります。

---

Zodバリデーション連携

型安全なランタイムバリデーションは、現代のTypeScript開発で欠かせない要素です。

Zodスキーマの自動生成

プロンプト: このTypeScript型定義からZodスキーマを生成してください。
バリデーションルール（メールフォーマット、文字数制限、数値範囲）も追加してください。

import { z } from 'zod';

const skillSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1).max(50),
  requiredYears: z.number().int().min(0).max(30),
  level: z.enum(['required', 'preferred']),
});

const locationSchema = z.object({
  prefecture: z.string().min(1),
  nearestStation: z.string().nullable(),
  remotePolicy: z.enum(['full', 'partial', 'none']),
});

const sesProjectSchema = z.object({
  id: z.string().uuid(),
  title: z.string().min(5).max(200),
  unitPrice: z.number().min(30).max(200),
  description: z.string().max(5000).nullable(),
  requiredSkills: z.array(skillSchema).min(1).max(20),
  location: locationSchema,
  startDate: z.string().datetime(),
  createdAt: z.string().datetime(),
});

// 型の自動推論
type SesProject = z.infer<typeof sesProjectSchema>;

---

tRPC連携で型安全なAPI通信

フルスタックTypeScriptプロジェクトでは、tRPCを使ったエンドツーエンドの型安全性が強力です。

tRPCルーターの自動生成

プロンプト: 案件管理のtRPCルーターを生成してください。
CRUD操作にZodバリデーション、ページネーション、
認証ミドルウェアを含めてください。

import { router, protectedProcedure } from '../trpc';
import { z } from 'zod';

export const projectRouter = router({
  list: protectedProcedure
    .input(z.object({
      cursor: z.string().optional(),
      limit: z.number().min(1).max(100).default(20),
      skill: z.string().optional(),
      remote: z.enum(['full', 'partial', 'none']).optional(),
    }))
    .query(async ({ input, ctx }) => {
      const projects = await ctx.db.project.findMany({
        take: input.limit + 1,
        cursor: input.cursor ? { id: input.cursor } : undefined,
        where: {
          ...(input.skill && { skills: { some: { name: input.skill } } }),
          ...(input.remote && { remotePolicy: input.remote }),
        },
        orderBy: { createdAt: 'desc' },
      });

      let nextCursor: string | undefined;
      if (projects.length > input.limit) {
        const nextItem = projects.pop();
        nextCursor = nextItem?.id;
      }

      return { data: projects, nextCursor };
    }),

  create: protectedProcedure
    .input(sesProjectSchema.omit({ id: true, createdAt: true }))
    .mutation(async ({ input, ctx }) => {
      return ctx.db.project.create({ data: input });
    }),
});

---

SES案件でのTypeScript需要

TypeScriptはSES市場で最も需要の高いスキルの一つです。

市場動向

スキルレベル	月額単価目安	Codex CLIの活用度
TS基礎（型定義が書ける）	50〜65万円	★★★ 型生成で生産性UP
TS中級（ジェネリクス活用）	65〜85万円	★★★ 複雑な型設計を支援
TS上級（型パズル・DX設計）	85〜110万円	★★ 設計判断は人が主導

---

まとめ

Codex CLIをTypeScript開発に組み込むことで、型定義の手書き工数を削減しつつ、より堅牢なコードベースを構築できます。SES案件でのTypeScript需要は今後も右肩上がり——Codex CLIで生産性を上げて、高単価案件を確実に獲得しましょう。

関連記事

• OpenAI Codex CLI 使い方入門ガイド
• OpenAI Codex CLI × フロントエンド開発ガイド
• OpenAI Codex CLI プロンプトエンジニアリング
• OpenAI Codex CLI × テスト自動化
• OpenAI Codex CLI × Next.jsフルスタック開発ガイド