今ではAIツール（Claude、ChatGPT、Cursor、Gemini、Copilot）が、私たちの仕事に深く入り込んでいる。開発速度は飛躍的に上がった一方で、率直に言えば、サービスの完成度はそれほど向上していないように感じる。機能が増えた分だけバグも増え、「なぜこうなったのか分かりません」という言葉を耳にする機会も多くなった。

開発が速くなるほど、コードを一行ずつ細かく確認することは減っていく。だからこそ筆者は、AIを正しい方向へ導ける基礎力がいっそう必要になると考えている。AIが書いたコードの問題に気づき、望む方向へ改めて導けなければ、成果物の品質は保てない。その基礎力には、ドメイン視点での開発、抽象化、TDD（Test-Driven Development、テスト駆動開発）、ライブラリの活用、パフォーマンス上の優位性の確保など、さまざまなものがあるだろう。

ところが、フロントエンドの同僚や他のIT職種の同僚に「フロントエンド開発で最も難しい作業は何ですか？」と尋ねるたび、最も多く返ってきた答えはいつも同じだった。「状態の流れを管理することです」

この記事では、なぜ状態の流れを管理することがそれほど難しいのか、そして適切に扱うためにどのような設計眼と感覚を養うべきかを整理していく。

状態（State）とは何か

本題に入る前に、最も基本的な問いから確認しよう。私たちが言う「状態」とは、正確には何だろうか。

フロントエンド開発を学ぶ中で、hoseung.me氏の記事をよく読んだ。そこでは状態を、**「UIに影響を与え得るすべてのデータ」**と説明している。いいね数、カートの中身、モーダルが開いているかどうか、入力値、ログイン中のユーザー情報、現在選択されているタブ、検索結果、ローディング中かどうか。これらはすべて状態である。

React公式ドキュメントは、もう少し形式的に定義している。ページのタイトルはそのまま「State: A Component's Memory」であり、かみ砕けば、「コンポーネントがレンダー間でデータを保持（retain）し、そのデータが更新されたときにReactへ再レンダーを促す仕組み」といったところだ。つまり、時間が経っても消えず、何らかのイベントによって更新され、更新時にUIを描き直すデータである。もう一つ押さえておくと、状態はコンポーネントのインスタンスごとに分離される。 同じコンポーネントがページ上に10個あっても、それぞれが独立した状態を持つ。この事実は、後で扱う「状態をどこに置くか」という議論に直結する。

どちらの定義も、同じものを指している。**「レンダーに影響し、時間とともに変化する値」**が状態である。変化しない定数（constant）は状態ではない。ビルド時に固定されるプリミティブなデザイントークンは状態ではないが、ユーザーが切り替えるダークモードは状態だ。（厳密には、値そのものがダーク／ライトというテーマの状態に応じてresolveされるため、「テーマの選択」が状態であり、トークンはその状態を映す鏡だと捉えるのが正確である）

ここで一つ確認しておきたい。すべての状態がコンポーネント内に存在するわけではない。 Cookieに存在する状態もあれば、localStorage・sessionStorage・IndexedDBに存在する状態も、URLに存在する状態もある。サーバーにあるデータをクライアントへ持ってきてキャッシュすれば、それも一種の状態になる。ブラウザ自身が保持するスクロール位置や履歴スタックも、アプリの振る舞いを決めるという点で、状態として扱うべき場合がある。

なぜそれほど難しいのか

状態を扱うことがなぜ難しいのか、まずは単純に考えてみよう。必要な状態を作り、必要な場所まで渡し、更新と初期化さえ適切に処理すればよいのではないだろうか。

この問いを頭に置いたまま、いま携わっているサービスのページを一つ開いてみよう。

そのページには、いくつのコンポーネントがあるだろうか。単純なページでも少なければ数十、多ければ数百のコンポーネントがツリーを構成しているはずだ。各コンポーネントは独自の状態を持つこともあれば、兄弟コンポーネントと状態を共有することも、親から状態を受け取ることもある。ページ間で状態が遷移することもあり、再読み込み後も残るべき状態も、タブを閉じたら消えるべき状態もある。

状態の管理が難しい本当の理由は、ここにある。無数の状態がどこで宣言され、どのように更新され、いつ消滅するのかを、私たちは一目では把握できない。 似た役割を持つコンポーネントが増えるほど、状態の命名も、状態を変更するコードの追跡も難しくなる。

こうして、目に見えない蜘蛛の巣ができあがる。AコンポーネントでのクリックがBのデータを無効化し、Bの無効化によってCのUIが閉じ、Cが閉じるとフォームの入力が失われる。この連鎖がコードのどこにも明示されていなければ、バグをデバッグするたびに、私たちは頭の中で蜘蛛の巣を描き直さなければならない。

では、この蜘蛛の巣をどう整理すればよいのだろうか。筆者が最初の一歩だと考えるのは、**「状態には種類がある」**と認識することである。

すべての状態が同じではない

Kent C. Doddsは、状態をServer Cache（サーバーに存在する情報を、クライアントが素早くアクセスするために保持するもの）とUI State（インターフェースの動作を制御するため、UIにのみ存在するもの）に分けている。私たちは、この二つを一緒に扱うときにしばしば間違いを犯す。

TanStack Query公式ドキュメントでは、TanStack Queryをサーバーとクライアント間の非同期処理を管理するServer Stateライブラリ、Redux、MobX、ZustandなどをClient Stateライブラリと位置づけている。（非同期データを保存することはできるが、それは非効率である）

要点は明確だ。Server StateとClient Stateは異なる問題である。 Server Stateは非同期で、他のユーザーによって変更される可能性があり、時間が経つとstaleになる。Client Stateは同期的で、私たちが制御でき、再読み込みすれば消える。（正確には、ページがunloadされるとJavaScriptランタイムが再起動し、heapメモリ上にあったコンポーネントツリーとその内部の状態がまとめて回収される。 そのため、再びマウントされるとuseStateの初期値からやり直す）この二つを同じツールで扱おうとすると、キャッシュの無効化、バックグラウンド更新、楽観的更新といったパターンをすべて自分で実装しなければならない。

筆者はさらに一歩進めて、フロントエンドの状態を7つの分類に分けて捉えている。あらかじめ断っておくと、この7つは一つの軸できれいに分割できるものではない。保存場所・出所・ライフサイクル・役割が混在しているため、一つの状態が複数の分類に同時に属することもある。完全な分類表ではなく、状態をどう管理するか決める際に投げかける問いだと考えてほしい。

• ローカル状態（Local State） — 一つのコンポーネント、または狭いツリー内だけで使う状態
• グローバル状態（Global State） — アプリ全体で共有する必要がある状態
• サーバー状態（Server State） — サーバーがSingle Source of Truthで、クライアント側はキャッシュである状態
• フォーム状態（Form State） — ユーザーの入力中だけ一時的に存在する状態
• URL状態（URL State） — アドレスバーにあり、共有でき、再読み込み後も残る状態
• 外部状態（External State） — Cookie、localStorage、sessionStorage、IndexedDBなど、Reactの外部にある状態
• 状態ガード（State Guard） — 状態そのものではなく、状態の組み合わせに応じてアクセスや実行を制御・検証するロジック

この分類以外にも、状態マシンで精緻化すべきワークフロー状態や、WebSocket・CRDTを基盤とするリアルタイム共同編集状態がある。

それぞれに異なるツールが必要な理由と、どのような視点で向き合うべきかを、一つずつ見ていこう。

ローカル状態（Local State）

最も単純な状態である。一つのコンポーネント内でのみ使われ、外部が知る必要も、知る権利もない状態だ。モーダルの開閉、トグルボタンのon/off、ホバー状態、入力途中の検索語などが該当する。

function SearchBox() {
  const [query, setQuery] = useState("");
  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

この程度なら馴染みがあるだろう。しかし、ローカル状態で本当に難しいのは、**「この状態をどこに置くべきか」**という配置の判断である。

Kent C. DoddsのState Colocationの記事では、**人々は状態を「引き上げる（lift up）」ことには慣れているが、コードが変わったときに状態を再び「近くに置く（colocate）」ことはあまりしない。**と述べている。

状態を引き上げるのは、兄弟コンポーネントが同じ状態を共有する必要があるときに、私たちが自然に取る行動だ。二つの兄弟が同じデータを見る必要があるため、共通の親へ状態を移し、propsで渡す。

問題は、その状態が兄弟に必要なくなったときである。私たちは状態を再び子の側へ引き下げることを、あまりしない。その結果、親コンポーネントには本来関係のない状態が大量に蓄積し、親が再レンダーされるたびに、子のツリー全体まで再レンダーされることになる。

したがって、ローカル状態に関する第一の設計眼は、高速かつシンプルにするため、状態はそれを使うコードのできるだけ近くに置くことである。あるコンポーネントの子の一つでしか使わない状態なら、親が持つ理由はない。その子の内部へ移そう。その分、親は軽くなる。

グローバル状態（Global State）

グローバル状態とは、アプリのどこからでもアクセスできる必要がある状態である。ログイン情報、テーマ、言語、通知（トースト）などが候補になる。

ローカル状態とグローバル状態の違いは、単に「どこに存在するか」ではない。参照に関する契約が異なる。ローカル状態は**「このコンポーネントの内部でのみ意味を持つ」という契約を、グローバル状態は「アプリのどこからでも、この名前でこの値を参照できる」**という契約をコード全体に公開する。その契約のコストが高いことこそ、グローバル状態の本質である。

グローバル状態を一つ作ることは、実のところ、アプリ全体にまたがる暗黙的な依存関係を一つ追加することだ。

サーバー状態（Server State）

APIから受け取ったデータをClient Stateに入れ、ローディングとエラーをbooleanで直接管理し続けた末に、**「なぜ毎回、同じボイラープレートを書いているのだろう？」**という疑問へ行き着く。

TanStackのメインメンテナーであるTanner Linsleyは、「Client Stateは同期的で予測可能だ。Server Stateは非同期で、複数のコンポーネントにまたがって共有され、キャッシュ・バックグラウンド更新・エラー状態を慎重に扱う必要がある」と述べている。つまり、Server StateはClient Stateとは本質的に別種のものである。同じツールで扱うべきではない。

Server Stateが難しいのは、ツールの問題ではなく、データの本質によるものだ。

クライアントが見ているデータは、サーバーのものだ。クライアントが持つデータは、ある時点のスナップショットにすぎない。このデータは時間の経過とともにstaleになる。また、非同期で失敗する可能性があり、pending、error、successなどの状態を持つ。

最も重要な本質は、レスポンスがリクエストを送った順番どおりに返る保証はないという点だ。検索欄へ「react」と素早く入力するとしよう。r → re → rea → reac → reactの順にリクエストは送られるが、「react」のレスポンスが先に到着し、その後で「rea」のレスポンスが届けば、画面には「rea」の結果が表示されてしまう。この問題を防ぐには、AbortControllerやリクエストIDの追跡を毎回手作業で実装する必要があり、**並行処理に伴う危険（race conditions）**を考慮しなければならない。

フォーム状態（Form State）

フォームは少し特殊な状態である。ユーザーが入力している間は激しく変化するが、送信が終われば通常は消える。他の場所と共有されることも、保存先があることも（ほとんどの場合）ない。

問題は、この「激しい変化」のコストが高いことだ。キー入力のたびにReactの再レンダーが起きれば、大きなフォームでは入力遅延が目立つようになる。そしてフォームは、単に「値を保持する」だけのものではない。バリデーション、dirty check、送信状態、エラーメッセージ、複数ステップのフローまで、一つのフォーム内で複数種類の状態が同時に動き続ける。

3段階の決済フローのような複数ステップのフォームには、「途中で再読み込みしても進行状態が残ること」が期待される。このときフォームの値をuseStateだけで保持していれば、再読み込みですべて失われる。sessionStorage（タブ単位の一時保存）やURL（共有可能なステップ）に保存するのが自然だ。つまりフォーム状態は、ライフサイクル上の要件に応じて、External StateやURL Stateと組み合わせることになる。

URL状態（URL State）

検索ページで、カテゴリー・並び順・ページ番号を使って絞り込んでいるとしよう。これらの状態をuseStateで保持すると、三つの問題が同時に生じる。

• 再読み込みすると、すべてのフィルターが初期化される
• URLを友人に共有しても、相手にはフィルターが適用されていないページが表示される
• 戻るボタンを押しても、以前のフィルターへ戻らない

こうした問題を解決するには、状態をURLに入れるのが自然だ。 URLはそれ自体が、再読み込み・共有・履歴に対応した、無料で使える永続ストレージである。

/products?category=shoes&sort=price-desc&page=2

この一行のURLには、**「靴カテゴリーを価格の降順で並べた2ページ目」**という完全な状態が含まれている。useStateで別途保持する必要はない。

では、どのような状態をURLで扱うのが適切だろうか。URLは公開インターフェースである。 パスワード、認証トークン、ユーザーが他人に見せたくない一時的なメモなどをURLへ入れてはいけない。また、頻繁に変わる値（入力のたびに更新される検索語）をそのままURLへ反映すると、履歴スタックがゴミで埋まってしまう。この場合はdebounceしてから反映するか、pushではなくreplaceを使い、履歴を汚さないようにする必要がある。

URLの値は常に文字列である。数値、boolean、配列、オブジェクトには、シリアライズとデシリアライズの工程が必要だ。さらにURLは、パーセントエンコーディング（percent-encoding）の規則に従う必要があるため、&、=、韓国語、スペースなどは特別に処理される。これを毎回手作業で実装すれば、やがてバグの温床になる。

const params = new URLSearchParams(location.search);
const page = Number(params.get("page") ?? "1");
params.set("page", String(page + 1));
navigate(`?${params.toString()}`);
 
const [page, setPage] = useQueryState("page", parseAsInteger.withDefault(1));

nuqsのようなライブラリは、*パーサー（parser）*という概念で、この二つの問題を解決する。parseAsInteger、parseAsBoolean、parseAsJsonといったパーサーが、シリアライズ・デシリアライズ・型をまとめて担う。Next.js（App/Pages Routerの両方）、React Router v6/v7、TanStack Router、Remixなど、ほとんどの環境に対応している。

では、URLへ状態をいくらでも詰め込んでよいのだろうか。シリアライズや型の問題とは別に、最後に考慮すべき制約が一つ残っている。RFC 7230は正確な上限を定めてはいないものの、「サーバーは最低でも8,000オクテット（ネットワークやデータ通信において、8 Bitからなる1 Byteを明確に指す際に使う単位）をサポートすべき」と推奨している。ブラウザごとの上限もさまざまで、モダンブラウザではおおむね8KBから数万文字まで許容されるが、検索エンジンやソーシャルメディアのOG／共有処理、一部のゲートウェイでは2KB前後で切り捨てられることもある。 したがって、URLへ無制限に詰め込むのは避けよう。共有可能な主要フィルターだけを置き、残りはsessionStorageやサーバー側の保存に任せるのが安全だ。

外部状態（External State）

Reactが認識できるのは、自身の内部にある状態だけだ。しかし、私たちのアプリはReactの外の世界とも絶えずやり取りしている。そこに存在する状態はReactのライフサイクルと無関係に残り、変化する。ここでいうExternal Stateには、Cookie、localStorage、sessionStorage、IndexedDBがある。

ストレージはどのように選ぶのが適切だろうか。筆者は通常、寿命・容量・同期性・セキュリティという四つの観点から考える。

認証トークンに関するOWASPの推奨では、HttpOnly + Secure Cookieが第一候補となる。localStorageはJavaScriptからアクセスできるため、XSSにさらされた瞬間、トークンをそのまま盗まれる。 セキュリティガイドの中には、アクセストークンはメモリに、リフレッシュトークンはHttpOnly Cookieに置くハイブリッドパターンを推奨するものもある。永続的で、機密性がなく、頻繁に変わらないデータにはlocalStorageを、タブとともに消えるデータにはsessionStorageを活用する。オフラインキャッシュ・大容量データ・ファイルを扱う際には、一般にIndexedDBを利用する。

CookieとWeb Storage（local/session）は、文字列しか保存できない。 そのため、オブジェクトを入れるにはJSON.stringify/JSON.parseを経由する必要がある。しかし、JSONには限界がある。

JSON.stringify({ when: new Date() });
// → { "when": "2026-05-19T..." } — Date becomes a string
 
JSON.stringify({ map: new Map([["a", 1]]) });
// → { "map": {} } — Map is lost entirely
 
JSON.stringify({ value: undefined });
// → "{}" — the undefined field is omitted

DateはJSONとの往復で文字列になり、Map、Set、undefinedではデータが失われることがある。BigIntはデフォルトではJSON.stringifyがTypeErrorをスローし、シリアライズ自体が失敗する。外部ストレージへオブジェクトを入れるときは、どの型が失われたり変化したり、シリアライズを失敗させたりするかを常に意識し、必要に応じてシリアライズ用のアダプターを用意しなければならない。

External Stateの本当の難しさは、Reactがその変化を自動では検知できない点にある。localStorageへ値を書き込んでも、Reactコンポーネントは再レンダーされない。これを解決するパターンは、主に三つある。

• カスタムフック（useLocalStorage）で一段ラップし、External StateをReact stateと同期する。 軽量だが、自分で実装するなら、複数タブ・SSR・tearingといったエッジケースをすべて扱わなければならない。
• React 18で導入されたuseSyncExternalStoreフックを使い、「React外部の状態と同期できる」。 これにより、並行レンダリングでtearingが発生しないことを保証できる。 localStorage・ブラウザAPI・外部ストアをつなぐ標準的なツールである。
• ZustandのpersistミドルウェアやJotaiのatomWithStorageのように、状態管理ライブラリは外部ストレージとの連携を第一級の機能として提供しているため、既存のライブラリを活用できる。

ここでもう一つ、設計上の視点を加えよう。External StateをReactへ取り込んだ瞬間、同期の責任は私たちに移る。 別のタブで更新されたら？ サーバーがCookieを変更したら？ ユーザーがブラウザの開発者ツールからlocalStorageを直接編集したら？ こうした事象が、最も大きなバグの温床になることも多い。

状態ガード（State Guard）

最後の分類は、少し性質が異なる。状態そのものではなく、状態の組み合わせによって、何らかのフローを止めたり許可したりするロジックである。

最も一般的な例は、**認証ガード（Auth Guard）**だ。

function ProtectedRoute({ children }) {
  const { isAuthenticated, isLoading } = useAuth();
 
  if (isLoading) return <Spinner />;
  if (!isAuthenticated) return <Navigate to="/login" replace />;
  return children;
}

ここでは、isAuthenticatedという状態がルーティングのフローを制御している。これがガードロジックである。認証ガード（認証済みか）、権限ガード（特定のロールや権限を持つか）、フローガード（進入先の分岐）、検証ガード（ステップを有効化できるか）など、さまざまな種類のガードがある。

ガードロジックは、一か所に集中しやすい。一つのコンポーネントに、**「未ログインならログインページ、権限がなければ403、カートが空なら商品ページ、ユーザーが停止中なら停止案内」**がすべて入ってしまうことも珍しくない。ガードが肥大化するほど、どの条件によって、どこで止められたのかをデバッグしにくくなる。

優れたガードは、一つのことだけを検査する。 組み合わせにはCompositionを使う。

<AuthGuard>
  <RoleGuard role="admin">
    <FlowGuard require={["cartHasItems"]}>
      <CheckoutPage />
    </FlowGuard>
  </RoleGuard>
</AuthGuard>

各ガードは一つの判断だけを行い、合成はツリー構造が担う。新しいガードを追加するときに、既存のガードへ手を加える必要はない。

ガードを扱う際、止めること以上に考えるべきなのは、どこへ遷移させるか／その後どう扱うかを決めることだ。止めるだけでフォールバックのないガードは、真っ白な画面や無限スピナーに行き着く。

最もよくあるバグは、**「ガードの非同期チェックが終わる前に、保護対象のコンテンツが一瞬表示される」**ことだ。認証トークンの検証や権限の取得は、ほとんどが非同期であり、その間、isAuthenticatedが一時的にundefinedやfalseになる瞬間がある。ローディング状態を明示的に扱わなければ、その隙に保護対象の画面が露出したり、誤ってログインページへリダイレクトされたりする。

// Ignores loading and handles only missing data => incorrect
if (!user) return <Navigate to="/login" />;
 
// Treat loading as a first-class state (early return) => correct
if (isLoading) return <Spinner />;
if (!user) return <Navigate to="/login" replace />;
return children;

権限ガードを実装するときは、二つのモデルがよく使われる。

• RBAC（Role-Based Access Control）：ロール単位で権限を付与する。「adminはすべてのユーザー情報を閲覧できる」といった形だ。シンプルで高速だが、ロールを細分化するほど、その数が爆発的に増える
• ABAC（Attribute-Based Access Control）：属性の組み合わせで権限を決める。「ユーザーがその投稿の作成者である、同じチームに所属している、またはadminである場合」といった形だ。表現力は高いが、実装とデバッグが難しい

TanStack RouterのRBACガイドのように、ルーターレベルでbeforeLoadにガードを組み込むパターンが推奨される。重要なのは、権限チェックをコードの各所にばらまかず、データ（ロール／権限の一覧）として表現できるようにすることだ。そうすれば、権限ポリシーの変更はデータの変更だけで済む。

まとめ

整理しよう。状態管理が難しいのは、ライブラリが難しいからではない。状態には種類があるという事実を忘れがちだからであり、種類ごとに異なるツールと考え方が必要だという点を見落としやすいからだ。

ローカル状態はできるだけ近くへ置く。グローバル状態は本当にグローバルであるべきか、もう一度疑う。Server Stateはキャッシュとして扱う。フォームはドメインから分離する。URLはより積極的に活用する。外部ストレージは責任を意識する。ガードは薄く分けて合成する。これが7つの分類を扱うための基本である。

そして、それらすべての土台となる設計眼は、最終的に四つの問いへ集約される。

• このデータのSingle Source of Truthはどこにあるか？
• これは計算で求められる値か、それとも本当に保存すべき値か？
• この状態の組み合わせに、不可能な組み合わせはないか？
• この状態は、本当にこの場所にあるべきか？

新しい画面を実装するとき、PRをレビューするとき、AIが生成したコードを受け取るとき。そのたびに、これらの問いを一度ずつ投げかける。それこそが、設計眼と感覚を養う最も確実な道だと筆者は信じている。

冒頭で述べたとおり、AIはこれからも長く私たちのそばにいるだろう。コードを一行ずつ確認する時間は、ますます減っていく。しかし、だからこそ、**「この状態はどこにあるべきか？」**という小さな問いに答えられる感覚の価値は高まる。AIに「ここへuseStateをもう一つ追加して」と頼むのは簡単だ。だが、その一行がアプリの蜘蛛の巣にどのような糸を加えるのかを理解できるかどうかは、そのコードを読む人の設計眼にかかっている。

正解はない。それでも、**「状態が何かを理解せずに状態を作ること」と、「状態の種類と配置を意識して作ること」**の間には、明確な違いがある。この記事を読んだ方にも、次にuseStateを一行書く前に一度立ち止まり、「これはどの分類の状態だろう？」と問いかけてみてほしい。

参考資料

筆者は開発を続けるなかで、「ドメイン（Domain）」 という言葉をかなり頻繁に耳にしてきた。しかし、いざ「ドメインとは正確には何か？」と聞かれると、明快に答えるのは簡単ではない。（正直なところ、開発を始めたばかりの頃は、ドメインとはwwwのことだと思っていた。）

ドメインについて調べると、自然と ドメインモデル、ドメインオブジェクト、ドメインオブジェクトモデル といった概念に行き着く。しかし、それぞれがどう違うのか、また、これらの概念がバックエンドではなく フロントエンド でどのような意味を持つのかを整理した記事は、意外と多くない。この文章では、各概念の定義から始め、フロントエンドでドメインロジックをどのように分離し、抽象化するのが適切なのかまで、例を交えて整理してみたい。

最近は税金に関するドメインに関心がある。まもなく5月の総合所得税申告の時期を迎えるので、今回は税金を例に取り上げる。

ドメイン（Domain）

最も基本的な問いから始めよう。ドメインとは何だろうか？

Eric Evansは著書 Domain-Driven Design: Tackling Complexity in the Heart of Software（2003） で、ドメインを次のように定義している。

知識、影響力、または活動の領域。

"A sphere of knowledge, influence, or activity."

簡単に言えば、プログラミングによって解決しようとする問題領域そのものがドメインである。税務申告サービスを作るなら「税務申告」がドメインであり、保険請求プラットフォームを作るなら「保険請求」がドメインとなる。ドメインはコードではない。ソフトウェアより先に存在する、現実世界の問題領域である。

これはフロントエンド開発者にとって、どのような意味を持つのだろうか？私たちが作るUIは、最終的にこのドメインをユーザーへ見せ、操作できるようにする 窓（window） である。税金を主なドメインとするToss Incomeや3o3のような税金還付サービスを開発するなら、所得区分、必要経費率、所得控除、税額控除、還付額といったドメインの概念をUIで表現することになる。そのため、フロントエンド開発者も自分が扱うドメインを深く理解しなければならない。UIコンポーネントをうまく描画することと同じくらい、「このサービスが解決する問題は何か」 を知ることが重要だという意味である。

とはいえ、「税金」という一つのドメインだけを見ても、その内部には数多くのサブドメインが存在する。筆者が表面的に把握している総合所得税の計算パイプラインだけでも、次のとおりだ。

このパイプラインの各段階は、それぞれ固有のルールとデータを持つサブドメインである。「税金」という一つの大きなドメインの中で、所得（Income）、控除（Deduction）、税額（Tax）、申告結果（Filing）という細かなドメインが絡み合っている。これらをコード上でどう分けるかが、まさにドメインモデリングの中心的な問いである。

ドメインモデル（Domain Model）

では、ドメインモデルとは何だろうか？ドメインと「ドメインモデル」はどう違うのだろう？

Martin FowlerとEric Evansは、ドメインモデルを次のように定義している。

振る舞いとデータの両方を含む、ドメインのオブジェクトモデル。— Martin Fowler

An object model of the domain that incorporates both behavior and data.

ドメインの選択された側面を記述する抽象化の体系であり、そのドメインに関する問題を解決するために使用できるもの。— Eric Evans

A system of abstractions that describes selected aspects of a domain and can be used to solve problems related to that domain.

重要なのは、「選択的な抽象化」 だという点である。ドメインモデルは、現実世界のすべてを含むわけではない。映画監督が現実のすべての場面を収めず、物語に必要な場面だけを選ぶように、ドメインモデルも 解決したい問題に必要な側面だけを選び、構造化したもの である。

ここで大切な点が一つある。ドメインモデルは、必ずしもコードである必要はない。ホワイトボードに描かれた図かもしれないし、チーム内で共有されているメンタルモデル（Mental Model）かもしれない。つまり、ドメインモデルという用語自体は、ソフトウェアとは独立した概念であり得る。

ここには、フロントエンド開発者が特に混同しやすい点がある。APIレスポンスの構造を見て、「これがドメインモデルだ」と考えることだ。しかし、それは データモデル（Data Model） であって、ドメインモデルではない。

データモデルとドメインモデルを区別すると、次のようになる。

データモデルは「どのような形でデータがやり取りされるか」を定義し、ドメインモデルは「このデータがビジネス上何を意味し、どのようなルールに従うか」を定義する。 この二つを区別できなければ、コンポーネントがAPIレスポンスの構造へ直接依存し、バックエンドのスキーマが変わるたびにフロントエンド全体が揺さぶられることになる。

ドメインオブジェクト（Domain Object）

ドメインモデルが概念の体系であるなら、ドメインオブジェクトは、その概念をコードとして実装した実体である。

Code with Jasonを運営するJason Swettの記事では、ドメインオブジェクトを次のように定義している。

私のオブジェクトモデルにあるオブジェクトのうち、ドメインモデルにも一つの概念として存在するものを、ドメインオブジェクトと呼ぶ。

Any object in my object model that also exist as a concept in my domain model I would call a domain object.

つまり、ドメインモデルに「総合所得」という概念があり、コード上にIncomeという型があるなら、このIncomeがドメインオブジェクトである。ただし、コード上のすべてのオブジェクトがドメインオブジェクトなのではない。HttpClient、LocalStorageAdapter、useDebounceなどは技術的な道具であり、ドメインの概念ではない。

EntityとValue Object

Evansは、ドメインオブジェクトを Entity、Value Object、Service の三つに分類している。（Martin Fowlerはこの分類を「Evans Classification」と呼ぶ。）Serviceは、「特定のオブジェクトへ自然に帰属しないドメインの操作」を表す別の概念だが、この記事の中心はデータをどのように識別するかという問題なので、EntityとValue Objectの二つに焦点を当てる。

Entity（エンティティ） は、時間やさまざまな表現を超えて維持される、一意のアイデンティティを持つオブジェクトである。税務申告書（TaxFiling）、納税者（Taxpayer）、所得記録（IncomeRecord）のように一意なIDで識別され、属性が変わっても同じIDなら同じEntityである。申告書の控除項目が修正されても、申告書IDが変わらない限り、それは同じ申告書であり続ける。

Value Object（値オブジェクト） は、属性の組み合わせだけで意味を持つオブジェクトであり、すべての属性値が同じなら同一とみなす。金額（Money）、税率（TaxRate）、税率区分（TaxBracket）のように、値そのものに意味があるオブジェクトだ。「税率6%」は、どこで使われても「税率6%」でしかない。

この区別は、フロントエンドでなぜ重要なのだろうか？次のコード例で見てみよう。

interface TaxFiling {
  id: string;
  taxpayerName: string;
  taxYear: number;
  status: FilingStatus;
}
 
const isSameFiling = (a: TaxFiling, b: TaxFiling) => a.id === b.id;
 
interface Money {
  amount: number;
  currency: "KRW" | "USD";
}
 
const isSameMoney = (a: Money, b: Money) =>
  a.amount === b.amount && a.currency === b.currency;

TaxFilingはidをアイデンティティの基準とするため、Entityである。（idフィールドを持つこと自体がEntityの定義なのではなく、「そのidによって同一かどうかを判断する」点が重要である。）Moneyはidを持たず、amountとcurrencyの組み合わせだけで識別され、すべての属性が同じなら同じ値とみなされる。

EntityはIDによる比較、Value Objectは属性による比較。この区別が明確であれば、状態管理で「このデータが同じものか別のものか」を判断するロジックが自然に整理される。リスト内の項目を更新するとき、EntityならIDで探して置き換え、Value Objectならイミュータブルな置き換え（immutable replace）を行う、といった具合だ。

ドメインオブジェクトモデル（Domain Object Model）

「ドメインモデル」と「ドメインオブジェクト」は分かった。では、ドメインオブジェクトモデルとは何だろうか？

調べてみると、意外にも合意された定義はない。多くの文献では、「ドメインモデル」「ドメインオブジェクトモデル」「概念モデル（conceptual model）」「分析オブジェクトモデル（analysis object model）」を 実質的に同義語 とみなしている。オブジェクト指向分析の段階で描かれる概念モデルを指す、複数の呼び方だという立場である。

一方で、もう少し分離された層として捉える見方もある。ドメインモデルが実際のコードへ変換される地点がオブジェクトモデルである、という説明が代表的だ。

この二つ目の観点では、オブジェクトモデルとは、システム内の すべてのコードオブジェクトの構造 である。そこにはHttpClientやuseDebounceのような技術的な道具も含まれる。その中で、ドメインの概念を表すオブジェクトの部分集合と、それらの関係が ドメインオブジェクトモデル である。「Object Model」をシステムの静的構造（クラス、属性、操作、関係）と定義してきた、オブジェクト指向モデリングの伝統にもつながっている。

筆者は、こちらの観点のほうがフロントエンド開発者にとって実用的だと考えている。実際に書くコードには、ドメインオブジェクトと技術的なオブジェクトが常に混在しているからだ。

結局、ドメイン → ドメインモデル → ドメインオブジェクトモデル → ドメインオブジェクト は、抽象から具体へと下りていく階層である。ドメインが最も広く、ドメインオブジェクトが最も具体的だ。したがって、フロントエンドのコードを書くときに実質的に考えるべき領域は、ドメインオブジェクトモデル（ドメインの概念を表す型と、その間の関係）をどのように構造化するか ということになる。

フロントエンドのドメインロジックはどこに置くべきか？

概念の定義はここまでにして、ここからは実践について考えよう。フロントエンドのドメインロジックは、どこに置くべきなのだろうか？

ソフトウェア設計に深い関心を持つKhalil Stemmlerは、当初「ビジネスロジックはフロントエンドに属さない」と主張していたが、後に「バックエンドでアーキテクチャ上行っているほぼすべてのことを、フロントエンドでも実践できるし、実践すべきだ」と立場を改めた。

筆者もこの立場に同意する。もちろん、フロントエンドがビジネスロジックの 信頼できる唯一の情報源（Single Source of Truth） になってはならない。それはバックエンドの役割である。しかし、フロントエンドにも フロントエンド独自のドメインロジック が確かに存在する。

「ユーザーが入力した情報に応じて、予想還付額をリアルタイムに表示しなければならない」ケースを考えてみよう。この計算ロジックがバックエンドにしかなければ、ユーザーが所得金額を一文字直すたびにAPIを呼び出す必要がある。ネットワークの往復時間だけUIが止まり、入力の速いユーザーなら不要なリクエストが爆発的に増えてしまう。debounceを適用しても、数百ミリ秒の遅延は「リアルタイムプレビュー」という体験を損なうのに十分である。結局、即時フィードバックが必要な計算はフロントエンド自身が実行せざるを得ず、フロントエンドでしか実行できないロジックが存在することになる。

ドメインロジックがコンポーネントに混在している場合

総合所得税のプレビュー画面を例にしよう。ユーザーが所得情報を入力すると、予想税額をリアルタイムに表示する機能である。次は、ドメインロジックとUIロジックが入り交じった、よく見かけるコードだ。

function TaxPreviewPage() {
  const [총수입, set총수입] = useState(0);
  const [경비율, set경비율] = useState(0.641); 
  const [인적공제대상인원, set인적공제대상인원] = useState(1); 
 
  const 종합소득금액 = 총수입 - 총수입 * 경비율;
 
  const 소득공제합계 = 인적공제대상인원 * 1_500_000;
  const 과세표준 = Math.max(0, 종합소득금액 - 소득공제합계);
 
  let calculatedTax = 0;
  if (과세표준 <= 14_000_000) {
    calculatedTax = 과세표준 * 0.06;
  } else if (과세표준 <= 50_000_000) {
    calculatedTax = 과세표준 * 0.15 - 1_260_000;
  } else if (과세표준 <= 88_000_000) {
    calculatedTax = 과세표준 * 0.24 - 5_760_000;
  } else if (과세표준 <= 150_000_000) {
    calculatedTax = 과세표준 * 0.35 - 15_440_000;
  } else {
    calculatedTax = 과세표준 * 0.38 - 19_940_000;
  }
 
  const 기납부세액 = 총수입 * 0.033;
  const refundOrPayment = 기납부세액 - calculatedTax;
 
  return <div>...</div>;
}

このコードの問題が見えるだろうか？「人的控除は1人当たり150万ウォン」「8段階の累進税率」「3.3%の源泉徴収」という 税法で定められたビジネスルール が、Reactコンポーネント内へ直接埋め込まれている。税法は毎年改正されるため、このようなルールがコンポーネントに散らばっていれば、改正時に修正箇所を探し回ることになる。開発者だけでなく、QAチームが管理するE2Eシナリオがあるなら、テストコストも無視できないだろう。

やがて、これがビューロジックなのかビジネスロジックなのか区別しづらくなり、大量の条件分岐とカスタムフックが複雑に絡み合ってしまう。

ドメインロジックを分離してみよう

Alex BespoyasovのClean Architectureのアプローチから、中心的な原則を借りよう。ドメインロジックを、フレームワークに依存しない純粋関数として分離するのである。

ドメインは、あるアプリケーションを別のアプリケーションと区別する中核である。ReactからAngularへ移行しても変わらないもの、と考えることができる。

The domain is the core that distinguishes one application from another. You can think of the domain as something that won't change if we move from React to Angular.

先ほどの税額計算の例をリファクタリングしてみよう。

まず、ドメインの型とルールを定義し、関連する情報をまとめる。

export interface Income {
  grossAmount: number;
  expenseRate: number;
}
 
export interface Deductions {
  personalCount: number;
  pensionPaid: number;
  additionalDeductions: number;
}
 
const PERSONAL_DEDUCTION_PER_PERSON = 1_500_000;
const WITHHOLDING_RATE = 0.033;
const TAX_BRACKETS = [
  { limit: 14_000_000, rate: 0.06, progressiveDeduction: 0 },
  /** ...구간들... **/
] as const;

次に、ドメインロジックを純粋関数として分離する。

先ほどの所得計算、控除、課税標準、税額、還付額などの計算ロジックをcomputeFullTax関数へ分離する。各段階は、さらに小さな純粋関数へ分割する。結果の型をReturnType<typeof computeFullTax>で推論させれば、別途インターフェースを宣言する必要はない。

その後、コンポーネントはドメインロジックを「使う」だけにする。

import { computeFullTax } from "../domain/tax";
 
function TaxPreviewPage() {
  const [income, setIncome] = useState<Income>({
    grossAmount: 0,
    expenseRate: 0.641,
  });
  const [deductions, setDeductions] = useState<Deductions>({
    personalCount: 1,
    pensionPaid: 0,
    additionalDeductions: 0,
  });
 
  const result = computeFullTax(income, deductions);
 
  return (
    <div>
      <IncomeForm value={income} onChange={setIncome} />
      <DeductionForm value={deductions} onChange={setDeductions} />
      <TaxResultSummary result={result} />
    </div>
  );
}

何が変わったのだろうか？

• 8段階の累進税率表（TAX_BRACKETS）が一か所にまとまり、税法改正時はdomain/tax.tsだけを修正すればよい
• 計算パイプラインがcomputeFullTaxという一つの関数へ集約され、全体の流れをひと目で把握できる。（例を単純にするため一つにまとめたが、実際のプロジェクトでは所得計算・控除計算・税額算出など、目的別にさらに細分化するのが適切である。）
• コンポーネントは「どう見せるか」だけに集中する。税率が変わってもコンポーネントを修正する必要はない
• Reactから別のフレームワークへ移行しても、domain/tax.tsは 変わらない

ドメインロジックを分離すると、テストは驚くほど単純になる。税金ドメインでは、計算の正確さがそのままユーザーのお金に直結するため、この点は特に重要である。

税金に関する計算ロジックを持つ純粋関数には、React Testing Libraryも、renderも、screen.getByTextも必要ない。入力を与えて出力を確認するだけでよい。「1,400万ウォン以下は税率6%」「課税標準が0ウォンなら税額も0ウォン」「フリーランサーの所得3,000万ウォンに対する還付額」といったケースを、一行のitで表現できる。ドメイン単体テストはコンポーネントを分離する基準を自然に示し、テストコードはドキュメントとしての役割まで果たす。

貧血ドメインモデル（Anemic Domain Model）

前節では、計算ロジックを分離した。しかし、ドメインロジックには計算以外にも、状態遷移ルールと 権限の判定 がある。「この申告書は今編集できるか？」「提出できるか？」「請求方式を切り替えられるか？」といった問いがそれに当たる。このようなルールを分離する際、陥りやすい罠が一つある。Martin Fowlerが名付けた 貧血ドメインモデル（Anemic Domain Model） である。

貧血ドメインモデルとは、型はドメインの言葉で適切に定義されているのに、その上で動作するルールがドメインの外へ散らばっている状態を指す。税務申告（Filing）ドメインを例にしよう。型はすっきりしている。

// types/filing.ts
export interface TaxFiling {
  id: string;
  status: "draft" | "submitted" | "reviewing" | "completed" | "amended";
  taxYear: number;
  filingType: "regular" | "late" | "amendment";
  determinedTax: number;
}

ところが、この型に関する判定・遷移ルールは、別の場所に埋め込まれている。

// utils/filingHelpers.ts
export function canAmendFiling(filing: TaxFiling) {
  return filing.status === "completed" && filing.filingType !== "amendment";
}
 
// components/FilingDetail.tsx
function FilingDetail({ filing }: { filing: TaxFiling }) {
  // 같은 도메인 규칙을 컴포넌트 안에 다시 작성한다
  const canEdit = filing.status === "draft" || filing.status === "reviewing";
  // ...
}
 
// hooks/useSubmitFiling.ts
export function handleSubmitFiling(filing: TaxFiling) {
  if (filing.status !== "draft") return;
  // ...
}

同じドメインルールが、utils、コンポーネント、フックの三か所に、それぞれ異なる形で存在している。この状態で「請求可能条件を変更します」という要件が入れば、修正すべき場所を探し回ることになる。そして一か所でも見落とせば、サイトのどこかで誤った判定が行われる。Fowlerはこのようなコードを、「オブジェクト指向の皮をかぶった手続き的コードと変わらない」 と批判した。

解決策は、前節で計算ロジックに適用したものと同じである。ルールを型の隣に置く。

export interface TaxFiling {
  id: string;
  status: FilingStatus;
  taxYear: number;
  filingType: FilingType;
  determinedTax: number;
}
 
export type FilingStatus =
  | "draft"
  | "submitted"
  | "reviewing"
  | "completed"
  | "amended";
 
export type FilingType = "regular" | "late" | "amendment";
 
// 도메인 규칙은 도메인 옆에 둔다
export function canEdit(filing: TaxFiling): boolean {
  return filing.status === "draft";
}
 
export function canSubmit(filing: TaxFiling): boolean {
  return filing.status === "draft" && filing.determinedTax >= 0;
}
 
export function canAmend(filing: TaxFiling): boolean {
  return filing.status === "completed" && filing.filingType !== "amendment";
}

これで、申告に関するルールはdomain/filing.tsの一か所で管理される。どのコンポーネントでもcanAmend(filing)を呼び出せばよく、ルールが変わればこのファイルだけを修正すればよい。重要なのは、型と、その上で働くルールを一つのまとまりとして捉えることだ。 型だけをドメインフォルダに置き、ルールをutilsへ切り出す部分的な分離は、見た目がすっきりしていても、依然として貧血状態である。

APIレスポンスとドメインモデルの間の変換層

実務では、もう一つ考慮すべきことがある。バックエンドのAPIレスポンス構造とフロントエンドのドメインモデルが、常に一致するとは限らない点だ。国の機関と連携する税金サービスなら、なおさらである。韓国国税庁のHometaxから連携されるデータは略語やコード値にあふれており、フロントエンドのドメインモデルと同じ形で返ってくる可能性は低い。

そこで必要になるのが 変換層（Mapper） である。APIレスポンスの型をそのままコンポーネントまで流すのではなく、一度ドメインの型へ整えてから使う。純粋関数が一つあれば十分だ。

import type { Income } from "../domain/tax";
 
interface HometaxIncomeResponse {
  총수입금액: number;
  경비율: number;
  소득유형코드: string;
  // ... 나머지 약어 필드들
}
 
export function toIncome(response: HometaxIncomeResponse): Income {
  return {
    총수입_금액: response.총수입금액,
    경비_비율: response.경비율,
  };
}

こうすれば、APIレスポンスの총수입금액、경비율のような略語やコード値による分類を、フロントエンドのドメインに合わせて 一か所で 変換できる。所得区分コードのようにenumへ展開する必要がある値には、mapper内に小さなlookup tableを置けばよい。Hometax APIのフィールド名が変わっても、mapper一つを修正するだけで済む。

ユーティリティ関数とドメインロジック

ドメインロジックを分離していると、必ずぶつかる問いがある。「これはユーティリティ関数ではないのか？」

たとえば、次の二つの関数を見てみよう。

function formatCurrency(amount: number): string {
  return `${amount.toLocaleString()}원`;
}
 
function calculateTax(taxableBase: number): number {
  const bracket = TAX_BRACKETS.find((bracket) => taxableBase <= bracket.limit);
  return Math.floor(taxableBase * bracket.rate - bracket.progressiveDeduction);
}

formatCurrencyは、数値を文字列へ変換する純粋な プレゼンテーション（Presentation）ロジック である。「ウォン」という単位を付け、3桁ごとにカンマを入れることはビジネスルールではなく、ユーザーにどう見せるかに関するものだ。一方、calculateTaxには「8段階の累進税率を適用する」という、税法に基づくビジネスルール が含まれている。これはUIがなくても同じように適用されるべき、ドメインのルールである。

筆者が実務で用いる判断基準は、次のとおりだ。

このロジックがなくなったとき、ビジネスが壊れるのか、それとも画面だけが壊れるのか？

ビジネスが壊れるならドメインロジックであり、画面だけが壊れるならプレゼンテーションロジックである。この問い一つで、ほとんどの境界を区別できる。

しかし、現実はそれほど明快ではない。最も厄介なのは、ドメインロジックのように見えて、実際にはプレゼンテーションロジックである場合だ。

次のコードを見てみよう。FilingStatusというドメインの概念を引数として扱うため、ドメインロジックに分類している。しかし、本当にこれはドメインロジックなのだろうか？

// domain/filing.ts
function getStatusBadgeColor(status: FilingStatus): string {
  const colors: Record<FilingStatus, string> = {
    draft: "gray",
    submitted: "blue",
    reviewing: "yellow",
    completed: "green",
    amended: "purple",
  };
  return colors[status];
}
 
function getStatusDisplayText(status: FilingStatus): string {
  const labels: Record<FilingStatus, string> = {
    draft: "작성 중",
    submitted: "제출 완료",
    reviewing: "검토 중",
    completed: "신고 완료",
    amended: "경정청구",
  };
  return labels[status];
}

getStatusBadgeColorとgetStatusDisplayTextは、FilingStatusというドメインの概念を使ってはいるが、行っているのは 画面上の表現 である。バッジの色が変わっても、ビジネスには何の影響もない。このような関数をdomain/filing.tsへ入れると、ドメインモジュールが次第に肥大化し、本当のドメインロジックとプレゼンテーションロジックが混在することになる。

ドメインモデルとViewModelの分離

この問題を解決する実用的な方法がある。同じドメインフォルダ内で、ViewModelを別ファイルに分離することだ。.ui.tsではなく.viewModel.tsという名前を使えば、MVVMパターンのViewModelという概念へ自然につながる。「ドメインデータを画面に合わせて変換する層」という役割が、名前からすぐに伝わるためだ。

domains/
└── filing/
    ├── filing.ts              # 순수 도메인 모델 + 도메인 로직
    ├── filing.viewModel.ts    # ViewModel (표현 변환 계층)
    ├── filing.test.ts         # 도메인 로직 테스트
    └── filingMapper.ts        # API ↔ 도메인 변환

先ほど見たgetStatusBadgeColor、getStatusDisplayTextを、そのままfiling.viewModel.tsへ移す。さらに、getFilingTypeLabel(type: FilingType): stringのように、申告の種類を韓国語のラベルへ展開する変換もここへ集める。filing.tsはビジネスルールだけ、filing.viewModel.tsは画面上の表現だけを担う。

重要なのは 依存関係の向き である。filing.viewModel.tsはfiling.tsをimportするが、filing.tsはfiling.viewModel.tsを決してimportしない。ドメインはプレゼンテーションを知らず、プレゼンテーションがドメインを知る構造だ。これはRobert C. Martinが述べた依存性のルール（Dependency Rule）の縮図といえる。

筆者は、一緒に変更されるファイルは同じディレクトリに置くべきだと考え、同じフォルダへ配置した。FilingStatus型に新しい値（たとえば'rejected'）が加われば、filing.tsとfiling.viewModel.tsの両方を修正しなければならない。同じフォルダにあれば、修正範囲をひと目で把握できる。

境界と凝集

ドメインロジックを分離することと同じくらい重要なのが、どこに境界を引くか である。筆者が実務でよく直面する境界判断の問題を、いくつか整理してみよう。

フロントエンドで扱うデータは、おおむね四つの出所に分けられる。

• サーバーデータ：APIレスポンスとして受け取ったもの
• 派生データ：サーバーデータから計算されたもの
• UI状態：画面制御のためのもの、ユーザーの操作
• ユーザー入力：フォームへの入力途中のもの

この四つを一つの型に混ぜると、ドメインモデルが汚染される。

// 안티패턴: 모든 것이 섞인 타입
interface TaxFiling {
  // 서버 데이터 (도메인)
  id: string;
  status: FilingStatus;
  determinedTax: number;
 
  // 파생 데이터 (도메인)
  refundAmount: number;
  canAmend: boolean;
 
  // UI 상태 (표현)
  isExpanded: boolean;
  activeStep: number;
 
  // 임시 상태
  editingDeductions: Deduction[];
}

この型には、ドメインの概念、UI状態、一時データが一つのかごに入っている。activeStepが変わるたびに、申告ドメインが更新されることになる。（フォームのステップが変わることは、ビジネスイベントではない。）

改善するには、境界に従って型を分離する。ドメインモデルにはid、status、determinedTaxのようなビジネスの概念だけを、UI状態（FilingFormViewState）にはisExpanded、activeStepのような画面制御だけを、フォーム状態（DeductionEditForm）には入力途中の一時データだけを含める。

こうすれば、それぞれの型が 一つの変更理由 だけを持つ。ドメインの型は税法が変わるときだけ、UI状態は画面設計が変わるときだけ、フォーム状態は入力UXが変わるときだけ修正される。

一緒に変わるものは一緒に置こう

Eric EvansのDDDには、Aggregate（集約） という概念がある。「関連するオブジェクトのまとまりを一つの単位として扱うこと」である。フロントエンドでこの概念をそのまま適用する必要はないが、一緒に変わるデータとルールは一緒に置く。 という中心的な原則は参考にできる。

税金サービスを例にすると、Income（所得）とExpenseRate（必要経費率）は常に一緒に変わる。所得区分が変われば適用される必要経費率も変わり、総合所得金額の計算にも影響する。したがって、これらは一つのファイルdomain/tax.tsへまとめる。

一方、TaxFiling（申告書）は税額計算とは別に変わり得る。申告書の状態遷移ルールが変わっても、税率の計算ロジックには影響しない。そのため、domain/filing.tsへ分離するのが適切である。

이렇게 묻자: "A가 변할 때 B도 반드시 변해야 하는가?"
  → Yes: 같은 모듈에 둔다 (Income + ExpenseRate + TaxBracket)
  → No: 분리한다 (Tax 계산 ↔ Filing 상태관리)

Classと関数型

ここまで読むと、一つの根本的な疑問が浮かぶかもしれない。これまでの例はすべてinterfaceと純粋関数の組み合わせだったが、Classでドメインを表現すれば、凝集がより自然になるのではないだろうか？

そのとおりである。Classベースでドメインを表現すると、データと振る舞いが一つのオブジェクトにまとまるため、凝集がコード構造にそのまま現れる。

class TaxFilingModel {
  constructor(
    public readonly id: string,
    public readonly status: FilingStatus,
    public readonly taxYear: number,
    public readonly filingType: FilingType,
    public readonly determinedTax: number,
  ) {}
 
  canEdit(): boolean {
    return this.status === "draft";
  }
 
  canAmend(): boolean {
    return this.status === "completed" && this.filingType !== "amendment";
  }
 
  canSubmit(): boolean {
    return this.status === "draft" && this.determinedTax >= 0;
  }
}
 
const filing = new TaxFilingModel(
  "F-001",
  "completed",
  2025,
  "regular",
  547200,
);
 
filing.canAmend();

Classベースで書けば、振る舞いがデータへ帰属する。そして、利用側で主語が明確になる。filing.canAmend()は、まるで自然言語を読むように直感的だ。主語（filing）と動詞（canAmend）がはっきり結び付いている。jihoon.eat('감자탕')と書けば、「ジフンがカムジャタンを食べる」とすぐに読み取れるのと同じだ。

一方、関数型スタイルでは次のようになる。

canAmend(filing);
eat("jihoon", "감자탕");

関数型では、データが外部に存在する。上の二つのコードは、filingというデータを引数として受け取り、何らかの動作を実行する。eat関数は、jihoonと감자탕というデータを引数として受け取って実行する。

結果として、主語と動詞の結び付きが弱くなる。canAmendという関数がTaxFilingに関係することは、ファイルを開くか型シグネチャを確認しなければ分からない。さらに、同じファイルにcanAmend(filing)、canEdit(filing)、calculateTax(taxableBase)のような関数が混在すれば、どの関数がどのドメインに属するのかをひと目で把握しにくくなることがある。

では、Classを使うべきか？

正直に言えば、答えは 「状況による」。しかし、筆者の経験上、React + TypeScript環境でClassが万能ではない現実的な理由がある。

1. Reactの状態管理との摩擦

Reactの状態管理は、基本的に Plain Object と最も自然に組み合わせられる。useStateやuseReducerは技術的にはどんな値でも保持でき、Redux DevTools自体がClassインスタンスのプロトタイプを取り除くわけでもない。ただし、Redux/Zustandの永続化ミドルウェアが状態をJSONとして保存・復元すると、ClassインスタンスはJSON.stringify → JSON.parseのサイクルでメソッドとプロトタイプを失い、plain objectになる。一方、React Server ComponentからClient Componentへpropsを渡す境界は、対応するシリアライズ可能な（serializable）値だけを受け付けるため、任意のClassインスタンスはそもそも渡せない。

次のコードを見てみよう。

const [filing, setFiling] = useState(
  new TaxFilingModel("F-001", "draft", 2025, "regular", 0),
);

Reactの状態を更新するだけなら、filingがTaxFilingModelのインスタンスでなくなることはない。ただし、Redux/Zustandの永続化でJSONとして保存・復元されると、値がメソッドのないplain objectになる可能性があり、何気なく呼び出したfiling.canAmend()がランタイムエラーを起こし得る。React Server ComponentからClient Componentへ渡す場合は、Classインスタンスが対応するシリアライズ形式ではないため、受け渡しの時点で失敗する。

2. イミュータビリティを保証する難しさ

Reactは、状態の変更を 参照同一性（referential equality） に基づいて検出する。Classインスタンスのメソッドがthis.items.push(...)のように内部を変更しても参照は同じままなので、Reactは再レンダリングをトリガーしない。そのため、結局はaddDeduction(item)がreturn new DeductionList([...this.items, item])のように毎回新しいインスタンスを返すよう実装しなければならない。そうなると、Classの利点である「カプセル化された状態変更」の意味が薄れ、関数型の更新とさほど変わらないコードになる。

関数型で凝集を確保する方法

では、関数型スタイルでeat('jihoon', '감자탕')のような、凝集の弱さに関する問題をどう改善できるだろうか？筆者が効果的だと感じた三つの方法を紹介する。

1. モジュールの名前空間で凝集させる

最も直感的な方法である。ファイル（モジュール）自体をドメイン単位にし、import時に名前空間を利用する。先ほど定義したdomain/filing.tsをそのまま使えばよい。

import * as FilingModel from "../domain/filing";
 
FilingModel.canEdit(filing);
FilingModel.canAmend(filing);
FilingModel.canSubmit(filing);

FilingModel.canAmend(filing)はfiling.canAmend()ほどではないが、少なくともこの関数がFilingドメインに属することがコードからすぐに分かる。関数が複数のドメインにまたがって混在するリスクもなくなる。

2. 最初の引数をドメインの主体に統一する

関数型で凝集を表す、もう一つの規約がある。最初の引数を常に「振る舞いの主体」にする。 canAmend(filing)、calculateTotalIncome(income)のようにシグネチャを統一すると、canAmend(filing)は「filingについてcanAmendかどうかを問う」と読める。Unixのパイプラインという考え方（data |> transform）にも通じる。実際、Goのメソッドレシーバーはまさにこのパターンであり、Rustのimplブロックでselfを最初の引数として受け取るのも同じ発想である。

3. ドメインオブジェクトの生成関数（Factory）で振る舞いをまとめる

Classの凝集性が欲しいときに使えるパターンである。ファクトリ関数がドメインオブジェクトとその振る舞いをまとめて返す。

export function createFilingModel(data: TaxFiling) {
  return {
    ...data,
    canEdit: () => data.status === "draft",
    canSubmit: () => data.status === "draft" && data.determinedTax >= 0,
    canAmend: () =>
      data.status === "completed" && data.filingType !== "amendment",
  } as const;
}
 
const filing = createFilingModel(rawFiling);
filing.canAmend();
filing.canEdit();

このパターンなら、Classの表現力（filing.canAmend()）と、オブジェクトリテラルで振る舞いを構成する関数型の実用性を同時に得られる。ただし、返されるオブジェクトは関数プロパティを持つため、それ自体はJSONシリアライズ可能なデータではない。毎回関数オブジェクトを新しく作るコストもあるが、フロントエンドで扱うデータ量なら、パフォーマンス上の問題になることはほとんどない。

どこまで分離するべきか？

Clean Architectureを読むと、3〜4層に分けてPort/Adapterを定義する理想的な構造が示されている。しかし、実際にすべてのプロジェクトへこの構造を適用するのは、過剰設計（over-engineering）になり得る。

筆者が考える実用的な基準は、次のとおりだ。

• ドメインの型をAPIレスポンスの型から分離する。interfaceでもtypeでも、フロントエンドで使用するドメインの概念を別ファイルに定義する。
• ビジネスルールを含むロジックは、コンポーネントの外へ出す。 domain/フォルダでなくてもよい。重要なのは、Reactに依存しない純粋関数にすることである。
• APIレスポンス → ドメインモデルへの変換を一か所で行う。 Mapper関数でもZodスキーマでも、その一か所だけを修正すれば変更が波及しない構造にする。

プロジェクトが複雑になったら、次のような対応も検討できる。

• Bounded Context単位でフォルダを分ける。 Tossフロントエンドチャプターでも、「一緒に変更されるファイルを同じディレクトリに配置する」という原則を強調している。ドメイン単位でフォルダを分ければ、importパスがドメインの境界を自然に表す。
• Use Case層を導入する。 ドメインロジックの組み合わせが複雑になったら、「所得情報の取得 → 必要経費率の適用 → 控除項目の計算 → 税額の算出 → 還付額の確定」というシナリオを一つの関数にまとめるApplication層が必要になる。

src/
├── domains/
│   ├── tax/
│   │   ├── tax.ts                  # 세액 계산 도메인 (세율, 공제, 계산 파이프라인)
│   │   ├── tax.viewModel.ts        # 세액 표현 (금액 포맷, 구간 라벨)
│   │   ├── tax.test.ts             # 세액 계산 테스트
│   │   └── incomeMapper.ts         # 홈택스 API ↔ 도메인 변환
│   ├── filing/
│   │   ├── filing.ts               # 신고 상태 도메인 (상태 전이, 권한)
│   │   ├── filing.viewModel.ts     # 신고 표현 (상태 배지, 라벨)
│   │   ├── filing.test.ts
│   │   └── filingMapper.ts
│   └── deduction/
│       ├── deduction.ts            # 공제 항목 도메인 (자격 조건, 한도)
│       └── deduction.viewModel.ts
├── hooks/                           # React 의존 로직
├── components/                      # UI 컴포넌트
└── api/                             # API 호출

「税金」という一つのドメインの中でも、税額計算（tax）、申告管理（filing）、控除項目（deduction） は、それぞれ独立したサブドメインに分けられる。税率が変わっても申告状態の遷移ロジックには影響せず、控除項目が追加されても申告書の提出フローはそのままである。これがBounded Contextの実践的な適用である。

まとめ

まとめると、ドメインは私たちが解決しようとする問題領域であり、ドメインモデルはその問題を選択的に抽象化した概念体系、ドメインオブジェクトモデルはその概念体系をコードとして実装したもの、そして ドメインオブジェクトはその実装内の個々のオブジェクトである。

そして、これらの概念をフロントエンドで実践するとは、単にフォルダを分けることではなく、何層もの境界を意識的に判断することである。「これはビジネスルールか、プレゼンテーションロジックか？」「このデータはドメインの状態か、UIの状態か？」「この関数は十分に凝集しているか？」。こうした問いを習慣的に投げかけるだけでも、コードの構造は自然と改善される。

もちろん、すべてのプロジェクトでClean Architectureの層をすべてそろえる必要はない。単純なCRUDアプリを4層に分け、すべてのドメインにFactoryパターンを適用するのは、本末転倒である。Classの優れた凝集性と関数型の実用的な柔軟性のどちらを選ぶかは、プロジェクトの複雑さとチームのコンテキストによって決まる。

唯一の正解はない。しかし少なくとも、「ドメインが何かを知らずにコードを書くこと」 と 「ドメインを認識し、境界を判断し、意識的に分離すること」 の間には明確な違いがある。この記事を読んだ方にも、自分のプロジェクトで「ここでのドメインは何だろう。そして、このコードはどこに置くべきだろう？」と一度問いかけてみてほしい。

参考資料

以前からコードレビューやリファクタリングに関心があった筆者は、Tossが公開した「Frontend Fundamentals 模擬試験」という興味深い形式の課題に取り組むことになった。課題は、与えられた会議室予約アプリをリファクタリングするというものだった。テストコードも用意されており、リファクタリングの過程で機能が壊れていないかを検証できるセーフティネットが整っていた。

最終的に2日間かけてリファクタリングを行った。ここでは、その過程で感じたことをまとめてみようと思う。

初めてコードに向き合ったとき

コードを初めて開いたとき、筆者が真っ先にしたのはテスト仕様を読むことだった。テストコードは、このアプリケーションが何をすべきかを最も正直に教えてくれるドキュメントだからだ。App.easy.spec.tsxとApp.hard.spec.tsxに目を通し、アプリケーション全体の要件を把握した。

次に実際のコードを確認すると、目に入ったのは2つのモノリシックなコンポーネントだった。

• ReservationStatusPage は400行あまりのコンポーネントで、日付選択、タイムラインの可視化、予約詳細のツールチップ、自分の予約一覧、キャンセル機能がすべて1つのファイルに収められていた。
• RoomBookingPage は300行あまりのコンポーネントで、フィルター、部屋一覧、予約作成ロジック、URLパラメーターの同期がひとつに絡み合っていた。

筆者はコードを読みながら、「改善が必要だ」と判断するより先に、まずコードの性質を分類することに集中した。どのコードがドメイン情報を持ち、どのコードがユーティリティの役割を担い、どのコードが純粋なUIレイヤーなのかを見分けていった。

// 도메인 정보: 장비 라벨, 타임 슬롯 등 비즈니스 상수
const EQUIPMENT_LABELS: Record<string, string> = {
  tv: 'TV', whiteboard: '화이트보드', video: '화상장비', speaker: '스피커',
};
 
// 유틸리티: 날짜 포맷, 시간 변환
function formatDate(date: Date): string { ... }
function timeToMinutes(time: string): number { ... }
 
// 서버 상태: 인라인 useQuery, useMutation 호출
const { data: rooms = [] } = useQuery(['rooms'], getRooms);
const { data: reservations = [] } = useQuery(['reservations', date], () => getReservations(date));
 
// UI + 비즈니스 로직 혼재: 필터링, 정렬, 충돌 감지가 JSX 사이에 산재

このように性質ごとに分類しておくと、どこから手を付けるべきかが自然と見え始めた。それぞれのコード領域に簡単なコメントを付け、改善の方向性をメモしていった。（今の会社に入社した当時、jQueryベースのプロジェクトを移行していたときと似た気分だった）

では、どこから手を付けるべきだろうか。

リファクタリング戦略を立てる

筆者は、次の順序でリファクタリングを進めることにした。

1. サーバーコードの整理：queryとmutationの分離
2. ドメインロジックの分離：Equipment、Room、Reservationモデル
3. 型定義：ドメインモデルに基づく型体系の整理
4. ユーティリティ関数の分離：日付フォーマット、タイムライン計算など
5. UIレイヤーの分離：コンポーネントを関心事ごとに適切な粒度で分ける
6. 抽象化と関心の分離：エラー／ローディング処理、クエリキー管理

この順序を選んだのは、依存関係の外側から内側へ進めるためだ。インフラ（サーバーコード、ユーティリティ）から整理し、ドメインモデルを確立したあと、最後にUIを整える。もしUIコンポーネントを先に分割すると、まだ整理されていないドメインロジックやクエリコードを複数のコンポーネント間で何度も移動させることになりかねない。

戦略が決まったところで、一つずつ実行に移そう。

サーバーコードとユーティリティから整理する

日付表示ユーティリティの分離

最初に手を付けたのはformatDate関数だった。2つのページで同じ関数がそれぞれインライン定義されていたためだ。

// utils/formatYYYYMMDD.ts
export function formatYYYYMMDD(date: Date): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const date = String(date.getDate()).padStart(2, '0');
  return `${year}-${month}-${date}`;
}

小さな変更ではあるが、リファクタリングの最初のコミットとして重要な意味があった。最も独立していて副作用の少ない部分から触り、テストが引き続き通るかを確かめるウォームアップのようなものだ。

React Queryフックの分離

次に、コンポーネント内へ直接記述されていたuseQuery、useMutationの呼び出しを別ファイルに分離した。queryOptionsパターンを活用し、クエリ設定を再利用可能な単位にまとめた。

この過程で、remotes.tsにあったAPIレスポンスの型も明示的に定義した。従来はanyのまま流れていた型が、GetRoomsResponse、GetReservationsResponseなどとして明確になった。

インフラレイヤーを整理できたので、次はドメインモデルに目を向けよう。

ドメインモデルの分離

リファクタリングにおける最大の転換点は、ドメインモデルを独立したmodels/ディレクトリへ分離したことだった。

従来のコードでは、EQUIPMENT_LABELSやTIME_SLOTSのようなビジネス上の定数がコンポーネントファイルの先頭に宣言されていた。RoomやReservationの型もサーバーハンドラー（_tosslib/server/types.ts）にしか存在せず、クライアントコードではanyに近い状態で使われていた。

// models/equipment.ts
export const EQUIPMENT_LABELS = {
  tv: 'TV', whiteboard: '화이트보드', video: '화상장비', speaker: '스피커',
} as const;
 
export type Equipment = keyof typeof EQUIPMENT_LABELS;
export const ALL_EQUIPMENT = Object.keys(EQUIPMENT_LABELS) as Equipment[];

// models/reservation.ts
export interface Room {
  id: string;
  name: string;
  floor: number;
  capacity: number;
  equipment: Equipment[];
}
 
export interface Reservation {
  id: string;
  roomId: string;
  date: string;
  start: string;
  end: string;
  attendees: number;
  equipment: Equipment[];
}

なぜドメインモデルの分離が重要なのだろうか。ビジネスロジックがUIコンポーネントに依存していると、そのロジックを変更する際にコンポーネントのレンダリングロジックまで確認しなければならない。一方、models/ディレクトリに独立して存在していれば、ビジネスルールの変更をUIから切り離して行える。もちろん現実的に完全な分離は難しい。それでも少なくとも、「このロジックならここにあるはずだ」と予測できる構造を作ることが重要だ。

ドメインモデルを分離したことで、UIはどこまで軽くできるだろうか。

コンポーネントの解体

ReservationStatusPage

この作業は、最も劇的な変化をもたらしたコミットであり、最も時間がかかった。385行のモノリシックなコンポーネントを次のように分割した。

ReservationStatusPage/
├── index.tsx                    # 페이지 레벨
└── components/
    ├── DateSelector.tsx         # 날짜 선택 UI
    ├── ReservationTimeline.tsx  # 타임라인
    └── MyReservation.tsx        # 내 예약 목록 + 취소

分割の基準は、**「このコードが独立して意味を持つか」**だった。タイムラインの可視化は、日付に応じた予約データを受け取ってグリッドを描画する独立した関心事だ。自分の予約一覧は、ユーザーの予約データを取得してキャンセルする独立した関心事だ。それらが同じファイルにある理由はなかった。

分割後のindex.tsxは、**オーケストレーター（orchestrator）**としての役割だけを担うようになった。状態管理、メッセージの表示、子コンポーネントの組み合わせを担当するだけで、実際のデータ取得やレンダリングの詳細は子コンポーネントへ委ねた。

RoomBookingPage

予約ページも同じ原則で分割した。

RoomBookingPage/
├── index.tsx                    # 페이지 레벨
├── components/
│   ├── BookingFilter.tsx        # 날짜, 시간, 인원, 장비, 층 UI
│   └── AvailableRoomList.tsx    # 예약 가능 방 목록
└── hooks/
    └── useBookingParams.ts      # URL searchParams 기반 상태 관리

この過程では、ひとつ興味深い選択があった。当初はreact-hook-form + zodを導入してフォームのバリデーションを試みた。しかし最終的にはそれを取り除き、カスタムフックuseBookingParamsへ置き換えた。この決定については、後ほど詳しく説明する。

ここまで読めば、自然とひとつの疑問が浮かぶ。いったいどこまで抽象化すべきなのだろうか。

抽象化の適切なライン

このセクションは、筆者が今回の模擬試験で最も悩んだ部分だ。

ネストした条件文は、どこまで分解すべきか

会議室が予約可能かを判定するロジックには、複数の条件が組み合わされている。収容人数が十分か、必要な設備があるか、希望する階と一致するか、時間が重なっていないか。元のコードでは、これらすべての条件がひとつのfilterコールバック内にインラインで記述されていた。

筆者はこれをmodels/roomFilter.tsへ抽出し、各条件を名前の付いた関数に分けた。

const isEnoughCapacity = (room: Room, attendees: number) => room.capacity >= attendees;
const hasRequiredEquipment = (room: Room, equipment: Equipment[]) =>
  equipment.every(eq => room.equipment.includes(eq));
const isOnPreferredFloor = (room: Room, floor: number | null) =>
  floor === null || room.floor === floor;
const hasNoTimeConflict = (room: Room, reservations: Reservation[], date: string, start: string, end: string) =>
  !reservations.some(reservation => reservation.roomId === room.id && reservation.date === date && reservation.start < end && reservation.end > start);
 
export function filterAvailableRooms(rooms: Room[], reservations: Reservation[], params: Params): Room[] {
  return rooms
    .filter(room =>
      isEnoughCapacity(room, params.attendees) &&
      hasRequiredEquipment(room, params.equipment) &&
      isOnPreferredFloor(room, params.floor) &&
      hasNoTimeConflict(room, reservations, params.date, params.startTime, params.endTime)
    )
    .sort((a, b) => {
      if (a.floor !== b.floor) return a.floor - b.floor;
      return a.name.localeCompare(b.name);
    });
}

ここで重要なのは、抽象化できる明確な名前がある場合に限って関数へ分割したことだ。isEnoughCapacityやhasRequiredEquipmentという名前なら、実装を見なくても何をするのか予測できる。もしprocessRoomConditionsのような曖昧な名前にせざるを得ないなら、その抽象化はかえって読み手の認知負荷を高める可能性がある。

もちろん、これが唯一の正解というわけではない。ただ、筆者の判断基準は**「この関数名だけを見て動作を予測できるか」**だった。予測できるなら抽象化し、できないならインラインのままにするほうが、かえって可読性を高められると考えた。

searchParamsとフォームの状態

予約フィルターの状態をどこに置くかも、かなり悩んだ部分だった。元のコードではuseStateで各フィルター値を管理しつつ、useEffectでURLのsearchParamsと同期していた。

// 원본: useState + useEffect 동기화 방식
const [date, setDate] = useState(searchParams.get('date') || formatDate(new Date()));
const [startTime, setStartTime] = useState(searchParams.get('startTime') || '');
 
// ... 6개의 개별 상태
useEffect(() => {
  const params: Record<string, string> = {};
  if (date) params.date = date;
 
  // ... 모든 상태를 searchParams에 동기화
  setSearchParams(params, { replace: true });
}, [date, startTime, endTime, ...]);

筆者は最初にreact-hook-form + zodを導入し、フォームとして管理する方法を試した。しかし最終的にはこれを取り除き、**searchParamsを信頼できる唯一の情報源（Single Source of Truth）**として使うuseBookingParamsフックに置き換えた。

// useBookingParams: searchParams가 곧 상태
export function useBookingParams() {
  const [searchParams, setSearchParams] = useSearchParams();
 
  const params = useMemo<BookingParams>(() => ({
    date: searchParams.get('date') || formatYYYYMMDD(new Date()),
    startTime: searchParams.get('startTime') || '',
    // ...
  }), [searchParams]);
 
  const updateParam = useCallback(<K extends keyof BookingParams>(key: K, value: BookingParams[K]) => {
    setSearchParams(prev => {
      // 기존 파라미터 병합 후 업데이트
      return result;
    }, { replace: true });
  }, [setSearchParams]);
 
  return { params, updateParam };
}

この決定の核心にあったのは、**「状態が別々に動くのは適切ではない」**という判断だ。useStateとsearchParamsがそれぞれ状態を持つと、同期するタイミングによって不整合が起きる可能性がある。一方、searchParamsだけを状態として使えば、URLそのものがアプリケーションの状態となり、同期の問題自体がなくなる。ユーザーがURLを共有すれば同じフィルター状態を再現できるのは、おまけの利点だ。

ほかの参加者の振り返りにも、似た悩みが見られた。「URLのsearchParamsを信頼できる唯一の情報源として統一した」「個別のフィルターpropsをひとつのfilterオブジェクトへまとめる方法を選んだ」。表現は異なっていても、**「分散した状態をひとつの概念にまとめる必要がある」**という問題意識は同じだった。

安定性

SuspenseとErrorBoundary

コンポーネント構造が固まったあと、エラー処理とローディング処理を追加した。順序が重要なのは、境界（Boundary）をどこに設けるかは、コンポーネントツリーが決まって初めて判断できるからだ。

react-error-boundaryライブラリを使い、独立したデータ取得単位ごとにErrorBoundaryとSuspenseで囲んだ。タイムラインの取得に失敗しても自分の予約一覧は正常に表示されるべきであり、その逆も同じだからだ。

{/* 각 영역이 독립적으로 에러/로딩을 처리 */}
<ErrorBoundary FallbackComponent={ErrorFallback} resetKeys={[date]}>
  <Suspense fallback={<Loading message="예약 현황을 불러오는 중..." />}>
    <ReservationTimeline date={date} />
  </Suspense>
</ErrorBoundary>
 
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Suspense fallback={<Loading message="내 예약을 불러오는 중..." />}>
    <MyReservation onCancel={handleCancel} />
  </Suspense>
</ErrorBoundary>

Query Keyの一元管理

リファクタリングの過程でクエリフックを分離すると、query keyが複数のファイルへ分散する問題が生じた。mutationのonSuccessでinvalidationを行う際、どのkeyを使うべきか追いにくくなったのだ。

@lukemorales/query-key-factoryを導入し、クエリキーを一元管理するよう変更した。

// queries/queryKeys.ts
export const roomKeys = createQueryKeys('rooms', {
  list: { queryKey: null, queryFn: () => remotes.getRooms() },
});
 
export const reservationKeys = createQueryKeys('reservations', {
  list: (date: string) => ({ queryKey: [date], queryFn: () => remotes.getReservations(date) }),
  my: { queryKey: null, queryFn: () => remotes.getMyReservations() },
});

これにより、useSuspenseQueries({ queries: [roomKeys.list, reservationKeys.list(date)] })という形で利用でき、クエリキーと取得関数が常に一緒に扱われるようになる。また、routeのパスもPATHS定数へ抽出し、文字列のハードコーディングを取り除いた。

出題者の意図は何だったのか

リファクタリングを終えたあと、筆者は一歩引いて考えてみた。この模擬試験が評価しようとしていたものは何だったのだろうか。

ほかの参加者の振り返りを読み、興味深い共通点に気づいた。ほぼすべての記事に、**「コードは読むものではなく、予測するものだ」**という一文が登場していた。私たちの脳はコードを一行ずつ解釈するのではなく、経験から蓄積したパターンをもとに予測しながら読む。そして、その予測が外れたときに認知負荷が急激に高まる。

この観点から見れば、模擬試験が評価するのは単なるコーディング能力ではなく、**「同僚が読むコードを、どれだけ予測可能なものにできるか」**という協働の力なのだ。（出題者や同僚の心を読むことこそ、真のソフトウェアエンジニアの能力なのかもしれない）

ほかの参加者の振り返りを見ると、**「他人が書いたコードを理解するのは簡単ではない」「インターフェースを先に設計することは重要だが、膨大な既存コードを前にすると、そのアプローチが揺らぐこともある」という内容に共感した。筆者も同じような経験をした。既存のコードがすでに動いていると、その構造を合理化したくなる。「もう動いているコードなのに、わざわざ？」という考えだ。しかし模擬試験の核心は、その誘惑を乗り越え、「自分ではない誰かがこのコードを読んだとき、どれだけ早く把握できるか、自分の認識に基づいて問題を判断し解決していけるか」**を基準に判断することにあった。

リファクタリングから学んだこと

リファクタリングの順序が結果を左右する。 外側（インフラ）から内側（UI）へ進めるのが、途中で絡まない安全な道筋だった。ユーティリティとドメインモデルを整理してからコンポーネントを分割すると、各コンポーネントが何に依存しているのかが明確になった。

抽象化の判断基準は「名前」だ。 関数や変数として抽出したとき、その名前で動作を説明できるなら抽象化する価値がある。どうしても名前が曖昧になるなら、インラインのほうが適切な選択かもしれない。

状態を置く場所が、そのままアーキテクチャになる。 一緒に動くべき状態は同じ場所に置く必要がある。useStateとsearchParamsを同期させるよりも、searchParamsだけを信頼できる唯一の情報源として使うほうが、構造として健全だ。

おわりに

課題を終えたあと、2人の同僚と話をした。一人でコードを眺めていたときには見えなかったものが、対話を通じて考えを解きほぐす過程で姿を現し始めた。筆者が当然のこととして見過ごしていた構造上の選択に「なぜそうしたの？」と問われた瞬間、それまで意識していなかった判断の隙が見えてくる。

AIがコードの作成やレビューにかかる時間を劇的に減らしているのは事実だ。それでもコードレビューやデイリーミーティングが今なお重要だと思う理由は、まさにこうした経験にある。AIはコードの整合性を検証できるが、**「あなたが見落としている観点はこれだ」**と指摘するのは、結局のところ同じ文脈を共有する同僚の役割だ。自分には見えなかった部分の発見、そしてその発見を通じたプロダクトの安定化。これこそが協働の本質ではないだろうか。

問題を解いていく過程で書くコードに、唯一の正解はない。同じ模擬試験に取り組んだほかの参加者も、それぞれ異なる道筋を選び、それぞれに根拠があった。大切なのは、「なぜこのように書いたのか」を説明できることだ。この記事を読む方にも、一度は自分のコードを初めて見る人の視点で眺めてみることを勧めたい。その視点こそが、コードの品質を決める最も強力な基準になり得るだろう。

筆者がジュニアだった頃、特に印象深く読んだ記事の一つに、ペ・フィドンさんの「フロントエンドエンジニアのキャリアロードマップ、ジュニアのための3つの専門性トラック」がある。フロントエンドエンジニアのキャリアを、**Web特化（Software Engineer）／プロダクト特化（Product Engineer）／運用特化（Full-Stack Engineer）**という3つのトラックに分けて整理し、「優れたエンジニアに必要な5つの基礎能力」と「シニアになるための3つのポイント」まで押さえた記事だ。当時は、トラックごとにどんな力を伸ばすべきかを考えることが最大のテーマだった。ところが、この記事を読んでから2年も経たないうちに、テーマそのものがすっかり変わってしまった。

最近、同僚のエンジニアたちと話していると、ここ数年耳にしてきた悩みとは少し性質が違うと感じる。

• 「会社でAIを導入したんですが、デザイン案を渡せばほとんど全部作ってくれます。便利ではあるんですが……」
• 「採用市場がものすごく冷え込んでいますね」
• 「AIが書いたコードをそのままマージするのは怖いし、かといって一つひとつレビューすると効率が落ちるので悩んでいます」

筆者も同じような時期を経験したし、今も経験している。1〜2年前までは「AIは便利な補助ツール」くらいに考えていたが、今やAIなしで開発する姿そのものが想像できない環境になった（筆者もこの記事を書きながら、Claudeにリサーチを頼んでいる）。今回はペ・フィドンさんの記事の続編という位置づけで、この間に景色がどう変わったのか、そして変化した景色の中で、フロントエンドエンジニアとしてどんな力をさらに伸ばすべきなのかを、筆者なりの視点で整理してみたい。

今回もできる限り多くの資料を探して検証するよう努めたが、非常に変化の速い分野だけに、この記事が公開された時点ですでに一部の内容が古くなっている可能性があることを、あらかじめご了承いただきたい。反論や議論したい点があれば、いつでもコメントで知らせてほしい。

「もうAIが全部やってくれるんじゃないですか？」

まず確認しておかなければならないことがある。「AIが全部やってくれる」という文は事実なのか。どこまでが事実で、どこからが幻想なのか。

2025年2月、OpenAIの共同創業者で、テスラのAIディレクターも務めたAndrej Karpathyは、自身のTwitterに次のように投稿した。

私が「vibe coding」と呼ぶ新しい種類のコーディングがある。雰囲気に完全に身を委ね、指数関数的な成長を受け入れ、コードそのものが存在することさえ忘れるやり方だ。

There's a new kind of coding I call 'vibe coding', where you fully give in to the vibes, embrace exponentials, and forget that the code even exists.

**バイブコーディング（Vibe Coding）**とは、一言でいえば「AIにキーボードを渡し、欲しいものを自然言語で説明するだけのコーディング手法」だ。アーキテクチャ文書も、ボイラープレートも、セミコロン探しもない。ただバイブだけでコードが動いていく。この言葉は1年も経たないうちに、英語圏の開発者コミュニティで標準的な語彙として定着した。

ところが、ちょうど1年後の2026年2月、同じKarpathyが一歩後退した。彼はvibe codingという言葉を**「agentic engineering」**に置き換えようと提案する。両者の違いは明確だ。

• Vibe coding：欲しいものを説明し、出来上がったものを受け入れること
• Agentic engineering：システムを設計し、制約を仕様として定め、頭の中ですでに推論を終えた実装をAIで加速すること

1年前は「頼めば全部作ってくれます」が基本的な前提だったとすれば、今では「AIに何をどう指示するかを設計する力」そのものがエンジニアリング能力として定着している。この流れは、一人のツイートだけにとどまるものではない。同じ頃、GoogleのエンジニアであるAddy Osmaniは、Beyond Vibe Coding: From Coder to AI-Era Developerという本を出版し、「AIはアシスタントにすぎず、自律的に信頼できるコーダーではない。シニア開発者はあなたであり、LLMはあなたの判断を加速するために存在する」と明言した。

ツールは暴走する勢いで進化している

ツール側も、この流れに合わせて急速に進化している。2026年5月時点で最もよく言及されるコーディングツールは、Cursor、Claude Code、GitHub Copilot、Windsurf、v0 by Vercel、Bolt.new、Devinあたりだ。

とりわけ、v0の変化は象徴的だ。Vercelは「90% problem」という表現を使っている。現実の開発の90%は、既存のコードベースと既存のインフラの中で行われる、という意味だ。当初はグリーンフィールドのプロトタイプさえうまく作れればよかったv0が、今ではGitHubリポジトリを直接取り込んで作業し、デザインシステムを適用し、デプロイ環境変数を自動で取得して使う。「AIはおもちゃのようなデモしか上手に作れないのでは」というシニアたちの反論に、ツール側が直接答えているわけだ。

ビッグテックのコードベースが、この変化を最もよく表している。

GoogleのSundar Pichaiは、2024年10月の第3四半期決算説明会で「新しいコードの25%以上がAIで生成され、その後エンジニアがレビュー・承認したもの」だと発表し、2025年4月には30%以上に増えたと述べた。MicrosoftのSatya Nadellaは、2025年4月のLlamaConで「私たちのコードの最大30%はAIが書いたコード」だと明かした。Metaの社内目標は、「2026年前半までに、エンジニアの65%がコミットの75%以上をAIで生成する」という水準にまで引き上げられた。

韓国でも流れは変わらない。Tossは、開発者がもはや文書を探さずに済み、DXを高められるようAIベースのドキュメントシステムを構築し、さらに一歩踏み込んで「AI時代、デザイナーをなくしたら起きたこと」といったテーマも扱った。Daangnは毎週火曜日のAI Show & Tellでチームごとの実験を共有し、「エンジニアを超えてビルダーへ」という採用スローガンを掲げ始めた。Woowa Brothersは「AIがコードを書く時代、それでも開発者になりますか？」といった記事を通じて、「開発者の本質はコードではなく、問題を定義し解決する力にある」というメッセージを発信している。

しかし、数字は少し違う物語を語る

ここまでを見れば、「もう頼むだけで全部できるんだな」という結論に向かいやすい。ところが、実際のデータを詳しく見ると、話は少し違う。

ソフトウェア開発の現状を総合的に分析した2025 Stack Overflow Developer Surveyの数字から見てみよう。

• 開発者の84%が、AIツールを使用している、または使用する予定だと回答した（2024年の76%から上昇）。
• プロの開発者のうち51%が、AIツールを毎日使っている。
• しかし、AIツールに対する好意度（positive sentiment）はむしろ下がった。2023年と2024年には70%以上だった好意度が、2025年には60%まで落ち込んだ。
• 10年以上の経験を持つシニア開発者は、AIの出力に対する信頼度が最も低い。

要するに、**「みんな使ってはいるが、時間が経つほど信用できなくなっている」**ということだ。

METRという非営利研究所が2025年に行った実験は、この認識と現実の隔たりをさらに劇的に示している。平均5年の経験と平均1,500コミットの実績を持つ熟練したオープンソース開発者16人に246件の作業を依頼し、AIを使うかどうかを無作為に割り当てた対照実験だった。結果は次のとおりだ。

• 開始前、開発者たちは「AIを使えば24%速くなる」と予測した。
• 作業を終えた直後にも、「20%ほど速くなった気がする」と自己評価した。
• ところが、実測値では19%遅くなっていた。

研究チームが指摘した原因は興味深い。AIが生成したコードの採用率は44%以下で、却下したコードにもレビューとテストの時間がかかり、採用したコードでさえレビューと修正にかなりの時間を要したという。遅くなったのに速くなったように感じる錯覚。この隔たりが、シニア開発者たちがAIに対してますます懐疑的になる理由の一つだ。

さらに、「AIが書くコードの品質」そのものも盤石ではない。Veracodeが100以上のAIモデルにコードを書かせた実験を見てみよう。

• AI生成コードの45%にOWASP Top 10のセキュリティ脆弱性が含まれていた。
• XSS（クロスサイトスクリプティング）の防御に失敗した割合は86%。
• ログインジェクション（Log Injection）の防御失敗率は88%。
• 別の研究では、AIコードの脆弱性密度は人間のコードと比べて2.7倍高いと報告された。

フロントエンドに直結するXSSの失敗率86%は、とりわけ重く受け止めるべき数字だ。AIが書いたform inputをそのままマージすることが何を意味するのか、この数字がよく示している。（フロントエンドのセキュリティ監査を経験した開発者なら、dangerouslySetInnerHTMLを自分で直接書くときでさえ違和感を覚えて不安になるのに、AIがこっそり差し込んだものはさらに怖いと感じるだろう。）

品質面でも、同じような兆候が表れている。GitClearが2020〜2024年の間に行われた2億1,100万行のコード変更を分析した結果は次のとおりだ。

• 作成後2週間以内に元に戻された（reverted）コードの割合（Code Churn）：2020年5.5% → 2024年7.9%
• リファクタリングが占める割合：2021年25% → 2024年10%未満
• コピー＆ペースト（クローン）の割合：2021年8.3% → 2024年12.3%（2025年には実に4倍に増加）

解釈はそれほど難しくない。コードを素早く量産する力は高まった一方で、再び手を入れる価値のあるコードを書く力は低下したということだ。Fortune 50企業を分析したApiiroのデータでは、さらに強い傾向が見られる。AI支援を利用する開発者は、同僚の3〜4倍のコミットを生み出す一方、セキュリティ上の指摘事項は10倍多く生み出す。権限昇格経路（privilege escalation）は322%増、アーキテクチャ設計上の欠陥は153%増と急増した。

AIは何を代替し、何を代替できなかったのか

ツールは暴走する勢いで進化しているが、数字が示す実態は一筋縄ではいかない。ではAIは、具体的に何を代替し、何をまだ代替できていないのか。この区別を明確にしてこそ、どこに時間を投資すべきかが見えてくる。

代替されたのは、開発者が自らタイピングする比重だ。ボイラープレートや反復的なコードを書く場面は減り、デザイン案さえあれば、規約に沿った水準の画面が数分で出来上がる。構文やAPIを調べる時間も、学習曲線を上る時間も急激に短くなった。要するにAIは、「生産速度」を平準化した。

しかし、「判断」の領域はまだ代替できていない。（正確には「まだ期待を満たせていない」に近い。人によってAI活用能力には差があるだろうが、ここでは平均的な利用体験を基準に話を進める。）

最初に立ちはだかるのは、要件を仕様へ翻訳する作業だ。曖昧なビジネス要件を、正確なエッジケースとステートマシンに落とし込む作業には、今なお人の手がより深く必要になる。システム全体への影響を把握することも同様だ。このコンポーネントがバンドルにどのような影響を与えるのか、依存関係はツリーシェイキング可能なのか、データフェッチのパターンがCore Web VitalsのINP（Interaction to Next Paint）スコアにどう影響するのか。こうした問いにAIがもっともらしい答えを出しても、結局は人がもう一度確認しなければ安心できない。

先ほど見た45%のOWASP脆弱性の問題と同様に、セキュリティとリスク評価も欠かせない。新しいコンポーネントが既存システムのトークン、アクセシビリティルール、インタラクションパターンと整合しているかを見るデザインシステムと一貫性の維持、なぜこの機能が必要なのか、どのユーザーフローに組み込むべきなのかを考える顧客・市場の文脈理解といった領域も同じだ。

最後に、yceffortさんの記事にある表現を借りれば、「システムの複雑さと、チームがそのシステムを理解している度合いとの隔たり」、すなわち認知負債（Cognitive Debt）の管理は、むしろAI導入後により速く広がる領域だ。この隔たりを縮めること自体が、人の役割として残っている。

なくなるのは開発者ではなく、開発者がしていた仕事の形だ。ボトルネックが「作る速さ」から「決める速さ」へ移った。

同じ文脈で、Tossの「開発者はAIに代替されるのか」は、もう少し重い診断を下している。記事の要旨はこうだ。AIはすべての人員を代替するのではなく、徒弟制度の階段（apprenticeship ladder）を取り払いつつある。今のシニアたちが引退する10〜20年後には、複雑なシステムを設計する次世代の人材が不足するだろう。これは「うちの会社は来年どう採用しようか」という次元ではなく、業界全体に仕掛けられた時差式爆弾のような問題だ。（悩みの多い時期に、本当によく書かれた記事だと思う。）

AIが作ってくれる「動く最初のバージョン」は70%だ。「実際のユーザーに提供してもよいバージョン」に至るまでの30%が、人の領域だ。そして、その30%を埋める力は一朝一夕には身につかない。これが徒弟制度の階段をめぐる問題の本質だ。ボイラープレートや単純なコンポーネントを書きながら「手を汚す時間」がなくなれば、その30%を埋められる人も同時にいなくなる。

ペ・フィドンさんの元記事では、「優れたエンジニアに必要な5つの基礎能力」として、良いコードを書くこと、現在価値の最大化（迅速なリリースと長期的な保守性のバランス）、データに基づく意思決定、同僚の効果的な意思決定の支援、継続的な学習を挙げていた。5つすべてがAI時代にも有効だが、その中でも最後の項目が最も危うい位置にある。学習そのものがなくなったのではなく、学ぶ対象が変わった。以前は「このツールをどう使うか」を学んでいたとすれば、これからは「このシステム全体がどう動くのか」を学ぶことに時間を使わなければならない。さらに恐ろしいのは、Evan Moonさんが指摘した「AIがコード作成を代行した瞬間、脳の認知負荷が急激に減る問題」だ。認知負荷が減るのは一見よいことに聞こえるが、その負荷こそが学びの材料だったという点で危険だ。楽になるほど成長しない。

ここで自然に浮かぶ疑問がある。では、ペ・フィドンさんの記事にある3つのトラック（Web特化／プロダクト特化／運用特化）は、もう意味がないのだろうか。

筆者の考えは違う。トラックそのものは今も有効だ。ただし、それぞれのトラックがAI時代に合わせて一段階ずつ進化したと見るのが妥当だろう。トラックごとに景色がどう変わったのか、整理してみよう。

生産者から「検証者」へ

ペ・フィドンさんの元記事では、Web特化トラックはSoftware Engineerという名前でまとめられていた。「インターネット、Webブラウザ、HTML/CSS/JSに対する深い理解と活用」、Webエコシステムのツールの長所と短所を見極める力とトラブルシューティング経験、新しい技術に敏感な姿勢が核心であり、シニアへの道としては、Webエコシステムのツール開発会社のエンジニア／フロントエンドの教育者／複雑なプロダクト組織のテックリードが提示されていた。一言でいえば「ブラウザとHTML/CSS/JSの動作原理を深く掘り下げる人たち」であり、1〜2年前まで彼らの最大の武器は「誰よりも正確にコードを書けること」だった。

AI時代に彼らの価値はどう変わったのだろう。コードを書く速さだけを見れば、AIが追いついた。しかし、**「AIが書いたコードを正確に評価する力」**は、むしろ彼らがほぼ独占していると言ってよい。

• AIを使う一般の人：自分が望んだ要件どおりに実装されて、問題なく動いている。
• AIを使う開発者：動いてはいるが、この依存関係はこういう問題を引き起こす可能性があり、このパターンはこう改善したほうが規約に合っている。関連部分をもう一度確認しよう。

先ほど取り上げたVeracodeの研究には、XSSで86%、ログインジェクションで88%が防御に失敗したという数字があった。これを見つけて食い止められる人こそ、私たちのような専門家だ。彼らは、AIの成果物を品質管理（QA）するシニアの役割へと自然に進化していく。

もう一つ、専門家の領域にまったく新しいトピックが加わった。生成UI（Generative UI）とAIインターフェースデザインだ。LLMの応答をストリーミング表示するチャットUI、途中で停止できるabortコントロール、Markdownやコードブロックの段階的レンダリング、ツール呼び出しの結果をインラインで表示するUX、Vercel AI SDKやMCP（Model Context Protocol）を利用したアシスタント統合などがその例だ。この領域では、「Webの動作原理を正確に理解しながら、同時にLLMの動作特性も理解して応用・活用できる人」への需要が爆発的に高まっている。

Product Engineerへの自然な進化

プロダクト特化トラックは、最も大きな恩恵を受けたトラックだ。市場と顧客への理解が深く、外部のステークホルダーと頻繁にコミュニケーションを取る人は、AIが加わった瞬間、はるかに強力な武器を手にした。シニアへの道として、グロースエンジニア・コンサルタント／PM・PO・CPOへの転向など、他職種への広がりもあわせて提示されていたのが、このトラックの特徴だ。

興味深い変化は、このトラックの名称がグローバルスタンダードとして定着し始めたことだ。元記事でもすでにこのトラックを「Product Engineer」と呼んでいたが、記事を読んだ当時、筆者にとってはやや耳慣れない表現だった。それから1年が経った今では、Vercelが職務記述書の「Fullstack Engineer」を一斉に「Product Engineer」へ変更するほど定着している。

Lee Robinsonは、Product Engineerの核となる資質として3つを挙げている。

• 反復（Iteration）重視：デプロイ → フィードバック → 調整のサイクルを素早く回す。
• 顧客中心性：顧客と直接対話しながらプロダクトを改善する。
• 実用性：「技術選択はすべて手段にすぎない」。プロダクトの目標に貢献しないツールは思い切って捨てる。

ここで一つ注意したいのは、プロダクト特化エンジニアを「速く作る人」とだけ捉えるのは危険だということだ。AIが登場した今、その危険はさらに大きくなった。「機能を素早く実装すること」は、今やどの職種でもAIツールを使えばできるからだ。Product Engineerの違いは、「顧客の問題を正確に定義し、最小のソリューションで素早く検証する力」にあって、「手が速いこと」にあるのではない。

この流れの中で、Design Engineerという職種が正式なポジションへ格上げされ始めた。Vercelはデザインエンジニアを年俸20万ドル超の正式なトラックとして採用しており、LinearやStripeも同じ方向に動いている。フロントエンドとデザインの間のハンドオフそのものをなくす職種だ。AIが素早く絵を描いてくれるようになったからこそ、「何を描くか」と「描かれた結果が一貫したデザインシステムに沿っているか」を同時に扱う能力が、さらに希少になった結果だ。

AIオーケストレーター

運用特化トラックは、最も劇的に変わりつつあるトラックだ。ペ・フィドンさんの元記事では、このトラックをFull-Stack Engineerに分類し、「プロジェクトの構造・統合・テスト・デプロイに強い関心を持ち、簡単なAPIとインフラを自ら扱いながら、組織の隙間を埋め、プロセスを改善する人」と定義していた。その上に、この1〜2年でAIエージェントそのものを運用する役割が新たに加わり、トラックの裾野が急速に広がっている。

2026年のトレンドを整理する中で、**「コーディングエージェントのオーケストレーション（Orchestrating Coding Agents）」**という概念が中心的なものとして挙げられた。これは、一つのAIに指示することを超えて、複数のAIエージェントを同時に協働させるシステムを設計・運用することを意味する。同じ文脈で、彼は「agent-skills」というフレームワークを提案している。プロフェッショナルなワークフローや品質ゲート、業界のベストプラクティスを、エージェントの動作ロジックに直接組み込もうという意見も出ている。

関連資料をまとめてみたところ、筆者が考える、運用トラックのエンジニアが新たに扱うべきキーワードは次のとおりだ。

• MCP（Model Context Protocol）：Anthropicが提案した、LLMと外部ツールを接続するための標準
• AIガバナンス：誰がどのコンテキストでAIを使えるのか、シークレットが漏れていないかを管理
• エージェント評価（Evaluation）：エージェントが生み出した成果物を自動採点するパイプライン
• AIゲート：PRのマージ前に行う自動的なセキュリティ・品質検証、AIコードのラベリング

元記事では、運用トラックのシニアへの道として、大規模組織のプラットフォームチームのエンジニア／テックリード／アジャイルコーチ／テクニカルプログラムマネージャー（TPM）／CTOといった役割を挙げていた。この道は今も有効だが、そこに**「AI開発インフラリード」、「開発者生産性（DevProd）エンジニア」**といった新しい役割が加わったと考えればよい。

3つのトラックがそれぞれ進化する一方で、すべてのトラックに共通して、より重要になった能力がある。本来は5年後を基準に考えたかったが、最近の進歩の速さを見ると、1年という単位さえ長すぎるように感じる。そこで、ひとまず「来年」程度まで視野を狭め、筆者が今後さらに重要になると考える能力を見ていきたい。

5つの能力

一つ目は、仕様（Specification）を書く力だ。 AI時代における「コーディングの出発点」は、キーボードではなく仕様だ。AIに何をさせるかを正確に書き表す力が、コードそのものより重要になった。ここでいう仕様とは、大がかりなRFC文書ではない。ビジネスロジックに期待する動作をコードで記述したテスト、UIコンポーネントのシナリオと視覚的な契約を整理したStorybookのストーリー、データフローの契約を明示する型定義などだ。結局のところ、AIが作った成果物を自動で検証する基準をあらかじめ用意する作業であり、これがない状態でAIコーディングを進めれば、問題が積み重なっていく。

二つ目は、検証力と判断力だ。 AIは、もっともらしいが間違ったコードを自信満々に作り出す。そのため、「AIのコードを素早く正確にレビューする力」そのものが中核になると考えている。セキュリティヘッダー、入力値のサニタイズ、CSRFトークンを見落としていないか、アクセシビリティ（ARIA、キーボードナビゲーション、フォーカストラップ）が保たれているか、レンダリングコスト、メモリ、バンドルサイズなど、パフォーマンスへの影響に問題がないかを見極めることだ。レビューせずにAIスロップをPRへ投げ込むのは、エンジニアとしての職務放棄だ。マージボタンを押すのは今も人であり、その責任をAIに押しつけることはできない。Stack Overflowの調査でシニアのAIへの信頼度が最も低いのも、結局はこうした細部を見抜く目を持っているからである可能性が高い。

三つ目は、システム理解とアーキテクチャ思考だ。 AIは一度に一つのファイルをうまく扱い、フローや関連性を認識する力にも優れている。AIは症状を素早く直すが、能力の高い開発者は根本原因を探す。この力を伸ばす方法の一つは、Architecture Retrospectiveのような意識的な活動を行うことだ。コードの変化が速くなったぶん、チームのシステム理解も意識して引き上げなければ、認知負債が急速に蓄積する。

四つ目は、AIオーケストレーション能力だ。 AIそのものを扱う力も、独立したスキルセットとして分化しつつある。単にプロンプトを上手に書くという次元ではなく、作業を小さなチケットに細分化する力、同じ作業にどのモデルを使うか選ぶ力、エージェントの評価・検証パイプラインを設計する力、エージェントが失敗した際の復旧（rollback）戦略までを、一つのまとまりとして扱う領域になった。Steve Yeggeは、この流れを**6つのwave（traditional → completions → chat → coding agents → agent clusters → agent fleets）**に整理している。

五つ目は、Context Engineeringだ。 2025年半ばからKarpathyとShopifyのCEOであるTobi Lütkeがともに推し始めた概念で、一言でいえば「AIにどのコンテキストを、どのような形で、どの程度見せるかを設計する力」だ。具体的には、プロジェクトの規約、アーキテクチャ原則、禁止事項をAIが参照できる場所にまとめておくCLAUDE.md／rulesファイルの整備、すべてのファイルをコンテキストに入れず、関連するモジュールだけを選んで見せる意図的なコンテキストの縮小、計画 → 実装 → 検証を別々のセッションに分け、コンテキストの汚染を防ぐ明示的な段階分離、デザインシステム、APIスキーマ、モニタリングデータなどの外部コンテキストを標準インターフェースで接続するMCPを通じた外部コンテキストといった形で現れる。Anthropicの公式文書はこれを「the new prompt engineering」と呼び、単一のプロンプトだけでは、システムのアーキテクチャ知識、パターン、組織内の暗黙知を決して収められないと明言した。言い換えれば、「一度でよいプロンプトを書くこと」よりも、「AIが常によいコンテキストを受け取れるよう環境を設計すること」のほうが、はるかに重要になった。

ここまで読めば、自然な疑問が浮かぶ。では、具体的にどう学べばよいのか。筆者が実践している方法は、大きく4つある。

学び方

元記事で挙げられた「継続的な学習」という項目は今も有効だが、学習時間の配分を変えなければならない。

以前は多くの時間を使っていたものの、今では減らしてもよい領域がある。その一方で、以前は難しくて手をつけなかった領域や、時間のかかる複雑な領域もある。後者には、テスト仕様の作成、パフォーマンス測定ツールの活用（Lighthouse、WebPageTest、Chrome DevTools Performance）、アクセシビリティ（WCAG）、セキュリティ（特にOWASP Top 10）などがある。そして、Vercel AI SDK、LangChain.js、MCP、ストリーミングUIパターン、エージェント評価パイプラインのように、まったく新しく身につけるべき領域も存在する。自分に必要な能力が何かを認識し、時間を配分することが重要だ。

AIが生み出すコードは、大きくなりがちだ。1分間に数百行を出力する。そのため、PRのサイズとマージの周期を意識的に管理しなければ、コードレビューそのものが崩壊する。社内では、AI導入後に平均PRサイズが18%増、PR当たりのインシデントが24%増、変更失敗率が30%増となった。先ほどまでのデータとあわせて考えれば、大きく作って一度にマージすると、流れを把握して意図を反映するのが難しくなるため、作業単位を細分化することが重要だ。

Evan Moonさんの記事が指摘した、認知負荷の減少という問題に直結する話がある。1日に1〜2時間は、AIなしでコードを書く時間を別に確保するとよい。アーキテクチャを手で描いてみたり、慣れていない領域のコードを自分で一行ずつ読んだりすることが、その例だ。（筆者も毎日、昼食後の眠くなる時間帯にはAIなしでコードを書いている。昔からの感覚を手放さないよう、つなぎ止めておく時間だ。）

これは単に「昔のやり方を忘れないため」ではない。AIが代わりにやってくれる時間の分だけ、自分自身の深さも育たないからだ。検証力や判断力、システム理解といった能力は、自ら向き合った時間の関数である。

だから、私たちは

ここまで長く書いてきたが、実のところ、AI時代を生き残るフロントエンドエンジニアの姿は、元記事が示した結論とそれほど変わらない。元記事で挙げられていた、優れたシニアエンジニアになるための3つのポイントは次のとおりだった。

• 基本に忠実であろうと努める（5つの基礎能力を継続的に維持・強化する）。
• 明示的なリーダーでなくても、模範となる行動によって自然な影響力を発揮する。
• 与えられた仕事をうまく終わらせるだけで満足せず、前後の文脈に目を配り、大きな影響を生み出す。

これをAI時代の観点から捉え直すと、次のようになる。

• AIが作るコードの先にある基礎力（Web、システム、ドメイン）を大切にする。
• AIではなく、自分が方向を決める。明示的な責任者でないときでさえ、「どこへ向かうべきか」を判断する。
• AIを個人の生産性ツールとして使うだけでなく、チームとシステムのボトルネックを解消するために使う。

OpenAIの権威であるAndrej Karpathyの文章を見ると、彼が今強調している**「agentic engineering」**の核心も、結局は同じだ。システムを設計し、制約を仕様として定め、頭の中ですでに推論を終えた実装をAIで加速する。ツールが変わっても、方向を決めるハンドルは今も人の手にある、という話だ。

元記事が最後に伝えたメッセージも、結局は「与えられた仕事をうまく終わらせることに満足せず、前後の文脈に目を配り、大きな影響を生み出す人」がシニアになる、というものだった。AI時代には、その「インパクト」の定義が変わっただけだ。AIが1時間で作った画面を「動くからこれでいい」とマージする人と、その画面がアクセシビリティ、セキュリティ、パフォーマンス、システム整合性の面でどこまで妥当かを、さらに30分かけて確認する人がいる。1年後にシニアとして認められるのは後者だ。70%（動作）と30%（応用と活用）の境界で、30%側に立つ人が生き残る。

この記事を読むフロントエンドエンジニアの皆さんにも、「これから何をもっと勉強すべきか」という問いに、自分なりの答えを持ち帰ってもらえたらと思う。正解は誰にも分からない。それでも、AIがコードを書く時代であるほど、「コードの先にあるもの」を見る人が生き残るという点については、筆者はかなり確信している。1年後、この景色がさらにどう変わっているのか、そのとき改めて文章にまとめられることを願って、この記事を終える。

（もしこの記事が1年後にはあまりにも当たり前、あるいは古い話に見えるなら、それだけ私たちがうまく対応できたということではないだろうか。）

参考資料

筆者はフロントエンド開発をする中で、「このロジックはどこまで分離すべきだろう？」「このコンポーネントはどの単位で分割すべきだろう？」と数え切れないほど悩んできた。最初は、単に共通部分を取り出すことが抽象化だと思っていた。繰り返されるコードを関数にし、似たコンポーネントの共通点を抽出して一つにまとめること。しかし、そうして作ったコードが時間とともにかえって手を入れにくい怪物へと変わっていく経験を何度かして、抽象化について改めて考えるようになった。

この記事では、抽象化の本質とは何か、そしてフロントエンド開発で抽象化をどう活用すれば良いコードを作れるのかについて、筆者が考えてきたことを整理したい。

抽象と抽象化

本題に入る前に、「抽象」と「抽象化」という言葉がプログラミングで正確に何を意味するのかを確認しておきたい。この二つの言葉は似ているように見えるが、性質はかなり異なる。

抽象（Abstract） は状態であり、属性である。「これは抽象的だ」と言うとき、それは具体的な詳細が省かれ、本質的な概念だけが残っている状態を意味する。JavaやTypeScriptでabstractキーワードが付いたクラスやメソッドが、まさにこの意味に当たる。具体的な実装がまだ埋められておらず、本質的な形だけが定義された未完成の設計図なのだ。

抽象化（Abstraction） はプロセスであり、行為である。複雑な対象から本質的な特徴だけを残し、不要な詳細を取り除いて単純化する、そのプロセス自体を指す。重要なのは、抽象化は「大雑把にひとまとめにすること」ではなく、各レベルで役割を正確に定義する行為だという点である。

日常では「抽象的」という言葉が、しばしば「曖昧だ」というニュアンスで使われる。しかし、プログラミングにおける抽象化はその正反対だ。抽象化の目的は曖昧になることではなく、絶対的に正確であり得る新たな意味のレベルを作ることである。与えられた文脈で関連する情報を保持し、関連しない情報を忘れる行為こそが、抽象化の本質となる。

結局、抽象と抽象化を区別して理解すると、こうなる。抽象は「本質だけが残った状態」であり、抽象化は「本質だけを残すプロセス」 である。コードを設計するときに私たちが行っているのは、まさにこの抽象化、つまり複雑な実装から本質的なインターフェースだけを残し、それ以外を隠すプロセスなのだ。

では、こうした抽象化はなぜプログラミングに必要なのだろうか。

なぜ抽象化が必要なのか

プログラミングに抽象化が必要な根本的な理由は、意外にも単純だ。より複雑なものを作るためである。より複雑なものを作ろうとしても、複雑な要素が多すぎると、そのすべてを覚えて扱うことが難しいからだ。そこで私たちは、複雑な要素をグループ化し、単純化された抽象的な概念にする。

フロントエンド開発者が毎日使うReactも同じだ。コンポーネントを一つレンダリングするために、内部ではVirtual DOMの生成、再調整（Reconciliation）、実際のDOM操作という複雑なプロセスが行われる。しかし私たちは、それらを気にせずJSXを書けばよい。Reactがこの複雑なプロセスを抽象化してくれているからだ。

次のコードを見てみよう。UserProfileコンポーネントを使うとき、内部で行われるVDOMの生成やdiffingといった複雑なプロセスを知らなくても、十分にUIを作り、扱うことができる。

<UserProfile name="jihoon" />

以前はWebpackを自分で設定することがフロントエンド開発者の日常だったが、現在ではNext.jsやViteのようなフレームワークがバンドル設定を抽象化している。おかげで私たちは、バンドラーの内部動作を知らなくてもアプリケーションを開発できるようになり、その時間を使って、ビジネスロジックやユーザー体験といった、より高次の問題に集中できるようになった。（だからこそ筆者は、フロントエンド開発者の役割において抽象化の概念が非常に重要だと考えている。）

結局、抽象化の核心的な価値はこれだ。複雑なものを隠して単純に見せ、それぞれが自分の領域だけに集中できるようにすること。そのおかげで私たちは、一人ですべてを理解しなくても、ますます巨大で複雑なソフトウェアを作り出せるようになった。

では、抽象化がこれほど良いものなら、多ければ多いほど良いのだろうか。どのような目的で抽象化すべきなのかを考えてみよう。

文脈を減らす

多くの開発者は、抽象化を「共通部分を選び出すこと」だと捉えている。間違いではないが、これは抽象化を行う手法の一つにすぎず、抽象化の本質を説明するものではない。

筆者が考える抽象化の本質は、「コードを読む人が知るべき文脈を、適切なレベルまで減らすこと」 である。

簡単な例を見てみよう。

interface Order {
  id: string;
  status: "pending" | "completed";
  amount: number;
}
 
let total = 0;
 
const orders: Order[] = [
  { id: "a", status: "pending", amount: 10000 },
  { id: "b", status: "completed", amount: 5000 },
  { id: "c", status: "completed", amount: 8000 },
];
 
for (let i = 0; i < orders.length; i++) {
  if (orders[i].status === "completed") {
    total += orders[i].amount;
  }
}

このコードを読む開発者は、ループの初期化・条件・更新を把握し、インデックスで要素にアクセスし、条件を確認して分岐し、外部の累積変数がどのように更新されるのかまで、すべて頭に入れなければならない。このコードが実際にやろうとしていることは、「完了した注文の合計を求める」 という一文にすぎないのに、その一文を理解するために四つの異なる文脈を同時に抱えているわけだ。

const total = orders
  .filter((order) => order.status === "completed")
  .reduce((sum, order) => sum + order.amount, 0);

filterとreduceという抽象化のおかげで、開発者は「完了した注文だけを選ぶ」と「金額を累積する」という二つの意図だけを追えばよい。インデックスの管理、累積変数の宣言と更新という文脈は、コードの表面から消えた。

さらに一歩進めることもできる。

const total = sumCompletedOrders(orders);

これでコードを読む人は、この計算が配列の走査によって行われるという事実すら知る必要がなくなる。「完了した注文の総額を求める」というビジネス上の意図だけが残る。コードがどのように（How）計算されるかではなく、何を（What）計算するかに集中できるようになったのだ。

この観点から見ると、私たちが日々書いているReactコードも、数多くの抽象化の組み合わせであることが分かる。

import { css } from "@emotion/css";
import { format } from "date-fns";
 
const TodayHeader = () => {
  const now = new Date(); // Date 객체 생성이라는 복잡한 과정을 추상화
  const formatted = format(now, "yyyy-MM-dd"); // 날짜 포맷팅 로직을 추상화
 
  return (
    <h1
      className={css`
        font-size: 1.8rem;
      `}
    >
      {/* CSS-in-JS 처리 과정을 추상화 */}
      Today is {formatted}
    </h1> // React.createElement를 추상화
  );
};
 
// 그리고 위 모든 것을 다시 추상화
<TodayHeader />;

もしemotion、date-fns、reactの内部コードがすべてこのコンポーネントファイルに展開されていたら、どうなるだろう。どこから読めばよいのか、どの部分がビジネスロジックで、どの部分がライブラリのコードなのかを区別するのが難しいはずだ。抽象化が各領域の文脈を適切に隠してくれているからこそ、私たちは「今日の日付を表示する」という本質だけに集中できる。

では、実際にコードを設計するとき、抽象化にはどのような方向から取り組むべきだろうか。

抽象化レベルが高い、低いとはどういうことか

抽象化を語る上で欠かせない概念が、抽象化レベル（Level of Abstraction） である。コードの抽象化レベルが「高い」あるいは「低い」とは、一体どういう意味なのだろうか。

抽象化レベルが低いコードは、コンピューターが実行する具体的な手順に近いコードである。文字列を直接パースし、インデックスで配列を走査し、バイトを操作する。どのように（How） 動作するのかが、ありのままに表れている。

// 추상화 수준이 낮은 코드
const response = await fetch('/api/users');
const users = await response.json();
const filteredUsers = users.filter(user => user.status === 'active');
 
filteredUsers.forEach(user => {
  const element = document.getElementById(`user-${user.id}`);
  if (element) element.style.display = 'block';
});

抽象化レベルが高いコードは、ビジネスドメインや問題領域の言葉で表現されたコードである。processPayment(order)、sendNotification(user, message)、validateUserInput(formData)などがそれに当たる。抽象化レベルが高いコードには、何を（What） するのかが表れ、どのようにするかは隠されている。

Robert C. MartinはClean Codeで、この概念を**「一つの関数につき一つの抽象化レベル（One Level of Abstraction per Function）」** という原則にまとめた。一つの関数内に高いレベルと低いレベルのコードが混在すると、読む人は「これは中心的なロジックなのか、それとも実装の詳細なのか」を一行ごとに判断しなければならないからだ。

実際のコードを見ると、この問題は明確になる。

// 추상화 수준이 뒤섞인 함수
async function registerUser(name: string, email: string, password: string) {
  // ✅ 높은 수준: 비즈니스 규칙 검증
  validateUserInput({ name, email, password });
  await ensureEmailNotDuplicated(email);
 
  // ❌ 낮은 수준: 비밀번호 해싱 직접 구현
  const encoder = new TextEncoder();
  const data = encoder.encode(password);
  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
  const hashedPassword = Array.from(new Uint8Array(hashBuffer))
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
 
  // ✅ 높은 수준: 사용자 저장
  const user = await userRepository.save({ name, email, password: hashedPassword });
 
  // ❌ 낮은 수준: 이메일 전송 직접 구현
  const verifyToken = crypto.randomBytes(32).toString("hex");
  await db.execute(
    "INSERT INTO email_tokens (user_id, token, expires_at) VALUES (?, ?, ?)",
    [user.id, verifyToken, new Date(Date.now() + 86_400_000)]
  );
  await transporter.sendMail({
    from: "noreply@example.com",
    to: user.email,
    subject: "Welcome! Please verify your email",
    html: `<a href="/verify?token=${verifyToken}">Verify your account</a>`,
  });
 
  // ✅ 높은 수준: 환영 이메일 발송
  await sendWelcomeEmail(user);
}

この関数を読む人は、「ユーザー登録の流れ」というビジネスルールに基づく高いレベルの文脈を追っていたのに、突然、ハッシュバッファの操作、SQLクエリ、メールテンプレート文字列という低いレベルの文脈へと引きずり下ろされる。そして再び、sendWelcomeEmailという高いレベルへ飛ぶ。このように抽象化レベルが上がったり下がったりすると、読む人の頭の中も一緒に上下することになる。

同じ関数を、抽象化レベルを揃えて書き直すと次のようになる。

// 추상화 수준이 일관된 함수
async function registerUser(name: string, email: string, password: string) {
  validateUserInput({ name, email, password });
  await ensureEmailNotDuplicated(email);
 
  const hashedPassword = await hashPassword(password);
  const user = await userRepository.save({ name, email, password: hashedPassword });
 
  await sendVerificationEmail(user);
  await sendWelcomeEmail(user);
}

すべての文が同じ高さの抽象化レベルで語られている。メール送信がどのように実装されているのか、パスワードのハッシュ化にどのアルゴリズムを使うのかは、それぞれ下位の関数が担う。この関数を読む人は、「ユーザー登録の全体的な流れ」という一つの文脈だけに集中すればよい。

Martinはこれを、「ステップダウン・ルール（The Stepdown Rule）」 とも呼んでいる。コードを上から下へ読むとき、新聞記事のように、上には全体像があり、下へ進むほど詳細が現れるべきだという考え方だ。

Kent BeckもSmalltalk Best Practice Patternsで、同じ原則をComposed Methodパターンとして提示した。一つのメソッドは同じ抽象化レベルの処理だけで構成され、各ステップは一行のメソッド呼び出しで表現されるべきだというものだ。

結局、これらの話はすべて一つに集約される。一つの関数は、一つの抽象化レベルだけで語るべきである。 これを守るだけでも、コードの可読性は目に見えて変わる。

では、抽象化の方向性はどう定めればよいのだろう。具体的なものから始めるべきか、それとも抽象的なものから始めるべきか。

共通点の抽出ではなく、部品の組み立てとして考える

OOPでは、「具体的なものの共通点を抜き出して、抽象的なものを定義せよ」とよく言われる。このアプローチ自体が間違っているわけではないが、筆者は、この方法にこだわりすぎると、現在の要件に縛られた設計を作る危険があると考えている。

例を挙げよう。要件にA、B、Cというボタンがあり、三つとも青く丸い形で、違いはラベルのテキストだけだとする。共通点だけを抜き出して設計すると、次のように表現できる。

const BlueRoundButton = ({ label }: { label: string }) => {
  return <button className="blue round">{label}</button>;
};

現在の要件は完璧に満たされる。ところが数日後、企画担当者がこう言う。

「Bボタンの色を変更できるようにしてください。」

この瞬間、BlueRoundButtonという名前からして不自然になる。色のpropを追加すれば対応はできるが、そもそも「青く丸いボタン」という具体的な共通点から出発した設計が、変更に弱かったのだ。（この程度ならまだかわいいものだ。現実には、ボタンの形やサイズなど、数え切れないほどの要望が飛んでくる。）

こうした状況が繰り返されると、自然と気づくことがある。具体的な要件から共通点を抜き出す方法では、抽象化された成果物さえも現在の要件だけを反映したものになりやすいということだ。

そこで筆者が好むのは、反対方向のアプローチである。具体的なものから抽象を抜き出すのではなく、まず抽象的な部品を考え、それらを組み立てて具体的なものを作る方法だ。

トースト通知コンポーネントを作るとしよう。最初の要件は単純だ。「保存が完了したら、画面下部に短い案内メッセージを表示してください。」共通点を抽出するアプローチなら、次のようになる。

// 현재 요구사항의 공통 특성에서 출발한 설계
type ToastProps = {
  message: string;
  hasAction?: boolean;
  actionLabel?: string;
  onAction?: () => void;
};
 
const Toast = ({ message, hasAction, actionLabel, onAction }: ToastProps) => (
  <div className="toast">
    <span>{message}</span>
    {hasAction && <button onClick={onAction}>{actionLabel}</button>}
  </div>
);

現在の要件には完璧に対応できる。ところが数日後、企画担当者が「成功／警告に応じて左側にアイコンを入れてください」と言う。hasIconとiconNameが追加される。続いて、「アップロードの進捗バーが付いたトーストも必要です」という要望が飛んでくる。progressというpropがまた一つ増える。このプロセスを何度か繰り返すと、Toastは十個を超えるpropsを持ち、この組み合わせは使えるが、あの組み合わせは使えないという隠れたルールまで暗記しなければならないコンポーネントになる。（そしてたいてい、そのルールはコメントにも残されない。）

そもそも、「トーストはこういう形であるべきだ」という現時点の具体的なイメージから出発した設計が、変更に弱かったのだ。

部品を組み立てるアプローチなら、話は変わる。

// 부품을 조립하는 설계
const Toast = ({ children }: PropsWithChildren) => (
  <div className="toast">{children}</div>
);
 
Toast.Icon = ({ name }: { name: "check" | "warn" | "info" }) => {
  /* ... */
};
 
Toast.Message = ({ children }: PropsWithChildren) => <span>{children}</span>;
 
Toast.Action = ({
  children,
  onClick,
}: PropsWithChildren<{ onClick: () => void }>) => (
  <button onClick={onClick}>{children}</button>
);
 
Toast.Progress = ({ value }: { value: number }) => {
  /* ... */
};
 
// 필요한 부품만 골라 조립한다
<Toast>
  <Toast.Message>저장되었습니다</Toast.Message>
</Toast>;
 
<Toast>
  <Toast.Icon name="check" />
  <Toast.Message>업로드 완료</Toast.Message>
  <Toast.Action onClick={undo}>실행 취소</Toast.Action>
</Toast>;
 
<Toast>
  <Toast.Progress value={0.4} />
  <Toast.Message>파일 전송 중...</Toast.Message>
</Toast>;

「トーストは何かを収める浅いコンテナである」という変わらない本質と、「その中に何が入るか」という変わりやすい具体が分離された。これでToastの内部に手を加えなくても、新しい部品をいくらでも追加でき、既存の部品を新たな組み合わせで配置できる。propの組み合わせに関する有効性のルールもなくなる。単純に、入れたいものを入れればよいのだ。

もちろん、経験豊富な開発者なら「最初からIoC（制御の反転）で設計すればいいのでは」と言うかもしれない。その通りだ。しかし、その判断ができるのは、過去に数多くの試行錯誤を重ね、「どこが変更されやすい部分なのか」を見抜く感覚が培われているからである。

こうした感覚がまだ十分でないなら、「この機能はどのような部品で構成され、それぞれの部品をどう組み立てるべきか」という問いから始めるほうが、変更に開かれた設計をはるかに作りやすい。

ここまで読むと、自然に一つの疑問が浮かぶ。では、部品をどのような基準で分け、外部にどう表現すればよいのだろうか。

良い抽象化のための三つのこと

表現について考える

抽象化されたモジュールにとって最も重要なのは、ソースコードを開かなくても動作を推測できることである。Kent Beckはこれを**「意図が伝わる名前（Intention-Revealing Name）」** パターンと呼び、簡潔な名前を付けられないなら、抽象化そのものを見直すべきだと述べた。

そのために使える道具は、大きく二つある。名前と型だ。

// 도대체 뭘 하는 건지 알 수 없는 함수
function calculate(price: number, rate: number): number;
 
// 이름과 타입만으로 동작을 유추할 수 있는 함수
function calculateDiscountedPrice(originalPrice: number, discountRate: number): number;

calculateDiscountedPriceは、名前を見るだけで、元の価格と割引率を受け取り、割引後の価格を計算することが分かる。numberを受け取ってnumberを返すという型情報も、それを裏付けている。内部でどのような計算ロジックが適用されるかは、知らなくてもよい。

一方、calculate(price: number, rate: number): numberは、何を計算するのか分からないため、結果を予想できない。結局、ソースコードを開かなければ使えず、抽象化の利点を失ってしまう。

ここで、名前の付け方そのものが抽象化レベルを反映する点に注目したい。プログラミングにおける関数名は、一般に動詞＋名詞の組み合わせで構成されるが、どの動詞を選ぶかによって、その関数がどの抽象化レベルで動作するかが表れる。

ただし、動詞だけで抽象化レベルが決まるわけではない。一緒に使われる名詞（ドメインの文脈）が最終的なレベルを決める

抽象化レベルが低い側でよく使われる動詞がある。parse、encode、decode、serialize、read、write、push、pop、convert、transformなどだ。これらの言葉は、データの物理的な変換やデータ構造の直接的な操作を示唆する。

中間レベルでは、get、save、load、validateといった動詞が登場する。技術的な動作ではあるものの、その動作の意図がある程度伝わるレベルだ。

抽象化レベルが高い側では、register、refund、confirm、cancel、submitといった動詞が使われる。これらはビジネスドメインの言葉である。内部でどのような技術的手順が行われるかは一切表れず、ユーザーの行為やビジネスプロセスだけが表現される。

// 낮은 수준: 기술적 동작이 드러남
function parseJSON(text: string): object;
function encodeBase64(data: Uint8Array): string;
 
// 중간 수준: 의도가 드러나되 기술적 맥락이 남아있음
function getUserById(id: string): Promise<User>;
function validateEmail(email: string): boolean;
 
// 높은 수준: 비즈니스 의도만 드러남
function registerUser(form: RegistrationForm): Promise<User>;
function refundPayment(orderId: OrderId, amount: Money): Promise<Refund>;

Robert C. MartinはClean Codeで、これについて**「短く謎めいた名前より、長く説明的な名前のほうがよい」** と述べている。また、「一つの概念には一つの単語を使う」 という原則も提示した。同じ文脈の動作にfetch、retrieve、getを混在させると、読む人が「この三つは異なる動作なのか」と混乱するからだ。

この原則は、Reactコンポーネントやフックの命名にもそのまま当てはまる。

<Button />           
<SearchInput />      
<SubmitOrderButton />

コンポーネントは、抽象化レベルに応じて名前の具体性が異なる。Buttonは低いレベルの汎用UIプリミティブとして使われるが、SubmitOrderButtonは高いレベルでビジネス上の意図が明確に表れる。

const handleSubmit = async(data: FormData) => { 
  await registerUser(data);
};
 
<Form onSubmit={handleSubmit} />           

on*は、コンポーネントが外部に公開するpropの名前である。コンポーネントを使う側で「どのイベントに反応するか」を宣言する。handle*は、そのpropに実際に渡される実装関数の名前だ。

const user = useAuth();                  
const [items, setItems] = useCartItems();
const { isOpen, toggle } = useModal();   

カスタムフックはuse接頭辞を使ってReactのルールに従い、フックが提供する状態や動作をコンポーネントで利用できるようにする。

Coding Horrorを運営するJeff Atwoodは、Managerという接尾辞の問題を指摘したことがある。UrlManagerという名前では、URLをプールするのか、検証するのか、生成するのかがまったく分からない。UrlBuilder、UrlValidator、UrlPoolのように、具体的な役割が伝わる名前のほうがはるかに良い。名前が曖昧であることは、そのモジュールの責務自体が曖昧である兆候かもしれないのだ。

結局、良い名前とは、そのコードがどの抽象化レベルで動作するのかを、読む人に即座に伝える名前である。

入力の自由度を意図的に設計する

抽象化されたモジュールを設計するとき、よく直面する悩みがある。「機能をどこまで開放するか」だ。この決定によって、モジュールを使う開発者の体験は大きく変わる。

// 기능이 닫힌 컴포넌트
const Button = ({ children }: {children?: React.ReactNode}) => {
  return <button>{children}</button>;
};
 
// 기능이 완전히 열린 컴포넌트
const Button = (props: ComponentProps<"button">) => {
  return <button {...props} />;
};

最初のボタンはchildrenしか受け取れない。onClickもtypeもdisabledも設定できない。その代わり、使う人が迷うことはない。

二つ目のボタンは、button要素のすべての属性を受け取れる。自由度は高いが、使う側は数十個のpropのうち何を使うべきか悩むことになる。筆者はこの状況を、「コンポーネントが開発者に判断を強いる」 と表現している。

正解はない。ただし、モジュールの目的と利用者に応じて、適切なレベルを見つける必要がある。デザインシステムの基本ボタンなら、制限されたPropsで一貫性を保つほうがよいかもしれないし、汎用ユーティリティコンポーネントなら、柔軟に開放するほうがよいかもしれない。

// 지나치게 닫힌 인터페이스 — 다양한 상황에 대응 불가
<Button onClick={handleSubmit}>제출</Button>
// onClick 외의 이벤트, className, disabled 등을 전달할 방법이 없다
 
// 지나치게 열린 인터페이스 — 의도가 사라짐
<Button {...anyProps} />
// 무엇을 전달해야 하는지 사용자가 직접 파악해야 한다

抽象化の幅は、利用者が誰なのかに応じて決めるべきだ。内部実装を理解して細かく制御する必要がある利用者には、低いレベルのインターフェースが適している。一方、詳細を知らなくてもよい利用者に、開きすぎたインターフェースを提供すれば、混乱が増すだけだ。反対に、さまざまな状況に対応しなければならない利用者に対して入力を過度に制限すれば、そもそも利用できなくなってしまう。

抽象化の単位を適切に保つ

抽象化の単位、つまり「どこまでを一つのモジュールとしてまとめるか」も重要な論点である。

フロントエンドでよく見られるアンチパターンの一つが、カスタムフックの過剰な抽出だ。

// 이 훅은 단 하나의 컴포넌트에서만 사용된다
const useUserProfileData = () => {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
 
  useEffect(() => {
    fetchUser()
      .then(setUser)
      .finally(() => setLoading(false));
  }, []);
 
  return { user, loading };
};

一つのコンポーネントでしか使われないロジックを、あえてフックとして分離すると、コードを読む人は二つのファイルを行き来しながら文脈を把握しなければならない。抽象化が文脈を減らすどころか、増やしてしまったのだ。

反対に、一つのフックにあまりに多くのものを詰め込むことも問題だ。

// 관련 없는 관심사가 하나의 훅에 뒤섞여 있다
const useEverything = () => {
  const auth = useAuth();
  const theme = useTheme();
  const analytics = useAnalytics();
  const toast = useToast();
 
  return { auth, theme, analytics, toast };
};

こうした「God Hook」はテストが難しく、一つを変更すると無関係な部分にまで影響が及ぶことがある。

抽象化の適切な単位を判断する基準は、「この分離によって、コードを読む人の文脈が実際に減るか」 である。分離した結果、かえって文脈が分散して把握しにくくなるなら、その抽象化にはまだ早いということだ。

早すぎる抽象化に注意せよ

ここまで読むと、「では、いつ抽象化すればよいのか」という疑問が残るかもしれない。筆者の考えはこうだ。基本的な前提として、抽象化を急ぐべきではない。

明確な抽象化の兆候が見えない限り、コードをそのままにしておくほうが、誤った抽象化を作って後から解きほぐすよりも、悪い状態になりにくい。誤った抽象化が作られる過程は、おおよそ次のようなものだ。

1. コードAとコードBに似たパターンが見つかる。
2. 「DRY原則だから共通関数に切り出そう！」と抽象化する。
3. コードCにも似たパターンが見つかり、同じ関数を使う。ただし、少し違う動作に対応するため、引数を一つ追加する。
4. コードD、Eでも使うようになり、条件文と引数が増え続ける。
5. こうして、この関数はあらゆる場所で使われているのに、誰も触れるのを恐れるコードになる。

// 처음에는 단순했던 함수가...
const formatUserName = (user: User) => `${user.firstName} ${user.lastName}`;
 
// 요구사항이 추가될 때마다 매개변수가 늘어나고...
const formatUserName = (
  user: User,
  includeMiddleName?: boolean,
  format?: "full" | "short" | "initials",
  locale?: string,
  honorific?: boolean,
) => {
  if (format === "initials") {
    /* ... */
  }
  if (includeMiddleName && user.middleName) {
    /* ... */
  }
  if (honorific && locale === "ko") {
    /* ... */
  }
  // ...끝없는 분기
};

この状況に陥ったなら、解決策は明確だ。抽象化されたコードを各利用箇所にもう一度インライン化し、それぞれの箇所で不要なコードを取り除く。そしてきれいになった状態で本当の共通点が見えたら、そのとき改めて抽象化する。「最速で前に進む方法は、引き返すことだ。」

では、抽象化すべきなのはどのようなときか。筆者が感じる抽象化の兆候は、おおよそ次のようなものだ。

• 一貫性が崩れている。 同じロジックなのに、あるコンポーネントではインラインで書かれ、別のコンポーネントでは別関数に分離されている。同じ計算ロジックがあちこちに散らばっている。
• 内部構造が外部に不必要に公開されている。 外部が知る必要のない実装の詳細を、呼び出し側が一つずつ扱っている。
• 自身の動作が露出し続けている。 モジュールが内部の手順を隠せず、使う側がその手順をそのまま追わなければならない。

問題は、こうした兆候を検知すること自体はたいてい単純なのに、実際にはその兆候を無視し、より「重要な」要件を満たすことに集中しがちだという点である。スケジュールに追われたり、機能実装に没頭したりすると、「ひとまず動くから、後で整理しよう」となり、その「後で」はなかなか訪れない。

ここでもう一つ重要なのは、一貫した抽象化の基準を保つことである。コードベース内で、同じ種類のロジックが、ある場所ではインライン、ある場所では関数、また別の場所ではカスタムフックとして分離されていれば、新しくコードを読む人は「この違いには意図があるのか」と混乱する。抽象化するにせよ、しないにせよ、チーム内の基準は一貫していなければならない。

Joel Spolskyが2002年に提唱した**「漏れのある抽象化の法則（The Law of Leaky Abstractions）」** も、この文脈で覚えておく価値がある。漏れのある抽象化の法則とは、抽象化は複雑な実装を隠そうとするが、その実装の詳細は結局、外へ漏れ出す（leak）というものだ。つまり、抽象化を使う人は内部実装を知らなくてもよいように設計したはずなのに、実際には、それを知らなければ正しく使えない状況が生じることを指す。

TCPは不安定なネットワークを安定した接続のように見せる形で抽象化するが、ケーブルが切れれば、その抽象化は崩れる。ReactはUIの更新を宣言的に抽象化するが、再レンダリングを最適化するには、結局その内部動作を理解しなければならない。完璧な抽象化は存在しないからこそ、抽象化するときには、「この抽象化が崩れたとき、利用者は対処できるか」 まで考える必要がある。

結局、「抽象化は作業時間を節約してくれるが、学習時間を節約してはくれない。」

抽象化は体得するものだ

以前、同僚と抽象化について話したことがある。そのときに出た話が印象深かった。抽象化の兆候を捉え、適切なタイミングで適切なレベルに分離することは、結局のところ感覚の領域だという話だ。

もちろん、ここまで述べてきた原則、つまり抽象化レベルを揃え、適切な名前を付け、入力の自由度を設計することは、間違いなく重要である。しかし、実際にコードを書く瞬間にこれらの原則を一つひとつ思い浮かべ、「これを分離すべきか、しないべきか」と考えるやり方は、かえって流れを妨げることがある。試合中にジャブを打つとき、肘の角度を意識すると逆にタイミングを逃してしまうように、コードを書くときも、抽象化は意識的な判断ではなく、自然な感覚から生まれるべきなのだ。

コードを書き進める中で、何かに抵抗を感じる瞬間がある。「このロジックはここにあるべきではない気がする」「このコンポーネントはあまりに多くのことを知りすぎている気がする」という感覚だ。その感覚こそが抽象化の兆候であり、それを自然に捉えて反応できることが、体得するということである。

ただし、この感覚は一朝一夕には身につかない。数多くのパターンを学び、多様なコードを読み、自ら試行錯誤を重ねて初めて、「これは分離したほうがよさそうだ」 という勘が自然に働き始める。後から同僚に「なぜこれを分離したの？」と聞かれたとき、「これは〇〇だから分離した」と自然に説明できるなら、それは体得できているということだ。

どの分野でも同じなのだと思う。暗記して上手くなろうとすると、かえって判断が難しくなる。結局は大きな流れだけを押さえ、細部は自然に埋まるようにしなければならない。そして、その自然さは、日頃から積み重ねてきた多様なパターンと経験から生まれるのだ。

おわりに

プログラミングにおける抽象化とは、複雑なものを隠して単純に見せ、コードを読む人が必要な文脈だけに集中できるようにする行為である。

良い抽象化のために覚えておきたいことを、もう一度確認すると次のようになる。

• 基本的な前提として抽象化を急がず、明確な兆候が見えたときに初めて分離しよう。
• 一つの関数は、一つの抽象化レベルだけで語ろう。
• 名前と型で動作を十分に表現し、ソースコードを開かなくても使えるようにしよう。
• 入力の自由度を、モジュールの目的と利用者に合わせて意図的に設計しよう。
• 誤った抽象化の上に付け足すより、解きほぐしてやり直す勇気を持とう。
• そして、これらすべてを意識しなくても自然にできるよう、多様なパターンを体得しよう。

もちろん、この記事で筆者が述べたことが正解というわけではない。適切な抽象化レベルは、ビジネスの状況、チームの構成、プロジェクトの性質によって変わらざるを得ない。ただし、一つだけ変わらないものがあるとすれば、抽象化の究極の目的は、人にとって理解しやすいコードを作ることだという点である。

この記事を読んだ方にも、それぞれのコードベースで「この抽象化は本当に文脈を減らしているだろうか」と、一度問いかけてみてほしい。その問い一つだけでも、コードを見る視点が少し変わるはずだ。

参考資料

この記事は、複数の公式ドキュメントや先行記事から多くの着想を得た。直接引用した箇所の出典と、思考の枠組みを作る上で役立った記事を併せて記載する。

筆者は実務で TanStack Query を使う中で、queryKey の管理方法を何度も作り直してきた。最初はコンポーネント内に ['user', userId] のような配列を直接書いていたが、無効化のたびに同じキーを複数箇所へ記述するうちにタイプミスが増え、QUERY_KEYS のような定数オブジェクトへ移行した。その後、TkDodo の記事を読んでクエリキーファクトリーパターンを採用し、しばらくして @lukemorales/query-key-factory ライブラリを導入した。そして v5 の登場を機に、今度は queryOptions を使う形へと再び作り直した。

単なるキャッシュの識別子にすぎない小さな配列をめぐって、なぜこれほど多くのパターンが生まれたのだろう。なぜ一つの queryKey に、これほど多くの進化の痕跡が残っているのか。 そして、それぞれの段階は具体的にどの問題を解決しようとしていたのか。

本記事では、TanStack Query の公式ドキュメント、TkDodo のブログシリーズ、さらに v5 で導入された queryOptions の内部実装までたどりながら、queryKey がどのような仕組みで動作し、なぜ現在の形へ進化してきたのかを整理する。

queryKey がなかった時代

本題に入る前に、一つ確認しておこう。今では TanStack Query や SWR といったライブラリを当たり前のように使っているが、これらがなかった時代には非同期データをどのように扱っていたのだろうか。

最も一般的だったのは、useState、useEffect、fetch、axios などを組み合わせる方法だろう。

function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);
 
  useEffect(() => {
    let cancelled = false;
    setLoading(true);
 
    fetch(`/api/users/${userId}`)
      .then((res) => res.json())
      .then((data) => {
        if (!cancelled) setUser(data);
      })
      .catch((err) => {
        if (!cancelled) setError(err);
      })
      .finally(() => {
        if (!cancelled) setLoading(false);
      });
 
    return () => {
      cancelled = true;
    };
  }, [userId]);
 
  // ...
}

このコードの問題は明白だ。同じ userId を参照するコンポーネントがページ内に二つあるだけで、同一のリクエストが二度送られる。 キャッシュがないからだ。また、ユーザーが別のページへ移動して戻ってくると、再び最初からフェッチする。データを取得したのが1秒前なのか1時間前なのかを判別できないため、「キャッシュ済みの値を表示しながらバックグラウンドで更新する」といった動作を再現するのも難しい。（独自のキャッシュシステムを導入すれば実現できるが、その管理はかなり厄介だと思う。）

この問題を解決するために登場したのが、Redux と redux-thunk（または redux-saga）の組み合わせだった。データ取得ロジックをサンクに切り出し、結果をストアへ保存しておけば、別のコンポーネントでも同じデータを再利用できた。しかし、その都度アクションタイプを定義し、リデューサーを書き、ローディング・成功・失敗の状態を自分で管理しなければならなかった。データを一つ取得するためだけに、膨大な定型コードが必要だった。（筆者はこの時期に実務を始め、「データを一つ取得するだけなのに、なぜ複数のファイルを作らなければならないのか」と疑問に思っていた。）

この流れの本質は、結局のところ**「このリクエストが何のリクエストかを識別できて初めて、同じリクエストを繰り返さずに済む」**ということだ。そして、その「何のリクエストか」を示す識別子こそが queryKey の正体である。

SWR と React Query（現在の TanStack Query）は、この問題に真正面から取り組んだ。「非同期リクエストには識別子が必要であり、識別子が同じならキャッシュを共有する」。この単純な原則一つで、先ほどの定型コードがすべて不要になった。

queryKey の本質

では、queryKey とは正確には何だろうか。TanStack Query の公式ドキュメントでは、次のように定義されている。

TanStack Query は、その中核において、クエリキーに基づいてクエリのキャッシュを管理する。クエリキーの最上位は配列でなければならない……クエリキーがシリアライズ可能で、かつクエリのデータに対して一意である限り、使用できる。

At its core, TanStack Query manages query caching for you based on query keys. Query keys have to be an Array at the top level... As long as the query key is serializable, and unique to the query's data, you can use it.

要点は二つある。シリアライズ可能であること、そしてそのデータに対して一意であること。 同じキーは同じデータを意味し、異なるデータには異なるキーが必要だ。この単純な規則が、キャッシュシステム全体の動作を決める。

さらに、もう一つ重要な点がある。queryKey は依存配列としての役割も担う。 React の useEffect で依存配列が変わると副作用が再実行されるのと同じように、queryKey が変わると TanStack Query は自動的に新しいデータをフェッチする。

const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

userId が 'A' の場合と 'B' の場合では、queryKey が異なる。異なればキャッシュミスとなり、キャッシュミスならフェッチする。これは自動で行われる。この単純さのおかげで、「userId が変わったので再度フェッチする」というロジックを自分で書く必要がない。

ここで一つ疑問が生じる。queryKey が「同じキー」であることを、どのように判定しているのだろうか。単純に === で比較すればオブジェクトの参照は異なるため、毎回キャッシュミスになるはずだ。

QueryCache の内部

TkDodo の React Query の内部によれば、QueryCache は結局のところ、メモリ上に保持される一つのデータ構造にすぎない。より正確には、v5 の公式実装で使われているデータ構造は、プレーンオブジェクトではなく Map<string, Query> だ。クラス内で #queries = new Map<string, Query>() と宣言され、すべての書き込みと読み込みは #queries.set(query.queryHash, query) と #queries.get(queryHash) を通じて行われる。キーは queryKey をシリアライズした形式（queryHash）、値は Query クラスのインスタンスである。

古いバージョンではプレーンオブジェクトが使われていた時期もあったが、v5 ではネイティブの Map へ移行した。（Map はキーの衝突やプロトタイプ汚染のリスクがなく、挿入順を保持し、文字列キーの検索が平均 O(1) であるため、キャッシュのデータ構造としては定石に近い選択だ。）

useQuery が呼ばれるたびに起こることは単純だ。queryKey をハッシュ値へ変換し、そのハッシュ値を使って Map を検索する。 存在すればキャッシュ済みの Query インスタンスを取得し、なければ新しく作成して set する。

ここで自然に次の疑問が生まれる。なぜわざわざ queryKey を文字列へシリアライズするのか。 Map<QueryKey, Query> のように配列自体をキーとして使えばよいのではないか。

その答えは、JavaScript の等価性モデルにある。ネイティブの Map はキーを参照等価性で比較する。内容が同じでも、メモリ上で別のオブジェクトなら異なるキーとして扱われる。

const m = new Map();
m.set(['user', 1], 'alice');
m.get(['user', 1]); // undefined — 새로 만든 배열은 다른 참조다

ところが、React コンポーネントで useQuery({ queryKey: ['user', userId] }) と記述すると、レンダリングのたびに新しい配列インスタンスが作られる。 最初のレンダリングと二度目のレンダリングで使われる queryKey 配列は、内容が同じでもメモリ上では別のオブジェクトだ。もしキャッシュが参照等価性に依存していたら、同じデータを参照するコンポーネントがレンダリングのたびにキャッシュミスを起こすという悲惨な事態になっていただろう。

参照等価性によって生じる問題の解決策は単純だ。参照等価性を構造的等価性へ変換することである。queryKey の内容だけから決定論的な文字列を作り、その文字列を Map のキーとして使う。そうすれば、「内容が同じなら同じキー」という期待どおりの意味論を取り戻せる。JSON.stringify は、その変換を行う最も単純な手段にすぎない。（TanStack Query が v3 の時代に複数のシリアライズ方式を試した末、安定した JSON.stringify の変種へ落ち着いた理由でもある。）

ここで中心となるのが、ハッシュ値を作る関数 hashKey だ。packages/query-core/src/utils.ts に定義された公式実装は、正確には次のようになっている。

export function hashKey(queryKey: QueryKey | MutationKey): string {
  return JSON.stringify(queryKey, (_, val) =>
    isPlainObject(val)
      ? Object.keys(val)
          .sort()
          .reduce((result, key) => {
            result[key] = val[key]
            return result
          }, {} as any)
      : val,
  )
}

JSON.stringify ではあるが、単純に文字列化しているわけではない。置換関数のコールバックを挟み、プレーンオブジェクトのキーをアルファベット順に並べ替えてからシリアライズしている。

この並べ替えが本質的なのは、文字列へのシリアライズには、さらに厳しい条件が伴うためだ。意味が同じ入力は、常に同じ文字列へ変換されなければならない。 しかし、通常の JSON.stringify はキーの順序をそのまま維持する。{ a: 1, b: 2 } と { b: 2, a: 1 } は意味上は同じオブジェクトなのに、異なる文字列へシリアライズされ、最終的に別々のキャッシュスロットとなる。その結果、同じデータを二度リクエストする事態が再び起きてしまう。

これを一貫して防ぐ手法が、正準形だ。意味上同じ入力が、常に一意な一つの表現に対応するよう強制する。hashKey の置換関数がプレーンオブジェクトのキーを並べ替える理由は、まさにこれだ。どの順序で入力されても出力が同じになるようにし、シリアライズの結果とオブジェクトの意味を一対一で結びつける。数学的に言えば、キーの順序が異なるオブジェクト群によって作られる同値類から、並べ替え済みの形式を代表元として選び出す操作である。

配列を並べ替えないのも、同じ原理の裏返しだ。配列は順序そのものに意味があるデータ構造なので、並べ替えると情報が失われる。オブジェクトのキー順は偶然だが、配列の要素順は意図である。hashKey は両者を明確に区別して扱う。公式ガイドが queryKey を「汎用的なものから具体的なものの順に配置する」よう推奨しているのは、このためだ。配列の順序が意味を担う以上、その意味は作成者が自ら定める必要がある。

ここでもう一つ確認しておくべき点がある。キーの並べ替えが適用されるのは、プレーンオブジェクトだけだ。同じファイル内の isPlainObject は単に typeof === 'object' を見るのではなく、Object.getPrototypeOf(o) === Object.prototype まで検査し、純粋なオブジェクトリテラルとクラスのインスタンスを区別する。そのため、{ foo: 1 } のようなリテラルは並べ替えられる一方、class User { ... } で作成したインスタンスは並べ替えられず、そのまま処理される。（クラスのインスタンスをそのまま queryKey に含めると、JSON.stringify が列挙可能なプロパティだけを出力する挙動と相まって、意図しないハッシュが生成されることがある。）

この仕組みから、二つの重要な結果が導かれる。

1. オブジェクトのキー順は問わない。

useQuery({ queryKey: ['todos', { status: 'done', page: 1 }], queryFn });
useQuery({ queryKey: ['todos', { page: 1, status: 'done' }], queryFn });
// 두 쿼리는 같은 캐시 슬롯을 공유한다

キーを並べ替えてからシリアライズするためだ。この仕組みがなければ、オブジェクトリテラルを使うたびにキーの順序を覚えておかなければならなかっただろう。

2. 配列の要素順は重要である。

useQuery({ queryKey: ['todos', status, page], queryFn });
useQuery({ queryKey: ['todos', page, status], queryFn });
// 두 쿼리는 다른 캐시이다

配列は順序そのものに意味があるデータ構造だからだ。JSON.stringify も配列の順序は維持する。

また、undefined 値はシリアライズの過程で消えることも覚えておくとよい。{ a: 1, b: undefined } と { a: 1 } は同じハッシュ値になる。（筆者はこのことを知らず、「undefined を明示的に入れたのだから別のキャッシュだ」と考えてしまったことがある。）

もう一つ、queryKey に循環参照や関数を含めることはできない。JSON.stringify では処理できないためだ。Date オブジェクトや Map/Set、BigInt なども同様に、標準の挙動では推奨されない。シリアライズ可能な純粋なデータ構造である必要がある。

興味深いのは、この制約が完全に強制されているわけではない点だ。TanStack Query は queryKeyHashFn というオプションを通じて、ハッシュ関数自体を差し替えられる逃げ道を用意している。内部では hashQueryKeyByOptions(queryKey, options) が、オプションに queryKeyHashFn があればそれを呼び、なければ既定の hashKey を呼ぶように分岐する。

useQuery({
  queryKey: [{ id: userId, fetchedAt: new Date() }],
  queryFn,
  // Date를 ISO 문자열로 바꿔서 해싱
  queryKeyHashFn: (key) =>
    JSON.stringify(key, (_, v) => (v instanceof Date ? v.toISOString() : v)),
});

ただし、このオプションはクエリごとに個別に指定する必要があり、queryClient.setQueryData のようにオプションを知らないまま呼び出される命令型 API には適用されないという制約がある（課題 #1343）。そのため実務では、回避手段を使うよりも、queryKey を作る時点でシリアライズ可能な形式へ変換してから渡す方がはるかに安全だ。（筆者も一度 Date をそのまま入れ、「同じ時刻なのに、なぜキャッシュが更新されないのか」と長時間悩んだことがある。結局、答えは「その Date は同じ時刻を表していても別のオブジェクトインスタンスなので、毎回異なるハッシュになっていた」だった。）

queryKey の記述規則

ここまでの複雑な内部動作を理解すれば、記述規則も自然に見えてくる。公式ドキュメントが推奨する規則を整理すると、次のようになる。

規則1. queryKey は必ず配列にする。

文字列を渡しても動作はする（内部で配列へ変換される）。ただし、一貫性を保つため、最初から配列で記述する方がよい。

// 비권장
useQuery({ queryKey: 'todos', queryFn });
 
// 권장
useQuery({ queryKey: ['todos'], queryFn });

規則2. queryFn が依存するすべての変数を queryKey に含める。

// 잘못된 예: userId가 쿼리키에 없다
useQuery({
  queryKey: ['user'],
  queryFn: () => fetchUser(userId),
});
 
// 올바른 예
useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

useEffect の依存配列と同じ考え方だ。関数内で使う変数はすべてキー（＝依存関係）に含めなければならない。この規則を破ると、対象ユーザーが変わったにもかかわらず以前のユーザーのデータがそのまま表示されるような、追跡しにくい不具合が生じる。

規則3. 最も汎用的なものから最も具体的なものの順に配置する。

// 좋다
['todos', 'list', { filter: 'done' }]
['todos', 'detail', todoId]
 
// 안 좋다 (순서가 뒤집혀 있음)
[{ filter: 'done' }, 'list', 'todos']

この順序が重要なのは、無効化に関係するからだ。TanStack Query の invalidateQueries は、既定では接頭辞一致で動作する。

// 모든 todos 관련 쿼리 무효화
queryClient.invalidateQueries({ queryKey: ['todos'] });
// → ['todos', 'list', ...], ['todos', 'detail', ...] 모두 매치된다
 
// list 쿼리만 무효화
queryClient.invalidateQueries({ queryKey: ['todos', 'list'] });
// → ['todos', 'list', ...]만 매치된다

キーをツリー構造として設計しておけば、「このドメインのすべてのデータを再取得する」から「この一つの項目だけを再取得する」まで、一行で表現できる。（初めて見たときは大したことではないように思えるが、一度設計を誤り、無効化の範囲が意図どおりに動かない経験をすると、その価値を痛感する。）

queryKey 管理の変遷

ここまでは queryKey の動作原理と使い方を見てきた。ここからは、queryKey の管理方法がどのように変化してきたのかという問いに移ろう。

筆者が実務でたどってきた段階を、時系列で整理する。

1. インライン配列

最も単純な形式だ。コンポーネント内で固定文字列とプロパティの値を組み合わせる。

function UserProfile({ userId }: { userId: string }) {
  const { data } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  });
  // ...
}
 
function PostList({ filter }: { filter: PostFilter }) {
  const { data } = useQuery({
    queryKey: ['posts', filter],
    queryFn: () => fetchPosts(filter),
  });
  // ...
}

使い始めの段階では、これでも十分だ。

問題は、コードベースが大きくなるにつれて現れる。ユーザー情報を更新するミューテーションで無効化を行いたくても、「ユーザー関連のクエリキーは何だったか」を毎回検索しなければならない。ある箇所では ['user', userId]、別の箇所では ['users', userId]（複数形）と書かれることも起きる。両者はまったく別のキャッシュスロットなので、無効化は片方にしか適用されない。

2. 定数オブジェクト

タイプミスを防ぐため、クエリキーを定数として一か所にまとめる。

// queryKeys.ts
export const QUERY_KEYS = {
  USER: 'user',
  POSTS: 'posts',
  COMMENTS: 'comments',
} as const;
 
// 사용처
useQuery({
  queryKey: [QUERY_KEYS.USER, userId],
  queryFn: () => fetchUser(userId),
});

タイプミスはなくなる。しかし、キーを組み立てる責任は依然として利用側に残る。[QUERY_KEYS.USER, userId] という組み合わせを、ある人は [QUERY_KEYS.USER, userId, 'detail'] と書き、別の人は ['user', 'detail', userId] と書く。どれが正しいか、別途規約として覚えなければならない段階が訪れる。

3. クエリキーファクトリー

このパターンは、TkDodo の効果的な React Query のキーという記事で具体化された。ドメインごとにキーを生成するオブジェクトを定義し、階層構造を関数で表現する。

// features/todos/queries.ts
const todoKeys = {
  all: ['todos'] as const,
  lists: () => [...todoKeys.all, 'list'] as const,
  list: (filters: string) => [...todoKeys.lists(), { filters }] as const,
  details: () => [...todoKeys.all, 'detail'] as const,
  detail: (id: number) => [...todoKeys.details(), id] as const,
};
 
// 사용
useQuery({ queryKey: todoKeys.detail(1), queryFn: ... });
useQuery({ queryKey: todoKeys.list('done'), queryFn: ... });
 
// 무효화
queryClient.invalidateQueries({ queryKey: todoKeys.all });        // 전체
queryClient.invalidateQueries({ queryKey: todoKeys.lists() });    // 모든 리스트
queryClient.invalidateQueries({ queryKey: todoKeys.detail(1) });  // 특정 항목

このパターンが強力なのは、階層構造がコード上に明示されるからだ。todoKeys.all は todos に関するすべてのクエリ、todoKeys.lists() はすべてのリスト形式のクエリ、todoKeys.detail(1) は特定の項目を指す。無効化の範囲を一行のコードで正確に表現できる。

もう一つの利点は、コロケーションだ。TkDodo は、キーをグローバルなファイルへまとめることを推奨していない。代わりに、機能ディレクトリ内へ queries.ts を置き、その中にキーとフックをまとめる。

src/
└── features/
    └── todos/
        ├── index.tsx
        └── queries.ts   # 키와 훅을 모두 여기에

こうすることで、「todos を変更するなら todos フォルダだけ見ればよい」という単純なメンタルモデルができる。ともに変化するものを同じ場所に置く、という原則を忠実に実践した形だ。

4. @lukemorales/query-key-factory

3番目のパターンを毎回手作業で書いていると、定型コードが増えていく。また、複数ドメインのキーを統合して管理したい場合、標準化されたインターフェースが欲しくなる。@lukemorales/query-key-factory は、このパターンをライブラリとして実装したものだ。

import { createQueryKeys, mergeQueryKeys } from '@lukemorales/query-key-factory';
 
const users = createQueryKeys('users', {
  detail: (userId: string) => ({
    queryKey: [userId],
    queryFn: () => api.getUser(userId),
  }),
  list: (filters: UserFilters) => ({
    queryKey: [{ filters }],
    queryFn: () => api.getUsers(filters),
  }),
});
 
const todos = createQueryKeys('todos', {
  detail: (id: number) => ({
    queryKey: [id],
    queryFn: () => api.getTodo(id),
  }),
});
 
export const queries = mergeQueryKeys(users, todos);
 
// 사용
useQuery(queries.users.detail('abc'));
useQuery(queries.todos.detail(1));
 
// 무효화
queryClient.invalidateQueries(queries.users._def);            // 모든 user 쿼리
queryClient.invalidateQueries(queries.users.detail('abc'));   // 특정 항목

createQueryKeys は接頭辞を自動的に付け、mergeQueryKeys を使えば複数のドメインを統合できる。また、_def という所定のプロパティからドメイン全体のキーへアクセスできる。手書きのファクトリーで毎回 as const を付け、型を自分で絞り込んでいた作業が不要になる。

このライブラリは、しばらくの間、事実上の標準として使われていた。（筆者も長い間愛用していた。）しかし、queryOptions の登場によって状況が変わった。

5. queryOptions（v5 公式）

TanStack Query v5 における最も重要な変更の一つが、queryOptions API の導入だ。v4 から v5 への移行で、すべてのフックの引数が単一のオブジェクトに統一された。この変更の真の目的は、そのオブジェクトを再利用可能な単位として切り出せるようにすることだった。

import { queryOptions } from '@tanstack/react-query';
 
export const userDetailOptions = (userId: string) =>
  queryOptions({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
    staleTime: 5 * 60 * 1000,
  });
 
// 어디서나 사용 가능
useQuery(userDetailOptions('abc'));
useSuspenseQuery(userDetailOptions('abc'));
queryClient.prefetchQuery(userDetailOptions('abc'));
queryClient.setQueryData(userDetailOptions('abc').queryKey, newUser);

一見すると、「何が違うのか。単にオブジェクトを関数で包んだだけではないか」と思うかもしれない。TkDodo もクエリオプション APIという記事で、その点を認めている。実行時には、本当に受け取ったオブジェクトをそのまま返すだけだ。

本当に重要な働きは、型システムの中で生じる。続けて見ていこう。

queryOptions の DataTag

queryOptions が単なる補助関数ではない理由は、返された queryKey にデータ型の情報を埋め込むからだ。この仕組みは、TanStack Query の内部で DataTag と呼ばれている。

概略的な実装は、次のとおりだ。

declare const dataTagSymbol: unique symbol;
declare const dataTagErrorSymbol: unique symbol;
 
export type DataTag<TType, TValue, TError = unknown> = TType & {
  [dataTagSymbol]: TValue;
  [dataTagErrorSymbol]: TError;
};

unique symbol を使ったブランド型だ。実行時には何の影響もない印にすぎないが、TypeScript から見ると、「この配列は単なる配列ではなく、TValue 型のデータに紐づいた配列である」という情報を持っている。

ここで、あえて unique symbol を使うのには理由がある。Zenn の DataTag の背後にある unique symbol を解き明かすという記事では、この仕組みを「型情報専用の駐車スペース」にたとえている。通常の文字列キーなら、別のライブラリやユーザーコードのキーと衝突する可能性がある。しかし、各 unique symbol 宣言はそれ自体が一意な型を作るため、ほかのどの宣言とも同じ型にはならない。絶対に衝突しない識別子になるわけだ。

この一つの仕組みが生む違いは大きい。

const data = queryClient.getQueryData(['user', 'abc']); // unknown
const data = queryClient.getQueryData(userDetailOptions('abc').queryKey); // User | undefined

getQueryData や setQueryData は queryKey 一つしか受け取らない。しかし、その queryKey にデータ型がすでに刻み込まれているため、返り値の型が自動的に推論される。ジェネリック型を明示的に渡す必要がなく、誤った型の値を setQueryData に渡そうとすれば、コンパイラが即座に検出する。

もちろん、制約もある。getQueriesData のように複数のクエリを一度に取得するメソッドでは、結果が異種のタプルからなる配列になるため、型推論は適用されない。また、unique symbol を使用するため、.d.ts の生成時にモノレポ環境で TS4023 エラーが発生することがある。この場合は、dataTagSymbol を明示的に import することで回避できる。

ここまでの仕組みを整理すると、一つの事実が明確になる。queryOptions の型推論は、queryKey と queryFn が同じ場所で一緒に宣言されていることに全面的に依存する。 queryFn の返り値の型を queryKey に刻み込むには、両者が同じ場所で宣言されていなければならないからだ。

この点は、クエリキーファクトリーの設計方針に重要な示唆を与える。以前の世代のパターンは、queryKey の管理を独立した抽象化単位として切り離すことを重視していた。ところが、v5 の推奨は正反対だ。queryKey と queryFn を一つの単位として再びまとめることである。TkDodo はこれについて、「queryKey と queryFn を分離したのは誤りだった」とまで述べている。結局、キーは関数が使う依存関係の集合であり、両者は切り離せない関係にあるからだ。

実務で使う queryOptions の合成パターン

queryOptions の真価は、ドメイン別のファクトリーと組み合わせたときに発揮される。v5 の公式ドキュメントが推奨する形は、次のとおりだ。

import { queryOptions } from '@tanstack/react-query';
 
export const todoQueries = {
  all: () => ['todos'] as const,
  lists: () => [...todoQueries.all(), 'list'] as const,
  list: (filters: TodoFilters) =>
    queryOptions({
      queryKey: [...todoQueries.lists(), filters],
      queryFn: () => fetchTodos(filters),
      staleTime: 30 * 1000,
    }),
  details: () => [...todoQueries.all(), 'detail'] as const,
  detail: (id: number) =>
    queryOptions({
      queryKey: [...todoQueries.details(), id],
      queryFn: () => fetchTodo(id),
      staleTime: 5 * 60 * 1000,
    }),
};

このパターンが優れている理由を、一つずつ見ていこう。

1. 階層構造と型推論を同時に得られる。

todoQueries.all() や todoQueries.lists() は単に配列を返すが、todoQueries.detail(1) は queryOptions によって作られた、データタグ付きのオブジェクトを返す。無効化には配列を、クエリの呼び出しにはオプションオブジェクトを使えばよい。

useQuery(todoQueries.detail(1));                                // 옵션 객체
queryClient.invalidateQueries({ queryKey: todoQueries.all() }); // 배열

2. コンポーネントでオプションを部分的に上書きできる。

queryOptions の結果は最終的にはオブジェクトなので、呼び出す時点で一部のオプションを合成できる。

const { data: title } = useQuery({
  ...todoQueries.detail(1),
  select: (todo) => todo.title,  // 컴포넌트별로 다른 select 적용
});

このパターンが特に強力なのは、select の返り値の型が自動的に推論され、data の型が string に絞り込まれる点だ。コンポーネント側では必要な部分だけを選んで使いながら、ドメインの定義は一か所に保てる。

3. useQuery をラップするカスタムフックが次第に不要になる。

v4 の頃は、ドメインごとにカスタムフックを作るのが一般的なパターンだった。

この方法の問題は、プリフェッチが必要になった瞬間、同じ定義をもう一度書かなければならないことだった。useTodoDetail はフックなのでコンポーネントの外では呼べない。そのため、ルーターのローダーやイベントハンドラーでは、再び queryClient.prefetchQuery({ queryKey: [...], queryFn: ... }) と書く必要があった。

queryOptions を使えば、この重複はなくなる。

同じ一つの定義が、どこでも機能する。そのため TkDodo は、「v5 ではフックを作るより queryOptions を定義する」ことを推奨している。フックは必要なときだけ薄くラップするための道具となり、ドメインの定義はフックがなくても自立して存在できる。

ミューテーションの無効化

queryKey の階層構造が真価を発揮するのは、ミューテーション後の無効化だ。TanStack Query のクエリの無効化に関するドキュメントによると、invalidateQueries は既定で接頭辞一致を行う。

// 모든 todos 관련 쿼리 (list, detail, lists 모두)
queryClient.invalidateQueries({ queryKey: todoQueries.all() });
 
// 모든 list만 (detail은 건드리지 않음)
queryClient.invalidateQueries({ queryKey: todoQueries.lists() });
 
// 정확히 이 키만 (자식 키 매치 안 함)
queryClient.invalidateQueries({
  queryKey: todoQueries.detail(1).queryKey,
  exact: true,
});
 
// 더 복잡한 조건은 predicate으로
queryClient.invalidateQueries({
  predicate: (query) =>
    query.queryKey[0] === 'todos' &&
    (query.queryKey[2] as any)?.version >= 10,
});

キーが階層的に設計されていれば、無効化の範囲とコードの意味が一致する。 「todos をすべて更新する」は all()、「リストだけ更新する」は lists()、「この項目だけ更新する」は detail(id) で表現できる。

もしキーが ['todoList']、['todoDetail', 1] のように平面的に散らばっていたら、「todos ドメイン全体」を無効化するために二つの呼び出しを別々に記述するか、専用の接頭辞定数を作って管理しなければならなかっただろう。（そして新しいドメインキーを追加するたびに、その定数への追加を忘れると、無効化から漏れる不具合が発生する。）

queryFn 内で queryKey を取り出して使う

最後に、もう一つ触れておきたいパターンがある。queryFn は実際には QueryFunctionContext というオブジェクトを引数として受け取り、その中には呼び出し時の queryKey がそのまま含まれている。

queryOptions({
  queryKey: ['user', userId, { include: 'profile' }] as const,
  queryFn: ({ queryKey }) => {
    const [, id, options] = queryKey;
    return fetchUser(id, options);
  },
});

このパターンはなぜ役立つのだろうか。TkDodo のクエリ関数コンテキストを活用するによれば、queryKey と queryFn の依存関係を強制的に同期できるからだ。

const sortBy = 'name';
 
queryOptions({
  queryKey: ['users'],
  queryFn: () => fetchUsers({ sortBy }),
});

このコードは、queryFn が外部変数に依存している危険なコードだ。しかも、sortBy が変わってもキャッシュは更新されない。依存関係をキーに含めていないからだ。しかし、queryFn が外部のクロージャから変数を取り込む限り、このようなミスはいつでも起こり得る。

解決策は単純だ。queryFn が外部変数に依存しないようにする。すべての依存関係を queryKey から取り出して使えば、queryKey に含まれていない変数は、そもそも関数内で使えなくなる。

queryOptions({
  queryKey: ['users', { sortBy }] as const,
  queryFn: ({ queryKey: [, { sortBy }] }) => fetchUsers({ sortBy }),
});

このように書けば、新しい依存関係が増えたとき、queryKey に含めずに関数内で使うことはできない。コンパイラが「そのキーは存在しない」と検出してくれる。キーと関数の同期を規約ではなく、型システムに委ねるわけだ。

どこまで分離するべきか

ここまで読むと、一つ疑問が浮かぶかもしれない。「では、すべてのクエリを queryOptions に切り出すべきなのか」

筆者の答えは、いつもどおり**「状況による」**だ。

覚えておきたいのは、抽象化が常によいとは限らないことだ。一度しか使わないクエリをわざわざドメインファクトリーへ切り出すと、コードを読む人が二つのファイルを行き来するだけになる。queryKey 管理パターンの進化は、「常により精巧な道具を使うべきだ」という意味ではない。**「必要になったとき、はしごを一段ずつ上る選択肢がある」**と捉えるのがよい。

まとめ

まとめると、queryKey は、TanStack Query が非同期データを識別してキャッシュするための最も基本的な単位だ。その小さな配列には、キャッシュスロットの識別子、依存配列、無効化の範囲、そして v5 ではデータ型の情報までが凝縮されている。一点にこれほど多くの責務が集まっているからこそ、どのように記述し、どのように管理するかが、コードベース全体の認知負荷に直結する。

各段階は、その時点で誰かが直面した現実の問題に対する答えだった。だから、単に「今は v5 だから、常に queryOptions だけを使えばよい」のではなく、**「自分のコードベースは今、どの段階の問題に直面しているのか」**を先に見極めるのが正しい順序だ。インライン配列で十分なプロジェクトへドメインファクトリーを導入することは、それ自体が過剰設計になり得る。

読者の皆さんも、自分のプロジェクトで一度確認してみてほしい。queryKey がコード全体にどのように散らばっているか、無効化がどのように行われているか、そしてその構造が現在のチーム規模とドメインの複雑さに合っているかを。

参考資料

筆者は実務でエラーハンドリングを書くたび、どこか釈然としない感覚を抱くことが多かった。あるエラーは try/catch で捉え、別のエラーは ErrorBoundary が捉え、さらに別のエラーは TanStack Query の onError が捉える。それぞれの守備範囲は微妙に重なったり、ずれたりする。その結果、エラーが漏れる日もあれば、意図しない場所まで伝播する日もあった。

問題は、こうした道具の挙動をまとめて整理する機会がほとんどなかったことだ。「Error Boundary はレンダー段階のエラーだけを捉える」とは知っていても、それが実際に何を意味するのか、reset を呼ぶと内部で何が起きるのか、throwOnError を有効にしたとき TanStack Query がいつエラーを再送出するのかを正確に説明しろと言われると、答えに詰まってしまう。

この記事では、React の公式ガイド、react-error-boundary ライブラリ、TanStack Query v5 の公式ドキュメントをもとに、フロントエンドのエラーハンドリングに使う各ツールがどこまでを担うのか、そしてどう組み合わせるのかを整理する。

React が捉えられるエラー、捉えられないエラー

最も基本的な問いから始めよう。React はどのようなエラーを捉えるのか。

React の公式ドキュメントでは、Error Boundary が捉えられるエラーと、捉えられないエラーを明確に区別している。

Error Boundary が捉える範囲

• 子コンポーネントのレンダー中に発生したエラー
• ライフサイクルメソッド内で発生したエラー
• コンストラクターで発生したエラー

Error Boundary が捉えられない範囲

• イベントハンドラー内のエラー
• setTimeout、requestAnimationFrame、Promise などの非同期コードのエラー
• **サーバーサイドレンダリング（SSR）**中のエラー
• Error Boundary 自身で発生したエラー

なぜこの区別が重要なのだろうか。普段扱うエラーの大半は、実は**後者に属する。**ボタンのクリックからミューテーションを実行したところサーバーが 500 を返した、useEffect 内のデータ取得が失敗した、フォーム送信中に検証ロジックが例外を送出した、といったケースだ。これらのエラーを React が自動で捉えることはない。開発者が明示的に捕捉して処理する必要がある。

したがって、フロントエンドのエラーハンドリングは二つに分かれる。レンダー段階のエラーは Error Boundary で、それ以外のエラーは try/catch やライブラリのコールバックで扱う。この二つが交わる地点で、TanStack Query のような非同期状態管理ライブラリが橋渡しの役割を果たす。

Error Boundary の正体

Error Boundary は、結局のところ二つのライフサイクルメソッドを持つクラスコンポーネントだ。React の公式ドキュメントによると、Error Boundary になるには、次の二つのメソッドのいずれか（通常は両方）を実装する必要がある。

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }
 
  // 에러 발생 시 state를 업데이트해 다음 렌더에서 fallback UI를 보여준다
  static getDerivedStateFromError(error) {
    return { hasError: true };
  }
 
  // 에러가 발생한 직후에 호출. 로깅 같은 사이드이펙트는 여기서 처리한다
  componentDidCatch(error, info) {
    logErrorToMyService(error, info.componentStack);
  }
 
  render() {
    if (this.state.hasError) {
      return this.props.fallback;
    }
    return this.props.children;
  }
}

getDerivedStateFromError は純粋関数でなければならない。副作用を起こさず、新しい状態だけを返す役割だ。一方、componentDidCatch は副作用を扱う場所である。Sentry へのエラー送信や、コンソールへのコンポーネントスタック出力はここで行う。

ここで重要な点が一つある。この二つのメソッドは**クラスコンポーネントにしか存在しない。**関数コンポーネントで Error Boundary を作る公式な方法は、今のところない。React 公式ドキュメントにも明記されている。

現在、Error Boundary を関数コンポーネントとして記述する方法はありません。

There is currently no way to write an Error Boundary as a function component.

毎回クラスコンポーネントを自分で書くのは煩雑なので、通常は react-error-boundary ライブラリを使うことになる。（React のメンテナーの一人だった Brian Vaughn が開発したライブラリで、事実上の標準として利用されている。）

react-error-boundary が提供する三つのフォールバック

react-error-boundary の ErrorBoundary コンポーネントでは、フォールバック UI を指定するプロパティが三つの形式で用意されている。それぞれの使い方を簡単に見てみよう。

フォールバック

最も単純な形式で、静的な JSX をそのまま渡す。

<ErrorBoundary fallback={<div>문제가 발생했습니다.</div>}>
  <Page />
</ErrorBoundary>

エラーオブジェクトやリセット関数にアクセスする必要がない場合に使う。実務ではエラーメッセージや再試行の操作が必要になることが多く、筆者はこれまで使ったことがない。

FallbackComponent

フォールバック UI を別のコンポーネントに切り出し、その参照を渡す。

function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <p>오류가 발생했습니다.</p>
      <pre>{error.message}</pre>
      <button onClick={resetErrorBoundary}>다시 시도</button>
    </div>
  );
}
 
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Page />
</ErrorBoundary>

エラーオブジェクトと resetErrorBoundary 関数が props として自動的に注入される。フォールバック UI をほかの場所でも再利用する可能性があるなら、この形式がすっきりしている。

fallbackRender

フォールバックをインラインで描画したいときに使う。

<ErrorBoundary
  fallbackRender={({ error, resetErrorBoundary }) => (
    <div role="alert">
      <p>오류가 발생했습니다: {error.message}</p>
      <button onClick={resetErrorBoundary}>다시 시도</button>
    </div>
  )}
>
  <Page />
</ErrorBoundary>

FallbackComponent と本質的には同じ役割だが、別のコンポーネントを作らずインラインで処理できる。外側のクロージャー（親の状態やハンドラーなど）へアクセスする必要があるときに便利だ。

三つのうち、どれか一つが正解というわけではない。筆者が実務でよく使うのは、共通の ErrorFallback コンポーネントを一つ用意し、FallbackComponent で注入するパターンだ。デザインシステムとトーンの一貫性を保つためである。ページごとに異なるフォールバックが必要な場合だけ、fallbackRender でインラインに記述する。

リセットは実際に何をするのか

react-error-boundary を使っていると、自然と resetErrorBoundary という関数に出会う。フォールバックの「もう一度試す」ボタンから呼ばれる、あの関数だ。この関数が実際に何をするのかを見てみよう。

結論から言うと、resetErrorBoundary は ErrorBoundary コンポーネントに対して、自身の状態を初期化し、子要素を再レンダーするよう通知するだけだ。TanStack Query のキャッシュなど、外部の状態を自動的に変更することはない。

内部で起きることを順に整理すると、次のようになる。

1. resetErrorBoundary() が呼ばれる。
2. ErrorBoundary 内部の hasError 状態が false に戻る。
3. （任意）onReset コールバックが実行される。ユーザー定義の副作用はここで起きる。
4. 子要素が再レンダーされる。エラーの原因となった状態やキャッシュなどが残っていれば、同じエラーが再び送出される。

最後の 4 番目が重要だ。**リセットは「エラーを忘れてもう一度描画してみる」という意味にすぎず、「エラーを引き起こした原因を直す」という意味ではない。**そのため、リセットするだけでは同じエラーが無限に繰り返される可能性がある。

この問題に対処するため、さらに二つの仕組みが用意されている。

onReset

リセットが起きる直前に呼ばれるフックの役割を担う。ここで、エラーの原因となった外部状態を整理する。

<ErrorBoundary
  FallbackComponent={ErrorFallback}
  onReset={() => {
    queryClient.invalidateQueries({ queryKey: ['user'] });
  }}
>
  <Page />
</ErrorBoundary>

resetKeys

配列に含まれる値が変わると、ErrorBoundary が自動的にリセットされる。URL パラメーター、検索語、選択中のタブなど、「この値が変わったなら再試行する意味がある」と判断できるキーを渡す。

<ErrorBoundary
  FallbackComponent={ErrorFallback}
  resetKeys={[userId]}
>
  <UserProfile userId={userId} />
</ErrorBoundary>

userId が変わると自動的にリセットされ、子要素が再レンダーされる。ユーザーが別のプロフィールへ移動すれば、以前のエラーは自然に消える。

イベントハンドラーと非同期エラーはどう捉えるのか

前述のとおり、Error Boundary はイベントハンドラーや非同期コードのエラーを捉えられない。しかし、扱うエラーの大半はそこで発生する。では、どうすればよいのだろうか。

react-error-boundary は、この問題に対処するための useErrorBoundary フックを提供している。このフックは showBoundary という関数を返す。この関数を呼ぶと、最も近い ErrorBoundary へ強制的にエラーを送ることができる。

import { useErrorBoundary } from 'react-error-boundary';
 
function MyComponent() {
  const { showBoundary } = useErrorBoundary();
 
  const handleClick = async () => {
    try {
      await someAsyncOperation();
    } catch (error) {
      showBoundary(error);
    }
  };
 
  return <button onClick={handleClick}>실행</button>;
}

重要なのは、開発者が明示的に引き上げる必要があるという点だ。React が自動で行うわけではない。非同期エラーを ErrorBoundary の領域へ移したいなら、try/catch で捉えて showBoundary に渡さなければならない。

このパターンを理解すれば、「ErrorBoundary が捉えるエラーと捉えられないエラーがあるのはなぜか」という疑問は明快に解ける。答えは単純だ。**「レンダー段階まで引き上げたかどうか」**である。

TanStack Query はエラーをどう扱うのか

ここまで整理すると、自然に次の疑問が浮かぶ。日々使っている useQuery は非同期リクエストを扱うが、そこで発生したエラーはどのように処理されるのだろうか。

TanStack Query は、デフォルトではエラーを error フィールドとして公開する。

const { data, error, isError } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
});
 
if (isError) {
  return <div>에러: {error.message}</div>;
}

これが最も単純な形式だ。エラーが発生してもコンポーネントは通常どおりレンダーされ、単に error フィールドへ値が入るだけである。ErrorBoundary は関与しない。

ここで重要な事実を確認しておこう。**TanStack Query のデフォルトの挙動は「エラーを送出しない」ことだ。**クエリ関数が例外を送出しても Promise を reject しても、そのエラーは error フィールドに格納されるだけで、React のレンダーフローを中断しない。そのため、特別な設定をしない限り ErrorBoundary が動作することはない。

もう一つ、TanStack Query はデフォルトでエラー時に自動で 3 回再試行する。

デフォルトの retryDelay は指数バックオフ方式で、最大 30 秒まで延びる。つまり、最初に失敗してもユーザーへすぐエラーが表示されるわけではない。1 秒、2 秒、4 秒の間隔で再試行し、それでも失敗すると、ようやく error フィールドへ値が入る。（開発中に「なぜエラーが表示されるまで時間がかかるのだろう」と疑問に思ったことがあるなら、十中八九これが原因だ。）

throwOnError で ErrorBoundary と接続する

では、TanStack Query のエラーを ErrorBoundary へ流すにはどうすればよいのか。答えは throwOnError オプションだ。（v4 までは useErrorBoundary という名前だったが、v5 で throwOnError に変更された。）

const { data } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  throwOnError: true,
});

このオプションを有効にすると、TanStack Query はエラーを**次のレンダーサイクルで再送出する。**すると、その例外送出はレンダー段階のエラーとなり、ErrorBoundary が捉えられるようになる。

throwOnError には関数も渡せる。あるエラーは ErrorBoundary へ送り、別のエラーはコンポーネント自身で処理する、といった分岐が可能だ。

useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  // 5xx 서버 에러만 ErrorBoundary로 보낸다
  throwOnError: (error) => error.response?.status >= 500,
});

このパターンが実用的なのは、**4xx のようなクライアントエラー（入力検証の失敗や権限不足など）**はその場でメッセージを表示するのが自然であり、5xx のようなサーバーエラーはページ全体を覆って「しばらくしてからもう一度お試しください」と表示するのが適切だからだ。

useSuspenseQuery

useSuspenseQuery を使っている場合、throwOnError を意識する必要はない。Suspense モードでは、常にエラーを送出するのがデフォルトの挙動である。

つまり、useSuspenseQuery を使うことは、ローディングは Suspense が、エラーは ErrorBoundary が処理するということだ。コンポーネント内で if (isError) や if (isLoading) といった分岐を書く必要がなくなり、代わりに外側を二つの境界で囲む必要がある。

QueryErrorResetBoundary

ここまで読むと、さらに一つ疑問が浮かぶ。ユーザーがフォールバックの「もう一度試す」ボタンを押すと、どうなるのだろうか。

先ほど見たように、resetErrorBoundary が初期化するのは ErrorBoundary の hasError 状態だけだ。しかし、TanStack Query のキャッシュには、依然としてエラー状態のまま固まったクエリが残っている。子要素が再レンダーされると、TanStack Query はキャッシュを見て「このクエリはすでにエラーだ」と判断し、すぐに同じエラーを再送出する。（恐ろしい無限ループだ。）

この問題を解決するため、TanStack Query は useQueryErrorResetBoundary フックと QueryErrorResetBoundary コンポーネントを提供している。長い名前だが、役割は単純だ。**「この領域内にあるクエリのエラー状態をリセットせよ」**と指示する。

import { useQueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
 
function App() {
  const { reset } = useQueryErrorResetBoundary();
 
  return (
    <ErrorBoundary
      onReset={reset}
      fallbackRender={({ resetErrorBoundary }) => (
        <div>
          <p>에러가 발생했습니다.</p>
          <button onClick={resetErrorBoundary}>다시 시도</button>
        </div>
      )}
    >
      <Page />
    </ErrorBoundary>
  );
}

ここで起きることを時系列で整理しよう。

1. ユーザーが「もう一度試す」ボタンをクリック → resetErrorBoundary() が呼ばれる
2. ErrorBoundary が onReset コールバックを実行 → reset() が呼ばれる（TanStack Query のエラー状態を初期化）
3. ErrorBoundary が自身の状態を初期化し、子要素を再レンダー
4. 子要素内の useQuery が動作 → エラー状態が消えているため、再びデータ取得を試みる

重要なのは、onReset に reset を接続した部分だ。この一行によって、ErrorBoundary と TanStack Query の状態が同期される。

コンポーネントとして使う場合

フックではなく、コンポーネントでも同じことができる。どちらか一方を使えばよい。

import { QueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
 
function App() {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary
          onReset={reset}
          fallbackRender={({ error, resetErrorBoundary }) => (
            <div role="alert">
              <p>에러가 발생했습니다: {error.message}</p>
              <button onClick={resetErrorBoundary}>다시 시도</button>
            </div>
          )}
        >
          <Page />
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}

フック版との最大の違いは、レンダープロップパターンで reset 関数を子へ渡すことだ。QueryErrorResetBoundary は子要素として関数を受け取り、その引数として { reset } を渡し、関数の戻り値をレンダーする。そのため、内側ですぐ onReset={reset} と接続できる。

フック版では、最も近い QueryErrorResetBoundary がなければ**グローバルキャッシュのエラーをリセットする。**コンポーネント版では、リセットのスコープを自身の子領域に限定する。範囲を狭く制御したいなら、コンポーネント版のほうが安全だ。

ここで一つ確認しておこう。**リセットはキャッシュを削除しない。**データを丸ごと消すのではなく、「エラーとマークされたクエリのエラー状態を解除する」ことに近い。実際にデータを無効化したい場合は、queryClient.invalidateQueries() を別途呼ぶ必要がある。

ミューテーションのエラー

ここまで説明したパターンは、ほぼすべて useQuery を前提としていた。しかし、useMutation では事情が少し異なる。

最大の違いは、ミューテーションは通常、**ユーザーの明示的な操作（クリックや送信）**によって開始されることだ。そのため、エラーもその操作に近い場所で処理するのが自然である。ページ全体をフォールバックで覆うより、トーストやフォーム脇のエラーテキストで「決済に失敗しました。カード情報をもう一度確認してください」のように表示するほうが適切だ。

TkDodo の React Query におけるミューテーションの使いこなしでは、この違いの本質を一言でまとめている。**クエリは宣言的で、ミューテーションは命令的である。**クエリはコンポーネントがマウントされると自動的に実行され、同じキーを持つほかのコンポーネントも共同で購読し、キャッシュして再利用される。一方、ミューテーションはユーザーがボタンを押して初めて実行され、キャッシュもされず、呼び出したコンポーネントのインスタンスと一対一で結び付く。この本質的な違いが、エラー処理の方法を二つに分ける。

useQuery のデフォルトの retry は 3 だが、useMutation のデフォルトの retry は 0 である。理由は単純で、ミューテーションは副作用を引き起こすからだ。決済リクエストがネットワークのタイムアウトで失敗したとき、ライブラリが自動的にさらに 2 回呼び出せば、ユーザーのカードへ 3 回請求されるかもしれない。

したがって、ミューテーションの再試行は、その処理が冪等であると開発者が確信できる場合に限り明示的に有効にするのが原則だ。同じリクエストを 2 回送っても結果が変わらないことが保証される GET 系の安全な取得処理や、サーバーが冪等性キーを受け取って重複を防ぐ場合に限られる。

useQuery のエラーは**キャッシュに保持される。**そのため、同じ queryKey を購読するほかのコンポーネントにもすぐ伝播し、QueryErrorResetBoundary のような仕組みで一括してリセットする必要があった。

ミューテーションは異なる。あるコンポーネントのミューテーションインスタンスで発生したエラーは、**そのインスタンスの状態にだけ残る。**同じ mutationFn を使う別のコンポーネントのミューテーションには影響しない。そのため、TanStack Query に MutationErrorResetBoundary のようなものは存在しない。必要がないからだ。

この違いは実務にも一つ影響する。同じ useMutation を呼ぶコンポーネントが二つあっても、一方で発生したエラーはもう一方からは見えない。「このミューテーションのエラーをアプリケーション全体で把握したい」のであれば、コンポーネント単位の onError では不十分で、MutationCache.onError まで引き上げる必要がある。

mutate と mutateAsync

useMutation は二つの実行関数を返す。この違いによって、エラーハンドリングの方法が分かれる。

mutate の戻り値の型は void であり、Promise を返さない。そのため await で結果を待つことはできず、呼び出し結果は onSuccess/onError などのコールバックを通じてのみ受け取れる。

const mutation = useMutation({
  mutationFn: createPost,
  onError: (error) => {
    toast.error(`등록 실패: ${error.message}`);
  },
});
 
mutation.mutate(newPost);

一方、mutateAsync は Promise を返す。エラーは try/catch で処理できる。

const mutation = useMutation({ mutationFn: createPost });
 
const handleSubmit = async () => {
  try {
    const result = await mutation.mutateAsync(newPost);
    router.push(`/posts/${result.id}`);
  } catch (error) {
    // 여기서 처리
  }
};

どちらをいつ使えばよいのか。筆者は次の基準で使い分けている。

• ミューテーションの完了後に後続処理が必要（成功時のルーティングや結果の利用など）→ mutateAsync
• 単に呼び出し、副作用はコールバックへ任せる（「いいね」の切り替えや、トーストを表示するだけの場合など）→ mutate + onError

ここで、よくある間違いが一つある。**mutateAsync を使いながら try/catch を置かないと、未処理の Promise rejection が発生する。**コールバックベースの mutate は内部でエラーを吸収するが、mutateAsync は呼び出し元へエラーを送出するのがデフォルトの挙動だ。この違いを知らずに混在させると、コンソールが赤い警告で埋め尽くされる。

onError

もう一つ見落としやすい点がある。useMutation の onError は二か所（フックと mutate）で定義できる。

const mutation = useMutation({
  mutationFn: createPost,
  onError: (error) => {
    Sentry.captureException(error);
  },
});

フックレベルでは常に実行されるが、mutate レベルでは呼び出し時にのみ実行される。

mutation.mutate(newPost, {
  onError: (error) => {
    setFormError(error.message);
  },
});

公式ドキュメントに明記された実行順序は、フックレベル → mutate レベルである。両方のコールバックが定義されている場合、まずフックレベル、続いて mutate レベルが実行される。

グローバルなエラーハンドリング

ここまでのパターンは、すべてコンポーネントレベルのものだった。しかし、「すべてのクエリエラーを一か所で記録したい」「401 エラーは必ずログアウトとして処理したい」といった要件もあり得る。このような横断的関心事には、QueryClient の作成時に QueryCache/MutationCache へコールバックを設定する方法がある。

import { QueryClient, QueryCache, MutationCache } from '@tanstack/react-query';
 
const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      if (query.state.data !== undefined) {
        toast.error(`데이터 갱신 실패: ${error.message}`);
      }
    },
  }),
  mutationCache: new MutationCache({
    onError: (error) => {
      if (error.status === 401) {
        redirectToLogin();
      }
    },
  }),
});

重要なのは、QueryCache.onError がクエリごとに一度だけ呼ばれることだ。同じクエリを複数のコンポーネントが購読していても、コールバックは一度しか実行されないため、トーストが重複するような問題は起きない。

上の例のように、query.state.data !== undefined を確認する方法もある。すでにキャッシュ済みのデータがある状態で再取得に失敗したのであれば、ユーザーはひとまず画面上でデータを見られている。このとき ErrorBoundary でページを覆うのは過剰だ。更新に失敗したことだけを知らせるのが適切である。反対に、キャッシュデータがない初回ロードで失敗した場合は、ErrorBoundary が捉えてフォールバックを表示するのが妥当だ。

この二つの流れを組み合わせれば、「初回ロードの失敗は ErrorBoundary、バックグラウンドでの再取得の失敗はトースト」という明快な方針を設計できる。

共通コンポーネント

ここまで読むと、一つ欲が出てくる。毎回 QueryErrorResetBoundary、ErrorBoundary、Suspense の三重構造で囲むのは面倒なので、一つのコンポーネントにまとめて再利用できないだろうか。

自然な発想だ。実際、筆者も以前は次のような AsyncBoundary コンポーネントを作って使っていた。

import { QueryErrorResetBoundary } from '@tanstack/react-query';
import { Suspense, type ComponentType, type ReactNode } from 'react';
import { ErrorBoundary, type FallbackProps } from 'react-error-boundary';
import { ErrorFallback } from './ErrorFallback';
import { Spinner } from './Spinner';
 
interface Props {
  children: ReactNode;
  pendingFallback?: ReactNode;
  rejectedFallback?: ComponentType<FallbackProps>;
}
 
export function AsyncBoundary({
  children,
  pendingFallback = <Spinner />,
  rejectedFallback = ErrorFallback,
}: Props) {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary onReset={reset} FallbackComponent={rejectedFallback}>
          <Suspense fallback={pendingFallback}>{children}</Suspense>
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}