はじめに Gson について Gson の課題 1. Null 安全が破壊されるリスク 2. デフォルト引数が無視される Kotlin Serialization について 具体的な修正内容 1. Data Class の書き換え 2. Retrofit の Converter の置き換え まとめと今後の課題 はじめに こんにちは、株式会社エブリーで Android アプリ開発を担当している岡田です。 弊社が提供する デリッシュキッチン の Android アプリでは、アプリの堅牢性向上とモダンな開発体験のための選択として、JSON パーサーを従来の Gson から Kotlin Serialization への移行を検討しています。 今回は弊社で行なっているイベント「挑戦WEEK」にて、Gson から Kotlin Serialization への移行を、Android のコードベース変更に限定して挑戦してみました。こちらについて、少しお話しさせていただければと思います。 弊社の挑戦WEEKの取り組みについては以下の記事をご覧ください！ tech.every.tv Gson について Android アプリの開発において、API との通信で受け取った JSON をデータクラスに変換する「JSON パース」は避けては通れない実装です。 デリッシュキッチン の Android アプリでは、長らく JSON パーサーとして Google 製の「Gson」を利用してきました。Gson は非常に歴史が長く、Android アプリ開発の黎明期からデファクトスタンダードとして広く使われており、Retrofit などのネットワークライブラリとも標準で連携しやすいという特徴があります。 長年アプリの通信基盤を支えてくれた Gson ですが、プロジェクトのフル Kotlin 化が進み、よりモダンな言語仕様を活用していく中で、実は Android アプリを開発する上でいくつかの大きな課題を抱えるようになっていました。 Gson の課題 Java 時代には非常に優秀だった Gson ですが、Kotlin で構成された現代のアプリにおいては、Kotlin の強みである言語仕様とコンフリクトを起こすケースが目立つようになってきました。 1. Null 安全が破壊されるリスク Gson は内部でリフレクション（ sun.misc.Unsafe など）を用いてインスタンスを生成します。そのため、Kotlin のデータクラスでプロパティを「非 Null（ String など）」で定義していても、サーバーから返ってくる JSON 側にそのキーが存在しない場合、Gson は強制的に null を代入してしまいます。 これにより、Kotlin コンパイラが保証しているはずの「Null 安全」がランタイムで破壊され、アプリの思わぬところで NullPointerException を引き起こす原因となっていました。 2. デフォルト引数が無視される Kotlin のデータクラスでは val isPremium: Boolean = false のようにデフォルト引数を設定できます。しかし、Gson はコンストラクタを経由せずにインスタンスを生成することがあるため、JSON に該当のキーが含まれていない場合、このデフォルト値が適用されません。結果として、意図しない型の初期値（ Int なら 0 、参照型なら null ）が入ってしまうという問題がありました。 これらの挙動は、開発者が意図しない「不正な状態を持ったインスタンス」がアプリ内を回遊することを意味しており、結果として予期せぬクラッシュの温床になり得ます。 Kotlin Serialization について 最終的に、これらの課題を根本から解決するために、Kotlin 公式が提供しているシリアライズライブラリ「Kotlin Serialization（ kotlinx.serialization ）」へ移行を検討しています。 Kotlin Serialization は、コンパイル時にシリアライズ・デシリアライズのためのコードを自動生成する仕組みを持っています。実行時に重いリフレクションを行わないため、非常にモダンで Kotlin ライクな設計となっています。 このライブラリへ切り替えることで、以下のような大きな恩恵を受けることができます。 厳格な Null 安全の保証 非 Null として定義したプロパティに対して JSON に値が存在しない場合、強制的に Null を入れるのではなく、パース時に明確に例外（ SerializationException ）を投げてくれます。これにより、不正なデータによる後続処理でのクラッシュを防ぐことができます。 デフォルト値の完全なサポート JSON にキーが存在しない場合、Kotlin 側で定義したデフォルト引数が正しく適用されます。 パフォーマンス向上とアプリサイズ削減 リフレクションに依存しないため、パース速度が向上します。また、ProGuard/R8 による最適化とも相性が良く、アプリのバイナリサイズの削減にも繋がります。 具体的な修正内容 実際に Gson から Kotlin Serialization へ移行するにあたり、行った具体的な修正内容をご紹介します。 1. Data Class の書き換え Gson の @SerializedName アノテーションを、Kotlin Serialization の @SerialName に変更し、クラスに @Serializable アノテーションを付与します。 【従来の Gson での実装】 data class UserResponse( @SerializedName ( "id" ) val id: Long , @SerializedName ( "user_name" ) val userName: String , @SerializedName ( "profile_image_url" ) val profileImageUrl: String ? ) 【新しい Kotlin Serialization での実装】 @Serializable data class UserResponse( @SerialName ( "id" ) val id: Long , @SerialName ( "user_name" ) val userName: String , // サーバーからキーが送られてこない可能性がある場合はデフォルト値を設定 @SerialName ( "profile_image_url" ) val profileImageUrl: String ? = null , @SerialName ( "is_premium" ) val isPremium: Boolean = false ) 2. Retrofit の Converter の置き換え API 通信に Retrofit を使用しているため、Gson の ConverterFactory を Kotlin Serialization 用のものへ差し替えました。 この際、サーバーからのレスポンスにおいて、アプリ側で定義していない未知のキーが含まれていてもパースエラーにならないよう、 ignoreUnknownKeys = true を設定しています。 // Json パーサーの設定 val json = Json { ignoreUnknownKeys = true // 未知のキーを無視する coerceInputValues = true // null が来た場合にデフォルト値があればフォールバックする } val contentType = "application/json" .toMediaType() val retrofit = Retrofit.Builder() .baseUrl( "https://api.example.com/" ) // GsonConverterFactory.create() からの置き換え .addConverterFactory(json.asConverterFactory(contentType)) .build() 主にこれらの修正を、API レスポンスを受け取る全てのデータクラスと Retrofit クライアントに対して適用し、段階的に移行を進めました。 また他にも com.google.gson.internal.bind.util.ISO8601Utils を利用している箇所や、 JsonUtil という Android アプリ側で Json を扱う際に使用するクラスの修正など、細かい修正も行いました。 総差分ファイル数はおよそ 500 ファイルと、大規模な改修になりました。 まとめと今後の課題 今回の改修で JSON パーサーを Kotlin Serialization に移行したことにより、Kotlin の言語仕様に沿った厳格な型安全性が担保されます。Android のコードベース上での堅牢性は大きく向上しました。 しかし、ライブラリが「厳格」になったからこそ直面する新たな課題もあります。 それは、 サーバーからのレスポンス仕様（スキーマ）の正確な把握 です。 Gson の時代は「JSON にキーがなくても、とりあえず Null を入れてクラッシュさせない」という緩さがありました。しかしこれからは、非 Null プロパティのキーが JSON に存在しなければ、即座にパース失敗となってしまいます。 これを防ぐためには、以下のような対応をサービス全体で意識していく必要があります。 サーバーレスポンスで Null が返る、またはキーが省略される可能性のあるフィールドには、適切な Nullable 定義やデフォルト値を設定する クラッシュログを監視し、パースエラーが発生した場合は迅速にデータクラスの定義をチューニングする サーバーサイドのエンジニアと密に連携し、API 仕様書とクライアント実装の乖離をなくす デリッシュキッチンは歴史のあるサービスですから、型安全に API レスポンスをパースするには、この辺りの見直しは避けて通れません。 時間と根気がいる作業にはなりますが、徐々にでも整備できればと思います。 もしまだ Gson を利用している方で、「データクラスの Null 安全が担保できずに困っている」「原因不明の NullPointerException に悩まされている」と感じているなら、一度 JSON パーサーの移行を検討してみてはいかがでしょうか。 今後も、Kotlin の厳格な型安全性を武器に、より品質が高く安定した デリッシュキッチン をユーザーの皆様にお届けできるよう、改善を続けていきます。

対象読者 Copilot の Agent Mode を日常的に使っている人 デバッグで「とりあえずエラーを貼って聞く」止まりの人 Copilot が的外れなコードを読みに行って消耗した経験がある人 Copilot の設定ファイルの全体像は「 GitHub Copilot の設定ファイル5種 」を参照してください。 デバッグ調査をチャットから始めてないか ども！龍ちゃんです。 バグ報告が来て、いつもみたいに Agent Mode のチャットに「このバグ調べて」と投げました。Copilot がファイルを次々読み始めて、待つ。関係なさそうなファイルまで読んでる。返ってきた分析は的外れだった。 「違う、そこじゃない」と追加で指示を出す。また読みに行く。また待つ。3ターン経っても全然進まない。結局自分でログ読んだ方が速かったんじゃないかと。精度を上げるためにPlanエージェントを使う手もあるんですけども、断続感がすごくて。 この体験、覚えがある人は多いんじゃないかなと思います。 なぜこうなるかというと、Plan エージェントがコードベースを広範囲に探索するからです。関係ないファイルまで読んでコンテキストウィンドウが埋まって、後半さらに精度が落ちる。「情報が足りないから広く探す」→「無駄な情報でコンテキストが埋まる」→「精度が落ちる」の悪循環です。 これ、Copilot が悪いんじゃなくて、渡し方の問題 なんですよね。 じゃあどうするか。 Copilot に投げる前に Issue.md を1枚書く 。問題・仮説・関連パスを整理してから渡すだけで、探索範囲が絞られて初手から的確になります。 この記事では、Issue.md を起点にした Copilot デバッグワークフローを実践ベースで紹介していきます。 今回の内容です。 Issue.md が効く2つの理由（思考の外部化とファイル起点のアクション） Issue.md を起点にしたデバッグの4ステップ 仮想シナリオで4ステップを走る実践例 人間がやること vs Copilot に任せることの役割分担 Issue.md でデバッグが変わる理由とフローの全体像 Issue.md とは バグ発生時に、プロジェクトルートに一時的な調査ファイル（ Issue.md ）を作ります。 Copilot に渡す前に、人間が先にコンテキストを整理する のがポイントです。 書くのは3つだけです。 発生している問題 （何が起きているか、再現手順） 仮説 （自分なりの原因予想） 関係するファイルのパス （Copilot の探索範囲を絞る） テンプレートはこんな感じです。 # Issue: [バグの概要] ## 発生している問題 - 現象：[何が起きているか] - 再現手順：[どうやったら起きるか] ## 仮説 - [自分なりの原因予想。わからなければ「わからないが○○が怪しい」でもOK] ## 関係するファイル - `src/components/XXX.tsx` - `src/hooks/useXXX.ts` 3行・パス2〜3個で十分です。30秒で書ける量がちょうどいいです。 もちろん、詳しければ詳しいほど良いです！ 仮説が浮かばないときは「わからないが、ここが怪しい」だけでも書いてください。完璧な仮説を書くのが目的じゃなくて、 書くことで頭が整理されるのが本質 です。「原因は○○かもしれない」と書こうとする過程で「いや、そもそも再現条件って何だっけ」みたいに思考が動き出す。それだけで Copilot への指示の質が変わります。 なぜこれが効くか 効く理由は2つあります。 理由1: 思考の外部化 チャットに「このバグ何？」と投げるのは、思考をスキップしてます。Issue.md を書く過程で「何が起きてるのか」「どこが怪しいのか」を自分の頭で一度整理する。この整理があるだけで、Copilot への指示の質が変わります。 「書くこと」が目的であって、「完璧なドキュメントを作ること」が目的じゃないです。 最終的に Issue.md に原因と対策までまとまるので、レポートを別途作る必要がない。振り返りもしやすいです。 理由2: ファイル起点で Copilot のアクションが変わる チャットで口頭説明するのと、MD ファイルとして渡すのでは Copilot の挙動が違います。 チャットで「このバグ調べて」と言うと、Plan エージェントは「まずコードベースを探索しよう」から始めます。ファイルとして渡すと「このドキュメントに書かれたパスを読もう」から始まる。この初手の違いがでかいんですよね。 ファイルに関連パスが書いてあると、Copilot はそのパスから読み始める。探索範囲が絞られるので、コンテキストウィンドウを無駄に消費しない。後半まで精度が持続します。 このワークフロー自体は汎用的で、Claude Code でも同じパターンは使えます。ただ、Copilot の Agent Mode は Plan エージェントがファイル探索の範囲を広く取るため、スコープを絞る効果が特に大きいです。もちろんPlanエージェントを使わないパターンでも読み込ませることで精度が継続します。 Before/After: チャットで聞く vs Issue.md を渡す 具体的にどう変わるか、比較してみます。 Before（チャットで聞く）: あなた: APIリクエストが多重に走ってるバグを調べて → Copilot がコードベース全体を探索 → 関係ないファイルまで読む → コンテキスト圧迫 → 的外れな分析が返ってくる After（Issue.md を渡す）: あなた: @Issue.md このドキュメントを元に調査して → Copilot が Issue.md に書かれた関連パスから読み始める → 初手から的を絞った分析が返ってくる 同じバグの調査なのに、初手の精度が全然違います。この差は Issue.md があるかないかだけで生まれます。 デバッグフローの全体像 Issue.md を起点にしたデバッグは、4ステップで進めます。 ステップ やること 担当 1. Issue.md を書く 問題・仮説・関連パスを整理 人間 2. Copilot に調査を依頼 Issue.md ごと渡して的を絞った調査 Copilot 3. 仮説→検証→フィードバック 人間が検証、Copilot が分析、を繰り返す 人間 + Copilot 4. 「なぜ直ったか」を確認 修正後に原因を言語化して次に備える 人間 + Copilot 次のセクションで、このフローを仮想シナリオで具体的に走らせてみます。 実践：仮想シナリオで4ステップを走る ここからは、実際のバグ調査セッション（33ターン）を元に、仮想シナリオに置き換えて紹介していきます。ワークフローのパターンを伝えることが目的なので、プロジェクトの詳細は出しません。 仮想シナリオ: API リクエストの多重発火 ダッシュボード画面を開くと、同じ API リクエストが3〜4回飛んでいる。 DevTools のネットワークタブ で確認すると、同じエンドポイントへの GET リクエストが重複している。ユーザーから「画面の表示が遅い」と報告があった。 フロントエンドあるあるですね。 useEffect の依存配列 ミスで同じ API が複数回飛ぶやつ。 ステップ1: Issue.md を書く（問題整理） バグ報告を受けたら、まず Issue.md を書きます。 # Issue: ダッシュボードの API 多重リクエスト ## 発生している問題 - ダッシュボード画面を開くと同じ API が3〜4回飛ぶ - DevTools のネットワークタブで GET /api/dashboard が重複しているのを確認 - ユーザーから「表示が遅い」と報告あり ## 仮説 - useEffect の依存配列に不要な値が入っていて再実行されているのでは - または、コンポーネントのマウント/アンマウントが繰り返されている可能性 ## 関係するファイル - `src/pages/Dashboard.tsx` - `src/hooks/useDashboardData.ts` - `src/components/DashboardWidgets.tsx` 書くのに30秒もかかりません。ポイントは、 Copilot に投げる前に自分の頭で一度整理すること です。「DevTools で見た」「3〜4回飛んでる」「依存配列かマウントが怪しい」ーーこれだけ書いておくと、Copilot の初手が全然違ってきます。 ちなみにバックエンドの場合も同じです。関連パスがサービス層や DB アクセス層になるだけで、Issue.md のフォーマットはそのまま使えます。 裏付けとして、ログファイルなどを与えると仮説の質や検討の精度がぐっと上がります。 ステップ2: Copilot に調査を依頼する Issue.md ごと Copilot に渡します。 @Issue.md このドキュメントを元に調査して。 関連ファイルを読んで、問題の原因候補を分析してほしい。分析結果は Issue.md に追記して。 Issue.md に仮説と関連パスが書いてあるので、Copilot はコードベース全体を探索せずに的を絞った調査を始めます。 Dashboard.tsx と useDashboardData.ts を読み込んで、 useEffect の依存配列を確認して、原因候補を分析してくれる。 何も書かずに「このバグ直して」だと、ここで大量のファイルを読みに行ってコンテキストが溢れます。 Issue.md がスコープの制約になっている わけです。 ここで「分析結果は Issue.md に追記して」と指示しているのがポイントです。Copilot の分析結果もチャットで受け取るんじゃなくて、最初から Issue.md に集約させる。こうすると調査の経緯がすべて1ファイルにまとまります。 Copilot が Issue.md に追記する内容はこんなイメージです: ## 調査結果（Copilot 追記） - `useDashboardData.ts` の `useEffect` 内で `fetchData()` を呼んでいる - 依存配列に `filters` オブジェクトが含まれている - `filters` が毎回新しいオブジェクト参照を生成しているため、レンダリングごとに `useEffect` が再実行 - → API リクエストが多重に発生している原因 仮説で「依存配列が怪しい」と書いておいたおかげで、Copilot がまさにそこにフォーカスして調査してくれたパターンですね。 ステップ3: 仮説→検証→フィードバックのサイクル ここから人間と Copilot のキャッチボールが始まります。実際のセッションでは一番ターン数が多かったフェーズです。 人間が仮説を投げる: filters の参照が変わってるのは分かった。 これって特定のウィジェットだけの問題？それとも全体で起きてる？ 手動検証して、結果を Issue.md に追記: ここが大事なポイントです。検証結果をチャットに直接書くんじゃなくて、Issue.md に追記して Copilot に渡す。こうすると Copilot が Issue.md を起点に読み直してくれるので、調査のコンテキストが途切れません。 ## 検証結果（追記） - DevTools で確認、全ウィジェット共通で発生 - filters をコンソールで見たら毎回新しいオブジェクトが作られていた - useMemo でメモ化すれば直る可能性あり ---copilot指示--- @Issue.md 検証結果を追記した。これを踏まえて原因と対策を分析して。分析結果も Issue.md に追記して。 Copilot が分析結果を Issue.md に追記: Copilot の分析結果もチャットで受け取るんじゃなくて、Issue.md に書かせます。こうすると調査の経緯がすべて1ファイルにまとまるので、後から振り返りやすい。 ## 分析結果（Copilot 追記） - [`useMemo`](https://react.dev/reference/react/useMemo) で `filters` をメモ化するのが正攻法 - ただし `DashboardWidgets.tsx` で `filters` を props として渡している箇所も確認が必要 - （コード差分を提示） 人間がスコープを絞る: サーバーサイドキャッシュの追加は今回は不要。 クライアント側の多重リクエスト防止だけでいい。 ポイントは、人間が「ここを見ろ」「これは対応不要」を言うだけで Copilot の無駄な探索が激減することです。「DevTools で確認した結果はこうだった」「全ウィジェット共通だった」というランタイムデータは Copilot が自分では取れない。人間がデータを集めて、Copilot が分析する。この分業が回ると調査がスムーズに進みます。 原因が特定できたら、対応方針を決めるのは人間の仕事です。「useMemo でいく」「カスタムフックに切り出す」みたいに、2〜3パターンの実装案を出させて比較するのがお勧めです。 ステップ4: 「なぜ直ったか」を確認する 修正を適用して、リクエストが1回に収まったことを確認。ここで終わりにせずに、もう1ステップ入れます。 自分の理解が合ってるか確認したい。 filters オブジェクトが毎回新しい参照を生成していたので、 useEffect の依存配列チェックで「変わった」と判定されて再実行されていた。 useMemo でメモ化して参照を安定させたことで、不要な再実行がなくなった。 この理解で合ってる？ 自分の言葉で原因を言語化して投げて、Copilot に補足・整理してもらいます。 このステップを入れることで、「なんとなく直った」で終わらなくなります。（まさにAIを自分のために使うってフェーズですね。） 「修正して終わり」にしないのが大事です。「なぜ直ったか」を言語化することで、次の類似バグに備えられます。「 Copilot チャット履歴から Instructions と SKILL.md を改善する3つの方法 」で紹介した lessons ポストモーテムと同じ発想ですね。この理解確認を lessons ファイルに残しておくと、同じパターンのバグに二度ハマらなくなります。 人間がやること vs Copilot に任せること ここまでの実践を踏まえて、役割分担を整理しておきます。33ターンのデバッグセッションから抽出した実績ベースの分担です。 人間がやるべきこと やること 実践での例 初期ドキュメント作成 ステップ1で Issue.md に問題・仮説・関連パスを記載 スコープの制限 「サーバーサイドキャッシュは不要、クライアント側だけで」 手動検証 DevTools でネットワークタブを確認、コンソールで filters の参照を確認 ランタイムデータの取得 HAR ファイル、ネットワークログ、ブラウザ上の実行時データ 方針決定 対策案の選択（useMemo でいく） Copilot に任せること やること 実践での例 ドキュメントを元にしたコード調査 ステップ2で Issue.md の関連パスからコードを読み込み 複数ファイルの一括読み込み Dashboard.tsx、useDashboardData.ts、DashboardWidgets.tsx を一度に確認 対策案の複数提示・比較 useMemo、useCallback、カスタムフックへの切り出しを比較提示 コード差分の生成 修正前/修正後の diff を出力 理解の補足・整理 ステップ4で人間の言語化を検証・補足 特に重要なのは、AI が取得できないデータを人間が補完すること です。ブラウザ上のランタイムデータ、認証が必要な API レスポンス、ネットワークログーーこれらは Copilot が直接アクセスできません。人間が取得して Issue.md に貼ることで、初めて Copilot の分析対象になります。 「人間がデータを集めて、AI が分析する」。この役割分担を意識するだけで、デバッグセッション全体の効率が変わります。 まとめ：Issue.md 1枚で変わること 「エラー貼って聞く」を「Issue.md 書いて渡す」に変えるだけで、Copilot の初手精度が上がります。 大事なのは3つだけです。 問題を書く （何が起きているか） 仮説を書く （わからなくてもいい、書こうとすることが大事） 関連パスを書く （Copilot の探索範囲を絞る） 30秒で書ける量で十分です。完璧なドキュメントを作ることが目的じゃなくて、自分の頭を整理して Copilot に的確な起点を渡すことが目的なので。 調査が終わった Issue.md は .gitignore に入れるか削除するか、運用は好みで構いません。コミットに残して調査経緯を追えるようにする派もいますし、一時ファイルとして使い捨てにする派もいます。 「修正して終わり」にしないことも大事です。「なぜ直ったか」まで確認して次に活かす。Issue.md → lessons → copilot-instructions.md / SKILL.md の流れが回ると、同じバグに二度ハマらなくなっていきます。この改善サイクルの詳細は「 Copilot チャット履歴から Instructions と SKILL.md を改善する3つの方法 」で紹介しているので、合わせて見てもらえると。 まずは次のバグで Issue.md を1枚書いてみてください。 ほなまた〜 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post GitHub Copilot デバッグの精度を上げるにはドキュメント1枚を先に書く first appeared on SIOS Tech Lab .

はじめに   こんにちは！2026年2月に CA Tech Job インターン生として就業 ...