Claude CodeでGraphQL開発を自動化する——スキーマからリゾルバー・型生成まで

はじめに

REST/GraphQL設計の話でも、TypeScript全般の型安全性の話でもない。「スキーマを書いたらリゾルバーとTypeScript型が自動で揃う」——GraphQL固有の実装ワークフローをClaude Codeで自動化する話だ。

GraphQLはREST APIと比べて型安全性・クエリ柔軟性で優れる一方、開発コストが高い。スキーマ定義 → リゾルバー実装 → TypeScript型生成 → テスト作成の一連の作業は、エンドポイントを一つ追加するたびに繰り返されるボイラープレートだ。さらにスキーマとリゾルバーの型定義がズレると、ビルドは通るが実行時にエラーが出るという厄介な問題も起きる。

Claude Codeにこの一連のフローを組み込めば、スキーマ定義の指示から始まりリゾルバー実装・型自動生成・テスト作成までをワンストップで処理できる。この記事では、そのワークフローをどう設計するかを具体的に見ていく。

CLAUDE.mdでGraphQL規約を定義する——スキーマ設計からN+1防止まで

GraphQL開発でCLAUDE.mdが特に効力を発揮するのは、「チーム固有の設計判断」を一度だけ定義すれば以降は自動的に従ってもらえる点だ。nullable/non-null設計・ページネーション方式・N+1対策——これらは毎回レビューコメントで指摘するより、CLAUDE.mdに書いておく方がずっと効率的だ。

# CLAUDE.md（GraphQL開発ルール）
## GraphQL Development Policy

### スキーマ設計ルール
- nullable/non-nullはスキーマレベルで厳密に定義（リゾルバーで吸収しない）
- ページネーションは必ずCursor-based（Offset-basedは禁止）
- Mutation名は動詞+名詞（例: createUser, updatePost, deleteComment）
- Query名は名詞または getXxx 形式（例: user, posts, getOrder）

### リゾルバー実装ルール
- DataLoaderをデフォルト使用（N+1問題の防止）
- 認証チェックはコンテキストで処理（リゾルバー内でJWT検証しない）
- エラーはGraphQL Error標準形式で返す

### 型安全性ルール
- GraphQL Code Generator必須（自動生成された型でリゾルバーを縛る）
- スキーマ変更時は codegen を実行してから PR を作成
- any型は禁止

### テスト要件
- 各リゾルバーにユニットテスト（モックコンテキスト使用）
- 統合テストはスキーマ全体を対象に

WP-GraphQLという大規模なOSS（github.com/wp-graphql/wp-graphql）がこのアプローチを実践している。CLAUDE.mdにGraphQL規約・ガイドラインを定義することで、Claude Codeに設計哲学を伝える実例として参考になる。ただしWP-GraphQL固有のWordPress実装詳細（プラグイン設定・WP特有の型）ではなく、スキーマ規約・リゾルバー実装ルール・テスト要件の定義部分が参照価値の高い部分だ。

N+1問題については特に注意が必要だ。GraphQLのリゾルバーは各フィールドを個別に解決するため、users クエリで100件のユーザーを返した後、各ユーザーの posts フィールドを解決しようとすると100回のDBクエリが発生する。CLAUDE.mdに「DataLoaderをデフォルト使用・N+1禁止」と明示することで、Claude Codeがリゾルバーを生成するたびにDataLoaderパターンを適用する。コードレビューで毎回「DataLoader使ってないですね」と指摘し続ける必要がなくなる。

GraphQL Code Generator × Claude Code——型安全なリゾルバー自動生成

GraphQL Code Generator（the-guild.dev/graphql/codegen）はThe Guildが提供するGraphQL公式エコシステムのコード生成ツールで、Claude Codeとの組み合わせで最大の効果を発揮する。

主要プラグインの役割は明確だ。typescript プラグインがスキーマから基本型を生成し、typescript-resolvers がリゾルバーに完全な型安全性を付与する。フロントエンド向けには typescript-operations プラグインがGraphQL操作（query/mutation）から型を生成する。特に注目すべきはApollo公式が推奨する「操作ベースの型生成」だ。GraphQLスキーマ全体の型ではなく実際のGraphQL操作から型を生成することで、GraphQLがリクエストしたフィールドのみを返す設計に即した正確な型安全性が保証される。

Claude Codeへの指示パターンはこうなる。

「このGraphQLスキーマに対してリゾルバーを実装して。
要件:
- GraphQL Code Generatorのtypescript-resolversで生成した型を使う
- DataLoaderでN+1を防止（UserのpostsフィールドはbatchUserPostsLoaderで解決）
- 認証はcontextのuserIdで確認
- エラーはApolloError標準形式で返す」

Claude Codeはこの指示からDataLoaderの初期化・バッチ関数の実装・認証チェック・エラーハンドリングを含む型安全なリゾルバーを生成する。生成されたリゾルバーのテストも合わせて依頼できる。

// Claude Codeが生成するリゾルバーテストパターン
describe('UserResolver', () => {
  it('ユーザーを正常に取得できること', async () => {
    const mockContext = { userId: '123', dataloaders: { user: mockUserLoader } };
    const result = await UserResolver.Query.user(null, { id: '123' }, mockContext);
    expect(result).toMatchObject({ id: '123', email: 'test@example.com' });
  });

  it('未認証の場合にエラーを返すこと', async () => {
    const mockContext = { userId: null };
    await expect(
      UserResolver.Query.user(null, { id: '123' }, mockContext)
    ).rejects.toThrow('Unauthorized');
  });
});

CIゲートの設計も重要だ。スキーマを変更した後にcodegenを実行せずにPRを作ると、生成済みの型と実際のスキーマが乖離してしまう。CLAUDE.mdに「スキーマ変更時はcodegenを実行してからPRを作成」と定義し、CIでもcodegenを実行して型ズレがある場合はビルドを失敗させる設計にする。これで「スキーマとリゾルバーの型ズレで本番エラー」を防ぐ自動化ゲートが完成する。

Apollo MCP Server——Claude CodeでGraphQL APIを直接操作する

Apollo MCP Serverを使うと、Apollo GraphQL APIをMCPサーバーとしてDockerコンテナ化してClaude Codeから直接GraphQL操作を実行できる（apollographql.com）。開発中にClaude Codeが「このクエリを実際のAPIで試して結果を確認する」という動作が可能になる。

実際の開発フローでの活用イメージはこうだ。スキーマを追加してリゾルバーを実装した後、Claude Codeが直接APIにクエリを投げて動作確認し、期待通りのレスポンスが返らなければリゾルバーを修正する——というサイクルを人間が介在せずに回せる。

コミュニティ製のGraphQL MCPサーバーも複数存在する。mcp-graphql-schema（github.com/hannesj/mcp-graphql-schema）は既存GraphQL APIのスキーマをClaude Codeに公開してスキーマ探索・理解を支援するツール、mcp-graphql（github.com/blurrah/mcp-graphql）はTypeScript型付きで任意のGraphQL APIにアクセスできるツール、text-to-graphql-mcp（github.com/Arize-ai/text-to-graphql-mcp）は自然言語からGraphQLクエリを自動変換するツールだ。実際に採用する前にメンテナンス状態を確認することを推奨する。

Apollo MCP ServerがなくてもCLAUDE.mdにスキーマを参照させるだけでも効果はある。毎回プロンプトにスキーマを貼り付けるのではなく、mcp-graphql-schemaのようなツールで最新のスキーマを自動的にコンテキストに含める設計にすることで、「古いスキーマを参照した誤ったコード生成」が防ぎやすくなる。

まとめ

GraphQL開発でClaude Codeを最大限活用するための流れは、まずCLAUDE.mdにスキーマ設計規約・DataLoaderデフォルト使用・codegen必須ルールを定義することから始まる。そこを整えれば、Claude Codeへのリゾルバー生成指示がはるかに精度高く機能するようになる。

GraphQL Code GeneratorとCIゲートを組み合わせることで、スキーマ変更が型ズレを引き起こす問題を自動的に防ぐ。Claude Codeがスキーマから型安全なリゾルバーとテストを生成し、CIが型の整合性を保証する——この回路ができるとGraphQL固有のボイラープレートに費やす時間が大幅に減る。

まず一つ試すなら、CLAUDE.mdに「DataLoaderをデフォルト使用・N+1禁止」の一行を追加してからリゾルバー生成を依頼してみてほしい。その一行が、コードレビューで繰り返す指摘を未然に防ぐ設計の出発点になる。

コメント

タイトルとURLをコピーしました