骨組みは、Thoughtworks の Juntao Qiu が 2023 年 2 月に martinfowler.com で連載した Modularizing React Applications with Established UI Patterns だ。原文をそのまま訳さず筆者の言葉で解き直しており、本文の図はすべてこの原文から借りている。その上に、著者のサンプルリポジトリを取得して型チェックとテストを回した結果と、同じ問題を扱った別の資料を付け加えた。

React は view library

React を初めて学ぶとき最も魅力的な考え方は、UI はデータを DOM に変える純粋関数だというものだ。ある程度は正しい。ところがサーバーにリクエストを送ったりページを遷移したりした瞬間、component はもう純粋ではない。そこにグローバルな state とローカルな state が絡むと、コードはすぐに複雑になる。

著者の答えは視点を変えることだ。「React アプリケーション」という特別な種類のソフトウェアは存在しない。React は UI を描く library であり、計算や業務ルールをどこに置くかは最初から関心の外にある。その上に載っているのはごく普通の JavaScript アプリだ。それなら、デスクトップ GUI の時代から使われてきた設計、特にコードを presentation、domain、data の三つの layer に分ける方法をそのまま使える。

実際のフロントエンドアプリには view 以外にも、router、local storage、いくつかのレベルのキャッシュ、ネットワークリクエスト、外部サービス連携とログイン、セキュリティ、ロギング、パフォーマンス調整がある。これを全部 component と hook に押し込むと、一つのファイルの中で注文状態をリクエストする行の次に文字列の先頭の空白を削る行が来て、その次に別の画面へ遷移する行が来る。読む人は抽象度を何度も切り替えながら前後を行き来しなければならない。

分ける理由は二つにまとめられる。画面は業務ルールより頻繁に変わる。そして二つを切り離しておけば、一度に一つのことだけ考えればよい。二つ目の理由は、Martin Fowler が PresentationDomainDataLayering でこの区分の最大の利点として挙げたものだ。三つのテーマを比較的別々に考えられるので、注意を向ける範囲が狭まる。

アプリが育つ五つの段階

著者はリファクタリングに入る前に、アプリが育つにつれて構造がどう変わるかを五枚の図で見せる。重要なのは次の段階へ進むきっかけだ。決まったタイミングではなく、その段階で生じる不便が次の段階を呼び込む。図の色は五枚とも同じ意味だ。黄緑は state を持つ container component、濃い緑は描画だけを担う presentational component、紫は hook、青は domain object、オレンジはネットワークのような infrastructure だ。

最初は component 一つがネットワークリクエスト、state、計算、render をすべて持つ。小さなアプリや使い捨てのプロジェクトならこれで十分で、コードが HTML に近いのでむしろ読みやすい。リストを回して項目を作るコードと外部 component を設定するコードが混ざり、何が起きているのかを読むのに時間がかかり始めたら次の段階へ進む。

画面が大きくなると、出力される HTML の形に沿って component を分ける。描画だけの component は切り出されるが、一番上の component にはネットワークリクエスト、レスポンスを画面用の形に変えるコード、サーバーに送るデータを集めるコードがそのまま残る。三つとも UI ではないのに component の中にある。

次に state とその変化を custom hook に切り出す。すると hook の中に、side effect でも state でもない純粋な計算が残る。

その計算を React と無関係なオブジェクトに切り出すと domain object が生まれる。データ形式の変換、null チェック、代替値がここに来る。オブジェクトが増えると、継承やポリモーフィズムが必要になり始める。

最後に、UI にも属さず、データがサーバーから来るのか local storage やキャッシュから来るのかも気にしないオブジェクトが見えてきたら、それを別の model layer としてまとめる。

図だけでは抽象的だ。この五つの段階を実際のコードで一度たどってみよう。著者が選んだ例は、オンライン注文の決済画面だ。

一つの決済画面から出発する

決済手段はサーバーの設定から来て、国ごとに異なる。サーバーが一つでも返せばその末尾に現金払いを付けてデフォルトで選択しておき、一つもなければ何も表示しない。

最初のコードはチュートリアルでよく見る形だ。useEffect の中で fetch し、レスポンスを画面用の形に変え、現金払いを付け、ラジオボタンのリストを描く。以下は筆者が短くして書き写したものだ。

export const Payment = ({ amount }: { amount: number }) => {
  const [paymentMethods, setPaymentMethods] = useState<LocalPaymentMethod[]>([]);
 
  useEffect(() => {
    fetch(url)
      .then((res) => res.json())
      .then((methods: RemotePaymentMethod[]) => {
        if (methods.length === 0) return setPaymentMethods([]);
        const extended = methods.map((m) => ({ provider: m.name, label: `Pay with ${m.name}` }));
        extended.push({ provider: "cash", label: "Pay in cash" });
        setPaymentMethods(extended);
      });
  }, []);
 
  return (
    <div>
      {paymentMethods.map((method) => (
        <label key={method.provider}>
          <input type="radio" defaultChecked={method.provider === "cash"} />
          {method.label}
        </label>
      ))}
      <button>${amount}</button>
    </div>
  );
};

このサイズなら問題ではない。しかしこの component を直すには、四つのことを一緒に理解する必要がある。ネットワークリクエストをどう始めるか、サーバーのデータを画面が知っている形にどう変えるか、決済手段一つをどう描くか、決済エリア全体をどう描くかだ。コードが大きくなると、読む人はこの四つの間を何度も行き来しなければならない。

hook と pure component

最初に取り出すのは state と fetch だ。判断のシグナルは単純だ。render と関係ないコードが component 本体の半分を超えたら hook に切り出す。usePaymentMethods が fetch と変換を受け持ち、component は hook から受け取った配列を描くだけになる。

二つ目はリストを描く JSX だ。props だけ受け取れば描けるブロックが見えたら component として切り離す。PaymentMethods は決済手段の配列一つだけを受け取る pure component なので、テストも再利用もしやすい。後で選択を知らせる onSelect callback が付いても外側の state には触れないので、依然として pure だ。

const usePaymentMethods = () => {
  const [paymentMethods, setPaymentMethods] = useState<LocalPaymentMethod[]>([]);
  useEffect(() => { /* 위의 fetch와 변환 */ }, []);
  return { paymentMethods };
};
 
export const Payment = ({ amount }: { amount: number }) => {
  const { paymentMethods } = usePaymentMethods();
  return (
    <div>
      <PaymentMethods paymentMethods={paymentMethods} />
      <button>${amount}</button>
    </div>
  );
};

著者はどちらの作業もリファクタリングカタログの Extract Function だと呼ぶ。React では component も関数だからだ。新しい概念を持ち込んだのではなく、関数一つを二つに分けただけだという点が重要だ。

これで終わったように見えるが、まだ二か所残っている。view の中には「現金ならデフォルトで選択」という判定があり、hook の中にはレスポンスを画面用の形に変える無名関数がある。著者は、このように業務ルールが view や hook に漏れ出たものを logic leak と呼ぶ。

domain object に集めたルール

三つ目のシグナルは、同じデータに対する判定が view と hook に散らばっているときだ。漏れ出た判定と変換を PaymentMethod class 一つに集める。このブログのドメインモデルで扱ったように、ルールをデータのそばに置くということだ。

class PaymentMethod {
  constructor(private remote: RemotePaymentMethod) {}
  get provider() { return this.remote.name; }
  get label() { return this.provider === "cash" ? "Pay in cash" : `Pay with ${this.provider}`; }
  get isDefaultMethod() { return this.provider === "cash"; }
}
 
const convertPaymentMethods = (methods: RemotePaymentMethod[]) =>
  methods.length === 0
    ? []
    : [...methods.map((m) => new PaymentMethod(m)), new PaymentMethod({ name: "cash" })];

view のラジオボタンは、今度は defaultChecked={method.isDefaultMethod} でオブジェクトに問い合わせる。現金払いのデフォルト値も同じ class のインスタンス一つで表現される。サーバーがくれたものとアプリが付け足したものが同じ形になるので、view は両者を区別する必要がない。

著者はこの構造の利点として、テストが簡単になることを挙げる。原文はそこで止まっているが、どれだけ簡単になるかはコードで見たほうが早い。以下は筆者が書いたテストだ。React も、レンダラーも、fetch の mock もない。

test("서버가 준 결제 수단 끝에 현금 결제를 기본값으로 붙인다", () => {
  const methods = convertPaymentMethods([{ name: "apple" }, { name: "google" }]);
 
  expect(methods.map((m) => m.label)).toEqual(["Pay with apple", "Pay with google", "Pay in cash"]);
  expect(methods.filter((m) => m.isDefaultMethod).map((m) => m.provider)).toEqual(["cash"]);
});
 
test("서버가 아무것도 주지 않으면 현금 결제도 보여 주지 않는다", () => {
  expect(convertPaymentMethods([])).toEqual([]);
});

同じルールを最初のコードで確かめるには、component を render し、fetch を横取りし、ラジオボタンが描かれるまで待たなければならなかった。ルールがオブジェクトとして外に出た瞬間、テストは関数呼び出し一行になる。

もう一つの利点は、新しい要件が来たときに行き先が決まっていることだ。この時点のファイル構成はこうなる。

src
├── components
│   ├── Payment.tsx
│   └── PaymentMethods.tsx
├── hooks
│   └── usePaymentMethods.ts
└── models
    └── PaymentMethod.ts

構造が本当に持ちこたえるかは、新しい要件が来てみないとわからない。著者はここで機能をもう一つ加える。

寄付機能と state machine としての hook

新しい要件は、注文金額を切り上げてその差額を慈善団体に寄付できるようにすることだ。19.80 ドルの注文なら 0.20 ドルの寄付を尋ね、同意すればボタンに 20 ドルと表示する。

著者はわざと、最初は同意の有無の state と計算を決済 component の中に入れる。チェックボックスのマークアップ、文言の分岐、合計の計算が一度に入ってきて、component は再び重くなる。整理する順番は前に見たとおりだ。state と計算は useRoundUp hook へ、文言の組み立ては helper 関数へ、チェックボックスのマークアップは DonationCheckbox component へ移る。

export const useRoundUp = (amount: number) => {
  const [agreeToDonate, setAgreeToDonate] = useState(false);
 
  const { total, tip } = useMemo(() => ({
    total: agreeToDonate ? Math.floor(amount + 1) : amount,
    tip: parseFloat((Math.floor(amount + 1) - amount).toPrecision(10)),
  }), [amount, agreeToDonate]);
 
  const updateAgreeToDonate = () => setAgreeToDonate((v) => !v);
  return { total, tip, agreeToDonate, updateAgreeToDonate };
};

toPrecision(10) は、原文が理由を説明していない部分だ。筆者が Node 24 で動かしてみると、20 - 19.8 は 0.1999999999999993 になった。浮動小数点の誤差を取り除くための仕掛けだ。

著者はこうした hook を「view の背後にある state machine」と捉える。UI からイベントが来ると新しい state を作り、新しい state がまた render を引き起こす。hook は本来、複数の component が logic を共有するために作られたものだが、使う場所が一つでも component を render に集中させてくれるので切り出す価値がある、というのが著者の立場だ。ここに一つ付け加えると、React 公式ドキュメントの Reusing Logic with Custom Hooks が指摘するように、custom hook が共有するのは state を扱う logic であって state そのものではない。この state machine は、hook を呼ぶ component ごとに一つずつ別々に生まれる。

整理が終わると、決済 component は hook を二つ呼び、子 component 二つとボタン一つを並べる形になる。機能が一つ増えたのに、決済 component の役割は変わらない。

国別ルールと shotgun surgery

次の要件は、国ごとに切り上げ単位を変えることだ。日本は 100 円単位、デンマークは 10 クローネ単位だ。著者は「簡単な修正に見える」と言いながら、国コードを prop で受け取って分岐を入れるやり方をわざと先に見せる。

// useRoundUp 안
total: agreeToDonate
  ? countryCode === "JP" ? Math.floor(amount / 100 + 1) * 100 : Math.floor(amount + 1)
  : amount,
 
// 체크박스 문구 helper 안
const currencySign = countryCode === "JP" ? "¥" : "$";
 
// 버튼 JSX 안
<button>{countryCode === "JP" ? "¥" : "$"}{total}</button>

同じ countryCode === "JP" の判定が、hook、helper、ボタンの三か所に一つずつ入った。デンマークを追加すれば三か所すべてを直し直す必要があり、三項演算子で手に負えなくなると国コードから通貨記号を引く表が生まれる。その表も結局あちこちで別々に参照される。一つの変更のために複数のモジュールを同時に直さなければならないこの臭いを、shotgun surgery と呼ぶ。

この段階が前の三つの段階と違うのは、判断のシグナルがコードではなく変更要求から来ることだ。今のコードだけを見れば、三つの分岐は読みにくくない。国を一つ増やすときに何か所直す必要があるかを数えてみて、初めて問題が見える。では、散らばった分岐をどこに集めればよいのか。

Strategy に集めた国ごとの違い

著者の答えは、国ごとの違いそのものをオブジェクトにすることだ。まず Extract Class と Replace Conditional with Polymorphism で、interface 一つと国ごとの実装を作る。

interface PaymentStrategy {
  getRoundUpAmount(amount: number): number;
  getTip(amount: number): number;
}
 
class PaymentStrategyAU implements PaymentStrategy { /* 1달러 단위 */ }
class PaymentStrategyJP implements PaymentStrategy { /* 100엔 단위 */ }

作ってみると、実装ごとに異なるのは通貨記号と切り上げ関数の二つだけで、getTip のような残りは同じだ。そこで著者は Inline Class で実装を一つの class にまとめ、異なる部分だけをコンストラクタで受け取る。国ごとに subclass を作らずに切り上げアルゴリズムを関数として受け取れるのは、JavaScript では関数が値だからだ。以下はその結果を筆者が短くして書いたものだ。

class CountryPayment {
  constructor(readonly currencySign: string, private roundUp: (n: number) => number) {}
  getRoundUpAmount(n: number) { return this.roundUp(n); }
  getTip(n: number) { return parseFloat((this.getRoundUpAmount(n) - n).toPrecision(10)); }
}
 
const japan = new CountryPayment("¥", (n) => Math.floor(n / 100 + 1) * 100);
japan.getRoundUpAmount(3312); // 3400
japan.getTip(3312);           // 88

hook と component はもう国を知らない。このオブジェクト一つを受け取って strategy.getRoundUpAmount(amount) と strategy.currencySign を使うだけだ。国を一つ増やすならオブジェクトを一つ作れば終わりで、直すファイルはない。

interface を経由してからまたまとめ直した過程は、無駄に見えるかもしれない。筆者はこの部分が原文で最も学ぶ価値のあるくだりだと考える。ポリモーフィズムは目的ではなく共通点と相違点を浮かび上がらせる道具であり、違いが関数一つにまで縮んだのが見えたところで class 階層を取り払った。パターンを持ち込むことより、そのパターンをいつ取り払うかのほうが難しい判断だ。

fetch を hook の外へ

最後に取り出すのは、usePaymentMethods の中の fetch と変換だ。hook は React の概念なので view 側に残る。error handling や retry を入れると hook はすぐに膨らみ、別の view library に移れば hook は使えない。一方、普通の関数はどこでも使える。

const fetchPaymentMethods = async () => {
  const response = await fetch(`${API}/payment-methods?countryCode=AU`);
  return convertPaymentMethods(await response.json());
};
 
export const usePaymentMethods = () => {
  const [paymentMethods, setPaymentMethods] = useState<PaymentMethod[]>([]);
  useEffect(() => {
    fetchPaymentMethods().then(setPaymentMethods);
  }, []);
  return { paymentMethods };
};

著者は、この関数が Anti-Corruption Layer あるいは Gateway のように振る舞うと書く。サーバーのレスポンス構造が変わっても、直す場所がこの関数一つで済むという意味だ。ただし二つの名前は同じものではない。Fowler の Gateway は外部システムへのアクセスを一か所に包むオブジェクトであり、Anti-Corruption Layer は Eric Evans の DDD から来た言葉で、意味体系の異なる外部モデルが自分のモデルを汚染しないよう翻訳する境界だ。この例のサーバーレスポンスは { name } 一つだけで、翻訳すべき意味の違いがほとんどないので、筆者は Gateway のほうが正確な名前だと考える。サーバーが別チーム所有のレガシーで、決済手段の意味そのものが異なる場合に、同じ場所が Anti-Corruption Layer になる。

最終的な構造はこうだ。render は component に、state は hook に、ルールは domain object に、ネットワークリクエストは関数にある。

著者は、このように分けた結果として五つの利点を挙げる。欠陥のある場所を見つけやすくなる。コードを再利用し組み合わせやすくなる。読みやすくなる。機能を加えても全体が揺らがない。そして domain logic が view を知らないので、view layer だけを差し替えられる。最後の一つについては、著者自身が大半のプロジェクトでは非常にまれなことだと断りを入れている。五つとも測定値はないという点も、あわせて覚えておく価値がある。

ここまでが原文のあらすじだ。ところが、このコードを実際に動かしてみると、記事からは見えなかったものが出てくる。

サンプルを動かすと見えるもの

筆者は著者のサンプルリポジトリ(コミット 16 件、最終コミット de186c5)を取得して、tsc --noEmit とテスト 7 件を回した。どちらも通り、原文で定義が抜けていた helper もリポジトリの src/utils.ts にあった。ところが構造をのぞいてみると、持ち込む前に知っておくべきことが三つあった。

render のたびに新しく作られる Strategy

決済 component は Strategy を prop で受け取り、渡されなければデフォルト値を new で作る。そして useRoundUp はその Strategy を useMemo の dependency に入れる。

export const Payment = ({
  amount,
  strategy = new PaymentStrategy("$", roundUpToNearestInteger),
}: { amount: number; strategy?: PaymentStrategy }) => {
  const { total, tip } = useRoundUp(amount, strategy); // 안에서 [agreeToDonate, amount, strategy]
  // ...
};

JavaScript の default parameter は呼び出しのたびに評価される。そして useMemo は dependency を Object.is で比較する。この二つが重なると、render のたびに新しいインスタンスが生まれ、memo は毎回再計算する。React 18 で同じ構造を四回 render したところ、デフォルト値を使う場合は計算が 4 回、同じインスタンスを渡す場合は 1 回走った。リポジトリの App.tsx は <Payment amount={19.9} /> で Strategy を渡さないので、アプリの実行経路はまさにデフォルト値の側だ。

この例の計算は足し算数回なのでコストはない。問題は構造だ。Strategy を誰がどこで作って渡すのかが記事にもリポジトリにも決まっておらず、テストだけが日本とデンマークのインスタンスを作っている。筆者なら、インスタンスを module レベルの定数に置き、国コードで取り出して渡す。

const strategies = {
  AU: new CountryPayment("$", (n) => Math.floor(n + 1)),
  JP: new CountryPayment("¥", (n) => Math.floor(n / 100 + 1) * 100),
} as const;
 
<Payment amount={amount} strategy={strategies[countryCode]} />

リポジトリの fetch には dependency 配列がない

原文のコードの useEffect には [] があるが、リポジトリの usePaymentMethods には最初のコミットから最後のコミットまで dependency 配列がない。配列のない effect は render のたびに再実行される。レスポンスが来ると新しい配列で state を変え、それが render を引き起こし、effect がまた fetch する。convertPaymentMethods が毎回新しい配列を返すので止まらない。

fetch をすぐ応答する mock に置き換え、Jest で 300ms の間の呼び出し回数を数えると、四回測って 152、225、231、233 回になった。[] を入れれば 1 回だ。リポジトリのテストは画面に文言が出るかどうかしか見ないので、この繰り返しを捕まえられず、すべて通る。原文に沿って打ち込んだ読者にはこの問題はなく、リポジトリをそのまま取得して使う場合にだけ引っかかる。

国コードを prop で受け取った瞬間に生じる race

原文のコードの fetch effect にも cleanup がない。React 公式ドキュメントの Synchronizing with Effects は、effect の中で fetch すると遅れて届いた以前のレスポンスが最新のレスポンスを上書きしうるので、ignore フラグで以前のレスポンスを捨てるよう勧めている。原文は mount 時に一度だけ fetch するので、今は問題がない。しかし URL の countryCode=AU を prop で受け取った瞬間に dependency が生まれ、race の余地が開く。筆者はこの構造を持ち込むなら、最初からこう書く。

useEffect(() => {
  let ignore = false;
  fetchPaymentMethods(countryCode).then((methods) => {
    if (!ignore) setPaymentMethods(methods);
  });
  return () => { ignore = true; };
}, [countryCode]);

もう一つ付け加えると、原文の切り上げは Math.floor(amount + 1) なので、金額がすでに整数ならさらに 1 上がる。20 ドルの注文は 21 ドルになる。原文は 19.80 ドルと 3312 円しか例に挙げていないので、これが意図なのかはわからない。実際のサービスに持ち込むなら、Math.ceil と何が違うのかをまず決める必要がある。

この構造はいつ使うのか

著者自身、分けることは固定のルールではないと言う。小さくまとまった component は一つのファイルに置いたほうが動作を理解しやすく、警戒すべきはファイルが理解できないほど大きくなることだ。Todo アプリやフォーム一つだけのアプリは全部 component に入れても構わず、サンプルはパターンを多く見せるためにわざと複雑にしたと明かしている。ほかの資料も同じ方向の但し書きを付けている。

Fowler は同じ layering の記事で、この区分は比較的小さな単位にだけ使うよう述べている。view、model、data をトップレベルのフォルダにするのは小さなシステムなら構わないが、どれか一つが大きくなりすぎたら、トップレベルをドメイン単位に分け、その中を layer で分けよということだ。前に見た components/、hooks/、models/ フォルダを大きなアプリのトップレベル構造としてそのまま持ち込むと、Fowler が避けるよう言った形になる。

Dan Abramov にも似た経緯がある。2015 年に presentational と container component に分けようと提案し、2019 年に冒頭へ、今はそう分けることを勧めないという更新文を付けた。Hooks が同じことを恣意的な区分なしにやってくれるというのが理由で、必要もないのに教条的に強制されるのをあまりにも多く見てきたと付け加えた。原文の hook の抽出は、この更新文が言うやり方に近い。container という名前の component を別に置かず、hook を呼ぶ Payment がその役割を兼ねる。

fetch については、React 公式ドキュメントがさらに一歩進む。You Might Not Need an Effect は、fetch logic を custom hook に切り出しておけば後でより良い戦略へ移しやすいとしながらも、第一候補としてはフレームワーク組み込みの fetching や TanStack Query のような client cache を勧めている。原文の最終段階のように fetch を普通の関数に切り出しておけば、その関数をそのまま TanStack Query の queryFn に渡せて、前の節の race と繰り返し呼び出しは library が引き受ける。筆者は、これが原文が一文でしか触れなかった最も実用的な利点だと見ている。キーと関数を結び付ける方法は queryKey で別に扱った。

まとめると、筆者の判断はこうだ。原文の順番(hook、pure component、domain object、Strategy、network client)はそのまま従う価値がある。段階ごとに、その段階の不便が次の段階の理由になるからだ。ただし最後まで進む必要はなく、今抱えている不便がどの段階のものかを見て、そこで止まればよい。render と無関係なコードが多ければ hook まで、同じ判定が散らばっていれば domain object まで、一つの変更で複数のファイルを直しているなら Strategy までだ。そして Strategy を使うなら、まずインスタンスを作る場所を決め、fetch を effect に置くなら cleanup と dependency から書く。原文が省いたこの二つが、実際に持ち込んだときに真っ先に壊れる場所だった。

正解はないが、この記事を読んでいる読者の皆さんも、自分のコードが今何段階目の不便を抱えているのか一度確かめてみてほしい。

最初に目に入った用途はブラウザ自動化だった。Browserbase が Stagehand の act() に Jev をつなぐ PR を出した。ページのアクセシビリティツリーを state として送り、「次にクリックする要素はどれか」を選択肢で問う構造だった。40 個の課題で act() の中央値が 1.97 秒から 0.46 秒に縮み、147 回の操作のうち LLM に戻ったのは 4 回だった。Playwright スクリプトが selector 一つ変わるだけで壊れる場所を、確率を一つ返してもらう呼び出しで埋めたわけだ。この記事を書いている時点で PR はまだマージされていない。

その PR が引いた線が、この記事の問いだ。Jev の答えを受け入れる基準を確率 0.7に置き、越えなければ LLM に渡す。あのモデルが返す確率を信じて、コードの中に線を引いてよいのか。

他人のベンチマークだけでは判断できないので、筆者のデータで検証してみることにした。このブログには音写された外来語を止めるゲートがある。ハングルの音写である 피커 ではなく picker と書こうという規則だが、正規表現が捕まえるのは確実な半分だけで、멀티스레드 や 콜 스택 のように複合語の中にあったり韓国語にすでに定着していたりする語は筆者が毎回手で判断する。答えは「戻す」と「そのまま」の二つしかなく、分かる人なら 1 秒で判断でき、ビルドスクリプトの中で人の確認なしに合否を決めなければならない。Stagehand の selector 判断と同じ形だ。

そこで順序をこう決めた。Jev が何を返すのか、その確率がどんな学習から出てくるのか、筆者のゲートに渡すとどんな数字が出るのか、そしてその数字をどこに使えるのか、だ。

テキストを生成しないモデル

公開日は2026年9月15日だ。同社はこれを LLM とは呼ばず、System One Model という新しいカテゴリとして扱う。この記事では決定モデルと呼ぶ。創業者の Diogo Almeida は OpenAI で InstructGPT 論文の4番目の著者として名を連ねた人物だ。ChatGPT の直系の祖先となったその手法を作ったチームにいて、いまはその手法の限界を指摘する側に立っている。

Jev は文を生成しない。答えの形をあらかじめ決めて渡すと、その中から選び、確率を一緒に返す。質問タイプは三つだけだ。

endpoint も一つだ。POST /v1/systemone に state（評価する内容）、model、questions（質問のマップ）を送れば答えが返る。同じ state に対する質問を複数まとめて一つのリクエストに入れられ、質問を増やしても応答時間はほとんど伸びない。

なぜ速いのかは、トークンの仕組みでまとめた prefill と decode の非対称で説明できる。LLM が遅いのは出力を1トークンずつ順に絞り出すからだが、Jev にはその decode の段階がない。入力を一度並列に読み、確率をそのまま読み出す。だから出力トークンの料金が最初から存在せず、入力のみ100万トークンあたり $0.042 だ。

Archer Hume という開発者が API を約1万回呼び出し、外側から動作を復元した分析がある。入力360トークンで中央値57.5ms、29,835トークンで218ms、質問を1,500個入れたときで610msだった。そのうち最も直接的な証拠は、選択肢が200個の応答が2個のものと同じ速度で返ってきたという観察だ。答えを書くのに時間がかからないという意味である。

人が見ていない判断

速度と価格が目を引くが、Almeida が公開の発表記事で投げかけた問いは別の方にあった。モデルは何年も前から対話では超人的なのに、自動化はどこへ行ったのか、という問いだ。

彼の答えは、二つの仕事は種類が違うというものだ。チャットボットと copilot とコーディング agent は、人が横で見ながら満足することが目標だ。サーバーで静かに回りながら誰も見ていない判断はそうではない。前者を assistant、後者を automation と呼ぶなら、これまでに出てきたモデルはすべて前者のために作られてきた。

harness 設計をまとめたときにも、似た区別をしたことがある。エージェントシステムの中には、人が見ていない判断が無数にある。このリクエストを人に回すべきか。このコマンドを実行してよいか。いまはそれらを全部、高価な LLM に尋ねている。筆者の正規表現ゲートが覆えない残りの半分も、そうした判断だ。

RLHFが残した空白

ところで、なぜ新しい学習法が必要だったのだろうか。既存のモデルに「はい」か「いいえ」だけを答えさせてはいけないのだろうか。

答えの手がかりはキャリブレーションにある。正解率が何パーセント当てるかなら、キャリブレーションは自分が何パーセント当てるかを知っているかどうかであり、そのズレを測る指標が ECE（expected calibration error）だ。確率の区間ごとに言った確率と実際の的中率の差を標本比率で重み付けして平均した値で、0が完璧である。ところが、人の選好を最適化する RLHF（reinforcement learning from human feedback）を経た後に、この目盛りがずれた例がある。GPT-4 技術レポートの Figure 8 では、事前学習モデルの ECE が 0.007 だったのに対し、post-training を経たモデルは 0.074 と10倍以上悪くなった。レポートはその原因を書いておらず、筆者も原因を確定する一次資料は見つけられなかった。定義と、原因がどこまで明らかになっているかはLLMのキャリブレーションと過信に別にまとめておいた。

ただし ECE 一つでは足りない。 すべての入力に0.6を出す定数予測器でも、実際の的中率が60%なら ECE は0になる。確率が正直なだけで案件ごとに分かれないなら、線を引く場所がない。だからキャリブレーションとは別に、確率が実際に分かれるかも一緒に見なければならず、後で使う「誤差予算の中で自動処理できる比率」が、その二つを一つの数字にまとめた指標である。

ソフトウェアの立場で重要なのはこの部分だ。確率が正直で、かつ分かれるなら、線を引ける。0.95を超えれば自動処理し、その下は人に回すという構造が作れる。

TypeSafe はその場所を狙って三番目の道を出したと言う。人の選好を最適化する RLHF、機械が採点できる正解を最適化する RLVR（reinforcement learning with verifiable rewards）、そしてキャリブレーションされた決定を最適化するという RLCD である。

ただし RLCD として公開されているのは出力契約の3行がすべてだ。この記事を書いている2026年9月23日の時点で、TypeSafe のドキュメントにも発表記事にも論文や技術レポートはない。同じ略語を使う ICLR 2024 の論文が別にあるが、そちらは reinforcement learning from contrastive distillation で別の手法だ。検索するときは混ざらないよう注意する。

confidenceの正体

では、Jev が返す数字は正直なのか。答える前に、まず見ておくことがある。返ってくる数字は一つではない。

Choice と Score の応答には probabilities と confidence が一緒に入っている。前者は選択肢全体にわたる確率分布で、後者は0から1のあいだの数字ひとつだ。コードでしきい値をかけるとき、まず手が伸びるのは confidence の方である。

この値は、モデルが作ったものではない。TypeSafe の organization が公開している system-one-adapter-python の _utils/confidence_metrics.py は全部で32行で、Choice の部分がこうなっている。

def choice_confidence(probs: list[float]) -> float:
    """Scale peak choice probability from uniform to certainty."""
    if len(probs) == 1:
        return 1.0
 
    normalized_probs = _normalize(probs)
    uniform_probability = 1.0 / len(normalized_probs)
    return (max(normalized_probs) - uniform_probability) / (1.0 - uniform_probability)

モデルの呼び出しもなく、学習されたパラメータもない。probabilities のベクトルが一つ入り、実数が一つ出る。式で書くと c = (p_max − 1/K) / (1 − 1/K) で、選択肢が三つで最大確率が0.8なら0.7になる。

このリポジトリはプロダクションの Jev サーバーではなく、LLM で同じ API を模倣する代替実装だ。だからこれだけで断定することはできない。ところが、同じ式を指す証拠がもう二つある。TypeSafe 公式ドキュメントの confidence ページはこの値を "a statistic computed from the probability distribution" と記し、デモコードには三つの選択肢用の近似式として (3 × largest probability − 1) / 2 を載せている。K が3なら上の式と同じだ。そして主張の監査台帳が、実際の API で、どちらも誤りの選択肢を二つだけ与えた応答の勝者が0.52のとき confidence が0.04で返ってきたと記録した。K が2なら (0.52 − 0.5) / (1 − 0.5) = 0.04 だ。式と一致する。

同じリポジトリで Score はまったく別の式を使う。最頻の水準からの平均絶対距離を、一様分布のそれで割ってから1から引く。 ドキュメントは Score の式を公開していない。つまり confidence という一つの名前の下に計算式が二つあり、タイプが違えば同じ数字でも意味が違う。Noul に confidence がないのも同じ理由だ。畳むべき分布がない。

ドキュメントもこれを隠していない。別の計算を使いたければ probabilities 全体を渡すので好きにしてよい、とまで案内している。書いてある内容であり、読まずに使う側の問題だ。

ところが、公開の発表記事の比較表は二つをくっつけて書いている。"Calibrated: higher confidence means higher accuracy" と書かれている。読む人は confidence がキャリブレーションされた値だと受け取るが、キャリブレーションの主張が実際にかかっているのは probabilities の方だ。

この区別が数字でどれだけ開くかは、測定がある。scienthoon という開発者が公開した独立したキャリブレーション測定が、confidence を「当たる確率」として読んだときの ECE を別に測っている。OpenBookQA で0.035、HellaSwag で0.078、合成した集合で0.18だ。同じ集合の元の確率はそれぞれ0.024、0.029、0.107だった。三つの集合すべてで confidence の方が悪い。

なぜ悪くなるのかは式にある。K が固定なら c は p_max の単調増加変換なので、順序は保存される。判別力はそのままで、しきい値だけ書き換えればよい。壊れるのは情報ではなく目盛りだ。 K が質問ごとに違うと、問題がもう一つ増える。引き伸ばす倍率も変わる。同じ p_max 0.8が、選択肢二つでは0.6になり、五つでは0.75になる。選択肢の数が混ざったワークロードでしきい値を一つだけ使った瞬間、それが問題になる。

分布によって変わるキャリブレーション

では、probabilities の方は信じてよいのだろうか。

Jev を実際に呼び出して測った記録が公開されている。Jared Palmer が作ったオープンソースの再現実装 Kev のリポジトリには runs/jev-* の directory があり、usage.json が "model": "typesafe-ai/jev" として、Vercel AI Gateway を経た実際の呼び出しであることを記録している。jev-* の directory 六つの usage.json を合わせると、2026年9月18日と20日にわたって5,364回呼び出し、入力が2,418,260トークンだ。以下の七つの集合のうち scienthoon は、その開発者の結果ファイルを変換して取り込んだものなので、この合計には入っていない。

価格が実際に入力だけ課金されることは、別のところで確認できる。フィッシングのベンチマークの著者が TypeSafe の dashboard を見て書き残している。二回回した456万トークンのうち入力が366万、出力が90万だったが、請求は $0.15 で、その値が入力だけを計算したものと一致した。

同じ directory の report.json から評価集合7個の指標を取り出して整理するとこうなる。以下で確信度は confidence フィールドではなく probabilities の最大値である。過信は 평균 확신도 − 정확도（平均確信度 − 正解率）で、合計5,743件だ。判断の根拠を消した「分からない」項目を正解率の採点から外す clean ブロックの値である。

二つのことが読み取れる。

第一に、ECE が10倍近く動く。 0.011から0.105だ。同じ採点器、同じモデルである。「キャリブレーションされている」はモデルの性質ではなく、モデルと分布の関係なのである。分布が変わればキャリブレーションが崩れること自体は、すでに知られた結果だ。ここで新しいのは、キャリブレーションを学習目標として掲げたモデルでも同じ形が出るという点である。

ECE が最も大きい集合の0.105は、先に見た post-RLHF の GPT-4 の0.074よりも大きい。ただし、この二つを順位として読んではいけない。課題が違ううえ、ECE は区間をいくつに分けるか、標本がどの区間に偏っているかによって値が動く推定量なので、別々の採点器から出た数字を突き合わせても比較は成立しない。

第二に、測定された ECE が過信ひとつでほぼ全部説明される。 二つの列の差は7個すべてで0.002から0.011のあいだだ。ECE は区間ごとの差の加重平均なので全体の過信より小さくなりようがないが、その差がほぼ0だということは、区間ごとのズレの符号が一方向に偏っているという意味である。区間ごとに食い違って打ち消し合うノイズではない。

なぜそうなるかは、縦に読むと見える。平均確信度は semif を除けば0.851から0.906のあいだに6個が固まっている。同じ区間で正解率は0.753から0.857へ、2倍の幅で動く。確信度は分布が変わってもあまり動かず、正解率だけが動く。残った差がそのまま ECE だ。

この性質が実務でどう現れるかは、別のベンチマークが見せてくれる。フィッシングメール2,000件に Claude Haiku 4.5 を対照群として置いた測定で、Jev の正解率は62.6%、Haiku は81.3%だった。ところが、もっと目を引くのは ECE だ。リポジトリが報告した ECE は Jev が0.154、Haiku が0.097で、主張の監査台帳が Jev の P(phishing) の値を0から1まで10区間で測り直すと0.170になる。どちらで読んでもキャリブレーションを学習目標として掲げたモデルが、RLHF で作った LLM にキャリブレーションで負けた。 同じ著者がリンクのホスト一覧の規則一つだけで91.6%を出した。

同じ指標を複数の集合で見ると、その幅はもっとはっきりする。誤差予算5%で自動処理できる比率が、scienthoon の集合で0.486、transfer-v9 で0.695、semif で1.000だ。Kev の採点器はこの値を、標本の中でしきい値を選んだ最大値だと書き残しており、デプロイ後の誤差の保証ではない。そのどれか一つをモデルのスペックのように引用してはいけない。

音写判別ゲート

他人のベンチマークを読むことと、自分のデータで測ってみることは違う。そこで冒頭のゲートを実際に通してみた。

筆者はまだ Jev の API キーを持っていない。代わりに、先に触れた Kev-9B をローカルで回した。 Qwen3.5-9B-Base に rank-16 LoRA と pointer head を載せた再現実装で、Apache-2.0 だ。以下の数字は Jev の数字ではない。Kev の学習データは英語の決定課題であり、同じ著者の測定でも Kev-9B は英語の課題ですら Jev に劣る。誤差予算5%の自動化比率が0.45から0.57なのに対し Jev は0.70で、MMLU-Pro は0.52対0.84だ。そして TypeSafe のドキュメントも Jev について、英語が主な学習言語であり CJK は同等ではないと明らかにしている。

評価集合は、このリポジトリの韓国語記事18本から取り出した。ラベルの正解基準は、このリポジトリがその単語を一貫してどの表記で書いているかである。韓国語技術文書のコミュニティの合意ではなく、このブログの慣習だという意味で、両者が分かれる単語では、モデルがコミュニティ基準では正しく、この基準では間違うことがありうる。

• ゲート集合102文：ゲートがすでに知っている単語だ。本文が英語で書いている calendar、picker、adapter のような単語をハングルの音写に戻した反事実の文が陽性23件、write-post.md が例外として明示した 리렌더링 や 콜 스택 が実際に使われている文が陰性79件である。ここでは現在の正規表現ゲートが定義上100%を当てる。
• 保留集合60文：ゲートが一度も見たことのない単語だ。 機械学習で held-out と呼ぶ側だ。 本文が英語だけで書く loader、mutation、prefill を音写に戻したものが陽性30件、本文がハングルだけで書く 리듀서、스냅샷、런타임 が陰性30件である。ここでは正規表現は陽性を一つも捕まえられない。

陽性が筆者の作った反事実の文で、陰性が実際の文だという非対称は、先に明らかにしておく。そして有効な標本は文の数ではなく単語の数だ。 ラベルが単語単位で決まるので、同じ単語が出てくる文どうしは独立した観測ではない。ゲート集合は24種、保留集合は13種である。

以下の表は「この単語を英語に戻すべきか」を問う noul の質問一つだけを集計したものだ。同じリクエストに質問を四つ入れたが、残りの三つは否定形と Choice の変形、そしてラベルをきちんと立てられなかった複合語の判定なので、ここには混ぜていない。5%予算の自動化比率は、確信度の高い方から切り下げていき、その上の区間の誤差が5%を超えない最大の比率である。

多数クラスのベースラインは、文を読まずに多い方のラベルだけを出したときのスコアだ。モデルはその下である。

最後の行がこの実験の答えだ。保留集合では、しきい値をどれだけ高く取っても、5%の誤差の中で自動処理できる決定は一件もなかった。

予測分布を見れば、何が起きたのかが分かる。モデルは162文すべてに「戻すべきだ」と答えた。 単語37種すべてである。陽性は全部当たり、陰性は全部外した。だから保留集合の0.500は実力ではなく、集合が均衡しているから出た数字だ。

それでいて平均確信度は0.876だった。ゲート集合で確信度0.9を超えたものが49%なのに、その区間の実際の的中は0.240である。

構造的な恒等式も成り立たなかった。「戻すべきか」と「そのままにすべきか」の確率を足すと、ゲート集合で平均1.655になり、102文すべてが1から0.1以上ずれた。

設計上そうなっている。二つの質問は互いを読めない別々の評価であり、TypeSafe 自身も jaggedness のページに、refund 0.72と not_refund 0.47を足して1.19になる例を載せている。

実務で引っかかる点はここだ。Noul に合わせて調整したしきい値を Choice に移してはいけない。 同じ判断なのに結論が分かれる文が14%から17%あった。

何を聞いても「はい」と答えるモデルなら、この結果は無意味だ。まずそれから確認した。

韓国語を読み、「いいえ」と言い、0.02と0.98を分ける。 全域的な迎合バイアスではない。排除できるのはそこまでだ。ゲートの質問の文言そのものが悪い可能性は残る。

規則をstateに入れた結果

では、判別に必要な知識を直接与えれば変わるだろうか。TypeSafe のドキュメントが勧めるドメイン適応の方式がこれだ。重みには触れず、参考資料を state に載せて送る。

write-post.md にすでに書かれている規則の段落を state に一緒に入れて、もう一度回した。入力が1文あたり100トークンから450トークンに増えた。ゲート集合はリークだ。 その参考資料が、ゲートの単語と例外の単語を名前で並べているからである。だからそちらは「参考資料を読んではいるのか」を見る対照群で、本当の試験は保留集合だ。

レイテンシは M2 Max で回したローカル推論なので、先に見た Jev の API レイテンシとは同じ軸ではない。ここで見るべきは絶対値ではなく、参考資料を入れたときの2.4倍である。

均衡の取れた保留集合で、文単位の正解率は0.500から0.500へ、まったく動かなかった。 単語単位では7/13から5/13へ、むしろ下がった。

ゲート集合の0.225から0.676は、実力の向上ではない。以前は102文すべてに「戻す」と答えていたが、参考資料を渡すと12文にだけそう答えた。陰性が0/79から68/79へ上がった一方、陽性は23/23から1/23へ崩れた。その集合は陰性が79対23で多いので、「おおむねそのまま置け」という定数が自動的により高いスコアを得る。区別を学んだのではなく、傾きを変えただけだ。

だからといって、モデルが文を読んでいないわけではない。同じ単語の同じ文なのに、参考資料を渡すと文ごとに予測が散らばった。로더 の標準偏差が0.096から0.217へ、뮤테이션 が0.042から0.236へ増えた。読んではいるが、区別ができない。

そしてこの結果は、前節の解釈を揺さぶりもする。state のテキスト一つで出力が丸ごとひっくり返るなら、初回の「全部戻す」もモデルの限界ではなく、質問の文言の不足かもしれない。この記事はその可能性を排除できていない。

一つだけは目に見えてよくなった。「戻す」と「そのまま」の確率の和が、保留集合で1.508から0.963へ近づき、1から大きく外れた文が59個から18個に減った。ところが正解率は動かなかった。 二つの質問の確率が互いに噛み合うことと、その確率が当たっていることは別の話だ。

決定モデルの居場所

ここまで見ると、このモデルのカテゴリ全体が役に立たないという結論に傾きやすいが、公開されたベンチマークを並べてみるとそうではない。

rerank の行だけが検索順位の品質指標なので、他の行の正解率とは軸が違う。

分布の内側では、正規表現や作り込んだ分類器が勝つか引き分ける。 筆者のゲート集合で正規表現が1.000対0.225で勝ったのと同じ位置だ。ラベルを集められるなら、小さなモデルを学習させる方が安く、速く、正確である。それは昔からやってきたことだ。

差が開くのは、分布が新しくラベルがないときだ。 分布外のスパムで98.6%対73.0%である。作り込んだ分類器は自分が見たことのない形の前で崩れるが、こちらは持ちこたえる。決定モデルの居場所は、データを集めてラベルを付けて学習させることができない判断だ。毎回状況が新しいのでラベルを集められないのに、判断は秒単位で下さなければならない場所である。

筆者の音写判別がなぜ失敗したのかも、この枠組みで説明できる。その判断に必要なのは一般的な推論ではなく、韓国語の技術文書でどの語が定着したかという特定ドメインの知識であり、英語の決定課題で学習した9Bの再現実装にとって、それは分布外ですらなく、単に持っていない知識だ。規則を文章で渡しても駄目だった理由がここにある。

TechCrunch の記事で、Pi harness を作る Earendil の CTO である Armin Ronacher がこう語っている。

At the end of the day, it delegates the hallucination problem a little bit to the user.

ハルシネーションをなくしたのではなく、判断を開発者に渡したということだ。TypeSafe のドキュメントも、キャリブレーションは予測の束に対して成り立つ性質であって、個別の答えが当たっているという保証ではないと書いている。そして公開の発表記事のハルシネーション率0%の棒の下の Nuance 項目には "Our number is not empirical" と書かれている。形式は保証され、中身は保証されない。

jevable の194プロジェクト

筆者のデータでは失敗したので、ほかの人はどこに使っているのかを見た。jevable.comは、Nikunj という開発者が X に投稿された Jev プロジェクトを審査して集めた独立のキュレーションだ。2026年9月23日時点で194件あり、登録日は9月16日から20日の間に集中している。152件が9月18日の一日に入ってきた。公開から三日後だ。

カテゴリではなく「何を尋ねているか」で括り直すと、三つの形が出てくる。以下の数値はすべて投稿者が自分の投稿に書いた値だ。

第一に、分類とルーティング。 メール1,500件の分類、税務書類の分類、競合他社の広告1,891件を19秒、$0.12で分類、PR の diff ひとつに typed check 14個、Android の通知から広告の判別、建設図面26枚を2.9秒で分類。冒頭の音写ゲートと同じ形だ。前の節の表が言ったとおりラベルが毎日たまる場所なので、時間がたてば自分のラベルで学習した小さな分類器が勝つか、引き分ける。Jev の利点はラベルのない初日にある。

第二に、行動選択のループ。 Browser Use につないで航空券の検索を7秒、$0.0039で終えたという browser agent、音声で Mac を操作する computer use、Mario が死ぬたびに VM を四つに fork して生き残る方を選ぶゲーム、3D キャラクターの口と眉と視線など十項目をメッセージごとに決める表情エンジン。ステップごとに action space が変わるのでラベルを集められず、判断は秒未満に下げなければならない。分布外のスパムで差が開いたのと同じ場所だ。Games が39件で最大のカテゴリである理由もここにあると見ている。ゲームは間違えても巻き戻せる行動選択のループだ。

第三に、確率をユーザーに見せる UI。 答えの代わりに判定だけを返す Ask Jev、次の質問を確率で選ぶ分岐フォーム JevForm、技術的な深さやドラマ性のようなスライダー六本で Hacker News のトップ画面を並べ直す Upweight。しきい値をコードに埋め込まず人が確率を読む場所なので、この記事が問題にしたキャリブレーションの要求が最も低い。

一つ目立つことがある。194件の説明文のうち、コストを書いたものが30件、速度を書いたものが53件ある一方で、正確さや基準線を書いたものは7件だ。説明文は元の投稿の冒頭だけを収めているので下限だが、方向は明らかだ。速くて安いことは初日にわかり、当たっているかは測ってみないとわからないのに、測る側がまれである。その7件のひとつが jevcal だ。みんなしきい値を勘で選んでいると言い、自分のデータと目標の正確さを入れるとしきい値と自動処理の比率を返す道具である。次の節が勧める手順をそのまま道具にしたものだ。

線を引く手順

この記事の結論はこれだ。モデルが返した確率をスペックのように読まず、自分のデータで直接測って線を引かなければならない。

測る手順はこうだ。ラベルのある100件ほどを集めて、確率の区間ごとの実際の的中率の表を作り、しきい値を上から下げながら、その上の区間の誤り率を見る。誤差予算を決めたなら、その予算を守れる最大のカバレッジが、そのまま自動化できる比率だ。筆者の実験で確信度0.9以上の区間の実際の的中が0.240だったというのは、102文で明らかになった。

目盛りがずれていることは、たいてい直せる。 過信が全区間に均等に広がっているなら、温度ひとつでほとんど合わせられる。Kev もそうして ECE を0.106から0.042へ下げた。問題は、その温度を合わせるにはその分布のラベルが必要だということで、プロダクションで手元にないのがまさにそれだ。しかも温度は確率の順序を変えられないので、自動化できる比率はその分だけ上がらない。だから目盛りより順序が、ECE より誤差予算のカバレッジの方が実務的な指標である。

ドキュメントが例に使った0.9をそのままコードに埋め込んでいたら、このゲートは静かに38件を誤って直していただろう。エラーが出ないので気づきにくい失敗だ。TypeSafe のドキュメントもその例のすぐ下に、自分のデータで試してみるようにと書いている。コードに埋め込まれるのは、たいていその下の文章ではなく上の数字の方だ。

キーがなくても、測ることだけなら今日からできる。Kev が Apache-2.0 で公開されていて、ノートパソコンで動く。

いま運営しているサービスで、大きなモデルに「はい」か「いいえ」だけを尋ねている呼び出しがいくつあるか、数えてみてほしい。その呼び出しを決定モデルへ移す前に、移したあとに引くべき線がどこなのかを先に測ってみることをお勧めしたい。筆者はその順序を守ったからこそ、ゲートには手を付けないと決められた。Jev のキーを受け取れたら同じ集合をもう一度回してみるつもりで、そのとき結論が変われば、それも書くつもりだ。

筆者は宣言的なコードが好きだ。オーバーレイを表示し、閉じ、その中で非同期処理を行うという一連の振る舞いは、そのオーバーレイ自身が管理するほうがよいと考えている。呼び出す側が isOpen を持って切り替える方式は、状態を扱うコードと、その状態が描画されるコンポーネントとを別々の場所に引き離してしまう。

ところが筆者が会社で担当していた画面のモーダルは、まさにその逆だった。開いているかどうかをグローバルストアに持たせ、呼び出し側が開き、呼び出し側が閉じていた。モーダルを閉じるコードも、結果を受け取るコールバックも、呼び出し側が直接書いていた。そのため、これを宣言的な方向へどう移すかを長く考え、結局は自分で作り直した。

その作業をしながら overlay-kit を見てみた。筆者が目指していたインターフェースと近かった。この記事では overlay-kit の宣言的なインターフェースを見ていき、社内のモーダルシステムをどう設計したかを記録しておく。

状態として持っていたモーダル

筆者は状態管理についての記事で、モーダルの開閉フラグを最も単純なローカル状態の例として挙げた。ひとつのコンポーネントの中だけで使い、外部が知る必要も知る権利もない状態だと書いた。その見解は今も変わらない。ただし、モーダルが数十種類になり、互いに重なって表示され、結果値を呼び出し側へ返さなければならなくなった瞬間から、その状態はコンポーネントの中にとどまらない。

筆者が引き継いだコードは、開いているモーダルの一覧をグローバルストアに置いていた。社内コードなので、以下の例は構造だけを残して識別子を変えてある。

const [openPopup, closePopup] = useModalStore(
  useShallow((state) => [state.openPopup, state.closePopup]),
);
 
const handleAddNote = useCallback(() => {
  openPopup(PopupType.ADD_NOTE, {
    itemId,
    onClose: () => closePopup(PopupType.ADD_NOTE),
    onSubmit: (note) => {
      closePopup(PopupType.ADD_NOTE);
      saveNote(note);
    },
  });
}, [closePopup, openPopup, itemId]);

このコードで気になった箇所は三つある。

第一に、開く関数をフックから取り出さなければならない。 openPopup と closePopup はストアから選び取る値なので、コンポーネントの中でしか手に入らない。そのため、モーダルを開くコードはコンポーネントの外へ出られない。APIレスポンスを横取りする場所やルーターガードのように、フックを使えない場所からモーダルを表示したければ、その関数を引数として渡していくしかない。

第二に、結果がコールバックで返ってくる。 ノートを保存したのか、ユーザーがそのまま閉じたのかを、onSubmit と onClose という二つの経路で受け取る。モーダルを開いたあとにやることがあれば、その処理はコールバックの中に入る。モーダルを二つ続けて開く必要があれば、コールバックの中にコールバックができる。

第三に、閉じる責任が呼び出し側にある。 closePopup(PopupType.ADD_NOTE) を呼び出し側が呼ぶ。モーダルが自分自身を閉じるのではなく、モーダルを開いた側がその種類を覚えていて閉じる。だから同じ定数がひとつの関数の中に三回出てくる。

三つに共通するのは、モーダルをひとつ表示するために呼び出し側が三種類のコードを書かなければならない、ということだ。開くコード、結果を受け取るコールバック、そして閉じるコードである。

何を表示するかを決めるところまでが呼び出し側の役目だとすれば、ここではその後の仕事まで呼び出し側が抱え込んでいた。とくに closePopup(PopupType.ADD_NOTE) は閉じる対象を文字列定数で名指しする。別のモーダルの定数を書いても同じ列挙型なので型検査を通ってしまい、見当違いのモーダルが閉じる。

結果を待つインターフェース

では、この三つのうち何を減らせるだろうか。筆者がたどり着いた答えは、モーダルを開くことを関数呼び出しにし、その関数が終了結果を含む Promise を返すようにすることだった。

const result = await openModalAsync('ADD_NOTE', { itemId });
if (result.reason !== 'confirmed') return;
 
await saveNote(result.value);

変わったのは三つだ。開く関数がフックではなくモジュール関数になり、コンポーネントの外でも呼べるようになった。結果がコールバックの引数ではなく戻り値になり、後続の処理が呼び出し関数の流れの中に残った。そして閉じる仕事はモーダルコンポーネント自身が担うようになった。

戻り値の型が Promise<ModalResult<V>> になったことで、モーダルの終了がひとつの値にまとまった。

Promise は一度しか終わらない。すでに終わった Promise を再び resolve しても何も起きないので、終了理由をその値ひとつにすべて詰め込む必要がある。そこで reason を五つに分けた。ユーザーが確定したのか、明示的にキャンセルしたのか、値なしで閉じたのか、同じ種類の新しいモーダルに置き換えられたのか、全体の後片付けで強制終了されたのかである。真偽値ひとつにすると「キャンセル」と「画面ごと片付けられた」が同じ値になってしまうが、後処理が必要な流れではその二つを区別しなければならなかった。

逆に、終わらせなければ呼び出し側は永遠に待つ。コールバックは呼ばなくても何も起きないが、await は戻らないまま残る。そのため、モーダルを画面から取り除く経路が増えるたびに、その経路も Promise を終わらせているかを確認する必要があった。置き換えと強制終了がそれぞれ reason をひとつずつ持っているのは、そのためである。

overlay-kit の呼び出し側

toss の overlay-kit の呼び出し側はこうなっている。

const confirmed = await overlay.openAsync<boolean>(({ isOpen, close }) => (
  <ConfirmDialog
    open={isOpen}
    onConfirm={() => close(true)}
    onCancel={() => close(false)}
  />
));

筆者が良いインターフェースだと思った点は三つある。

何が開くのかが呼び出し側にある。 筆者が作ったほうは 'ADD_NOTE' という文字列キーを渡す。そのキーがどのコンポーネントなのかは registry ファイルが知っている。文字列キーと、そのモーダルを読み込む import() 関数を組にしたオブジェクトがひとつ入っているファイルだ。

export const modalImporters = {
  ADD_NOTE: () => import('.../add-note-modal'),
  CONFIRM: () => import('.../confirm-modal'),
  // 모달 종류만큼 이어진다
} as const;

overlay-kit は JSX をその場に書く。コードを読む人は、このファイルへ移動しなくても何が出るのかが分かる。

結果の型が呼び出し側で決まる。 openAsync<boolean> の型引数がそのまま close の引数型であり、await の結果型になる。モーダルごとに結果の型を宣言して表に登録する必要がない。

閉じることと消すことが分かれている。 コントローラーが受け取る props は overlayId、isOpen、close、unmount の四つだ。close は isOpen を false にして、コンポーネントはそのまま残す。実際に取り除くのは unmount である。公式ドキュメントのオーバーレイの開閉についての案内はこう説明している。

このような違いが生じるのは、close を使うときにオーバーレイが閉じるアニメーションを見せるため、メモリに残し続けているからです。

筆者が作ったほうにはこの区別がない。閉じれば一覧からすぐ外れる。つまり閉じるアニメーションをコンポーネントライブラリ側に任せていたということであり、それが可能な画面だけを扱っていたということでもある。

overlay.open からレンダーまで

インターフェースが気に入ったら、次に気になるのは中身だ。ひとつのモジュール関数が React ツリーの中にコンポーネントを描くには、その間をつなぐ何かが必要になる。

イベントと reducer

overlay.open は状態を変えない。イベントをひとつ飛ばす。

// packages/src/event.ts
const open = (controller: OverlayControllerComponent, options?: OpenOverlayOptions) => {
  const overlayId = options?.overlayId ?? randomId();
  const componentKey = randomId();
  const dispatchOpenEvent = createEvent('open');
 
  dispatchOpenEvent({ controller, overlayId, componentKey });
  return overlayId;
};

受け取る側は OverlayProvider だ。Provider は useReducer を持っていて、イベントを購読して reducer に ADD を入れる。ここで注意して見るべきなのは、isOpen が false で入るという点である。

// packages/src/context/provider/index.tsx
const [overlayState, overlayDispatch] = useReducer(overlayReducer, {
  current: null,
  overlayOrderList: [],
  overlayData: {},
});
 
const open: OverlayEvent['open'] = useCallback(({ controller, overlayId, componentKey }) => {
  overlayDispatch({
    type: 'ADD',
    overlay: { id: overlayId, componentKey, isOpen: false, isMounted: false, controller },
  });
}, []);

そしてコントローラーがマウントされた次のフレームに OPEN を入れて isOpen を true にする。

// packages/src/context/provider/content-overlay-controller.tsx
useEffect(() => {
  requestAnimationFrame(() => {
    overlayDispatch({ type: 'OPEN', overlayId });
  });
}, [overlayDispatch, overlayId]);

ここで筆者の予想と違った部分がある。

状態が React の外にない。 モジュール関数で開く API なのでストアもモジュールレベルにあるだろうと思っていたが、実際には Provider の中の useReducer だった。React の外にあるのはイベントバスだけで、それは状態を持たない。オーバーレイは Provider の children の隣に兄弟としてレンダーされる。createPortal を使わず、react-dom を import もしない。

もうひとつ目に留まることがある。呼び出し側から見れば overlay.open() の一行だが、その中はイベントを飛ばし、reducer に ADD を入れ、一フレーム待ってから OPEN をもう一度入れるという順序の決まった手続きだ。宣言的なインターフェースは命令型のコードをなくしたのではなく、境界の内側へ移したのである。

開く側と閉じる側

先ほど見た requestAnimationFrame と、その前の節で見た close と unmount の分離は、一見すると別物に見える。実際には同じ制約の両端をそれぞれ塞ぐ仕掛けだ。

その制約とは、CSS トランジションが開始状態と終了状態の両方を実際にレンダーしないと動かないということである。MDN の CSS トランジションのドキュメントは、DOM に追加したばかりの要素についてこう警告している。

This is treated as if the initial state had never occurred and the element was always in its final state.

ここで失敗が二つの形で現れる。開くときは開始状態がないので動かず、閉じるときは終了状態が描かれる前に要素が消えるので動かない。

閉じる側が利用者の担当になる理由は最後の行にある。開く側は一フレームで足りるという定数をライブラリが知っている。閉じる側は、アニメーションが200ミリ秒なのか400ミリ秒なのかをライブラリは知りようがない。

unmount に渡された閉じる側

閉じる側が成り立つ根拠は reducer にある。CLOSE は overlayData の isOpen だけを反転させ、overlayOrderList には触れない。Provider はその一覧をたどってレンダーするので、一覧に残っているあいだコンポーネントは生きている。REMOVE が一覧から外して初めてアンマウントされる。

ただし rAF が常に必要なわけではない。 react-transition-group は既定では初回マウントで enter トランジションを実行しない。in がすでに true でも飛ばしてしまい、appear を有効にする必要がある。overlay-kit の rAF は isOpen をマウント後に false から true へ変えてくれるので、この場合を覆う。

Promise で包む20行

openAsync は別実装ではなく、open を包んだ薄い層だ。

// packages/src/event.ts
const openAsync = async <T>(controller: OverlayAsyncControllerComponent<T>, options?: OpenOverlayOptions) => {
  return new Promise<T>((_resolve, _reject) => {
    open((overlayProps, ...deprecatedLegacyContext) => {
      const close = (param: T) => {
        _resolve(param);
        overlayProps.close();
      };
      const reject = (reason?: unknown) => {
        _reject(reason);
        overlayProps.close();
      };
      const props: OverlayAsyncControllerProps<T> = { ...overlayProps, close, reject };
      return controller(props, ...deprecatedLegacyContext);
    }, options);
  });
};

コントローラーに渡る close を差し替えているのがすべてだ。もともとの close は引数を取らないが、ここでは引数を取って Promise を resolve したあとに元の close を呼ぶ。結果の型が呼び出し側で決まる理由もここにある。T が close の引数型であり、Promise の型でもある。

ただしこの構造には穴がひとつある。resolve は close が呼ばれたときにしか起きない。そのため、オーバーレイを unmount だけで取り除くと Promise は永遠に pending のまま残る。issue #169 に挙がっており、解決が必要だと考えているが、まだ issue はオープンのままだ。

resolve のタイミングが close だという点は、別の意味も持つ。閉じるアニメーションが終わった時点ではなく、閉じ始める時点だということだ。確認を取って API を呼ぶ流れなら問題ないが、確認を取って次のモーダルを開く流れでは、前のモーダルが消えていくあいだに次のモーダルが上がってくる。

設計が一周した場所

設計の過程をたどるためにコミット履歴を追ってみた。そして、この構造が最初からこうだったわけではないと分かった。1.0 は今と同じイベントと reducer の組み合わせだった。1.2.0 で状態をモジュールレベルの外部ストアへ移して useSyncExternalStore で読むように変え、1.8.0 で再び reducer に戻した。

戻した理由は issue #148 に書かれている。

useSyncExternalStore resolves tearing issues, but it doesn't work well with suspense.

オーバーレイの中でデータを取得して suspend すると、同期的な入力に応答している最中にコンポーネントが suspend したという React の警告が出た。外部ストアへ移した本来の目的はフックなしでもオーバーレイの状態を読めるようにすることだったが、意図したとおりには解決できなかったと当時の PR 本文に書かれている。結局、目的はフックで解決され、保存方式だけが元の場所に戻った。

筆者がこの記録から得たのは結論ではなく基準だ。状態を React の外に置けば呼び出し地点は自由になるが、その代わり React のスケジューリングとずれる余地が生まれる。overlay-kit は呼び出し地点だけを外に置き、状態は中に置いた。

同じ id で開き直したとき

reducer を読んでいて引っかかった箇所があった。ADD の先頭にこんな分岐がある。

// packages/src/context/reducer.ts
case 'ADD': {
  if (state.overlayData[action.overlay.id] != null && state.overlayData[action.overlay.id].isOpen === false) {
    const overlay = state.overlayData[action.overlay.id];
    if (overlay == null || overlay.isOpen) {
      return state;
    }
    return {
      ...state,
      current: action.overlay.id,
      overlayData: { ...state.overlayData, [action.overlay.id]: { ...overlay, isOpen: true } },
    };
  }
  // ...

overlayId を指定して開いたオーバーレイを close したあと、同じ id で開き直すとこの分岐に入る。ところが戻り値が既存の overlay オブジェクトをそのまま使っている。

新しく入ってきた action.overlay の controller はどこにも使われていない。

読んだだけでは確信が持てなかったので、ライブラリのリポジトリを取得してテストを自分で付けてみた。異なる内容を描くコンポーネントを二つ用意し、同じ id で順に開いた。

const ControllerA = ({ isOpen }: { isOpen: boolean }) => (isOpen ? <div data-testid="b">AAA</div> : null);
const ControllerB = ({ isOpen }: { isOpen: boolean }) => (isOpen ? <div data-testid="b">BBB</div> : null);
 
overlay.open(ControllerA, { overlayId: 'id-close' });
overlay.close('id-close');
overlay.open(ControllerB, { overlayId: 'id-close' });

結果はこうだった。overlay-kit 1.9.0 時点の main ブランチで vitest を使って実行した。

三行目はドキュメントが機能として説明している挙動なので予想どおりだ。問題は一行目である。

無視される新しい JSX

ここでもうひとつ確認した。同じ reducer の後半にはこんなコメントが付いている。

/**
 * @description Brings the overlay to the front when reopened after closing without unmounting.
 */
overlayOrderList: [...state.overlayOrderList.filter((item) => item !== action.overlay.id), action.overlay.id],

閉じたあとに開き直すと最前面へ持ってくる、という説明だ。ところが手前の分岐が先に return するため、この行はその状況では実行されない。オーバーレイを二つ重ねて開き、下に敷かれたほうを close してから開き直してみたところ、DOM の順序は変わらずそのままだった。

コメントと違う実際の挙動

ただし、これが画面上ですぐ問題として見えるかどうかは確認していない。テストは DOM の順序までしか見ておらず、多くのダイアログライブラリは独自の z-index やポータルを使うので、DOM の順序がそのまま視覚的な順序になるわけではない。

筆者が作ったほうは同じ状況をオプションとして公開している。同じ種類のモーダルを開き直すとき、既存のものを保つか新しい props で置き換えるかを呼び出し側が選ぶ。置き換えを選べば既存の Promise は replaced で終了する。先ほど結果の型を五つに分けた理由のひとつがこれである。

ここで二つの設計の違いが現れる。 筆者の方式はモーダルをデータとして扱う。文字列キーと props がストアにあるので、あとから置き換えたり更新したりできる。overlay-kit はモーダルを関数として扱う。コントローラーがクロージャなので、一度保存されると外からその中身を変える方法がない。

呼び出し側に JSX を書く代償

では、呼び出し側に JSX を書く方式は文字列キー方式より常に優れているのだろうか。筆者はそうは思わない。支払う代償が三つある。

コード分割が既定から外れる。 呼び出し側が JSX を書くということは、呼び出し側がそのコンポーネントを import するということだ。モーダルが重い編集画面で、そのボタンを押すユーザーが少数なら、その重さが一覧画面のバンドルに入る。

コントローラーの中で React.lazy は動作する。先ほどのテストと同じやり方で測ってみたところ、open の前にはモジュールが読み込まれず、開いたときに Suspense の fallback が先に出てから本体がレンダーされた。

const Heavy = React.lazy(() => import('./HeavyModal'));
 
overlay.open(({ isOpen, close }) => isOpen ? (
  <Suspense fallback={<Spinner />}><Heavy onClose={close} /></Suspense>
) : null);

つまり違いは可否ではなく既定値だ。

筆者が作ったほうは registry ファイルの値がすべて import() 関数なので、コード分割が構造上強制される。overlay-kit は呼び出し側ごとに手で書く必要がある。

unmount を呼ぶ場所を利用者が決めなければならない。 close だけ呼んで終えると、オーバーレイの情報がメモリに残る。公式ドキュメントもこの点を警告しながら、デザインシステムごとにどこへ unmount を掛けるべきかを個別に案内している。MUI と Mantine には遷移が終わるコールバックがあるのでそこへ掛ければよいが、そうしたコールバックがないライブラリではアニメーションの長さぶんタイマーを置くよう案内している。案内文書がライブラリごとに分かれていること自体が、この決定のコストである。

オーバーレイが Provider の位置でレンダーされる。 ポータルを使わないので、React Native でも同じコードが動くという利点がある。逆に OverlayProvider の下で提供したコンテキストは、オーバーレイの中からは見えない。ルーターやフォームのコンテキストに依存するモーダルを開くときは、この点を先に確認する必要がある。

宣言的という言葉の範囲

ここまで書いてきて、ひとつ引っかかることがある。筆者はこのインターフェースを宣言的と呼んで記事を始めたが、overlay.openAsync(...) はどう見ても関数呼び出しだ。

まず定義から置いてみよう。React 公式ドキュメントは二つをこう分けている。

In React, you don't directly manipulate the UI--meaning you don't enable, disable, show, or hide components directly. Instead, you declare what you want to show, and React figures out how to update the UI.

同じドキュメントが挙げる比喩のほうが鮮明だ。命令型は車に乗った人に道をひとつずつ伝えることであり、宣言的なほうはタクシーに乗って目的地だけを告げることである。

宣言的なインターフェースは命令型の手続きをなくすのではなく、境界の反対側へ移してその境界に名前を付けることだ。 先ほど見た overlay-kit の内部がまさにそうである。呼び出し側は一行なのに、中ではイベントを飛ばして二回 dispatch する手続きが回る。

では、各プロジェクトがこの言葉をどこに使っているのかを見てみよう。overlay-kit のドキュメントは従来の方式を命令型と呼ぶ。そのとき指しているのは、useState で開閉フラグを持ち、イベントハンドラーでその値を反転させるコードだ。逆に宣言的と呼んでいるのは、オーバーレイを状態ではなく振る舞いとして扱う側である。toss 技術ブログの宣言的なコードについての記事は、この言葉をより広く定義している。宣言的なコードとは抽象度が上がったコードであり、オーバーレイを表示する振る舞いを抽象化したフックがその例だというものだ。

そこで筆者はこの言葉をこう狭めて使うことにした。呼び出し側が閉じるコードを書かないこと。 いつ閉じるか、閉じるあいだ何が残っているかはオーバーレイ側が決め、呼び出し側は何を表示するかと、結果として何を受け取るかだけを書く。

この基準で見れば、useState で isOpen を持っているコードと、グローバルストアに開いている一覧を置いて呼び出し側が閉じるコードは同じ側にある。保存場所が違うだけで、閉じる文を呼び出し側が書いている点は同じだからだ。

おわりに

筆者が会社のコードで直したものは、結局のところ保存場所ではなかった。閉じるコードを誰が書くか、だった。

グローバルストアを使っていた時代にも状態はすでにコンポーネントの外にあったが、開閉の文は依然として呼び出し側にあった。await 一行に変えて初めて、その文がモーダルの中へ入った。

overlay-kit は同じ場所にたどり着いたうえで、さらに一歩進んだ。何を表示するかまで呼び出し側に書かせたのだ。筆者はそのインターフェースが読みやすいと思う。そして書きながら、その一歩の代償が何なのかも分かった。

モーダルを関数として扱うか、データとして扱うかの違いだった。 呼び出し側に JSX を書くとコントローラーはクロージャになり、クロージャは一度保存されると外から中身を変えられない。同じ id で開き直したときに新しい JSX が無視されるのは、その構造から生まれる。文字列キーで扱えばモーダルはストアに収まった値になり、置き換えも更新もコード分割もできるが、呼び出し側は名前しか知らなくなる。

ライブラリを選ぶとき、インターフェースが気に入るという感覚はかなり信頼できる合図だと思う。ただし、その感覚が正確に何を指しているのかを一度は言葉にしてみるべきだ。言葉にしてみなければ、気に入ったのがインターフェースなのか、そのライブラリを使う人たちの評判なのかを区別できない。この記事を読む読者の方々にも、いま使っているライブラリについて一度その作業をしてみることをお勧めしたい。

筆者は TypeSafe AI が公開した決定モデル Jev の主張を検証する中で、まずこの概念を整理する必要があった。Jev は文章の代わりに選択肢ごとの確率を返し、キャリブレーションを学習目標に掲げている。その主張を検討するには、キャリブレーションとは何か、既存のモデルでなぜずれるのかを先に知る必要があった。

正解率とキャリブレーション

まず正解率とキャリブレーションを区別しなければならない。正解率は何パーセント当てるかであり、キャリブレーションは自分が何パーセント当てるかを知っているかどうかだ。降水確率70%と言った日だけを集めたとき、実際に10回のうち7回雨が降ったなら、その予報はキャリブレーションがよく取れている。正解率が高いという意味ではない。自分の限界を知っているという意味だ。60%しか当てないモデルでも、自分で60%だと言えばキャリブレーションは満点である。

目盛りがずれる方向は二つある。モデルが言った確率が実際の的中率より高ければ overconfidence（過信）、低ければ underconfidence と呼ぶ。言った確率を横軸に、その確率区間の実際の的中率を縦軸に置くと、二つが分かれる場所がひと目で見える。こうして描いた図を reliability diagram と呼ぶ。

曲線が対角線の上に乗っていれば、言ったとおりに当てたということだ。対角線の下に垂れるほど、言った確率に比べて当たらない。

そのズレを測る指標が ECE（expected calibration error）だ。Guo et al. 2017 の定義に従えば、確率の区間ごとに「言った確率」と「実際の的中率」の差を、その区間の標本比率で重み付けして平均した値で、0が完璧である。下はその式を写したコードだ。10問中6問を当てるモデルが、毎回0.6と言う場合と毎回0.95と言う場合を比べる。

// Guo et al. 2017 의 식 (3). 구간은 등간격 10개(논문 실험은 15개), 경계는 왼쪽 닫힘
function ece(preds, M = 10) {
  const bins = Array.from({ length: M }, () => ({ n: 0, hit: 0, conf: 0 }))
  for (const { p, correct } of preds) {
    const b = bins[Math.min(M - 1, Math.floor(p * M))]
    b.n++
    b.hit += correct ? 1 : 0
    b.conf += p
  }
  return bins.reduce(
    (sum, b) => (b.n ? sum + (b.n / preds.length) * Math.abs(b.hit / b.n - b.conf / b.n) : sum),
    0,
  )
}
 
// 10문제 중 6문제를 맞힌다
const answers = Array.from({ length: 10 }, (_, i) => ({ correct: i < 6 }))
console.log(ece(answers.map((a) => ({ ...a, p: 0.6 }))).toFixed(3)) // 매번 0.6 이라고 말할 때
console.log(ece(answers.map((a) => ({ ...a, p: 0.95 }))).toFixed(3)) // 매번 0.95 라고 말할 때

2026-10-08 に Node v24.16.0 で実行した結果だ。

0.000
0.350

正解率はどちらも0.6だ。言った確率が変わっただけなのに、ECE は0から0.35に上がる。ただし式に絶対値が入っているので、ECE はズレの大きさだけを測り、方向はわからない。毎回0.25と言いながら6問当てても、ECE はまったく同じ0.35になる。overconfidence なのか underconfidence なのかは、reliability diagram か、平均確信度から正解率を引いた値を見なければわからない。

RLHFの目的関数

では、人のフィードバックで仕上げたモデルは、なぜこの目盛りがずれるのだろうか。まず RLHF（reinforcement learning from human feedback）が何を最適化しているのかを見る必要がある。人の選好比較から報酬モデルを立てる骨格は Christiano et al. 2017 で生まれ、これを言語モデルに移した初期の仕事が Ziegler et al. 2019 で、InstructGPT が指示追従に適用した。このとき押し上げる値は、人の選好を真似た報酬モデルの点数だ。言語モデルでの仕事は、強化学習を始める前のモデルから離れすぎないよう引き留める KL penalty を報酬に加え、InstructGPT は事前学習データの勾配も混ぜたが（PPO-ptx）、押し上げる対象はやはりその点数である。

チャットボットにとって、人の選好は正しい目標だ。問題は、その選好が不確実さを表に出した口調を避ける側に傾いていることにある。Zhou et al. 2024 は、四つの公開選好データセットで、アノテーターが "I'm not sure, maybe" のような弱める表現を含む答えをあまり選ばないことを示した。差は小さいが有意だった。ただし、確信を強める表現を含む答えをより多く選んだわけではない。Leng et al. 2025 は、報酬モデルが答えの実際の品質と関係なく、高い確信度の数値を書いた答えに高い点数を与えることを示した。どちらもトークン確率ではなく、文章の中の確信表現（verbalized confidence）についての結果だ。RLHF に代わる学習法を打ち出した TypeSafe も、自社の入門ドキュメントで、RLHF が自信ありげに聞こえるハルシネーション（confident-sounding hallucinations）に報酬を与えうると書いている。代替案を売る側の立場である。

GPT-4のキャリブレーション曲線

トークン確率でも同じ方向のズレが観測されている。GPT-4 技術レポート本文の Figure 8 は、事前学習モデルと post-training モデルの reliability diagram を並べて置いているが、そのキャプションがこうだ。

Right: Calibration plot of the post-trained GPT-4 model on the same subset of MMLU. The post-training hurts calibration significantly.

横軸は MMLU の多肢選択問題の選択肢 A、B、C、D それぞれにモデルが付けた確率（logprob）で、縦軸はその区間の実際の的中率だ。Figure 8 に刻まれた数字では、事前学習モデルの ECE が 0.007 で、PPO（RLHF で報酬モデルの点数が上がる方向にモデルを更新するときに使う強化学習アルゴリズム）を経たモデルが 0.074 だ。10倍以上悪くなった。

Figure 8 の右（PPO）のパネルでは、0.4以上の区間の棒は対角線の下にあるが、0.1から0.3の区間はむしろ対角線の上だ。0.1から0.9の棒は実際の的中率およそ0.3から0.5に平らに集まっていて、モデルが言う確率が上がっても的中率はほとんどついてこない。0.074 にはこの underconfidence の区間も混ざっている。そして Guo et al. が指摘したように、reliability diagram は区間ごとの標本数を示さないので、棒が対角線から離れた距離と、その区間が ECE に足した分は比例するとは言えない。

このパネルは上の概念図と二つの点で異なる。まず、概念図の曲線のように対角線の下に垂れるだけでなく、対角線を一度横切る。また、選択肢四つの確率をすべて区間に入れているので、上のコードのように選んだ答え一つの確率で測る定義とも異なる。だから 0.074 と上のコードの 0.35 を同じ目盛りに置いて比べはしない。

では、なぜ悪くなったのか。レポート本文は、事前学習モデルはよくキャリブレーションされていて、post-training の後にキャリブレーションが下がったとだけ書き、原因は述べていない。手がかりは Anthropic の Kadavath et al. 2022 にある。彼らが自社の言語モデルから学習させた RLHF ポリシーは、見かけ上キャリブレーションがとても悪かった。論文はこれを驚くことではないとし、RL fine-tuning が最も多くの報酬を受ける振る舞いのほうへ予測を寄せる傾向があるからだと書いた。本題ではなく、短く添えた実験である。ところが、すべての評価に同じ温度 T=2.5 を一つ適用すると、三つの評価でキャリブレーションの問題がおおむね解消された。温度は logit を割る値で、1より大きければ答えの順序はそのままに確率分布だけを平らに広げる。筆者は、値一つでおおむね解消されたという結果を、ズレが一部の区間に集まったのではなく、分布全体が一方に狭まった形だという意味に読む。論文は、より強い RL 学習はこのやり方では直せない形でキャリブレーションを損なうかもしれない、という但し書きも添えている。

これは Anthropic のモデルの結果なので、Figure 8 の原因としてそのまま持ち込むことはできない。前の節の研究も文章の中の確信表現を扱っている。人が不確かな口調を避けるという結果とトークン確率のズレを直接つなぐ一次資料を、筆者は見つけられなかった。

コードが受け取る確率

Figure 8 の確率はトークンの対数確率だ。同じ種類の値を受け取るには、OpenAI API の仕様どおり Chat Completions のリクエストで logprobs を true にし、top_logprobs でトークン位置ごとに受け取る候補の数を0から20のあいだで決める。モデルに答えと一緒に確信度を数字で言わせて受け取る値は、文章で述べた確信であり、トークン確率とは別の値だ。

二つの値を扱った研究は、それぞれ異なる組を比べている。Tian et al. 2023 は、ChatGPT、GPT-4、Claude のような RLHF モデルの中で、文章で述べた確信が条件付き確率よりおおむねキャリブレーションがよく、三つのベンチマークで ECE を相対的に50%ほど減らした場合が多かったと報告した。ただしこの比較で、重みが公開されていないモデルの条件付き確率は、API のトークン確率ではなく、同じ質問を10回サンプリングして答えが出た割合で推定した値である。先に見た Leng et al. は、RLHF 以前のモデルと比べて、RLHF モデルは文章で述べる確信でより overconfident だと報告した。二つの結果は両立しうる。そして 0.074 は2023年の GPT-4 post-training モデルが MMLU の一部で出した値なので、いま API で呼んでいるモデルにそのまま当てはめることはできない。

まとめ

まとめると、キャリブレーションは何パーセント当てるかではなく、自分が何パーセント当てるかを知っているかの問題であり、ECE はそのズレの大きさを測る数字だ。方向は reliability diagram か、平均確信度から正解率を引いた値を見なければわからない。RLHF は人の選好を真似た報酬モデルの点数を押し上げる。Kadavath et al. は、その最適化が多くの報酬を受ける側へ予測を狭める傾向があると見ている。人は不確実さを表に出した答えをあまり選ばず、報酬モデルは品質と関係なく高い確信度の数値を書いた答えに高い点数を与えるという研究がある。GPT-4 では post-training の後に ECE が 0.007 から 0.074 として刻まれたが、OpenAI はその原因までは書いていない。コードが受け取る確率がトークン確率なのか文章で述べた確信なのかによってキャリブレーションも違って出るので、どちらにしても自分のデータでもう一度測る必要がある。

キャリブレーションを学習目標に掲げた決定モデル Jev の確率が本当に正直なのかは、決定モデル、Jev と Kevで扱う。

この記事を読んでいる皆さんも、モデルが返した確率をしきい値としてコードに埋め込む前に、そのモデルが何を目標に学習されたのか、自分のデータで目盛りが合っているのかを一度は測ってみてほしい。

開発をしていて、私がコードを書くのと同じくらい時間を割いているのは、何を作るべきかを突き止める作業だ。企画者と要件をやり取りし、デザイナーと画面をすり合わせ、ドメインを知る人に用語が何を指すのかを尋ねる。そして、この過程がずれたときのコストがコードを書き間違えたコストよりはるかに大きいことを、何度か経験してきた。

最近、James Samuelが書いたエンジニアリングリーダーの日常業務という記事を読んだ。著者はリーダーの仕事を六つに分けるのだが、最初に扱っているのが情報収集だった。あらゆる決定と方向と行動が、いま何が起きているのかについての正確な理解に依存するからだという。

私はいつかリーダーの役割を担いたいと考えているが、この箇所を読んで浮かんだのは少し違うことだった。リーダーが最初に扱う仕事が情報収集なら、実務者にとってその対応物は要件の把握だ。いま要件を扱っているやり方が、のちに組織の情報を扱うやり方になる。

この記事でリーダーシップの話をしたいわけではない。いま実務者として他職種とコミュニケーションを取るとき、何を間違えていて、何を道具として使えるのかという話だ。結論から言うと、私はこの問題が態度だけの問題ではないと考えるようになった。代わりに使える表現としてubiquitous languageというものがあるので、それが何なのかを見ていこう。

同じ単語、違う意味

Martin FowlerはBounded Contextという記事で電力会社の事例を挙げている。私が経験したずれのかなりの部分は、この形だった。

ここで「meter」という単語は、組織の異なる部分で微妙に違う意味を持っていた。送電網とある場所の接続なのか、送電網とある顧客の接続なのか、それとも物理的な計器そのものなのか。

here the word 'meter' meant subtly different things to different parts of the organization: was it the connection between the grid and a location, the grid and a customer, the physical meter itself

同じ「meter」という単語が、組織の部署ごとに微妙に違うものを指していたということだ。そしてFowlerは、こうした混乱が特定の事例における偶然ではないと付け加える。CustomerやProductのような多義語で同じ混乱が繰り返されるのを見てきた、というのだ。

これは会議の参加者が会議下手だったから起きたことではない。組織に異なる文脈があれば同じ単語が分かれていくのは自然であり、それを放置すればコードまで分かれていく。

この話の技術的な背景についてはドメインモデルで一度扱った。あのときはコードの中でモデルをどう表現するかを論じた。この記事では、そのモデルが作られる前の、人と人との対話の段階を扱う。

二つの意味を持つ単語

ではなぜ、こうしたことが構造的に繰り返されるのか。説明は二筋ある。

一つは組織構造の側だ。Mel Conwayが1968年にDatamationへ発表した論文How Do Committees Invent?は、組織が自らのコミュニケーション構造を柔軟に変えられない度合いに応じて、その組織は自分自身のイメージを、生み出すあらゆる設計物へ刻印すると述べている。一般にConwayの法則として引用される一文は、実は著者が後年みずから定式化した表現であり、1968年の本文にあるこの記述のほうが直接的だと感じる。

私がこの文から実務的に読み取ったのは「刻印する」という表現だ。用語が分かれることが対話で終わらず、成果物にそのまま残るという話だからである。先ほどの「meter」がそうだ。「meter」の範囲を互いに違う形で理解したまま各自が作れば、その差は議事録ではなく、テーブル名やAPIレスポンスのフィールドや画面の文言に残る。そしてそこからは、直すコストが会話をもう一度するコストとは比べものにならないほど大きくなる。

ここで実務者にできることとできないことが分かれる。組織のコミュニケーション構造を変えるのは実務者の手を離れている。しかし用語の境界を目に見えるようにすることは、いまの場所からでもできる。この文書で言う単語の意味がどの範囲なのかを書き留め、他のチームが使う単語と違うのなら違うと明示する作業だ。後で見る道具はすべて、その作業を楽にするための装置である。

もう一つは、もう少し根本的だ。認知科学の側から見れば、協働はそもそも共有された背景の上でしか成立しない。Herbert ClarkとSusan Brennanが1991年に書いたGrounding in Communicationは、ピアノのデュエットを例に始まる。二人の演奏者は膨大な量の共有情報、すなわちcommon groundを前提としなければ、内容を合わせることすら始められないというのだ。ここでのcommon groundは相互知識と相互信念、相互の前提を指す。そして著者らは、あらゆる集団行動がcommon groundとその蓄積の上に築かれると明言する。

私がこの二筋を並べて見たあとに得た視点はこうだ。用語がずれるのは事故ではなく、既定の状態である。合っている状態のほうが、維持コストを払わなければならない例外なのだ。ではそのコストを誰がどう払うのかが、実務の問いになる。

積極的な監視

Evansは2003年に出したDomain-Driven Designで、ubiquitous language、日本語でいう共有言語というパターンを提示する。しばしば「developerとドメインエキスパートが同じ用語を使おう」という程度に要約されるが、原書を読むと処方ははるかに具体的だ。モデルを言語の骨格とし、チーム内のあらゆるコミュニケーションとコードでその言語を粘り強く使うとチームで約束せよと求める。そしてそれに続く文が、私にとって最も重要だった。

ドメインエキスパートは、ドメインの理解を伝えるのに不自然または不十分な用語や構造に異議を唱え、developerは設計を破綻させる曖昧さや非一貫性に目を光らせる。

Domain experts object to terms or structures that are awkward or inadequate to convey domain understanding, while developers watch for ambiguity or inconsistency that will trip up design.

ドメインエキスパートはドメインの理解を伝えるのに不自然だったり不足していたりする用語と構造に異議を唱え、developerは設計を破綻させる曖昧さや非一貫性を監視するということだ。

この文を読んで、私は自分の役割についての理解を修正した。それまで私は、要件定義の会議で自分を受信者だと考えていた。企画が決まればそれを正確に受け取って実装するのが自分の仕事だと思っていた。ところがEvansが規定したdeveloperの役割は受信ではなかった。曖昧さを見つけて返すことだ。これは消極的な協力ではなく、積極的な監視である。

（ちなみにFowlerは自身の記事でこの文を「Domain experts should object ... developers should watch」と訳している。原書に助動詞はない。些細な差だが、原書のほうがより断定的に読める。そうするのが望ましいという勧告ではなく、そうすることがこのパターンの定義だという語調だ。）

では曖昧さはどうやって見つけるのか。Evansはここにも答えを与えている。対話で繰り返し使えば用語解釈の差が現れる、というのだ。私はこの文をこう読んだ。曖昧さは文書を精読して見つけるものではない。仕様書をどれだけ丁寧に読んでも、「meter」という単語が複数の意味を持つという事実は現れない。その単語を実際の事例に当てて繰り返し使ってみて初めて分かれる。「ほかの方はmeterをどんな意味で理解していますか？」といった質問が出る瞬間が、その地点だ。

最小協力努力の原理

この方法を知っていても実践できない時期はあるだろう。では、なぜ繰り返し尋ねないのか。

もう一度ClarkとBrennanの論文に戻ろう。著者らは、語られたことをcommon groundの一部にしていく過程にgroundingという名前を与える。そして人々がこの過程でどう振る舞うかについて、一つの原理を提示する。最小協力努力の原理（the principle of least collaborative effort）だ。人は必要以上に懸命に働くことを好まない、という観察から出てきた原理である。

ここで重要な箇所が出てくる。

最小協力努力の原理によれば、人々は必要なだけの共同努力でgroundingしようとするはずだ。しかし何に努力がかかるのかは、コミュニケーションの媒体によって劇的に変わる。

By the principle of least collaborative effort, people should try to ground with as little combined effort as needed. But what takes effort changes dramatically with the communication medium.

努力がかかる地点が媒体によって劇的に変わるということだ。ある媒体で使える確認手法が、別の媒体では端から不可能だったり、可能でもコストがはるかに大きかったりする。著者らは特に、話した瞬間に相手が受け取らない媒体では、他人が誤解を正してくれることを当てにするコストが非常に大きくなるため、話し手がそれを避けようとすると指摘する。

ここで一つ断っておくことがある。この論文は1991年に書かれ、著者らが比較した媒体は対面の会話や電話、手紙、留守番電話といったものだ。SlackやNotionは扱っていない。媒体によってgroundingコストが変わるという枠組みは著者らのものであり、それをいまの非同期な業務チャネルに適用するのは私の解釈である。

そう適用して見ると、私がなぜ繰り返し尋ねなかったのかが説明できる。仕様書をテキストで受け取ってテキストで確認する環境では、曖昧な箇所ごとに確認メッセージを送る作業はコストが大きい。答えがいつ来るか分からず、何度も尋ねると理解できていないように見えるのではないかと心配になる。だから人は自然と自分の解釈へ移っていく。

ここで力が二つあるという点を区別しておく必要がある。一つは媒体が確認コストを上げるということで、これはClarkとBrennanの話だ。もう一つは何度も尋ねると無能に見えるのではないかという心配で、これは彼らの原理が予測するものではなく、後で出てくる心理的安全性の側の話である。正確に言えば、最小協力努力の原理が予測するのはより安い確認方法を選ぶであって、確認をやめるではない。確認を畳んで推測に移るのは原理の作動ではなく、groundingの失敗だ。そしてその解釈が間違っていたという事実は、実装が終わったあとに現れる。

十分な水準への到達

では曖昧なものすべてについて尋ねなければならないのだろうか。それは現実的ではないし、私はそうする人を見たこともない。この問いについても論文は基準を提示している。grounding criterionだ。相手が話し手の意図を現在の目的に十分な水準まで理解したと双方が互いに信じている状態を指す。著者らはその前に、完璧な理解はそもそも不可能だという文を添えている。

私にとってこの基準が実用的に感じられた理由は、目標を下げてくれるからだ。要件を完璧に理解する必要はない。いまやろうとしている作業に十分なだけ互いに信じられればよい。そして著者らは、目的が変われば基準も変わらなければならないと述べる。

この部分は実務では、確認の強度を調整する基準になる。まだ方向を探っている場で「ここでmeterはどんな意味に解釈されますか？」に食い下がると、会話が前に進まない。その段階で必要なのは、何をなぜやろうとしているのかについての合意であって、境界値の確定ではない。逆に実装に入る直前には、その質問が必ず出なければならない。このときは「meter」がどの範囲なのかについて互いに同じものを思い浮かべていると信じられなければならず、そうでなければ誤った前提の上にコードが積み上がる。

だから私は、同じ曖昧さに出会ってもいまがどの段階かによって違う扱いをする。探索の段階では一覧に書き留めて先へ進み、実装の直前にはその一覧を開いて一つずつ閉じていく。確認を先送りすることと確認を諦めることは別の作業だ。

この地点で併せて使いやすい道具が一つある。Matthew SkeltonとManuel PaisのTeam Topologiesは、チーム間の相互作用を三つのモードに分ける。定められた期間ともに新しいものを発見するcollaboration、一方が提供し一方が消費するX-as-a-Service、一方が他方を助けメンタリングするfacilitationだ。

もともとは組織設計の話だが、私はこれを会議単位に縮めて使うのが実用的だと感じた。いまこの会話がどのモードなのかを互いに違う形で認識していると、会議はずれる。企画者はすでに決まったことを伝える場だと思っているのにdeveloperはともに発見する場だと思っていれば、developerの質問は協働ではなく難癖に聞こえる。逆の場合もある。developerが確定した仕様を受け取りに来たのに企画者はまだ探索中だったなら、developerは仕様がないともどかしく感じる。

だから私は最近、会議の序盤にこれを先に確認する。「これはまだ開いているものですか、それとも決まったことを確認する場ですか？」この質問一つが、その後の会話の性格を変える。grounding criterionを目的に合わせて調整する作業と同じ話だ。

解像度が合わないと会話は空回りする

モードを合わせたとしても残る問題がある。私がよく経験したもう一つのずれは、互いに違う解像度で話している状況だった。

企画者が文章で渡してくる要件は、たいてい抽象的すぎる。「ユーザーが予約履歴を手軽に確認できるように」といった文からは、画面が何枚あるのか、どこからどこへ遷移するのかが出てこない。逆にデザイナーが渡してくる案は具体的すぎる。ボタンの色と余白まで決まっているので、肝心の「この流れは正しいのか」を議論しにくい。

BasecampのRyan Singerが書いたShape Upが、この問題を正確に突いている。ワイヤーフレームや具体的な視覚レイアウトから始めると、不要なディテールに囚われて必要なだけ広く探索できなくなる、というのだ。そこでShape Upが提案するものは、その中間の表現である。breadboardingと呼ばれ、電気工学から概念を借りている。ブレッドボードは実機の部品と配線はすべて揃っているが、工業デザインはない試作品だ。だから描くものもちょうど三つだ。遷移できる場所（places）、ユーザーが操作できるもの（affordances）、そしてその操作がユーザーをどこへ連れていくかを示す接続線（connection lines）である。

私がこの技法を良いと思った理由は、developerが作れる成果物だからだ。企画者にもっと詳しく書いてくれと頼んだり、デザイナーの案を待ったりせずに、いま理解した流れをその場で描いて「こう理解しましたが合っていますか」と返せる。Evansの言う監視（曖昧さを返すこと）を実行する具体的な方法というわけだ。そして前節の視点から見れば、これはgroundingコストを下げる装置である。一枚の図が、テキストでやり取りする何度もの確認を代替する。

ところがこの解像度は、思ったより維持するのが難しい。流れを描いていると自然に「ここのボタンは右下に置いたほうがよくないか」といった話へ降りていく。私も何度かそうなった。一度そうやって降りると、その場で議論されていた問い、つまりこの流れは正しいのかが静かに消える。まだ流れが確定していないのにボタンの位置を決めていると、後で流れが変わったときにその議論は丸ごと捨てられる。

だから私はこの段階で、わざと下手な図を保とうとする。四角と矢印と名前だけの図であれば、相手もディテールを指摘しようとせず流れにだけ反応する。図の完成度が低いことが、この道具においては機能なのだ。（きれいに描きたい気持ちを抑えるのが思いのほか難しい）

抽象化のレベルという概念そのものが協働の道具になりうるという点は、抽象化で扱った話ともつながる。あのときはコードの抽象化レベルを論じたが、対話にも同じものがある。

ルールと例と質問を分ける

解像度を合わせるもう一つの方法は、議論そのものを構造化することだ。

Cucumberプロジェクトを率いたMatt Wynneが2015年に紹介したExample Mappingを見てみよう。彼は多くのチームが要件の議論を苦手とする理由を、構造がないせいで時間がかかり退屈になるからだと診断する。だから定期的にも一貫してもやらなくなる、というわけだ。私もまさにそうだった。要件定義の会議が長引くと次からは短く終わらせようとし、短く終わらせれば曖昧なものがそのまま残る。

Example Mappingは四色のカードで議論を分ける。黄色はいま扱っているストーリー、青はルールあるいは受け入れ基準、緑はそのルールを説明する具体的な例、そして赤は答えの分からない質問だ。

私はこの中で赤いカードが核心だと考えている。残りの三つは整理の技法だが、赤いカードは「分からない」を会議の正式な成果物にする装置だ。分からないという事実を口にすることが、会議を遅らせる行動ではなく、会議が生み出すべき結果になる。

これがなぜ重要かは、逆の場合を思い浮かべると明らかになる。赤いカードのない会議で曖昧な箇所に出会うと、選択肢は二つだ。いま食い下がって会議を延ばすか、先へ進んで後で一人で解釈するか。前節で見たとおり、人はたいてい後者を選ぶ。ところがカードが一枚あると、三つ目の選択肢が生まれる。書き留めて先へ進みつつ、消えないようにすることだ。会議は進み続け、曖昧さはなくならないまま一覧に残る。

緑のカードも似た役割を果たす。ルールだけを書けば皆が同意するが、そのルールを説明する具体的な例を書こうとした瞬間に解釈が分かれる。Evansの言う「対話で繰り返し使えば差が現れる」を会議の様式へ移し替えたわけだ。ルール一つに例を三つずつ付けてみろと言えば、そのうちの一つでたいてい「あれ、この場合はどうなりますか？」が出てくる。（私の経験上、その質問が出ない会議は皆が理解した会議ではなく、各自が違う形で理解した会議だった）

似た発想でBDDの側で長く使われてきたThree Amigosもある。ビジネスと開発とテストという三つの視点がそれぞれ違う質問を投げるというもので、Agile Allianceの用語集はその質問を、何の問題を解こうとしているのか、その問題を解く解法をどう作るのか、そしてこれはどうか何が起こりうるか、と整理している。三つ目の質問が出ない会議がどうなるかは、あえて説明しなくてもよさそうだ。

分からないことを確認する手順を作る

ところで、なぜ私たちは赤いカードをうまく出せないのか。ここで心理的安全性の話をしないわけにはいかない。

Amy Edmondsonが1999年にAdministrative Science Quarterlyへ発表した論文が、チーム心理的安全性という概念を正式に打ち立てた研究だ。（論文自身は1965年のScheinとBennisの研究を源流として明かしている）チーム心理的安全性を、チームが対人関係上のリスクを取っても安全な場所だという共有された信念として定義する。分からないと言うこと、反対意見を出すこと、ミスを認めることがこれに当たる。論文は製造業企業の51チームを調査し、心理的安全性が学習行動と関連し、その学習行動が心理的安全性とチーム成果の間を媒介するという結果を示した。

ところが私がこの論文で最も実用的だと感じた文は、定義ではなくそのすぐ次だった。

たいていの場合、この信念は暗黙的である傾向がある。個人もチーム全体も当然のものとみなし、直接の注意を向けない。

For the most part, this belief tends to be tacit—taken for granted and not given direct attention either by individuals or by the team as a whole.

この信念はたいてい暗黙的であり、個人もチームも直接の注意を向けないということだ。

ここからは私の推測だ。論文が述べたのはこの信念が暗黙的だというところまでであり、だから様式を作ればよいという処方は論文にはない。ただ、暗黙的なものが宣言では変わらないというのは何度も見てきた。「うちのチームは分からないことを聞いてもいいチームです」と言うことでは、なかなか変わらない。だから私は前節の赤いカードが重要だと考えている。分からないという言葉を様式の中の欄にしてしまえば、それを埋める作業は勇気ではなく手続きになる。

もちろん反論は可能だ。安全でないチームでは赤いカードの欄もただ空のままだろう。もっともな指摘であり、この道具が安全性を生み出すと主張するつもりはない。ただ、欄があれば少なくとも空であるという事実が目に見える。誰も分からないことがなくて空なのか、言い出しにくくて空なのかを尋ねる場ができる。

同じ発想が実際の文書様式にも入っている。DDDコミュニティが作ったBounded Context Canvasを見ると、一つのコンテキストを設計し記録する協働ツールなのだが、欄の構成が興味深い。名前と目的、戦略的分類、ドメイン上の役割、インバウンドとアウトバウンドのコミュニケーション、そしてUbiquitous Language、ビジネス上の決定、Assumptions、検証指標、Open Questionsだ。

共有言語を書く欄と、前提を書く欄と、開かれた質問を書く欄がそれぞれ別にある。キャンバスの説明は、目的を書くという行為そのものがぼんやりした考えを明確に言語化させ、チーム全体を同じページに置くと述べている。

私はこの発想が、コミュニケーションの問題に対する最も現実的なアプローチだと考えている。人の態度を変えようとする代わりに、言いにくいことに欄を作ってやるのだ。良い構造は人にうまくやれと要求する代わりに、うまくやりやすくしてくれる。

これが好みの問題ではない理由

ここまで読むと、こういう反応が出るかもしれない。良い話だが、結局はコミュニケーションを頑張ろうということではないか。それは性格の問題ではないか。

私もしばらくはそう考えていた。ところがこの部分にはデータがある。

DORAは組織文化を扱うとき、社会学者Ron Westrumの分類を持ち込む。権力志向のpathological、規則志向のbureaucratic、成果志向のgenerativeの三つだ。そしてDORAの公式文書は、自分たちの研究結果をこう要約している。

高い信頼を持ち、情報の流れを重視する組織文化は、ソフトウェアデリバリーの成果を予測する。

organizational culture that is high-trust and emphasizes information flow is predictive of software delivery performance

信頼が高く情報の流れを重視する組織文化が、ソフトウェアデリバリーの成果を予測するということだ。コミュニケーションがうまくいくチームは気分がよい、という話ではなく、成果と一緒に動く変数だという話である。

ただし、ここで予測するという言葉を因果として読んではいけない。DORAのデータは同じ回答者が文化と成果を一緒に答えた調査であり、組織レベルの相関だ。組織に満足している人が両方とも甘めに答えた可能性が残っているし、組織レベルの関係から個人はこう行動せよという処方がただちに導かれるわけでもない。だからこの資料で言えるのはここまでだ。情報の流れは好みの領域だけにあるのではなく、成果と一緒に動く場所にある。

同じ文書は、Westrumの言う良い情報の三つの性質も整理している。受け手が必要とする問いに答えを与え、時機が適切であり、受け手が効果的に使える形で提示される、というものだ。三つとも基準が受け手にあるという点は注目に値する。たくさん共有することが良い情報の流れではない。

GoogleのProject Aristotleもよく引用される資料だ。reWorkで公開された内容によれば、180チームを調査し数百の変数に35以上の統計モデルを回した結果、チーム効果性に影響を与える五つの要因として心理的安全性、信頼性、構造と明確さ、意味、影響力を提示した。そして結論は、チームに誰がいるかよりも、そのチームがどのように協働したかが重要だった、というものである。

ただ一つ断っておきたい。公式ページは五つの要因を重要度順に並べていると明記しており、心理的安全性を最初に置いている。ところが、この研究を引用した記事によく見られる「圧倒的に一位」といった大きさの表現は、そのページにはない。順序があるということと、残りを圧倒するということは別の話だ。だからこの記事では大きさを主張しない。心理的安全性の重要性を語るなら、前節のEdmondsonの原論文に依るのが正確である。

ふたたびリーダーの話へ

最初に引用した記事に戻ろう。

James Samuelは情報収集を最初に扱いながら、実務者時代のやり方が通用しなくなると述べる。個人コントリビューターのときは自分の仕事の全体像を持っているが、人に対する責任を負うようになると以前のやり方は使えない、というのだ。そこで必要な力として、ノイズを取り除き情報を統合して一貫した現実の像にする能力を挙げる。どんなマネージャーもすべてを処理することはできないからだ。

私はこれが、先に見たWestrumの良い情報の三つの性質と同じ話だと感じた。たくさん集めることではなく、使える形にすることだ。そしてそれは、いま要件を扱いながらやっていることと変わらない。仕様書の文から曖昧な部分を選り分け、breadboardで描き直して確認し、分からないことを赤いカードとして残す作業こそが、ノイズを取り除いて一貫した像を作る練習である。

著者が意思決定について残した言葉も記憶に残る。確実性を待つこともそれ自体が一つの決定であり、コストを伴うということだ。要件が完全に明確になるまで待つことも同じである。だから完璧な理解ではなく現在の目的に十分な水準というgrounding criterionが、実用的な基準になる。

おわりに

まとめるとこうだ。

他職種とのコミュニケーションの失敗は、たいてい態度だけの問題ではない。組織に異なる文脈があれば同じ単語が分かれていくのが既定の状態であり、合っている状態のほうがコストを払って維持しなければならない例外だ。そのコストを払う方法が共有言語であり、その中でdeveloperの役割は要件を書き取ることではなく、曖昧さを監視して返すことである。

ところが返す作業には努力がかかり、人はその努力を最小化しようとする。だから私は意志に頼る代わりに三つを使うことにした。この会話がどのモードなのかを先に確認すること、文章とデザイン案の間の解像度で流れを描いて返すこと、そして分からないことを書く欄を会議の様式の中に作っておくことだ。三つとも態度を直せと要求せず、やりやすくする側である。

私はまだリーダーではないし、この記事に書いたこともその立場で検証したわけではない。チームの規模や組織文化が違えば通用しないものもあるだろう。ただ一つは、いま確信できそうだ。のちに情報を扱うやり方は新しく学ぶものではなく、いま要件を扱っている習慣がそのまま大きくなった形になるだろう。だから私は最近、会議で「それはどういう意味ですか」と尋ねることを、以前ほど恥ずかしがらないようにしている。

この記事を読んでくださっている方も、最近の会議でうなずいたけれど実は確信がなかった単語が一つでも思い浮かぶなら、次はその単語をもう一度使ってみることをお勧めしたい。繰り返し使えば現れる。

直前の記事であるtoken節約法をまとめながら、ずっと頭から離れない問いが一つあった。「個別のpromptを工夫する段階から、不要な情報を取り除き、必要な情報を選び取る技術（context engineering）へ重心が移っている」と考えていたが、記事を書き終えると自然に次の問いが続いた。では、コンテキストの次には何が来るのか。

「今後の方向」を語る文章には慎重さが必要だ。未来には数多くの選択肢があるはずなので、ここではすでに公開された一次資料から読み取れる重心の移動を整理することに焦点を当てる。多少の推論は含まれるが、さまざまな観点から読んでもらえればと思う。

promptからcontextへ

まず用語を整理しよう。しばらく業界の中心的な話題はprompt engineeringだった。モデルに送る一度の指示をどううまく書くか、つまり明確な指示文、良い例、出力形式をどう設計するかという問題である。

やがて仕事の単位が大きくなった。一回限りの質問ではなく、数十ターンにわたって動くagentが一般化すると、一つのpromptではなく、モデルが各ターンで見るcontext全体（system prompt + ツール定義 + 会話履歴 + 検索結果 + メモリ）をどう構成するかが、より重要になった。これをcontext engineeringと呼ぶ。Anthropicは2025年9月の「Effective context engineering for AI agents」でこの枠組みを整理し、Chroma研究チーム（Hong et al.）が同年発表したcontext rot研究が定量的な根拠を加えた。GPT-4.1、Claude 4、Gemini 2.5、Qwen3など18のモデルを対象に、単語をそのまま書き写す程度の単純な課題でさえ、入力が長くなるほど性能が不均一に崩れることを示した。モデルが100番目のtokenと10,000番目のtokenを同じように扱うという一般的な仮定は、実際には成り立たない。「contextは長いほどよい」ではなく、「何が入っているかと同じくらい、どう配置されているかが重要だ」という結論が、詰め込むことから選び取ることへの転換を後押しし、この用語は急速に定着した。

ここで、よくある誤解を一つ指摘しておきたい。prompt engineeringがcontext engineeringに置き換えられたわけではない。promptをうまく書くことは今も基本であり、context engineeringはその上に載る上位概念に近い。（良いコードの書き方から良いシステムの設計へ関心が移ったからといって、codingが不要になるわけではないのと同じだ。）したがって正確な表現は「乗り換えた」ではなく、「包含しながら広がった」である。

では改めて、その広がりはcontextで止まったのだろうか。そうは見えない。

Anthropicエンジニアリングブログ

方向を見極める最も誠実な方法は、この分野を実際に牽引する組織が何を書いているかを時系列で読むことだと思う。Anthropicのエンジニアリングブログを「Effective context engineering」（2025年9月）以降たどると、タイトルだけでも重心が次にどこへ移ったかが見えてくる。

• 2025年10月、Agent Skillsでagentを強化する
• 2025年11月、Code execution with MCP：より効率的なagent
• 2025年11月、Effective harnesses for long-running agents
• 2026年1月、Demystifying evals for AI agents
• 2026年1月、AI-resistantな技術評価の設計
• 2026年2月、agentic coding評価におけるインフラノイズの定量化
• 2026年3月、Harness design for long-running application development
• 2026年4月、Scaling Managed Agents：頭脳と手を分離する
• 2026年5月、製品全体でClaudeをcontainする方法

一覧から一歩引いて見ると、キーワードは三つにまとまる。harness、eval、そしてcontainmentである。contextをうまく満たし、空ける方法から一段上がり、agentというシステム全体を設計し、測定し、統制する方向へ議論が移っている、と読める。（もちろん、これは一社の重点にすぎないという限界がある。ただし、同社がcoding agentのエコシステムで占める位置を考えれば、単一vendorの関心事として片づけるのも難しい。）

一つずつ見ていこう。

harness

harnessという言葉は少し馴染みが薄いかもしれない。直訳すれば馬具、つまり馬に装着して力を望む方向へ引き出す装置である。AI agentにおけるharnessは、modelの外側でmodelを囲み、仕事をさせる骨格全体を指す。どのtoolをどの順番で使えるようにするか、一度失敗したらどう復旧するか、権限をどこまで与えるか、loopをいつ止めるか、といったものだ。

context engineeringが「modelに何を見せるか」という問題なら、harness設計は「modelをその中でどう動かすか」という問題だ。一つ外側の層にある。modelを優秀な新人にたとえるなら、contextは新人に渡す業務資料、harnessは新人が働く作業環境と手順書に近い。同じ人でも環境が乱雑なら成果は不安定になり、整った手順の上では同じ能力でさらに遠くまで進める。

その重要性は、Anthropicのエンジニアリングチームが実際に直面した失敗にはっきり表れている。彼らは最上位のコーディングモデルであるOpus 4.5をClaude Agent SDK上に載せ、「claude.aiのクローンを作って」といった高レベルな指示だけを与えて複数セッションを動かしたが、モデル自体が賢くても本番運用レベルのアプリにはならなかった。失敗は二つの形で繰り返された。一つは、一度にすべてを終わらせようとして実装途中でcontextを使い切り、次のセッションに作りかけの機能を引き継がせるケース。もう一つは、後から入ったセッションが「すでにかなり進んでいる」と判断し、残る仕事を放置して完了を宣言するケースだ。（長い仕事を複数人が交代勤務でつなぐのに、交代者が前任者の記憶をまったく持たない状況を想像すればよい。）

解決策はモデルをさらに賢くすることではなく、骨格を変えることだった。最初のセッションには環境構築専用のprompt（initializer agent）を与え、200を超える機能仕様をfeature_list.jsonに展開させ、開発サーバーを立ち上げるinit.shと進捗ログ（claude-progress.txt）を作らせた。それ以降のセッション（coding agent）は毎回ちょうど一つの機能だけを処理し、git commitと進捗メモで整理された状態を残して終了する。次のセッションはまずその進捗ファイルとgit logを読み、「前の担当者がどこまで進めたか」を把握してから引き継ぐ。同じモデルでも、この骨格に載せると結果が変わった。成否を分けたのはモデルではなくharnessだったということだ。（興味深いことに、Anthropicの処方は新しいものではない。機能一覧、小さな単位のcommit、進捗メモ、毎回実行するsmoke testは、熟練した開発者が日々行っていることそのものだ。agentにとって良い骨格とは、結局、良いエンジニアリングの習慣を環境に埋め込むことに近い。）

この流れがtoken節約の議論と接する点も明確だ。前の記事で扱ったsubagent隔離、tool定義のdiet、model routingは、個別に見れば別々の節約手法だが、まとめれば結局、一つのharnessをどう設計するかの一部である。どの作業をどのmodel laneへ送り、どのtoolだけを有効にし、verboseな探索をどこへ隔離するかを決める全体がharness設計だ。節約はその設計の副産物に近い。

しかしharness設計には奇妙な罠がある。よくできた骨格ほど、modelが改善すると古くなることだ。harnessは本質的に「modelが単独ではできないこと」についての仮定の集合であり、modelがそれを自力で行えるようになった瞬間、その仮定は余計なものになる。Anthropicが示す事例がまさにそうだ。Sonnet 4.5にはcontext上限が近づくと作業を急いで終わらせる癖（context anxiety）があり、骨格にcontext reset機構を入れて対応した。ところが同じ骨格をOpus 4.5に載せると、その癖自体が消えており、苦労して加えたresetは重荷になった。modelが一段賢くなるたびに、骨格の一部はこうして期限切れになる。

そこで、さらに一歩進んだ発想が現れる。特定の骨格を巧みに作るのではなく、骨格が変わっても揺らがないインターフェースを設計することだ。AnthropicのManaged Agentsはこの方向にあり、その着想の源は意外にもオペレーティングシステムである。OSが数十年も存続したのは、ハードウェアをプロセスやファイルといった抽象へ仮想化し、まだ存在しないプログラムまで収める器を先に作ったからだ。read()の一行は、1970年代のディスクでも現代のSSDでも同じように動く。同じ発想でagentを三つに分ける。判断する頭脳（Claudeとharness）、実際に手を動かす手（code execution sandbox・ツール）、そして起きたすべてを追記するセッションログだ。三つを分離すればコンテナが落ちても頭脳はtool call errorとして処理でき、harnessが落ちてもセッションログの最後の地点から再び立ち上がれる。副次的にコストとレイテンシも下がった。コンテナを本当に必要なときだけ起動することで、time to first token（TTFT）は中央値で約60%、p95で90%以上低下したと報告されている。（ここでtoken節約の記事と再びつながる。前の記事ではprompt cachingのため静的な部分を先頭に集めるよう勧めたが、「cache hit率を高めるためにcontextをどう配置するか」は、まさにこの頭脳のそばのharnessが担う仕事である。）

eval

二つ目の流れは、個人的に最も興味深かった。2026年初頭の記事は、申し合わせたかのように評価（eval）へ集まっている。

理由を考えると自然だ。contextを適切に構成したのか、harnessをうまく設計したのか、本当にcostを削減できたのかを、何で確認するのか？ agentが長く複雑な仕事を自律的に処理するほど、「結局、これはうまく動いたのか」を人が一つずつ目で確かめるのは難しくなる。最終的に信頼の根拠は測定へ移る。だからこそ「agent評価をどう設計するか」「評価自体のnoiseをどう除くか」「modelが評価に気づいて行動を変えるeval awarenessをどう扱うか」といったテーマが前面に出てきた。

agentの評価が難しいのは、一回限りの質疑応答とは性質が違うからだ。agentは複数turnにわたりtoolを呼び、stateを変えながら進むため、一度の失敗が後方へ伝播し、蓄積する。さらに同じ入力でも実行ごとに結果が揺れる。Anthropicはこの非決定性を二つの指標に分ける。pass@kはk回の試行中に一度でも成功する確率なので、試行を増やすほど上がる。pass^kはk回すべてに成功する確率なので、試行を増やすほど下がる。一度だけ正解すればよいcode生成ではpass@1が重要で、毎回安定して動く必要があるcustomer support agentではpass^kが核心となる。（per-trial成功率が75%なら、三回連続で成功する確率は0.75³、約42%まで急落する。「だいたいうまくいく」と「毎回うまくいく」の隔たりはこれほど大きい。）

では、一度の試行を何で採点するのか。同じ記事はgraderを三種類に分ける。code-based（testの合否、static analysis、tool call検証）は速く、安く、客観的だが、正解が複数あるopen-endedな課題には弱い。model-based（LLM-as-judge、rubric採点）は微妙な品質まで捉えられるが、非決定的なので人の採点と定期的に較正する必要がある。human-basedは最も正確だが、遅く高価だ。実務では三つを組み合わせ、可能なら決定論的な採点を土台にし、model採点で補助する。もう一つ区別がある。capability evalは「このagentは何を成し遂げられるか」を問うため、低いscoreから始めて登る余地を与える。regression evalは「以前できたことが今もできるか」を問うため、ほぼ100%を維持しなければならない。scoreが下がれば、どこかが壊れた合図だ。

ここには意外に見落とされやすい罠がある。scoreが低い原因はagentではなく評価側かもしれない。 Anthropicの報告では、Opus 4.5がCORE-Benchで最初に42%を記録したが、調べると「96.124991…」を期待して「96.12」を誤答扱いする硬直した採点、曖昧な問題仕様、再現不能な確率的課題が原因だった。bugを修正し、制約を緩めたscaffoldで再実行するとscoreは95%へ跳ね上がった。そこで彼らは一つの原則を強調する。scoreを額面どおりに信じず、transcript（実行記録）を自分で読め。 frontier modelが100回試して0%なら、たいていmodelが無能なのではなく問題が壊れている。

測定が進歩すると基準線そのものが急速に動く点も興味深い。代表的なコーディングエージェントのベンチマークであるSWE-bench Verified（実際のGitHubの課題を与え、テストの合否で採点する）で、最先端モデルのスコアは1年で30%台から80%以上へ上がった。この段階では簡単な問題がすべて解かれ、スコアが天井（飽和）に達し、大きな能力向上が小さなスコア差としてしか見えない逆説が生じる。実際、あるコードレビュースタートアップは当初、単発の評価だけを見て新モデルに冷淡だったが、より長く複雑な仕事を測るエージェント型評価へ切り替えて初めて改善を正しく認識したという。したがって評価は一度作って終わりではなく、より難しいものへ更新し続ける生きた資産となる。（Anthropicはこれを安全工学の「スイスチーズモデル」にたとえる。穴の開いたチーズ一枚では防げないが、自動評価、プロダクション監視、人による実行記録レビューを重ねれば、一層を抜けた失敗が次の層で捕まる。）

containment

三つ目は少し性質が違う。costやperformanceではなく、安全と統制の問題だ。

agentがより多くのtoolを持ち、より自律的に動くほど、一度の失敗が及ぼす範囲（blast radius）も広がる。fileを削除し、外部へrequestを送り、権限のある操作を代行するagentなら、「どれほど上手にできるか」と同じくらい「誤ったとき被害をどこで止めるか」が重要だ。2026年5月にAnthropicが製品全体のcontainmentを扱った記事を前面に出したことも、この文脈で読める。同記事はagentのriskを三つに分ける。悪意または不注意から有害なことを命じるuser misuse、誰にも指示されていない行動をmodelが自ら行うmodel misbehavior、tool・file・networkを通じて外部から入るexternal attackだ。興味深い指摘は、modelが賢くなればriskが単純に減るわけではないことだ。能力の低いmodelは状況を誤読して明白な失敗をするが、能力の高いmodelは失敗が減る一方、誰も明記していない制約を回避する予想外の経路を、より巧みに見つける。

彼らが強調する核心は、「人が毎回監督する方式」の限界である。Claude Codeは当初、書き込み・実行・network accessのたびにuserへ承認を求めて安全を確保したが、telemetryではuserが承認要求の約93%をそのまま許可していた。承認画面が増えるほど一つひとつへの注意が薄れるapproval fatigueが起きたのだ。人のclickに頼る確率的防御には、結局穴が残る。そこで重心は「agentが何をしているか監視する」から「agentがそもそも何をできるか制限する」へ移る。防御は三層に重ねる。sandbox・VM・egress controlなどのenvironment layer、system prompt・classifierなどのmodel layer、MCP・plugin・検索結果などのexternal content layerだ。中心原則は、決定論的に阻止するenvironment layerを最初に敷くことにある。model layerの防御が弱いからではない。実際、prompt injectionを試すGray Swan benchmarkではone-shot攻撃の成功率は約0.1%と最高水準だ。ただし100回適応的に攻撃すると5〜6%まで上がり、確率的防御は本質的に命中率100%にはなれない。だから最後にぶつかる硬い境界を置く。（OS-level sandboxを導入すると承認画面が84%減ったという。安全装置がむしろ摩擦を減らしたわけだ。）

token節約とは遠く見えるが、実は同じ根を持つ。どちらも「エージェントに何を、どこまで持たせるか」という問題だ。Anthropicは二つの事例でこの関係を示す。一つは社内レッドチームが社員をフィッシングし、悪意あるプロンプトでClaude Codeを実行させた事例だ。ひそかに差し込んだ指示は~/.aws/credentialsを読み、外部へPOSTさせ、25回中24回成功した。ユーザーが直接入力した指示だったためモデルの分類器には不審な点がなかった。防いだのは賢いモデルではなく、認証情報を最初からサンドボックス外に置く環境境界と外向き通信の制御だった。もう一つはより微妙だ。egress許可リストはapi.anthropic.comを正常に通したが、攻撃者が仕込んだファイルが攻撃者自身のAPIキーでAnthropicのファイルアップロードAPIを呼び、データが攻撃者のアカウントへ流出した。サンドボックスは完全に動作したのにデータは漏れた。許可リストを「宛先フィルター」ではなく、「そのドメインで可能なすべての機能を許可する権限」と見るべきだったという教訓だ。（Anthropicが繰り返し強調する原則はこれである。検証済みのハイパーバイザー、システムコールフィルター、コンテナランタイムは正常に耐え、実際に壊れたのは、その上に自分たちが作った部品だった。）使わないMCPツールを外すことも同じ文脈にある。コストを節約すると同時に攻撃対象領域を減らす。軽量に保つ設計は安く正確なだけでなく、より安全でもある。

まとめると

三つの流れを一文に縮めるとこうなる。関心の単位は、prompt（一度の指示）からcontext（各turnで見せるもの）へ、さらにagent system全体（どう動かし、どう測り、どう閉じ込めるか）へ一段ずつ外側に広がっている。harnessは「どう動かすか」、evalは「うまく動いたとどう知るか」、containmentは「誤って動いたときどう止めるか」にそれぞれ対応する。

もう一度念を押すと、この三つは筆者がすでに公開された資料から読み取った重心の移動であり、「2026年後半にはこれが標準になる」といった予言ではない。ある流れはさらに大きくなり、別の流れは違う名前に吸収されるだろう。ただ確かなのは、promptもcontextも消えず、より大きな枠組みの一部として残ることだ。新しい言葉が古い言葉を消すのではなく、その上に一層を積むように分野は動いてきたし、今後もそうなる可能性が高い。

costの話から始めて、ここまで来た。前の記事ではtokenの家計簿を開くことを勧めたが、この記事の提案は一歩先へ進む。節約したcostを何で確認するか（eval）、その節約をどんな骨格の上で再現可能にするか（harness）、その骨格がどこまで安全か（containment）を一緒に見てほしい。結局、最も長く残るのは特定の節約手法ではなく、自分のシステムを測定し、統制する習慣だと思う。

この記事は2026年6月に書いた振り返りを書き直したものだ。最初の記事が掲げた「7つのピッカーを1つのAPIで、競合ライブラリのカレンダー1つより小さく」は、改めて確かめてみると半分は誤りで、半分は差別化要因ではなかった。そこで、作った理由、既存の選択肢との違い、技術的な定義の順に整理し直す。

結論から言うと、Kalyxの違いはコンポーネントの数ではなく 値モデル にある。基準バージョンは @kalyx/react 1.4.7と @kalyx/core 1.4.8（MIT、React 19専用）で、コードの引用はGitHubリポジトリの2026-09-16時点の main（0bb302e）に基づく。

日付ピッカーを宣言的に使いたかった

作った理由は2つあった。複雑で使いにくい日付ライブラリをもっと宣言的かつシンプルに使いたかったこと、そしてそうしたライブラリが内部でどう作られているのかを学びたかったことだ。「使いにくい」という言葉は漠然としているので、筆者が引っかかった箇所が今の最新バージョンにも残っているかを、各ライブラリの型定義で改めて確認した。

モードをpropでオンにするAPI

react-datepickerは、時刻選択を showTimeSelect、月選択を showMonthYearPicker、年選択を showYearPicker、範囲選択を selectsRange でオンにする。1つのコンポーネントがpropの組み合わせによって別物になる構造だ。そのコストは型に表れる。9.1.0の型定義では、selectsRange の値によって onChange のシグネチャが分岐する。

// react-datepicker/dist/index.d.ts (발췌)
    selectsRange?: true;
    selectsMultiple?: false | undefined;
    formatMultipleDates?: never;
    onChange?: (date: [Date | null, Date | null], event?: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>) => void;

よくできたunionだが、モードが増えるほど分岐は掛け算で増え、使う側はprop名だけを見て今どの組み合わせなのかを思い浮かべなければならない。（筆者が抽象化の記事で扱った「誤ってまとめた抽象化は結合度を高める」と同じ形だ）筆者は「入力欄とポップオーバーとカレンダー」がJSXの構造そのものから読み取れることを望んだ。

値の型とタイムゾーンが漏れる場所

react-datepickerとreact-day-pickerはネイティブの Date をやり取りする。どちらにもIANAタイムゾーンを受け取る timeZone propはあるにはある。react-datepickerはoptional peerとして date-fns-tz を要求し、react-day-pickerのものは実験的機能だが、どちらにしても値の型は依然として Date だ。Date は実行環境のローカルタイムゾーンで解釈されるため、ソウルで new Date(2026, 3, 15) の toISOString() は 2026-04-14T15:00:00.000Z になる。4月15日を選んだのに、サーバーには14日に見える問題だ。react-datepickerの"Date Selected is One Day Off" issueは2017年9月に開かれ、2025年12月に閉じられた。

反対側のArk UIとReact Ariaは、@internationalized/date の CalendarDate、ZonedDateTime オブジェクトを使う。意味は正確だが、フォームの状態とサーバーのレスポンスがすべて文字列のアプリでは、境界ごとに変換コードが生まれる。

タイムゾーン対応が日付ライブラリの選択に縛られることもある。MUI X Date Pickers 9.13.0のアダプターコードを見ると、dayjs、Luxon、Momentのアダプターは isTimezoneCompatible = true、date-fns系は false だ。date-fnsを使うアプリが timezone propを使うには、日付ライブラリをもう1つ導入しなければならない。

モードはpropの組み合わせに、値は解釈が実行環境に左右される Date に、タイムゾーン対応は日付ライブラリの選択に散らばっている。1つの宣言で意図を書き表すのが難しかった。

作りながら学ぶ

日付ピッカーは小さく見えるが、カレンダー計算、ロケール、タイムゾーンとDST、キーボード操作、SSRがすべて詰まっている。そこで、使う側ではJSXを見るだけで何を作っているのかが読み取れるように、作る側では値がどこで変換されるのかを説明できるくらいに絞り込むことを目標にした。

では、こうした要求をすでに解決しているライブラリは本当になかったのだろうか。

既存の選択肢と何が違うのか

先に答えを言うと、ある。筆者はheadlessで複数のピッカーを備えたライブラリはないと思い込んで始めたが、改めて調べるとその前提は誤りだった。

各選択肢が選んだ値モデル

2026-09-16にnpmの最新版をインストールし、型定義と公式ドキュメントで確認した内容だ。サイズ列は後で説明する同じ方法で測った値だ。

react-day-pickerは公式ガイドで "DayPicker does not include a built-in time picker" と明言している。MUIのサイズは @mui/material とemotionを含む値なので、すでにMUIのアプリであれば増加分はずっと小さい。

headlessの完成形はすでにある

表で重要なのはArk UIとReact Ariaの行だ。Ark UIは DatePicker.Root のようなdot notationの合成APIで、単一・複数・範囲選択と月・年単位の選択を提供する。React AriaはAdobeによるアクセシビリティ重視の実装だ。だからKalyxの居場所は最初に考えていたより狭い。

headlessの完成形はすでにある。ただしArk UIとReact Ariaは値を @internationalized/date オブジェクトでやり取りし、時刻入力はセグメントフィールドで提供する。Kalyxは値をJSONにそのまま載るUTC時点の文字列に固定し、リストから選ぶTimePickerと月・年・週のピッカーを同じ合成APIに入れた。

とはいえ「値が文字列だから良い」は弱い主張だ。CalendarDate も toString() を一度呼べば文字列になる。差別化要因は形式ではなく、その文字列が常に実際の瞬間（時点）であり、カレンダーのマス（座標）と混ざらないという契約、そしてその契約を守るテスト にある。

バンドルサイズを同じ方法で測り直した

READMEバッジのバンドルサイズは、他のライブラリと比べられる量ではなかった。バッジの約19.5KBは @kalyx/react の dist ファイル1つで、このファイルは @kalyx/core、@kalyx/adapter-date-fns、@floating-ui/react を外部importとして残す。その数字を、依存関係込みの他ライブラリの数字の横に並べていたのだ。

そこで「利用側のアプリがimportを1行追加したとき、バンドルがどれだけ大きくなるか」ですべてを測り直した。

echo "import { DatePicker } from '@kalyx/react'; export default DatePicker;" > entry.jsx
npx esbuild entry.jsx --bundle --minify --format=esm --platform=browser \
  --external:react --external:react-dom --external:react/jsx-runtime | gzip -6 | wc -c

esbuild 0.28.2、2026-09-16の測定で、KBはバイト数を1024で割った値だ。react-datepickerはCSSを除いた。React Aria Componentsは、単一のDatePickerの組み立てに必要なexport 12個（DatePicker、DateInput、Calendar、Popover、Dialog など）と、範囲と時刻まで入れた14個（DateRangePicker、RangeCalendar、TimeField を含む）の2通りで測った。

同じ条件で正しい文は1つだ。DatePicker 1つ（18.9KB）は DayPicker（20.0KB）と同程度のサイズで、7種全部（25.6KB）はそれより大きい。（それすらDayPickerはカレンダーだけで、Kalyx DatePickerは入力欄とポップオーバーまで含む）サイズはimportの組み合わせとgzipレベルに敏感なので桁で読むのが妥当で、サイズはKalyxを選ぶ中心的な理由ではない。

Kalyxを技術的に定義すると

Kalyxは、すべての入出力をUTC時点の文字列に固定し、カレンダー座標と時点の間の変換を2つの関数だけに置き、その往復をランタイムが知るすべてのタイムゾーンについてプロパティテストで検査するheadlessなReact日付ピッカーだ。

使う側のAPIはこうだ。value と onChange は string | null で、displayTimezone はどのゾーンのカレンダーで見せるかを決める。

<DatePicker value={iso} onChange={setIso} displayTimezone="America/New_York">
  <DatePicker.Input />
  <DatePicker.Popover>
    <DatePicker.Calendar />
  </DatePicker.Popover>
</DatePicker>

値は時点、カレンダーのマスは座標

Kalyxの中には、形式が同じ2種類のISO文字列が流れている。座標 はカレンダーグリッドの1マスで、YYYY-MM-DDT00:00:00.000Z と書くがタイムゾーンの概念を持たない。グリッド計算はUTCだけで回るので、実行環境に依存しない。時点 は onChange から出ていく値で、displayTimezone におけるその日の0時という実際の瞬間だ。同じ1月15日が、ニューヨークでは 2026-01-15T05:00:00.000Z、ソウルでは 2026-01-14T15:00:00.000Z になる。

両者をつなぐ関数は @kalyx/core の2つだけだ。座標を時点に変える civilMidnightFromUtcDay と、その逆の calendarDayFromInstant だ。後者は「その時点はこのゾーンで何日か」を読み取り、UTC 0時の座標として書き直す。

// packages/core/src/utils/timezone.ts:187-190
export function calendarDayFromInstant(iso: ISODateString, timeZone: string): ISODateString {
  const p = partsInTimezone(new Date(iso), timeZone);
  return new Date(Date.UTC(p.year, p.month - 1, p.day)).toISOString();
}

ルールは方向だ。マスを選んで値をコミットするときは座標を時点に、保存値から表示する月とフォーカスを決めるときは時点を座標に変える。DatePicker Rootの selectDate は変換し、変換した時点で制約を検査し、通ればコミットする。

// packages/react/src/components/DatePicker/Root.tsx:182-194
const normalized =
  coordinate && displayTimezone
    ? civilMidnightFromUtcDay(coordinate, displayTimezone)
    : coordinate;
 
if (normalized && isDateDisabled(normalized, disabledRules, adapter, displayTimezone)) {
  return;
}
 
if (!isControlled) {
  setUncontrolledValue(normalized);
}
onChange?.(normalized);

呼び出し箇所はここだけではない。packages/react/src を検索すると、2つの関数はDatePicker、RangePicker、DateTimePickerのRootとCalendar、Presets、キーボード移動のユーティリティ、headlessフック6つに散らばっている。それでも日付のマスをコミットしたりビューを決めたりする経路はすべて2つのどちらかを通る。時刻のコミットは setTimeInTimezone が担うが、内部では同じ内部関数 resolveCivilDateTime で変換する。

この契約はプロパティベーステスト（property-based test）で守る。すべての座標 c とゾーン z について calendarDayFromInstant(civilMidnightFromUtcDay(c, z), z) === c でなければならない。

// packages/core/src/__tests__/timezone.property.test.ts:86-94
it('round-trips every UTC calendar coordinate through civil midnight', () => {
  fc.assert(
    fc.property(utcCalendarCoordinate(), zone(), (coordinate, timeZone) => {
      const instant = civilMidnightFromUtcDay(coordinate, timeZone);
      expect(calendarDayFromInstant(instant, timeZone)).toBe(coordinate);
    }),
    RUNS,
  );
});

fast-check が2020年から2045年の間の日付をランダムに生成し、+5:45のKathmandu、+14のKiritimati、-11のNiueなど代表的なゾーン14個と組み合わせて300回回す。すぐ次のテストは、同じ往復を Intl.supportedValuesOf('timeZone') が返すゾーンすべてについて、ゾーンごとに12回ずつ検査する。筆者のローカルのNode 24.16では、そのリストは418個だ。1.4.8では、DSTの切り替えごとに境界時刻の変換結果をTemporal実装と照合する全数テストが加わった。

では、ユーザーが渡した "2026-01-15T00:00:00.000Z" をライブラリが自動で時点に正規化すればよいのではないか。文字列だけでは座標なのか時点なのか分からないので、この道は塞がっている。すでに時点であるソウルの値 2026-01-14T15:00:00.000Z に civilMidnightFromUtcDay をもう一度かけると 2026-01-13T15:00:00.000Z になり、ソウルのようにオフセットが正のゾーンではレンダーのたびに1日ずつずれ続ける。（ニューヨークの値はもう一度かけても変わらない）何度適用しても結果が同じ startOfDayInTimezone に替えればずれは起きないが、座標を時点に変えるという本来の仕事ができない。

そこで正規化を諦め、契約をドキュメントで固定した。利用者はピッカーが出力した値をそのまま渡さなければならない。正直に言えば利用者に押しつけたコストで、ISODateString が string のエイリアスなのでコンパイラも防いでくれない。

IntlだけでDSTを解く方法

座標を時点に変えるには「そのゾーンのその日の00:00」がUTCでいつなのかを知る必要があるが、オフセットは時点が分からないと求められない。しかもDSTの切り替え日には、現地時刻が存在しなかったり（spring forward）、2回存在したり（fall back）する。

Kalyxは date-fns-tz のようなライブラリなしでこれを解く。Intl.DateTimeFormat(...).formatToParts で「このUTCの瞬間はそのゾーンで何時か」を尋ねてオフセットを測り、そのオフセットを要求時刻の1日前と1日後の2地点で読む。

// packages/core/src/utils/timezone.ts:251-254, 259
const candidate = (probeEpoch: number) =>
  civilEpoch - getTimezoneOffsetMinutes(new Date(probeEpoch).toISOString(), timeZone) * 60_000;
const epochBefore = candidate(civilEpoch - 86_400_000);
const epochAfter = candidate(civilEpoch + 86_400_000);
 
if (epochBefore === epochAfter) return new Date(epochBefore).toISOString();

civilEpoch は、求める現地時刻をUTCであるかのように読んだ値だ。オフセットは±14時間以内なので、1日前と1日後は近くの切り替えの前と後のオフセットを1つずつ与える。2つが同じなら切り替えはないので formatToParts 2回で終わり、グリッドの42マスごとに1回ずつ呼ばれるこの高速パスがコストを決める。（48時間以内に切り替えは1つという前提は、2020〜2045年のすべてのゾーンで成り立つ）

2つが違えば、2つの候補をそのゾーンで読み直し、要求した時刻と合うかを見る（timezone.ts:261-279）。fall backの重なりでは両方が合うので切り替え前のオフセットで作った早い方を選び、spring forwardの隙間ではどちらも合わないので同じ側を選んで隙間の長さだけ時刻を進める。実際に動かした結果はこうだ。

「隙間では時刻を進め、曖昧なら早い方を取る」は、MDNのTemporal.ZonedDateTimeドキュメントが説明する disambiguation のデフォルト値 "compatible" と同じだ。1.4.7のLondonの行がずれた理由は後で扱う。

アダプター境界は文字列メソッド21個

タイムゾーンをcoreが計算するなら、date-fnsやdayjsは何を担うのか。日付の演算とパースだ。その境界である DateAdapter はメソッド21個で、日付の引数と戻り値はすべてISO文字列だ。

// packages/core/src/types.ts:71-102 (발췌)
export interface DateAdapter {
  parse(value: string, format?: string): string;
  format(iso: string, formatStr: string, timezone?: string): string;
  addDays(iso: string, n: number): string;
  isSameDay(a: string, b: string, timezone?: string): boolean;
  startOfDay(iso: string, timezone?: string): string;
  today(timezone?: string): string;
  // addMonths, isBefore, startOfMonth, getYear 등 15개
}

タイムゾーンを受け取るメソッドは format、isSameDay、startOfDay、today の4つで、その4つも計算はcoreに任せる。date-fnsアダプターの format は、timezone があればcoreの formatInTimezone を直接呼ぶ（packages/adapter-date-fns/src/index.ts:112-115）。だからどのアダプターを使ってもタイムゾーンの答えは同じコードから出てくるし、3つのアダプター（date-fns、dayjs、luxon）は @kalyx/core/test-helpers の runAdapterConformanceTests をそれぞれ回して同じ答えを出すか確認する。

2つのエントリーもこの境界で分かれる。デフォルトエントリーの @kalyx/react はモジュール読み込み時に setDefaultAdapter(DateFnsAdapter) を呼ぶので、インストールしてすぐ動く（packages/react/src/index.ts:9-11）。@kalyx/react/headless にはこの呼び出しがなくバンドルも分かれているので、date-fnsのコードは入らない。

この境界の形には代償があった。筆者は2026年6月にTemporalアダプターを畳んだ。Temporalの価値は PlainDate、ZonedDateTime のように 型が意味を持ち運ぶこと にあるが、境界が文字列ではその意味が通り抜けられない。包んでも文字列に平坦化されるだけで、正確性の利得はないと判断した。振り返ると、前の節の「座標と時点が同じ string」という問題は、Temporalが PlainDate と Instant で型によって解くまさにその問題だ。文字列の境界はアダプターの交換を容易にした代わりに、型で解く道を塞いだことになる。

7つのピッカーは3つのコンテキストの組み合わせ

Kalyxのピッカーは、DatePicker、RangePicker、TimePicker、DateTimePicker、MonthPicker、YearPicker、WeekPickerの7種だ。重要なのは数よりも、7つが独立した実装ではないという点 だ。コンテキストは DatePickerContext、RangePickerContext、TimePickerContext の3つだけだ。

MonthPickerのRootは、表示形式のデフォルト値を yyyy-MM に変え、DatePickerのRoot実装に selectionGranularity="month" を渡すだけだ（MonthPicker/Root.tsx:11-20）。DatePickerの selectDate は、granularityが month なら座標をその月の1日に畳んだうえで、先に見た変換と制約検査をそのまま通る。DateTimePickerは2つのコンテキストを重ねて提供する。

// packages/react/src/components/DateTimePicker/Root.tsx:401-402
<DatePickerContext.Provider value={dateContext}>
  <TimePickerContext.Provider value={timeContext}>{children}</TimePickerContext.Provider>

だから DateTimePicker.Calendar は DatePicker.Calendar と同じコンポーネントで、自分がどのピッカーの中にいるのかを知らない。1か所の修正が同じコンポーネントを使うピッカー全部に届き、1か所の欠陥も全部に届く。先の図でDatePicker 1つが全体の74%だった理由も、この共有基盤だ。

契約を守るためにかかったコスト

1.0以降の3か月は新機能よりもこの契約の確認に使い、例示ベースのテストなら素通りしていたはずの欠陥が3回出てきた。1つ目はプロパティテストが、2つ目はコードのクロスレビューが、3つ目はこの記事の検証が見つけた。

Sydneyの10月1日の1時間

1つ目は、「startOfDayInTimezone の結果をそのゾーンで読むと00:00:00になる」というプロパティがAustralia/Sydneyで壊れたことだ。当時の実装はオフセットを1回しか測っていなかった。Sydneyは2034年10月1日02:00に+10から+11へ切り替わるが、その日の00:00はまだ+10なので、正解は 2034-09-30T14:00:00.000Z だ。ところが「10月1日00:00をUTCとして読んだ地点」は切り替え後なので+11を返し、結果は前日の23:00になった。この反例は回帰テストとして残っている（timezone.property.test.ts:276）。

ソウルでだけ通っていたテスト

2つ目は2026年8月3日のクロスレビューで出てきた。カレンダーで選択表示するマスを決めるコードが、変換を2回していた。マスはすでに座標なのに、マスと保存値の両方をそのゾーンの日付に変換していたのだ。「1月15日」を選んだ結果はこうだった。

正のオフセットのゾーンでは2回のずれが相殺されて偶然正しく、既存のテストはソウルしかカバーしていなかった。同じ点検で逆方向の違反も出てきた。表示する月を決めるときに時点へ startOfMonth を直接かけていたため、ソウルで1月1日を値として渡すと12月のカレンダーが開いた。

仕組みは違っても、破ったルールは1つだ。変換は方向ごとに決まった関数で1回だけ行う。

この事故で、coreの往復プロパティテストは「代表的なゾーンいくつか」から「ランタイムが知るゾーンすべて」に広がった。（React側のコンポーネントテストは、まだ America/New_York のような代表ゾーンを使っている）符号が変わる場所でだけ現れる欠陥は、サンプルでは捕まらない。

Londonで遅い方に解決されていた01:30

3つ目は、この記事のDSTの表を他のゾーンに広げる途中で出てきた。1.4.7は要求時刻をUTCとして読んだ地点からオフセットを測っていたが、切り替え後のオフセットが0以上のゾーンではその地点がすでに切り替え後なので、遅いオフセットに収束した。temporal-polyfillで418ゾーンの2020〜2045年の切り替えを全数照合すると、重なりの切り替え3,395件のうち1,908件で遅い方を選んでおり、84ゾーンにまたがっていた。（隙間の切り替え3,394件はすべて正しく、オフセットが負のニューヨークは偶然正しかった）

#226で1日前と1日後を読むように直して @kalyx/core 1.4.8としてリリースし、同じ照合を timezone.dst-oracle.test.ts として残した。（temporal-polyfillはテストでだけ使う）'earlier' と誤って書いていたソースコメントも 'compatible' に直した。今回も サンプルが片方の符号に偏っていた。

正確性に使った3KB

これらの修正にはコードが要った。KalyxはデフォルトエントリーのバンドルにCIの上限を設けており、超えるPRは必須チェックで失敗する。12KBから始まり機能が入るたびに1KBずつ上げていたその上限を、2026年8月にタイムゾーンと制約の正確性を全面的に修正する際、17KBから20KBへ一気に引き上げた。

サイズはREADMEバッジに載せていたセールスポイントだった。負のオフセットのゾーンで1日ずつずれる日付ピッカーは、小さかろうが大きかろうが使えない。

小さいと正しいのどちらかを選ばなければならないなら、正しい方だ。今の上限はぎりぎりだ。リポジトリの2026-09-11のバンドルバイトマップ文書によれば、dist/index.cjs をNodeのデフォルトgzipで測った値は20,259B、上限は20,480Bで、余裕は221Bだ。（依存関係を外部に残した自前ファイルのサイズなので、先の図とは別の量だ）次の機能は、まずバイトを回収しなければ入れられない。

最初の想定とは違う結論

筆者が望んだのは、複雑な日付ライブラリを宣言的に使うことだった。作ってみると、宣言的な合成APIもheadlessの完成形もすでにあった。残った違いはもっと内側にあった。値を1つの時点に固定し、座標と時点の間の変換を2つの関数に絞り、その往復をすべてのタイムゾーンでテストによって守ること。 IntlベースのDST処理、文字列のアダプター境界、3つのコンテキストで作った7つのピッカーは、その決定の結果だ。

学ぶという目標から見ると、一番大きく学んだのは「正しい」と主張する方法だった。最初の記事のバンドル比較は違う量を測っていたし、ソウルで通っていたテストはニューヨークで間違っていた。何を測り、どんなサンプルで確かめたのかを一緒に書かなければ、数字は簡単に自慢になる。

限界もはっきりしている。メンテナーは筆者1人で、React 19専用であり、@kalyx/react のnpmダウンロードは2026年9月5日から11日までで200回、そのうち156回が1.4.7のリリース日1日に集中している。座標と時点を型で区別できない問題はドキュメントだけで防いでおり、スタイルの接点である classNames と data-* 属性を公開APIとして保証するかどうかも決められていない。アクセシビリティは、カレンダーの grid、入力欄の combobox、時刻リストの listbox ロールと、矢印キー、Home/End、PageUp/PageDownの操作を備え、テストファイル8個の jest-axe 検査をCIで回しているが、React Ariaと同じくらい検証されていると言える根拠はまだない。

なので、すでにMUIのアプリならMUI Xを、セグメント入力と検証済みのアクセシビリティが優先ならReact Ariaを、カレンダー1つで足りるならreact-day-pickerを先に見るのが妥当だ。値がJSONで行き来するフォームで日付が1日ずつずれる問題を経験したことがあるなら、そのときにKalyxを覗いてもらえると嬉しいし、もっと良い解き方を知っているならGitHub Issueで教えてもらえるとありがたい。

pnpm add @kalyx/react

ドキュメントサイトのPlaygroundで、7つのピッカーとlocale、timezoneの設定を実際に変えて試せる。

以前は性能やコストよりも、結果とプロセスに意識を向けていた。AIの成果物には穴が多く検証が欠かせなかったうえ、早く結果を出したい一心で、筆者を含む多くの人がトークン不足のたびに追加料金を払い、より上位のプランを使っていた。筆者も同じだった。（実のところ、最初の数か月はトークンにいくらかかっているかさえ気にしていなかった。）

ところが、しばらくするとトークン使用量への警戒心が次第に強くなった。個人にとって月額料金は重く、企業にとっては人件費と運用費が深刻な課題になった。MCPとfunction callingではエージェントを外部システムにつなぐプロトコルを、コードインテリジェンスの4つの階層ではコード探索ツールとGitHub Trendingを、コンテキストファイルではエージェントが読むルールファイルをまとめた。このように、これまでの記事はどのようなツールがあり、それをどう使いこなすかに重点を置いてきた。その視点は今も変わらないが、時間がたてば、結局もっとも知りたくなるのはコストの話だと思う。

トークンとは正確には何か、BPEでどう作られるか、prompt cachingが単価を下げるTransformer内部の仕組みは何かといった原理は、別の記事トークンの仕組みにまとめた。本稿ではその土台に立ち、料金がどう発生し、どこで無駄が生まれるのかを確認したうえで、実証済みの節約パターンを整理する。主なパターンには、同じ作業を複数の戦略で呼び出して直接測ったトークン使用量を添えた。

トークン費用はどのように発生するのか

まず、トークン費用が生まれ、請求される仕組みを要点だけ簡潔に見ていこう。

送信したすべてのテキスト（システムプロンプト、ツール定義、会話履歴、ユーザーメッセージ）が入力トークンとなり、モデルが生成した応答が出力トークンとなる。モデルにとって、呼び出しは毎回初めて見る入力だ。昨日の会話でも1分前の呼び出しでも、新しい呼び出しでは同じ内容を入力として丸ごと送り直す。（この単純な事実がトークン費用の核心だ。モデルに記憶はなく、こちらが毎回もう一度伝えている。）

ここにもう一つ変数が加わる。同じ呼び出しを繰り返すたび静的部分を送り直すのは高くつくため、主要なLLMプロバイダーはprompt cachingを導入した。静的な入力を一度キャッシュに保存し、次の呼び出しではキャッシュから読み出したトークンを大幅に安い価格で請求する仕組みだ。（BPEでトークンがどう作られ、TransformerのKV cacheを呼び出し間でどう再利用して単価を下げるかは「トークンの仕組み」で扱った。ここでは、その原理が費用にどう換算されるかに集中する。）

入力トークン、出力トークン、キャッシュトークン

Anthropic SDKが応答として返すusageオブジェクトの四つのフィールドを見てみよう。

• input_tokens 送信した入力のうち、キャッシュ読み出しを除く部分
• output_tokens モデルが生成した応答
• cache_creation_input_tokens 今回の呼び出しで初めてキャッシュに保存されたトークン
• cache_read_input_tokens 既存のキャッシュから再び読み出されたトークン

この四つには、それぞれ異なる単価が掛かる。もっとも高いのは出力トークンで、もっとも安いのはキャッシュから読み出したトークンだ。Anthropicの公式ドキュメントでは、キャッシュ読み出しは通常の入力単価の0.1倍、つまりちょうど10%である。キャッシュ書き込みは5分TTL（Time To Live、キャッシュ有効期間）で1.25倍、1時間TTLで2倍になる。初回に少し多く払い、2回目から90%引きになる構造だ。

ただし、キャッシュにはあまり知られていない制約もある。キャッシュ可能な最小トークン数はモデルごと、同じファミリーでもバージョンごとに異なる。Anthropicの公式文書によれば、Sonnet 4.6とOpus 4.8は1,024トークン、Opus 4.7は2,048トークン、Haiku 4.5と旧世代のOpus 4.5/4.6は4,096トークンだ。それより短いプロンプトはcache_controlを指定しても、何の通知もなくキャッシュされない。cache_controlのブレークポイントは1リクエストにつき最大4個で、キャッシュはtools → system → messagesの階層順に読み込まれる。そのため、前方のツール定義が一つ変わるだけで、それ以降のキャッシュ全体が無効になる。

キャッシュで単価を90%下げられるのは、TransformerのKV cacheを呼び出し間で再利用するからだ。その内部動作は「トークンの仕組み」で詳しく説明した。コスト面で覚えるべき要点は一つだけ。キャッシュヒットはプレフィックスが完全に一致したときにしか起こらないため、静的部分は前、毎回変わる動的部分は後ろに置かなければならない。プロンプトの前方にタイムスタンプが一文字入るだけでも、その後ろのキャッシュはすべて無効になる。

ここで自然な疑問が浮かぶ。「マルチターンの会話はターンごとに入力が変わる。ならば、ほぼ毎回キャッシュが壊れるのではないか」。結論から言えば、そうではない。会話の入力は毎回書き直す一塊ではなく、前に積み上がった内容をそのまま残し、末尾に新しい発話だけを追加する（append）構造だからだ。システムプロンプトとツール定義、過去の質問と回答は確定するとそのまま固定され、今回の新しい質問だけが最後に付く。現在の入力を前回の入力と先頭から比べれば、最初に異なる箇所は必ず末尾の新しい質問になる。入力全体は毎回違っても、プレフィックスの大半は同じなのでキャッシュは生き残る。（毎ターンキャッシュが壊れるのは、動的な値をプロンプト前方に埋め込む誤った設計の場合だ。Claude Codeやopencodeは前方を固定して末尾にだけ追加するよう設計されており、利用者がキャッシュのために触る設定もない。入力の誤字や表記揺れがキャッシュに影響しないのも同じ理由で、その変化は常にキャッシュ対象の外側にある末尾で起こる。）

AIの比較

2026年6月時点のAnthropic、OpenAI、Googleの公式料金を一つの表にまとめると、傾向がよく分かる。（単位は100万トークン当たりのUSD。コーディングワークフローで日常的に使うモデルを中心に選んだ。）

三社とも、出力単価は入力の5～6倍だ。つまり出力が長くなるほど、同じ答えでも費用は急増する。同じ価格帯内でもモデル間の単価差は3～6倍に広がる。単純な計算だけでも、出力を短くする、同じ答えなら安いモデルを使う、静的入力はキャッシュに載せるという三原則がコスト削減の柱だと分かる。（もう一度計算すると興味深い。呼び出しごとに1万トークンの静的コンテキストを100回再利用する場合、GPT-5.5の通常料金では$5、キャッシュ読み出しなら$0.50。つまり一つのコンテキストを100回再利用してキャッシュが実質的に削る額は$4.5で、初回の書き込み追加料金がほぼないため、2回目からすぐ黒字になる。）

キャッシュ機構の違い

削減率が似ていても、内部構造はプロバイダーごとに異なる。違いが生まれる理由を知っておけば、方針を決めやすい。

三社の設計思想がそのまま表れている。Anthropicはキャッシュ範囲を利用者が明示する代わりに、初回に少し上乗せ料金（1.25倍）を取り、その後は大幅に割り引く。プレフィックス位置を制御しやすく、キャッシュ読み出し率を予測できる。OpenAIは正反対で、すべてを自動化している。1,024トークン以上なら自動でキャッシュされ追加費用もないが、利用者が動作に介入できる余地は少ない。Googleは両方式を提供し、明示的に制御する場合は別途保存料を課す。短く頻繁な利用なら暗黙的キャッシュ、1時間以上保管する大きなコンテキストなら明示的キャッシュと保存料のモデルが向く。

ツール定義とトークナイザー

さらに、意外に大きく効く変数が二つある。

一つ目はツール定義だ。複数のMCPサーバーを接続した環境では、毎回の呼び出しにツール名とパラメータスキーマがすべて入力として含まれる（どれほど膨らむかは後で実測する）。同じツールを使っても、モデルを替えるだけで費用が変わる点にも注意したい。Anthropicの公式料金文書を見ると、ツール用システムプロンプトの長さ自体がモデルによって違う。Sonnet 4.6とHaiku 4.5はtool_choice: autoで約497トークン、Opus 4.7は675トークン、Opus 4.8は290トークンだ。model routingの前に「現在のモデルがツール定義をどれだけ長く展開するか」を確認すると、桁の大きな差に気づくことがある。

二つ目はトークナイザー（人が書いたテキストをモデルが処理できるトークン単位に細分化する道具）自体の効率だ。「トークンの仕組み」で触れたように、同じテキストでもトークナイザーによってトークン数は異なる。OpenAIのo200k_baseはcl100k_baseより非英語圏のテキストを大幅に節約できる。一方AnthropicはOpus 4.7から新しいトークナイザーへ移行し、同じテキストで最大35%多くトークンを使う可能性があると明記した。単価だけでモデルを選ぶと、トークナイザー効率の差から費用が漏れる。正しい比較は、単価×予想トークン数の積で行うべきだ。

実際に比べると、韓国語では特に差が大きい。OpenAIの二つのトークナイザーで同じ文をトークン化したところ、英語の技術文は旧版と新版で同じ数だったが、韓国語は旧版（cl100k_base）が新版（o200k_base）より31～43%多くのトークンを使った。とりわけ注目すべきは韓国語の段落だ。167文字の一段落が旧版では169トークンとなり、文字数よりトークン数の方が多い結果になった。韓国語一文字が平均で一トークン以上を消費したことになる。

旧版は韓国語をバイト単位で細かく分解する一方、新版は「개발」「입니다」のような頻出のまとまりを一つのトークンに束ねるからだ。単価が同じでも、韓国語中心の作業ならトークナイザー効率だけで請求額が1.5倍以上変わり得る。

ここまで来ると、自然に一つの疑問が生まれる。「では私たちは、いったいどこで無駄を生み出しているのだろうか」。

トークンを浪費する典型的なパターン

AIを使いこなしているつもりでも、トークンが非効率に流出する場面は意外に多い。筆者自身と周囲の開発者の行動を集めると、いくつかの型に整理できる。

多すぎるMCPサーバーとツール定義

前節でも触れたが、改めて強調したい。MCPサーバー（Linear、GitHub、Notion、Figma、Slack、Sentry）は一度接続すると外されにくい。使わないツールスキーマが毎回入力トークンを膨らませる。Claude Codeで既定有効のMCP Tool Searchはこの問題に対処するため、セッション開始時にはツール名とサーバー説明だけを載せ、全スキーマはそのツールを実際に呼び出した時点で初めて読み込む。

差がどれほど大きいか、直接測ってみた。作業中のClaude Code セッションにある27個のMCPツール（serena 10、claude.ai OAuth 4セット8、figma 2、agentmemory 7）を使い、同じユーザーメッセージを二つの設定で呼び出した。一方はMCPを一つも導入していない状態、もう一方は27個すべてが接続済みだがモデルからは呼び出せない状態とし、ツール呼び出し回数は両方とも0回にそろえた。

質問もモデルも回答の意味も同じなのに、入力トークンだけが41 → 10,335（+10,294）へ増えた（Opus 4.7）。1回当たりの費用は$0.0048 → $0.0563、約12倍である。入力が250倍に膨らみプリフィル負荷も増え、応答時間には783msが加わった。金額そのもの以上に実感したのは、利用者がそのターンでMCPツールを一度も使わなくても、毎回払う費用だという点だった。前段のTool Searchが防ぐのは、この費用である。（この測定以降、筆者は普段使わないMCPサーバーを継続的に整理している。）

コンテキストの蓄積とLost in the Middle

長い会話をそのまま引きずると、呼び出しごとの入力トークンが増えるだけでなく、モデルの正答率まで下がる。StanfordのLiu研究チームによる「Lost in the Middle」論文は、重要な情報がコンテキストの冒頭か末尾にあると最も見つけやすく、中央に埋もれると性能が目に見えて落ちるU字型曲線を定量的に示した。多くのトークンを使いながら答えは悪くなる、最悪の組み合わせだ。Transformerのself-アテンションはトークン数の二乗に比例して計算量が増えるため、コンテキストが長いほど各トークンが受けるアテンションの絶対量が薄まる。さらに学習分布では重要情報が冒頭と末尾に集まりやすかったため、中央から先に弱くなる。

もう少し内部に入ると、モデルがトークンの「位置」を扱う方法そのものに、中央を埋もれさせる二つの性質がある。難しく聞こえるが、比喩にすれば単純だ。

第一に、モデルは近くのトークンへより強く耳を傾ける。 現代の公開モデルの多くが採用する位置表現RoPE（Rotary Position Embedding、回転位置埋め込み）は、二つのトークンが離れるほど結び付きを弱めるよう設計されている（距離とともに信号が薄れるdecay effect）。そのため、遠いトークンほど自然に注目されにくい。

第二に、モデルは先頭トークンへ無駄に多くのアテンションを流す。 モデルには、自分のアテンションを常に100%使い切るよう配分しなければならない制約（softmaxがアテンション総和を1に固定する）がある。いま特に集中すべき場所がなくても、余ったアテンションをどこかへ捨てなければならず、その捨て場所は多くの場合、文頭の最初のトークンになる。このように最初のトークンが余剰アテンションを吸い込む現象をアテンションシンク（アテンションの排水口）と呼ぶ。（MITのXiao研究チームがStreamingLLM論文で初めて定量分析した。先頭に重要情報があるからではなく、余ったアテンションを流す排水口として使われる副産物に近い。）

この二つが重なるとアテンションは両端（近い直近トークン＋先頭トークン）へ偏り、中央の情報が最も弱く扱われる。重要なのは、これが特定モデルのバグではないことだ。LLaMA、Mistral、Qwenなど公開モデルの大半がRoPE系を使い、ClaudeやGPTなど非公開モデルも似た系統だと考えられているため、lost-in-the-middleは現代Transformerに共通する偏りに近い。

近年、この現象はcontext rotと呼ばれる。Chroma研究チームがGPT-4.1、Claude 4、Gemini 2.5、Qwen3を含む18のフロンティアモデルに同じNIAH（needle in a haystack、干し草の山から針を探す）課題を与えた分析では、入力が10kから100k以上に増えると、モデルによって正答率が20～50%まで低下した。18モデルすべてが長くなるほど性能を落とし、低下が最も緩やかだったのはClaude系だった。Anthropicも、Transformerのn²アテンションに由来する「アテンション予算」が各トークンで消費される問題だと説明する。コンテキストを軽く保つことは、コスト削減であると同時に正答率を守ることでもある。

無分別なsubagent呼び出し

subagentが便利だからと、すべての作業を委任するのも落とし穴だ。subagentは親と別のコンテキストで始まるため、システムプロンプトとツール定義を最初から積み直す固定費がかかる。短いシェルコマンドや単純なgit確認のような軽い作業を委任すると、本文を整理する効果より開始費用の方が大きくなる。Anthropicのmulti-agent research system公開報告によると、一般的なチャットと比べて単一エージェントは約4倍、multi-agent systemは約15倍のトークンを使う。4～15倍の追加費用に見合う正答率向上があるときだけ、委任に意味がある。

同じ罠はMCPツールの接続にも当てはまる。ツールを一つ有効にするたびスキーマが毎ターンのシステムプロンプトに載り、モデルが使わないターンでも同じ費用が請求される。「使うかもしれないから全部有効にしよう」は直感的には安全に見えるが、実測はそうではない。

筆者はfacebook/react v19のreconcilerソースについて、同じ質問群を次の三つに分け、正答率と費用を測った。

• ツールなし
• 単一ツール（CodeGraph、Serena、ripgrep、bare grep）
• 四つのツールを同時に接続

結果には三つの特徴がそのまま表れた。（ここで再現率は正解を漏らさずどれだけ見つけたかを意味する。）

• ツールなしは平均再現率 0.31にとどまり、ツール自体の価値は明確だった。
• Serena（LSP）のみは再現率 1.00、費用$0.38で、単独戦略の中でもっとも効率的だった。
• 四ツールをすべて接続すると、再現率は逆に0.89へ下がり、費用は$0.47へ増えた。とりわけマルチホップ質問では、全接続のスコアがCodeGraph単独（0.78 / 0.88）と小数第2位まで同じだった。モデルが四つのうち一つに偏り、その弱点をそのまま受けた結果だ。

subagentとツール接続に共通する原則は一つ。追加費用が正答率向上で正当化されるときにだけ意味がある。作業ドメインに合うツールを一つ正確に選ぶ方が、使うかもしれないと全部を有効にするより安く、正確だ。

では、実証済みの節約法とは何だろう。本当に節約する方法はあるのだろうか。

実証済みのトークン節約法

節約パターンはそれぞれ異なるコスト軸を攻める。入力を減らすもの、同じ入力の単価を下げるもの、同じ作業を安いモデルへ任せるものがある。一つずつ見ていこう。

Prompt caching

もっとも即効性が高い方法だ。先に見たとおり、キャッシュ読み出しは通常の入力単価の0.1倍である。初回に少し書き込み上乗せ料金（1.25倍）を払えば、2回目から同じ静的部分を10分の1の価格で再利用できる。

節約の観点から改めて強調したいのは一つだ。どの方式でも、呼び出しごとにほぼ同じ部分（ツール定義、コードスニペット、RAGコンテキスト）がキャッシュの対象であり、その静的ブロックを動的内容（今回の質問、直前のツール結果）と混ぜなければ効果は保たれる。APIを直接扱うなら、静的ブロックを前にまとめ、動的部分を後ろへ移すだけで節約の大半を実現できる。Claude Codeやopencodeのような完成品なら、ツールが配置を処理してくれる。

Batch APIで非同期作業をまとめる

呼び出しをすぐ完了させる必要がなければ、Batch APIは単価そのものを下げる最も単純な手段だ。Anthropic、OpenAI、Googleはいずれも入力・出力トークンを50%割り引き、その代わり結果は最大24時間以内に受け取る。Anthropicでは実測上ほとんどのバッチが1時間以内に完了するが、SLAは24時間という意味だ。同じ呼び出しのまま単価だけ半分になるので、導入コストもほぼない。

この50%が興味深いのは、ほかの節約策と乗算で重なる点だ。Anthropicの公式文書は、キャッシュとバッチの割引が互いに掛け合わされる（重ね掛け）と明記している。静的入力の単価は標準×0.5（バッチ）×0.1（キャッシュ読み出し）＝0.05倍、つまり標準の5%まで下げられる。二つの割引は加算ではなく乗算だ。

どの程度違うか直接計算した。静的コンテキスト 1万トークン＋動的入力500トークン＋出力1,000トークンの作業を100件処理すると仮定し、Opus 4.8の単価で四つの戦略を比較した。

キャッシュだけなら57%、バッチだけなら50%、両方なら79%まで下がる。二つの割引が単純に足されたのではなく、静的入力区間で掛け合わされたからだ。（出力トークンはキャッシュ対象ではなくバッチの50%割引だけを受けるため、出力比率が高い作業ほど全体の削減幅は79%より緩やかになる。静的入力の比率が高いほど乗算効果は大きい。）夜間のコードベースの索引作成、公開前の記事評価、データ抽出、定期レポートなど、人が画面の前で待つ必要のない領域は意外に広い。

ただし、すべての作業を非同期に回せるわけではない。利用者が回答を見て次の行動を決めるコーディングエージェントのメインセッションや対話型チャットUIなど、応答時間そのものに価値がある領域にはBatchは向かない。作業を「結果をすぐ見る必要がある」と「次の出勤までに受け取ればよい」の二つに分けるだけでも、請求額を半分にできる。

Subagentで大量出力を伴う作業を隔離する

Claude Code公式文書の表現をそのまま借りると、subagentは「独立したコンテキストウィンドウで動作し、中間のツール呼び出しと結果はsubagent内に残り、最終メッセージだけが親へ返る」。つまり大量出力を伴う作業を丸ごと委任すれば、親コンテキストに入るのは整った要約だけになる。Anthropicのcontext engineering記事によれば、subagentが探索に数万トークンを使っても、親へ返すのは通常1,000～2,000トークンに圧縮した要約だけだ。親コンテキストを軽く保つ効果は明確である。

大量出力を伴う作業とは、一行の答えを得るまでに大量のトークンを吐き出す作業を指す。テスト実行、文書検索、ログ分析などがこれに当たる。

ただし、subagentがそのまま総費用の削減を意味するわけではない。Anthropic自身の報告では、エージェントは通常のチャットの約4倍、multi-agent systemは約15倍のトークンを使う。subagentは高価な長期コンテキストから大量の出力を切り離し、正答率と親側の費用を守る装置であって、総トークン支出を無条件に減らす魔法ではない。だからこそ「本文整理で浮く費用が開始費用を上回る場合だけ」委任するという原則が必要だ。短い作業は親が直接処理した方が安い。

適用ドメインについても補足したい。Anthropicのmulti-agent research system報告は、内部評価でOpus 4単独エージェントに対し、Opus 4（リーダー）＋Sonnet 4（subagents）の構成が90.2%性能を向上させたとしている。ただし、全ドメインで同じではない。同じ記事は「エージェント同士が同じコンテキストを共有する必要がある、またはエージェント間の依存が多いドメインはmulti-agentに向かない」と明記し、コーディングをまさにその例とした。リサーチは独立した方向へ並列探索できるが、コードは一つの関数変更が別の関数へ影響する依存グラフ上で動くからだ。（コーディングにmulti-agent構成を使っているなら、そのワークフローが本当に並列探索に近いか考え直す価値がある。単一エージェント＋隔離した探索subagent一つ程度が、コーディング分野ではより安全な既定値かもしれない。）

compactとprogressive disclosure

Claude Codeの/compactは、これまでの会話全体を要約へ圧縮し、新しいコンテキストで再開するコマンドだ。Anthropicの公式説明によれば、圧縮は単純な切り捨てではなく意味単位の要約で、進行中の作業コンテキストと最近の変更は残し、繰り返しのツール出力など再参照の必要が少ない部分は捨てる。/clearがすべてを消すのに対し、/compactは要約を残す点が違う。コンテキストウィンドウが95%近く埋まるとauto-compactが自動的に同じ処理を行う。長くなったセッションを一定地点で整理すれば、入力トークンの累積を断ち切れる。

内部をもう少し見ると、/compactは利用者が明示的に呼ぶ最終段階にすぎず、その前には自動で動く四段階のコンテキスト圧縮パイプラインがある。Claude Codeの内部動作を分析した外部研究（「Dive into Claude Code」）によれば、すべての呼び出し直前にquery.tsが次の五段階を順に確認する。

• Budget Reductionは個々のツール出力がサイズ上限を超えた部分を切り落とす。
• Snipは時間軸上で古い履歴を切る。
• Microcompactはキャッシュ認識を保ったまま微細な圧縮を行う。
• Context Collapseは非常に長い履歴を読み込み時に再投影し、次元を縮める。
• Auto-Compactは意味単位の圧縮を95%時点の最終手段として発動する。

上ほど軽く安く、下ほど重いが効果は大きい。一つの圧縮戦略ではすべてのコンテキスト圧力を解消できないという認識が、この五段構造の根拠だ。利用者が/compactを明示的に呼ぶ行為は、自動パイプラインの最後の段を前倒しで発動させることに近い。

同じ考え方はClaude CodeのSkillsにも入っている。/compactがすでに蓄積したコンテキストを事後に減らす装置なら、/skillsの三段階読み込みは最初から蓄積を防ぐ装置だ。

Anthropic文書によると、スキルは三段階で読み込まれる。名前と一行の説明（約100トークン）だけがセッション開始時にコンテキストへ入り、本文（SKILL.md、5千トークン未満）はスキルが起動して初めて読み込まれる。バンドルされたスクリプトやリソースはbashで実行された際に出力だけが戻り、コード自体はコンテキストに入らない。そのため数十個のスキルを導入しても、開始時のコンテキストはほとんど増えない。

model routing：同じ答えなら安いモデルへ

Opus 4.8とHaiku 4.5の入力単価には5倍の差がある。単純な検索、探索、短い要約まで最大モデルで処理するのは大きな損失だ。難易度に応じてHaiku → Sonnet → Opusの順に振り分け、本当に重い推論だけOpusを使うパターンが標準になりつつある。LMSYSのRouteLLM研究はGPT-4の品質を95%維持しながら、強いモデルの呼び出しを14%に抑えるルーターを示した（コーディング特化ではなく一般推論ベンチマークである点には留意が必要だ）。

ツールの勢力図も急速に固まっている。商用ゲートウェイにはOpenRouter、Martian、NotDiamondがあり、オープンソースのセルフホスト陣営にはLMSYSのRouteLLMとLiteLLM、Bifrostなどのコスト可視化レイヤーが定着した。AnthropicのエコシステムではAgent SDKのモデル選択引数、Claude Code subagentのmodelフィールド（Exploreは既定でHaiku）、/model スラッシュコマンドがいずれもmodel routingのための装置だ。ただし、APIを直接呼ぶ場合、入力難易度を見てモデルが自動選択されることはない。Anthropic、OpenAI、GoogleのAPIはいずれも利用者が指定したモデル名のまま動くのが基本で、自動ルーティングは製品（CursorのAuto、ChatGPTの自動モード、OpenRouterのopenrouter/auto）だけで有効にできるオプションだ。model routingで費用を下げるなら、ゲートウェイか分類器を自分で構築する必要がある。

だからといって外部の自動ルーターを無条件に付ければよいわけでもない。OpenRouterのAuto Routerのように呼び出しごとにモデルを変えるルーターは、prompt cachingと正面から衝突する。Anthropicの一時キャッシュは同じモデル＋同じプレフィックスでしかヒットしないため、呼び出しごとにモデルキーが変わるとキャッシュキーが毎回ずれる。キャッシュ読み出しで単価を90%下げていた効果を失い、model routingで半分近く節約したのにキャッシュミスで吐き出す例も多い。OpenRouterがsession_idベースのスティッキーセッションのオプションを勧めるのも、このためだ。

その結果、実務がたどり着いた形は意外に単純だ。呼び出しごとに動的分類せず、作業種類ごとに静的分岐する。先に見たsubagentのmodelフィールドがこのパターンだ。Explore subagentには常にHaikuで動くコード探索レーンを、コードレビュー subagentには常にOpusで動くレビューレーンを持たせる。各レーンでは同じモデル、システムプロンプト、ツール定義が繰り返されるため、モデルごとに独自のキャッシュが蓄積してヒットする。つまり「model routingが標準になりつつある」とは、毎回分類器を走らせる動的model routingではなく、「調整役＋実行役」型の作業種類別静的分岐が標準になったという意味に近い。model routingとcachingが同じ設計で矛盾なく共存できる理由もここにある。

Cursor Composer 2.5

少し性質の違う節約法だが、Cursorのようなエージェントも利用できる。Cursorが2026年5月18日に公開した独自モデルComposer 2.5は、Moonshot AIのオープンソースのチェックポイント Kimi K2.5を基に、コーディング向けにファインチューニングしたモデルだ。Cursorチームは独自ベンチマークで、Claude Opus 4.7に並ぶコーディング性能を約10分の1の価格で実現したと述べる。公開価格は入力$0.50、出力$2.50で、Opus 4.8の入力$5.00、出力$25.00とはちょうど一桁違う。

特化モデルのベンチマークはCursor自身の測定なので、絶対値をそのまま受け取るより、「コーディング専用に学習した小型モデルが、汎用フロンティアモデルと同じ作業で遜色ない性能を出しながら費用を一桁下げる」という流れとして読むのが安全だ。これは2026年にもっとも明確になった節約潮流の一つである。

本当に興味深いのは単価だけでなく、IDEと一体で設計すると入力トークン自体も減る点だ。ComposerやCascadeのようなモデルは、IDEが送るコードベースのコンテキスト（現在のファイル、隣接ファイル、索引済みのシンボル）を効率よく使うよう学習されている。同じ作業でも、汎用モデルが「関連ファイルをもっと見せてほしい」とgrepやreadを繰り返して膨らませる入力トークンを抑えられる。単価が一桁下がったうえトークン数も少し減るので、実際の削減幅は単価差以上になる。

コンテキストをコンテキストの外へ

2026年のもっとも興味深い流れは、「必要なものだけを、必要なときに」コンテキストへ載せる方向だ。Anthropicはこれをjust in time（JIT）コンテキストと呼ぶ。すべての資料を事前にコンテキストへ入れるのではなく、ファイルパスやクエリのような軽い参照だけを持ち、実際に必要になったときツールで取り込む。Claude Codeがコードベース全体の索引を作って丸ごと載せず、globやgrepでその都度ファイルを読むのがこのパターンだ。

AnthropicがSonnet 4.5とともに公開したmemory toolとcontext editingも、同じ思想から生まれた。ここで注意したいのは、memory toolの「memory」は一般的な意味と異なることだ。セッション内に積み上がる会話履歴（コンテキストウィンドウ内にあり、セッション終了で消える）でも、CLAUDE.mdのように人が事前に書き、開始時に自動で読み込まれる設定ファイルでもない。memory toolは、モデルが直接ファイルを読み書きするツールである。

さらに見ると、二つのツールの設計は意外に単純なインターフェースだ。memory toolでは、Claudeが利用者のインフラに用意された専用memory用ディレクトリへファイルを作成、読み取り、更新、削除する。つまりモデルは「どこかのテキストに書いておく」のではなく、通常のファイルシステムのようにmemoryを扱う。保存先を利用者のインフラに置くのが要点で、Claudeはコンテキストウィンドウ外に永続memoryを持てる一方、データの保存・保管方法は利用者が管理する。セッション内の記憶がコンテキスト内で揮発するのに対し、このmemoryは外側に残って次のセッションへ続く。context editingは逆方向から同じことを行う。トークン上限に近づくと古く参照されなくなったツール結果を自動で消し、会話の流れを保ったままエージェントを長く動かせる。

Anthropicの内部評価では、両者の併用でベースライン比39%、context editing単独で29%性能が向上し、100ターンのウェブ検索評価ではトークン消費が84%減った。（ベンダー自身のベンチマークである点は考慮すべきだが、方向性は明確だ。コンテキストは埋めることより、空ける設計が重要になっている。）この流れはClaude Codeの/compact五段パイプラインとも共通する。違いは、/compactがコンテキスト内部を減らすのに対し、memory toolはコンテキスト外に別のストレージを置くことだ。両者は競合せず補完する。

まとめ

ここまで整理すると、トークン節約は三つの軸に集約できる。同じ作業なら送る量を減らす、同じ入力なら安く送る、同じ答えなら安いモデルに任せる。Prompt caching、Batch API、subagent隔離、/compact、memory toolとcontext editing、model routing、特化モデルといったパターンは、三軸のどこを狙うかが違うだけだ。2026年の流れを一言で表せば、コンテキストは「埋める技術」から「空け、選び取る技術」、すなわちcontext engineeringへ重心を移している。context rotが示すとおり、軽いコンテキストは費用だけでなく正答率にも有利だからだ。

もちろん唯一の正解はない。チームごとに作業パターンは違い、同じ人でも文章を書くときとコードを書くときでは費用構造が異なる。ただ一つ確かなのは、エコシステムが急速に動くほど、「昨日正しかった節約パターンが今日も正しい」という前提は危険になることだ。新しいモデル、ツール、料金表を追い続け、自分の作業上で小さなPOCを試す習慣こそ、目立たなくても長く効く節約法になると思う。読者にも、自分だけのトークン家計簿を一度開いてみてほしい。（節約策がなぜ機能するのか、その根を知りたければ、「トークンの仕組み」でBPEとKV cacheもあわせて読むとよい。）

そして一つ問いが残る。コンテキストを空け、選び取る技術まで来たなら、その次はどこへ向かうのか。公開資料をたどると重心はコンテキストのさらに外へ移り、エージェントというシステム全体をどう動かすか（harness設計）、うまく動いたかをどう測るか（eval）、誤作動したときどう閉じ込めるか（containment）へ広がっている。興味深いことに、本稿が繰り返し強調した「POCで直接測る」という姿勢をシステム単位へ拡大すると、まさにevalになる。この先の方向は、コンテキストの次で詳しく扱う予定だ。

これまで筆者は、AIツールをうまく使う方法や、どのツールがなぜ流行しているのかを主に扱ってきた。ところがトークン節約術をまとめる中で、改めて気づいたことがある。コストの減らし方を語るには、まず「トークンとは何か、どのように課金されるのか」を知る必要があるのに、その土台をきちんと説明したことがなかったのだ。（節約術を書いているうちに、トークンの仕組みだけで一本の記事になる分量になった。）

そこで本稿では、節約術に入る前の基礎を整理する。トークンが単語でも文字でもないなら正確には何なのか（BPE）、どのような姿でモデルに入るのか（embedding）、なぜ入力より出力の方が高いのか（prefill/decode）、prompt cachingが単価を下げる理由はTransformer（ニューラルネットワークの設計）のどこにあるのか（KV cache）、そしてコンテキストが長くなるほどなぜ高くなるのか（注意機構の二乗コスト）を順に見ていく。実践的な節約方法を知りたい場合は、本稿の次にトークン節約術を読んでほしい。

トークンは単語でも文字でもない

まず最も基本的な事実から確認しよう。トークンは単語でも文字でもない。 モデルが学習データに頻出する文字列を圧縮して作った、語彙の単位である。

私たちが「この文は何語あるか」と数える直感と、モデルがテキストを分割する方法は異なる。モデルは頻繁に一緒に現れる文字の組み合わせを一つの単位としてまとめ、入力されたテキストをその語彙に沿って細かく分ける。そのため、同じ一単語でも一つのトークンになるものもあれば、複数に分かれるものもある。

この語彙を作るアルゴリズムが、ほぼすべての現代LLMに共通する基盤であるBPEだ。

BPEアルゴリズム

BPE（Byte Pair Encoding、バイト対符号化）は、隣接して頻出する記号のペアを繰り返し新しい一つの記号へ統合し、語彙を増やしていくアルゴリズムである。

興味深いのは、もともと自然言語処理のために生まれたものではない点だ。BPEは1994年、Philip Gageによってデータ圧縮手法として初めて提案された。データ内で最も頻出するバイト対を未使用の1バイトで置き換え、その置換規則を別の表に保存する圧縮方式だった。

これをニューラル機械翻訳の語彙問題へ持ち込んだのが、エディンバラ大学のSennrichらの研究チームである。2015年に公開され、ACL 2016で発表された「Neural Machine Translation of Rare Words with Subword Units」で、固定語彙では希少語や未知語を扱えないという限界をBPEで解決した。単語全体を覚える代わりに、より小さなサブワードの組み合わせで表せば、語彙にない単語も既知の断片から符号化できるという発想だ。

動作の流れは意外に単純である。

1. 最初は一文字ずつを一つのトークンとする。
2. コーパス内で最も頻繁に隣接するトークンのペアを探す。
3. そのペアを新しい一つのトークンに統合し、コーパス全体で該当ペアを新トークンに置き換える。
4. 語彙が目標サイズに達するまで2〜3を繰り返す。

初めは一文字が一トークンだが、やがて「th」「the」「tion」のような頻出する組み合わせが一つのトークンへまとまっていく。よく使われるパターンほど大きな塊になるわけだ。

GPT系は、さらに一歩進んだバイトレベルBPEを使う。テキストを文字ではなくUTF-8のバイト列へ変換してからBPEを適用する方式だ。これにより、基本語彙を256種類（バイトの種類数）から小さく始めながら、UTF-8で表現できるあらゆるテキストを未知トークンなしで符号化できる。絵文字でも漢字でも特殊記号でも、少なくともバイト単位では必ず表現できることが保証される。

同じテキストでもトークン数は違う

この仕組みのため、同じテキストでもtokenizer（人が書いたテキストを、モデルが扱えるトークン単位に分割するツール）によってトークン数は大きく変わる。語彙がどのように学習されたかにより、同じ文が細かくも、大きな塊にも分割されるからだ。

OpenAIがGPT-4oとともに公開した資料を見ると、この差がよく分かる。GPT-4o系の新tokenizerであるo200k_baseは、GPT-4系のcl100k_baseより同じテキストを少ないトークンで表現する。英語では約1.1倍効率的という程度だが、英語以外では差が広がる。公開された短い例文では、中国語と日本語で約1.4倍、韓国語で約1.7倍、ヒンディー語では最大約2.9倍トークンが減った。（韓国語話者にとって、tokenizerの世代差が英語話者より大きく感じられるのは興味深い。）

さらに広く見ると、言語そのものによる格差もある。cl100k_baseで複数言語を比較したYennie Junの分析では、同じ意味の文でも英語はほぼ常に最少トークンで、固有の文字体系を持つ言語ほど長くtokenizeされる傾向がある。ヒンディー語やベンガル語は英語の5倍、ビルマ語は10倍を超えることもある。韓国語や中国語も英語より長くtokenizeされるが、それらの極端な言語ほどではない。

ここから実務上重要な示唆が得られる。AnthropicもOpus 4.7から新しいtokenizerを導入し、公式料金資料に「同じテキストでも従来モデルより最大35%多いトークンとして課金される場合がある」と明記した。単価が同じでも、トークン数が増えれば請求額もそのまま増える。 モデル比較は単価だけでなく、単価×予想トークン数で見る必要がある。

では、分割されたトークンがモデルへ入るとき、文字や単語のまま入るわけではない。トークンはどのような形でモデルに入力されるのだろうか。

トークンがモデルに入るまで

ニューラルネットワークはテキストを直接扱えない。モデルが計算できるのは最終的に数値、より正確にはベクトル（複数の数値を並べた配列）だけだ。そのため、トークンはモデルに入る前にいくつかの段階を経て数値へ変換される。

順に整理すると次のようになる。

1. テキスト → トークン：BPE tokenizerがテキストをトークン片に分ける。
2. トークン → トークンID：各トークンは語彙内の位置を示す整数IDへ対応付けられる。たとえば" the"が語彙の1,234番目なら、そのトークンのIDは1234となる。
3. トークンID → embeddingベクトル：このIDでembedding行列の該当行を取り出す。embedding行列はvocabulary size × model dimension (d_model)という大きさの巨大な表で、各トークンIDが一行、つまり一つのベクトルに対応する。このベクトルをトークンの「意味」を表す座標と考えればよい。
4. 位置情報を加える：自己注意機構は、それ自体ではトークンの順序を知らない。つまり「私は君が好き」と「君が私は好き」を同じものとして見る。そこで各トークンベクトルへ位置情報を注入し、並び順を教える。

言葉だけでは抽象的なので、この4段階を直接試せる操作ツールを用意した。入力文を変えたりトークンをクリックしたりすると、IDからembeddingベクトルとなり、位置情報が加わって最終入力ベクトルになるまでの流れを追える。（表示する次元数は減らしているが、実際のGPT-4のベクトルは12,288次元であることを念頭に置いて見てほしい。）

ここでモデル次元（d_model）とは、一つのトークンを表現するベクトルの長さである。元祖Transformer論文では512だったが、現在のLLMははるかに大きい。（Llama 2の7Bモデルでも4,096次元ある。）モデル次元が大きいほどトークンの微妙な意味の違いを豊かに表せる一方、計算量とメモリも増える。

位置情報を注入する方法も世代によって変わった。元祖Transformerは正弦・余弦関数で作った位置ベクトルをembeddingへそのまま加えたが、現在の公開LLMで事実上の標準となったRoPE（Rotary Position Embedding、回転位置embedding）は、Query/Keyベクトルを回転させ、注意機構の計算時に相対位置を注入する。（方式は違っても「Transformerに順序感覚を持たせる」という目的は同じだ。）

まとめると、テキスト → トークン → トークンID → embeddingベクトル（+位置情報）→ Transformer入力という流れである。請求書にある「トークン数」とは、この流れの二番目、つまりテキストがいくつのトークンに分割されたかを数えたものだ。

ここまでで、トークンがどう作られ、どんな姿でモデルに入るかが分かった。ではモデル内部で処理されるとき、入力と出力のコストはなぜこれほど違い、同じ入力を繰り返し送るコストはどう減らせるのだろうか。

入力が安く、出力が高い理由

トークンを扱った人なら一度は疑問に思うはずだ。料金表を見ると、出力トークンは入力トークンの数倍も高い。 Anthropicでは、全モデルで出力単価が入力単価のちょうど5倍である。（Opusは入力$5／出力$25、Haikuは入力$1／出力$5。）同じ一トークンなのに、入るときと出るときでなぜ価格が違うのか。

答えは、モデルが入力と出力のトークンをまったく異なる方法で処理するからだ。LLM inferenceは二段階に分かれる。

• prefill（入力処理）：プロンプトとして入った全トークンをまとめて並列に処理する。1,000トークンでも10,000トークンでも、GPUが一度に走査して各トークンのK/V（Key/Value）を計算する。演算量は多いが、並列処理できるためトークン当たりの効率がよい。
• decode（出力生成）：応答トークンを一度に一つずつ順番に作る。一つ生成したら入力へ追加し、次のトークンを生成する。応答が終わるまでこれを繰り返す。

この非対称性がコスト差を生む。Databricksの推論性能分析によれば、prefillは演算律速の段階で、decodeはメモリ帯域律速の段階だ。decodeでは一トークンを作るたび、モデルの全重みをGPUメモリから再び読み込む必要があるのに、一回で得られるのは一トークンだけである。GPUの膨大な演算能力の大半が遊んでいることになる。（Databricksの表現を借りれば、GPUを動かす料金を払いながら、使える演算能力を使えていない状態だ。）

つまり、入力トークンは並列prefillでまとめて効率よく処理される一方、出力トークンは一つずつ非効率に絞り出さなければならない。 料金には需要や利益率など商業的要因も含まれるだろうが、技術的にはdecode段階の非効率が背景にある。したがって「出力を短くする」という節約原則は、単なる助言ではなく、最も高価な段階を減らすことなのだ。

では、この非効率なdecodeを少しでも改善する方法はないのか。そこで登場するのがKV cacheである。

キャッシュが単価を下げる仕組み

prompt cachingは静的な入力を一度キャッシュへ保存し、次の呼び出しでは大幅に安い料金で読み出す仕組みだ。Anthropic公式資料では、キャッシュ読み出しは基本入力単価の0.1倍、つまりちょうど10%である。キャッシュ書き込みは5分TTL（Time To Live、キャッシュの有効期間）で1.25倍、1時間TTLで2倍になる。最初の呼び出しで少し多く払い、二回目以降は90%安くなる構造だ。

だが、なぜ90%も安くできるのか。そして「接頭部が完全に一致しなければならない」という条件はなぜそれほど厳しいのか。Transformerの内部を見れば、どちらの答えも明確になる。

KV cache

モデルは入力トークンを処理するとき、各トークンに対応するQuery/Key/Value（Q/K/V）ベクトルを作る。自己注意機構はQueryとKeyの内積で注意スコアを計算し、そのスコアを重みとしてValueの加重和を作って出力する。一つのトークンがほかのトークンを「どの程度参照するか」を決める計算だと考えればよい。

先ほど見たdecode段階は、まさにここで問題になる。新しいトークンを一つ作るたび、それ以前の全トークンのK/Vが必要だが、毎回最初から計算すると同じK/Vを際限なく重複計算することになる。

KV cacheは、この重複をなくすために導入された。一度計算したK/Vを保存し、新しいトークンを生成するときは先行トークンのK/Vを再計算せず、キャッシュから読み出して再利用する。これにより、一つの系列内でトークンを一つ追加生成するコストは、各段階で全体を再計算するO(n²)から、キャッシュを読むだけのO(n)へ下がる。（厳密には一段階当たりのコストだが、要点は「計算済みのものは再計算しない」という単純な発想である。）decodeがメモリ律速なのも、各段階でこのKV cacheをメモリから読み直す必要があるためだ。

呼び出し間での再利用

KV cacheがもともと一つの応答生成中のdecodeを高速化する仕組みなら、prompt cachingはこのメモリ構造を一回の呼び出し内だけでなく、呼び出しと呼び出しの間でも再利用するという発想だ。

静的な接頭部（システムプロンプト、ツール定義、コード断片など、毎回ほぼ同じ冒頭部分）のK/Vを5分または1時間のTTL中GPUメモリに保持する。次の呼び出しが同じ接頭部で始まれば、その部分のK/V計算を丸ごと飛ばし、キャッシュから直接読み出して使う。正確には入力トークンの単価が魔法のように下がるのではなく、そのトークンを計算するGPUの仕事そのものが消える。 90%の値下げは、省かれた計算を料金に反映した結果なのだ。

この仕組みを理解すれば、「接頭部が完全一致しなければならない」という条件が厳しい理由も自然に分かる。キャッシュヒットは接頭部を累積的にハッシュ化した値が一致するかで判定されるが、自己注意機構には因果性があるため、前のトークンが一つでも変われば後続する全トークンのK/Vも変わる。プロンプトの先頭に時刻情報を一行置くだけでも、呼び出すたび値が変わって接頭部のハッシュが一致せず、それ以降のキャッシュ全体が無効になる。

Anthropicのキャッシュはtools → system → messagesの階層順に読み込まれる。したがって先頭側のツール定義が一つ変わるだけでも、その後のキャッシュ全体が無効になる。結論は単純だ。静的なものを前に、毎回変わる動的なものを後ろに置けばキャッシュが生きる。

キャッシュにはあまり知られていない制約もある。キャッシュ可能な最小トークン数はモデルごと、同じ系列内でもバージョンごとに異なる。それより短いプロンプトはキャッシュを有効にしても、通知なく保存されない。（この最小トークン数と提供元ごとのキャッシュ方針はコスト設計に直結するため、トークン節約術の記事で料金表とともに詳しく扱った。）

コンテキストウィンドウがトークン上限を生む理由

最後に、トークンを語るうえで欠かせない概念がコンテキストウィンドウである。モデルが一度に受け取れるトークン数の上限を指す。なぜこの上限があるのかを理解すれば、「コンテキストが長いほど高くなる」というよくある警告の正体も明らかになる。

鍵は自己注意機構の計算構造にある。注意機構では、すべてのトークンがほかのすべてのトークンを一度ずつ参照する。トークンがn個ならトークンの組はn × n、つまり自己注意機構の計算量とメモリは系列長nの二乗に比例して増える。 トークンが2倍になれば注意機構のコストは4倍になる。（モデル全体がO(n²)なのではなく、注意機構の段階がそうである点は明記しておきたい。）

この二乗増加がどれほど急かは、Hugging Faceの推計がよく示している。最適化なしの標準的な注意機構では、注意スコア行列を保存するだけでも、入力1,000トークンなら約50MBで済むが、16,000トークンでは約19GB、100,000トークンではほぼ1TB必要になる。

さらに、先ほどのKV cacheもトークン数に比例してメモリを消費する。コンテキストが長くなるほど保持すべきK/Vが線形に積み上がる。つまりコンテキストウィンドウの上限とは、「これ以上長くなるとメモリと計算が耐えられない」という物理的な限界にモデルが引いた線なのだ。

だから長い会話をそのまま引き継ぐことは、単に入力トークン数を増やすだけの問題ではない。注意機構のコストは二乗で増え、トークン数が上限に近づくほどモデルが情報を正確に扱う能力も落ちる。（この精度低下は、節約術の記事で扱ったコンテキスト劣化と直結する。コンテキストを軽く保つことがコストと正答率の両方に効く理由がここにある。）

まとめ

ここまでを整理すると、トークンの仕組みはいくつかの単純な事実に集約できる。トークンはBPEが頻出パターンをまとめて作った語彙の単位であり、トークンIDを経てembeddingベクトルへ変換され、モデルに入る。入力は並列prefillでまとめて処理できるが、出力は一トークンずつ絞り出すため高く、その非効率を和らげるのがK/Vを再利用するKV cacheだ。キャッシュが単価を下げるのは魔法ではなく、Transformerが計算済みのK/Vを再計算しないからであり、接頭部が完全一致しなければならない厳しい条件もこの構造から直接導かれる。そしてコンテキストが長いほど高くなるのは、注意機構のコストがトークン数の二乗で増えるためだ。

この基礎を知れば、コストの話はずっと明快になる。出力がなぜ高いのか、キャッシュを壊さないためプロンプトをどう配置すべきか、なぜコンテキストを軽く保つべきか、同じ答えならなぜ安いモデルへ移るべきかといった節約戦略は、すべてこの原理の上に立っているからだ。仕組みを知りたくてここまで読んだ方には、続けてトークン節約術を読み、これらの原理が実際のコストをどう削減するか確かめてほしい。

一つのプロジェクトにCLAUDE.md、AGENTS.md、SKILL.md、.cursor/rulesが積み重なっていて、それぞれがいつ読まれ、何を書くべきなのかがわからなくなっている開発者に向けた記事だ。最後まで読めば、ファイルごとの違いと、エージェントがそのファイルを読み込む仕組み、そしてETH Zurichの研究にもとづく「推論できない情報だけを書く」という判断基準が得られる。

筆者はフロントエンド開発者として働きながら、日常的にClaudeを活用している。そうしているうちに、いつの間にかプロジェクトルートにCLAUDE.mdができ、その隣には誰かが作ったAGENTS.mdがあり、.cursorrulesも片隅に残り、どこかで読んだ記事に倣って.claude/skills/フォルダまで作るようになった。（気がつけば、似たような内容を書いたファイルが5つほどできていた。）

永続メモリを持たないエージェント

AIコーディングエージェントには、永続的な記憶がないという根本的な制約がある。すべてのセッションは空の状態から始まり、昨日合意した規約や1時間前に伝えたフォルダ構成を、次の会話では覚えていない。コンテキストファイルは、この問題を解決する最も単純な仕組みだ。セッションの開始時に毎回自動で読み込まれるファイルをプロジェクトに置けば、同じ説明を何度も繰り返さずに済む。

問題は、同じ発想から生まれたファイルがツールごとに別々に作られたことだ。Claude CodeはCLAUDE.mdを、Cursorは.cursorrules（現在はdeprecatedとなり、.cursor/rulesの使用が推奨されている）を、GitHub Copilotは.github/copilot-instructions.mdを、OpenAI CodexはAGENTS.mdを読む。チームで複数のツールを使えば、同じ内容を4か所にコピーしなければならない状況になる。

CLAUDE.md

CLAUDE.mdは、Claude Codeがセッション開始時に自動で読み込むファイルだ。Anthropicの公式ドキュメント（code.claude.com/docs/en/memory）によると、Claude Codeは次の3階層からCLAUDE.mdを探す。

• ユーザーメモリ（~/.claude/CLAUDE.md）：マシン上のすべてのプロジェクトに適用されるグローバルなデフォルト
• プロジェクトメモリ（プロジェクトルートのCLAUDE.md）：Gitにコミットされ、チーム全体で共有
• ローカルメモリ（サブディレクトリのCLAUDE.md）：そのディレクトリで作業するときだけ追加で読み込まれる

3階層がすべて存在する場合、Claudeはすべてを読み込んで連結（concatenate）する。優先順位によって一つだけを選ぶのではなく、CSSのcascadeのように、より具体的なものが追加で重なる構造だ。（オーバーライドではなくマージである。）したがって、同じテーマのルールを複数の階層に分散させると競合する可能性がある。（Anthropicの公式ドキュメントも、競合時の動作は保証されないと明記している。）

ここで見落とされがちな点が一つある。現在の作業ディレクトリからリポジトリルートまで遡り、途中にあるすべてのCLAUDE.mdを読むという点だ。そのため、モノレポのpackages/ui/に入って作業すると、ルートのCLAUDE.mdとpackages/ui/CLAUDE.mdが両方読み込まれる。（これは強力だが、同時にコンテキストが気づかないうちに膨らむ可能性も意味する。）

AGENTS.md

AGENTS.mdは、前述したツール別ファイルの乱立を解消するために作られた標準だ。2025年12月、OpenAIはこの標準をLinux Foundation傘下のAgentic AI Foundation（AAIF）へ寄贈した。Linux Foundationの発表によると、AAIFはAnthropic・Block・OpenAIが共同で創設し、創設プロジェクトはAnthropicのMCP（エージェントを外部システムにつなぐプロトコル）、Blockのgoose、OpenAIのAGENTS.mdの3つだ。公式サイト（agents.md）では、6万以上のオープンソースリポジトリがこのファイルを採用していると明記されている。

対応ツールの一覧を見れば、さらに明確だ。OpenAI Codex、Google Jules、VS Code、GitHub Copilot、Cursor、JetBrains Junie、Aider、Devin、Zed、Factory、Warp、goose、opencode、Amp、RooCode、Gemini CLI、Kilo Code、Phoenix、Semgrep、Ona、Windsurf、Augment Codeなど、数多くのツールが対応している。GitHub Copilotは2025年8月からAGENTS.mdをネイティブサポートし始めた。興味深いのは、Claude CodeによるAGENTS.mdのネイティブサポートは、いまだactive feature requestの状態だという点だ。Claude Codeは今もCLAUDE.mdを第一のファイルとして扱う。

標準とはいっても、本当に採用が進んでいるのか疑わしく思えるかもしれない。最も強力な証拠は、dogfooding（自分たちが作った標準を自ら使うこと）だ。

• Vercel/Next.jsのcanaryブランチのルートにはAGENTS.mdがある。実際にはCLAUDE.mdを指すシンボリックリンクだが、その中にはモノレポ構成、pnpm --filter=next devによる1〜2秒単位の反復、TurbopackとWebpack双方のテストガイド、pr-statusスクリプト、環境変数やシークレットの扱いに関するルールまで含まれている。create-next-appが新規プロジェクトにAGENTS.mdとCLAUDE.mdを一緒に生成するようになったのも、同じ流れだ。
• OpenAI/codexリポジトリ自体が、独自のAGENTS.mdを運用している。

戦略としては、次の運用が定石として定着しつつある。AGENTS.mdを単一の情報源（single source of truth）とし、CLAUDE.mdは最小限に抑え、AGENTS.mdを参照する1行とClaude Code固有の指示だけを書く方法だ。これなら重複がなくなり、Claude Codeは両方のファイルを読むため、失うものもない。

SKILL.md

SKILL.mdは、前の2つとは性質が異なる。CLAUDE.mdとAGENTS.mdが常にコンテキストに存在する永続的な指示であるのに対し、スキル（Skill）は必要なときだけ呼び出されるオンデマンドの能力だ。

スキルはフォルダ単位で構成される。フォルダの中には、1つのSKILL.mdと、そのスキルが実行するスクリプト、追加のMarkdownドキュメントが入る。Claudeは、現在のタスクがスキルのdescriptionと一致するときだけ、そのフォルダを読み込む。これをprogressive disclosure（段階的開示）と呼ぶ。これは1995年にUX分野でJakob Nielsenが確立した概念で、高度な機能や使用頻度の低い機能を補助画面に移し、ユーザーが一度に一つの作業だけに集中できるようにして、認知負荷とエラーを減らす手法だ。Claude Skillsの文脈では、「必要なときだけ、そのスキルの本文をコンテキストへ取り込む」仕組みを指す。その結果、コンテキストウィンドウのコストを劇的に節約できる。

SKILL.mdのfrontmatterには、いくつか固有のフィールドがある。

• description：どのような状況でこのスキルが必要かを説明する。モデルが呼び出すかどうかを判断するトリガーになる
• allowed-tools：スキル内で利用できるツールを制限する（例："Read, Glob, Grep, Bash(python:*)"）
• disable-model-invocation: true：モデルからは呼び出せず、ユーザーだけがスラッシュコマンドでトリガーできる。副作用のある作業（デプロイ・コミットなど）に使う
• user-invocable: false：ユーザーのスラッシュメニューには表示されず、Claudeだけが自律的に呼び出し、背景知識として利用する

Claude Skillsは2025年10月16日、Claude.ai、Claude Code、API、Agent SDKで同時にリリースされた。そして2025年12月18日、AnthropicはSkillsの仕様そのものをオープン標準（agentskills.io）として公開した。Simon Willisonは「Skills are awesome, maybe a bigger deal than MCP」と評価している。その理由は、形式がMCPよりも劇的に単純でありながら、コンテキストウィンドウのコスト問題をprogressive disclosureで解決している点にあった。

ここでSkillsと比較されたMCP（Model Context Protocol）は、エージェントがSlack、GitHub、DBのような外部システムを呼び出せるようにつなぐ標準プロトコルだ。コンテキストファイルがエージェントに何を知らせるかの問題なら、MCPは何をできるようにするかの問題だ。MCPがfunction callingと何が違うのかは、MCPとfunction callingに別途まとめておいた。

エージェントが関連コードを探すコストを減らすツール（Repomix、Aider、CodeGraph、Serena）は、コードをどこまで深く理解するかによって、減らせるコストが異なる。その比較はコードインテリジェンスの4つの階層に別途まとめておいた。

ほかのツールのファイル

Cursorの.cursorrulesは、バージョン0.43からdeprecatedとなった。現在、公式には.cursor/rules/ディレクトリ内に複数の.mdcファイルを置く方法が推奨されている。各.mdcファイルはYAML frontmatterを持つ。

• description：エージェントがこのルールの関連性を判断するときに参照する
• globs：一致するファイルが会話に含まれたとき、自動で添付（auto-attach）される
• alwaysApply：trueなら、すべての会話に必ず含まれる（この場合、globsは無視される）

GitHub Copilotも同じような方向へ進化した。リポジトリ全体への指示は.github/copilot-instructions.mdに置き、パスごとのスコープが必要な指示は.github/instructions/*.instructions.mdファイルを作成して、frontmatterのapplyTo:キーでglobを指定する。（Copilot code reviewは2025年9月からpath-scoped instructionsを正式にサポートしている。）

Cursor・Copilot以外のツールも、すべて似たパターンへ収束している。表にまとめると次のようになる。

なかでも、AiderのCONVENTIONS.mdは興味深い。 公式ドキュメントには、リクエストのたびにこのファイル全体をコンテキストへ含めるため、「200行以内に保つこと」と明記されている。（Aiderは、この制約を早くから認識し、ユーザーへ明示的に伝えているわけだ。）

MEMORY.md

これまでのファイルとは別に、最近よく見かけるようになったパターンがもう一つある。MEMORY.mdだ。公式標準ではないが、コミュニティから自然発生した慣習であり、時間の経過に伴う意思決定と失敗を記録するために使われる。

## 2026-04-10
Pages Router에서 App Router로 이전. 신규 라우트는 App Router 컨벤션 사용.
 
## 2026-04-22
Prisma 쿼리 결과에 optional chaining 쓰지 말 것 — null은 if-check로 명시적 처리.
(이전에 옵셔널 체이닝으로 null을 흘려보내 프로덕션 이슈 발생.)

CLAUDE.mdやAGENTS.mdが現時点のルールを書く場所なら、MEMORY.mdはそのルールがなぜ作られたのかという歴史を書く場所だ。（両者は補完関係にあり、代替関係ではない。）

エージェントはこれらのファイルをどう読むのか

ここまで、どのようなファイルがあるのかを整理してきた。しかし、意外に見落とされやすい問いが一つある。エージェントはこれらのファイルを、正確にはどこへ、どのように読み込むのだろうか。 実はこの仕組みを理解すると、後で扱うETH Zurichの結果（コンテキストファイルの指示があまり守られないという結果）が、よりすっきりと理解できる。

まず押さえておくべき事実が一つある。CLAUDE.mdはsystem promptではなく、user messageとして注入される。 Anthropicの公式ドキュメントには、次のように明記されている。

CLAUDE.mdの内容はシステムプロンプトの一部ではなく、システムプロンプトの後にユーザーメッセージとして渡される。Claudeはそれを読み、従おうとするが、厳密な遵守が保証されるわけではない。

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance.

つまり、強制ルールではなく「参考用コンテキスト」にすぎない。特定の動作を確実に強制したいなら、PreToolUseフックのような別の仕組みを使うべきだと、公式ガイドでも推奨されている。

読み込み順は、broad → specificの順で積み重なる。具体的には、managed policy（組織レベルの設定）→ ユーザーグローバル（~/.claude/CLAUDE.md）→ プロジェクト（./CLAUDE.md）→ ローカル（./CLAUDE.local.md）の順だ。同じディレクトリでは、CLAUDE.mdの後にCLAUDE.local.mdが続く。最も近い場所の指示が最後に読まれることを利用すれば、LLMのrecency biasによって、より具体的なルールが強く働く効果を期待できる。

ここで興味深いのが@import構文だ。CLAUDE.mdの本文中に@path/to/fileと書くと、そのファイルがその位置に展開され、一緒に読み込まれる。再帰の最大深度は4 hopsまで許可され、相対パスはimport文が書かれたファイルを基準に解決される。そのため、公式には@AGENTS.mdで橋渡しする方法が推奨されている。CLAUDE.mdをほぼ空にして@AGENTS.mdの1行だけを書けば、Claude Codeも自然にAGENTS.mdを読む。（CLAUDE.mdがまだAGENTS.mdをネイティブサポートしていない現状では、最もすっきりした回避策だ。）

トークンの観点も確認しておこう。CLAUDE.md自体には明示的なトークン上限がなく、存在する内容はすべて読み込まれる。ただし、公式の推奨は1ファイル200行以内だ。200行を超えると「consume more context and may reduce adherence」と明記されている。興味深いことに、Claude 4.xではtool useを有効にするだけでspecial system promptが自動的に346トークン増える（tool_choice: autoの場合）。コンテキストは、知らないうちに少しずつ消費されているのだ。

Cursorは別の方法を採る。.cursor/rules/*.mdcのルールは、次の4タイプで動作する。

• Always Apply：すべてのチャットに必ず含まれる。globs／descriptionは無視される
• Apply Intelligently（Agent Requested）：エージェントがdescriptionを読み、関連性を判断して利用する
• Apply to Specific Files（Auto Attached）：globパターンに一致するファイルがコンテキストに入ったときに有効化される
• Apply Manually：@rule-nameでユーザーが明示的に呼び出す

ほかのツールは、さらに異なる。OpenAI CodexはGitリポジトリのルートからcwdへ向かってwalkし、すべてのAGENTS.mdを収集してユーザープロンプトの直前に注入する。GitHub Copilotは.github/copilot-instructions.mdを、「edit contextとexplicit referencesの後、loosely related open filesより前」という、コンテキストウィンドウの中間的な優先位置に挿入する。同じAGENTS.mdファイルでも、読み込み時点、優先順位、マージルールはツールごとに異なるため、3つのツールがまったく同じ方法でそのファイルを見る保証はない。

しかし、ここには一つ根本的な問いが残る。なぜモデルは、コンテキストにある指示の一部しか守らないのだろうか。 単に「指示が長いから」という説明では不十分だ。この現象の根底には、LLMの構造的な限界がある。

ハルシネーションとコンテキスト忘却

AIエージェントが会話の文脈を混同したり、前に明確に伝えた内容を後になって忘れたりする経験があるなら、それはまさにハルシネーション（Hallucination）の一種だ。一般にハルシネーションといえば「存在しない事実を作り出すこと」がまず思い浮かぶが、学術的には3つに分類される。Yue Zhangらの研究チームによる2023年のサーベイ「Siren's Song in the AI Ocean」では、これを入力競合型（ユーザーが明示した内容と異なる生成）、文脈競合型（以前に自ら生成した内容との矛盾）、事実競合型（世界知識との不一致）に分けている。コンテキストファイルの指示を無視する現象は、3番目ではなく1番目のタイプだ。モデルが入力を処理するとき、その中の一部の情報を「存在しなかったかのように」扱うのである。

さらに根本的な問題は、このハルシネーションを原理的に排除できないことだ。シンガポール国立大学の研究チームは、学習理論を用いてこれを数学的に証明した。どのLLMもすべての計算可能関数を学習することはできず、したがって汎用問題解決器として使う限り、どこかで必ずハルシネーションが生じるという。

位置効果も重要だ。Stanfordの研究チームは、関連情報がコンテキストウィンドウの先頭または末尾にあるとき、モデルが最もよく参照し、中央に埋もれたときに性能が大きく低下することを実験で示した。これはコンテキストファイルに直接関係する。CLAUDE.mdは読み込み順の中ほどに挿入され、会話が長くなるほど、その指示はコンテキストの「中央」へ押し込まれていく。先ほど触れたrecency bias（新しい情報ほどよく従う傾向）の反対側、つまりprimacy-recency効果において中央部分が最も弱いという事実ともつながっている。

これらの現象をまとめると、一つの図が見えてくる。コンテキストファイルは、LLMの最初のuserターンより前に、システムの外から差し込まれるテキストにすぎない。モデルの決定を強制する仕組みではなく、コンテキストウィンドウに置かれる、もう一つのトークンの塊なのだ。長いほど、そして会話が長引くほど、指示は「中央」へ押し込まれ、参照率が下がる。ETH Zurichの結果は、この構造的な限界を定量的に確認したものだといえる。

ETH Zurichの研究

多くの人は、「それなら、このファイルにできるだけ多く書いておけばよいのでは」と考えただろう。しかし、その直感に真正面から反論する研究が最近発表された。先ほどから触れてきたETH Zurichの研究である。

ETH Zurichの研究チームが2026年2月に発表した論文「Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?」だ。138件の実際のPythonソフトウェアエンジニアリングタスクのベンチマーク（AGENTBENCH）とSWE-bench Liteを使い、Claude Code（Sonnet-4.5）、Codex（GPT-5.2／GPT-5.1 mini）、Qwen Codeの4つのエージェントで測定したところ、意外な結果が得られた。

• LLMが自動生成したコンテキストファイルは、SWE-bench Liteで約0.5%、AGENTBENCHで約2%、タスク成功率をむしろ低下させた
• 人間が直接書いたファイルでさえ、平均約4%のわずかな改善にとどまった
• コンテキストファイルを追加すると、推論コストがインスタンス当たり20%以上増加した
• より強力なモデル（GPT-5.2）では、コンテキストファイルの効果がさらに小さかった（強力なモデルほどパラメトリック知識が十分で、追加コンテキストがノイズとして働く）

ただし、例外が一つあった。非標準ツールを明記した場合だ。たとえば、Pythonのパッケージマネージャーであるuvをコンテキストに明記すると、エージェントがuvを使う頻度がインスタンス当たり0.01回から1.6回へと、約160倍に増加した。

先ほど扱ったAiderの「200行推奨」「毎回コンテキストに入るため短く保つこと」という案内は実用的な指針であり、ETH Zurichの研究は「長いコンテキストファイルが統計的に性能を下げる」ことを定量的に示した。筆者が考える、この研究の実践的な示唆は次のとおりだ。

• 自動生成された巨大なコンテキストファイルは、役立つより害になる可能性がある。300行のCLAUDE.mdにコーディング規約・アーキテクチャ・ワークフローをすべて詰め込むと、エージェントは一部だけに従い、残りを無視する。その不整合は、コンテキストがない場合より悪い結果につながり得る。
• 必ず書くべきなのは「推論できない情報」だ。 非標準ツール、プロジェクト固有の規約、過去の失敗事例などが該当する。一般的なコーディングのベストプラクティスは、モデルがすでに知っている。
• AGENTS.mdを単一の情報源とし、CLAUDE.mdにはツール固有の短い指示だけを書き、詳細なワークフローはSkillへ分離する。

まとめ

コンテキストファイルは、ツールごとに名前も、置き場所も、読み込まれるタイミングも異なる。この記事で見たものだけでも、CLAUDE.md、AGENTS.md、SKILL.md、Cursor rules、copilot-instructions.md、MEMORY.mdがあり、どのツールがどのファイルに対応しているかも変わり続けている。ファイルの一覧を覚えておくだけでは、すぐに古くなる。

そこで筆者がこの記事で目指したのは、特定のファイル形式を薦めることではなく、ファイルがエージェントにどう読まれるのかを見る目を養うことだった。CLAUDE.mdがなぜuser messageとして注入されるのか、同じAGENTS.mdをツールごとになぜ異なる形で読むのか、指示がなぜコンテキストの中間で弱まるのかを理解すれば、新しいコンテキストファイルの形式が登場したときにも、「これはいつロードされ、どれくらい強く作用するのか」を素早く読み解ける。

最後に残るのは、ETH Zurichの研究が示した一つの直感だ。モデルはすでに多くのことを知っている。 コンテキストファイルへ何もかも詰め込んだからといって、エージェントがよりよく従うわけではない。モデルが知らない可能性の高いもの、つまりプロジェクト固有の規約、非標準ツール、過去の失敗だけを残し、それ以外を取り除くほうがよい。コンテキストファイルを長く書くことと、うまく書くことは別の問題なのだ。

この記事を読んだ方にも、今すぐCLAUDE.mdを数百行へ増やすのではなく、いま使っているツールがそのファイルをいつ、どこに、どれくらい強く読み込むのか、一度掘り下げてみることを勧めたい。それが、ファイル形式がどう変わっても揺らがない土台になると考えている。

大きなコードベースでエージェントがgrepとファイル読み込みを繰り返してトークンを使うのを見て、Repomix、CodeGraph、Serenaのようなツールのうちどれを組み込むべきか悩んでいる開発者に向けた記事だ。これらのツールはコードをどれだけ深く理解するかによって、context packing、tree-sitter repo map、ナレッジグラフ、LSPの4つの階層に分かれ、階層ごとに探索コストを減らす箇所が異なる。ナレッジグラフは開発元のベンチマークを、残りの3つの階層はこのブログのリポジトリで測った結果を載せる。

codegraphがGitHub Trendingに載ったのを見て真似してインストールしてみて以来、筆者は新しいツールを見るたびに、それがどんな原理でトークンを節約しているのかが気になっていた。この記事に出てくるツールの多くも、筆者が普段weekly単位でTypeScriptとPythonに絞って眺めているGitHub Trendingで初めて知ったものだ。

コードインテリジェンスツール

エージェントはコードを直す前に、まず関連コードがどこにあるかを探す。grepで探し、ファイルを読み、絞り込み、またgrepするループだ。後で見るCodeGraphのベンチマークでは、ツールなしで答えた側は質問1つにtool callを最大43回使った。コードインテリジェンスツールは、この探索コストを減らそうとする試みである。

ただし、「コスト」という言葉が指すものは1つではない。モデルが処理したトークン、tool callの回数、そして作業が終わった後もcontext windowに残っているトークンは、それぞれ別々に動く。この記事では、各階層がこの3つのうち何を減らすのかを見る。

筆者はツールがコードをどれだけ深く理解するかを基準に、これらの試みを以下の4つの階層(tier)に分けて捉えている。業界で決まった分類はなく、この区分は筆者が整理したものだ。この記事の実測値はすべてこのリポジトリのコミット 36e5cfa で2026-10-08に得たもので、トークンはtiktokenの o200k_base で数えた。Claudeのトークナイザーとは値が異なるので、絶対値よりも比較に使う。

コンテキストパッキング

最も単純な解決策は、「全部を1つのcontext windowに入れてしまおう」という発想だ。グラフも作らず、インデックスも作らない。リポジトリ全体をテキストの塊としてシリアライズし、モデルに丸ごと渡す。

代表的なツールがRepomixだ。デフォルトの出力形式はXMLで、READMEはAnthropicのXMLタグに関するドキュメントへのリンクを載せている。CLI、Web、ブラウザ拡張、MCPサーバーまで揃っている。

GitIngestはインストールなしで使えるのが強みだ。GitHubのURLの github.com を gitingest.com に変えると、リポジトリ全体が1枚のテキストページになる。RustのCLIであるcode2prompt(Mufeed VH作)は、テンプレートで出力形式を変えられる。

rtk(rtk-ai/rtk)は少し方向が違う。上のツールがリポジトリ全体を一度にパッキングするのに対し、rtkはエージェントが実行したCLIコマンドの出力を圧縮する。Rustで作られた単一バイナリで、Claude Code、Cursor、Copilot、Gemini CLI、Codexなど複数のエージェントのhookに登録され、エージェントが git status を呼び出すと rtk git status に置き換えて実行する。100以上のコマンドにfiltering、grouping、truncation、deduplicationを適用する。rtkのhookはBashのtool callだけを対象にする。Claude Codeの Read、Grep、Glob はそのまま素通りする。

減る量は注意して読む必要がある。rtkのREADMEは、Bashの出力を最大90%減らすと書きつつ、それが請求額を90%減らすという意味ではないとすぐに付け加えている。コマンドの出力はモデルから見れば入力トークンの一部で、入力トークンは請求額の一部なので、段階ごとに薄まる。公式サイトが掲げる数字は、rtkが置き換えて実行したコマンド基準で平均56%だ。上のツールが入っていくテキストを減らすのだとすれば、rtkはtool callの結果として戻ってくるテキストを減らす。

この階層の限界は、大きなリポジトリはトークン上限に引っかかることだ。このブログの src/ のファイル109個をパッキングするだけで94,596 tokensになる。この程度ならウィンドウに収まるが、ファイルが数千個あるリポジトリならすぐ上限に達する。Repomixはこの問題に --compress で答える。READMEによれば、Tree-sitterで関数とクラスのシグネチャを残し、実装の本体を捨てる。

# repomix 1.18.1, 이 리포 커밋 36e5cfa, 2026-10-08
npx -y repomix@1.18.1 src -o out.xml              # Total Tokens: 94,596 tokens
npx -y repomix@1.18.1 src --compress -o out.xml   # Total Tokens: 30,320 tokens

68%減った。コメントはそのまま残るので、JSDocが長い visit-counter.ts は1,642から約1,220 tokensへと26%しか減らなかった。圧縮版にはimport文とシグネチャが残るが、関数本体の中の呼び出しは消える。どのファイルが何を取り込むかはテキストで見えるが、誰が誰を呼ぶかは問えない。そのため、この階層と次の階層の境界は、構文を見るかどうかよりも、関係を問えるかどうかにある。

tree-sitterリポジトリマップ

次の階層は、tree-sitterを活用してコードの構造を解析しつつ、別途インデックスサーバーは立ち上げない方式だ。

この階層のツールが使うtree-sitterが作るのは、ソースコードの構造を木で表したCST(Concrete Syntax Tree)だ。tree-sitter公式ドキュメントもconcrete syntax treeを作ると書いている。括弧や句読点までノードとして残した木で、以下のツールが扱うのもこの木だ。

tree-sitterは、オープンソースのパーサジェネレータであり、インクリメンタル(incremental)パースライブラリだ。GitHubのcode navigationがtree-sitterを使っている。編集された部分だけを再パースするので、エディタで1行を直してもファイル全体を再パースせず、変わった部分の木だけを直す。この利点は、編集が絶えず起きるエディタのものだ。以下のAiderは、ファイルの更新時刻でキャッシュを持ち、変わっていないファイルを再パースしない。

ターミナルで使うAIペアプログラミングツールAiderが、このアプローチの代表例だ。Aiderはtree-sitterでファイルごとに関数、クラス、メソッドの定義と参照を抽出する。そしてファイルをノードとするグラフを作る。ファイルAがファイルBで定義された識別子を参照すると、AからBへエッジができる。

このグラフで重要なファイルを選ぶのに、AiderはPageRankを使う。PageRankは、リンクを多く、そして重く受けるノードほど高いスコアを与えるアルゴリズムだ。Aiderが使うのはその変種のpersonalized PageRankで、指定したノードの側へスコアを傾ける。こうして順位の高いファイルから、定義とシグネチャをトークン予算の分だけ入れる。

何が予算に入るかは、いまの会話によって変わる。Aiderのrepomap.pyでは、エッジの重みは参照回数の平方根に倍率を掛けた値だ。会話に出た識別子は10倍、8文字以上のcamelCase、snake_case、kebab-caseの識別子も10倍だ。_ で始まる識別子と、5つを超えるファイルで定義された識別子はそれぞれ0.1倍で、いまチャットに追加したファイルから出ていくエッジは50倍になる。チャットに追加したファイル、会話で言及したファイル、そしてパスやファイル名が会話中の識別子と一致するファイルは、PageRankのpersonalizationスコアも受け取る。

予算も固定値ではない。Aiderのドキュメントは --map-tokens のデフォルトを1kと書いているが、コードはモデルの入力上限の1/8を1,024から4,096の間に切り詰める。そしてチャットにファイルがなければ --map-multiplier-no-files(デフォルト2)倍まで広げる。このリポジトリの src/ で確かめた。実行した0.86.1と上でリンクしたコミットは、ランキングのコードが同じだ。出力されたmapは、Aiderが付ける案内文3行を含めてo200k_baseで数えた。

# aider-chat 0.86.1, 리포 루트에서 시작한다, 2026-10-08
mkdir /tmp/aidermap && cp -R src /tmp/aidermap/ && cd /tmp/aidermap && git init -q && git add -A && git commit -qm init
# 키는 더미 값이다. --show-repo-map 은 map 만 출력하고 LLM 을 부르지 않는다
export OPENAI_API_KEY=dummy
aider_map() { uvx --python 3.12 --from aider-chat==0.86.1 aider --no-check-update --analytics-disable --no-gitignore --model gpt-4o "$@"; }
aider_map --show-repo-map                                              # Repo-map: using 4096 tokens
aider_map --map-tokens 1024 --show-repo-map                            # Repo-map: using 1024 tokens
aider_map --map-tokens 1024 --show-repo-map src/lib/filter-posts.ts    # 이 파일을 채팅에 올린 상태

gpt-4oの入力上限は128kなので1/8が4,096に切り詰められ、チャットが空なのでその2倍以内でmapが出た。ファイルを1つチャットに追加すると、mapは予算内に縮み、前の27個のうち10個だけが残った場所に PostList.tsx と SearchModal.tsx が新たに入った。repo mapはリポジトリの固定された要約ではなく、その瞬間の会話に合わせた抜粋だ。

同じ階層でもう1つ触れておきたいツールがある。ast-grep(ast-grep/ast-grep)だ。tree-sitterベースの構造検索とrewriteを行うCLIで、テキストではなく構文木のノードをマッチングする。たとえば console.log($A) というパターンは、改行や空白がどうなっていても、引数1つで console.log を呼ぶ呼び出しをすべて捉える。捉えるのは同じ構文構造だ。$A の型や、console がどこから来た名前なのかは知らない。ast-grep-mcp サーバーもあるので、エージェントにテキストgrepの代わりに構造検索を使わせることができる。

ナレッジグラフ

3つ目の階層はさらに一歩進む。事前にコードベース全体をパースしてナレッジグラフを作り、ディスクに保存しておき、エージェントは保存しておいたグラフにクエリを投げる方式だ。最も話題になっている例がCodeGraphというツールである。

CodeGraphのREADMEが説明する構造は単純だ。tree-sitterでコードをパースしてシンボル、エッジ、ファイル情報を抽出し、それをローカルのSQLiteデータベースに保存する。名前検索はSQLiteのFTS5インデックスで行う。エージェントはMCPを通じてこのグラフに問い合わせる。READMEが説明する手順にLLMは登場しない。そのため筆者は、この抽出は決定論的(deterministic)、つまり同じコードからは常に同じ結果が出ると見ている。

LLMがコードを要約してグラフを作ると、同じコードでも結果が変わりうるし、ハルシネーションが混ざる危険がある。一方、構文木を直接パースすれば言語の文法が定めた規則どおりにだけシンボルの関係を抽出するので、そうした解釈が入り込む余地がない。

ここで登場するFTS5(SQLite Full-Text Search 5)は、SQLiteの仮想テーブルの形で提供される全文検索拡張だ。SQLiteのドキュメントによれば、3.9.0(2015-10-14)からamalgamationに含まれており、CREATE VIRTUAL TABLE ... USING fts5(...) でテーブルを作り、MATCH 演算子で問い合わせる。Elasticsearchのような別の検索エンジンを立てなくても、SQLiteファイル1つで全文検索インデックスを持てる。

ただし、決定論的であることと漏れがないことは別だ。同じREADMEは、慣習やリフレクションに頼るフレームワークのルート認識率をDjangoの74.1%からASP.NETの83.9%までと記し、これを静的解析の限界(honest static-analysis ceiling)と呼んでいる。同じコードからは同じ結果が出るが、その結果から抜け落ちたエッジがありうる。

ベンチマークはCodeGraph自身が測ったものだ。同じREADMEの2026-08-05の再測定では、Claude Opus 4.8をheadlessで動かし、7つのオープンソースリポジトリにアーキテクチャの質問を1つずつ投げた。CodeGraph MCPを有効にした側が、平均コストを44%、処理トークンを62%、tool callを88%減らした。この再測定では、両側ともBashで codegraph CLIを呼べないようにブロックした。ブロックしない測定環境では、ツールなしの側が28回中26回CLIを見つけて使っており、READMEは以前に発表した数値がこのブロックなしで出たものだと明かしている。

削減幅はリポジトリの大きさに従わなかった。ツールなしの側がtool callを28〜43回使った質問ではコストが57〜78%減り、7回で終わったGinではほぼ同じだった。ファイル約11k個のVS Codeが71%、約640個のExcalidrawが78%だった。READMEはこれを、質問が必要とした探索量で説明している。リポジトリごとに質問が1つしかないので、筆者は方向だけを読み取る。

READMEは逆方向の数字も記している。処理したトークンは減るが、複数ターンのセッションが終わった時点でcontext windowに残っているretrieval結果は、7つのリポジトリを通じてCodeGraph側が約80%多い。リポジトリごとの差は大きく、VS Code 1つでは67k対18k tokensで約3.7倍だった。一度に原文を密に返し、それがウィンドウにそのまま残るからだ。CodeGraphはtool callと処理トークンを減らす代わりに、ウィンドウに残る量を増やした。

Cursorは別の道を進み、その後方向を変えた。2026年1月のCursorブログが説明したインデックスは、構文グラフではなくベクトル埋め込みベースのセマンティック検索だった。ローカルでファイルをchunkに分け、Merkle treeのハッシュでサーバーと同期し、chunkを埋め込みに変えてセマンティック検索に使っていた。2026年7月、CursorのCommunity Support Engineerはフォーラムで「Semantic/embeddings indexing is being turned down in favor of grep-based retrieval」と答えた。同じスレッドで別のスタッフは、モデルがgrepをうまく使えるようになるにつれ、以前のセマンティック検索の経路はもう意味のある形で役立たなくなったと書いた。現在のCursorのドキュメントは、Instant Grepがインデックスをローカルで作って問い合わせ、検索用にコードベースの埋め込みを保存しないと記している。

LSP

最後の階層は、言語サーバーに直接依存する方式だ。tree-sitterが「シンボルが存在すること」を知っているとすれば、LSPは「そのシンボルが何であるか」を知っている。

LSP(Language Server Protocol)は、エディタと言語解析ツール(コード補完、定義へ移動、参照の検索、リファクタリングなど)の間の通信を標準化した、JSON-RPCベースのオープンプロトコルだ。2016年にMicrosoft、Red Hat、Codenvyが協力を発表した。核となる発想は、「エディタごとに言語解析器を作り直すのではなく、言語ごとにサーバーを1つ置き、すべてのエディタがそのサーバーに問い合わせよう」というものだ。rust-analyzerやPythonのpyrightがLSPサーバーで、TypeScriptは独自プロトコルを使う tsserver をLSPで包んだtypescript-language-serverを使う。

Serena(oraios/serena)がこの階層に属するMCPサーバーだ。2026-10-08時点で30,093 starsで、リポジトリは2025年3月に作られた。Serenaの核となる発想は一行にまとめられる。エージェントにコードをシンボル単位で見せよう。 主なツールは find_symbol、find_referencing_symbols、get_symbols_overview などだ。バックエンドは2つのうち1つを選べる。デフォルトはLSPを実装した言語サーバー(無料/オープンソース)、もう1つはJetBrains IDEのコード解析を活用する有料プラグイン(無料トライアルあり)だ。

このリポジトリで測ってみると、差がどこから生まれるのかが見える。非公開記事を除外する isHiddenPost(src/lib/filter-posts.ts:12)の使用箇所を、2つの方法で探した。テキスト側はgrepだ。

# 커밋 36e5cfa, 2026-10-08. 이 글도 같은 이름을 담고 있어 content/ 는 뺐다
git grep -n isHiddenPost -- ':!content'   # 16줄, 파일 9개
git grep -n -C1 isHiddenPost -- ':!content'   # 같은 16곳을 앞뒤 1줄과 함께

LSP側ではSerenaのfind_referencing_symbolsを呼んだ。LSPの参照検索は名前ではなく位置(ファイルと行、列)で問い合わせるので、このツールもシンボル名である name_path と、定義のあるファイルである relative_path を一緒に受け取る。SerenaをMCPサーバーとして起動せず、同じコミットでPythonからツールを直接呼び出した。

# serena 3b99f8b, 커밋 36e5cfa, 2026-10-08. 리포 루트에서 실행한다
# uvx --python 3.12 --from git+https://github.com/oraios/serena@3b99f8b024dafd58c962ea6e74f37c8a730ef532 python refs.py
from serena.agent import SerenaAgent
from serena.config.serena_config import SerenaConfig
from serena.tools.symbol_tools import FindReferencingSymbolsTool
agent = SerenaAgent(project=".", serena_config=SerenaConfig().with_headless_mode_overrides())
agent.execute_task(lambda: None)  # 언어 서버가 뜰 때까지 기다린다
tool = agent.get_tool(FindReferencingSymbolsTool)
print(agent.execute_task(lambda: tool.apply(name_path="isHiddenPost", relative_path="src/lib/filter-posts.ts")))

出力はJSON 1行だ。最初の項目だけを抜き出すとこうなる。行番号は0から数える。

{"src/lib/filter-posts.ts": {"Function": [{"name_path": "filterPublishedPosts", "body_location": {"start_line": 22, "end_line": 24}, "content_around_reference": "...  22:export function filterPublishedPosts(posts: Post[]): Post[] {\n  >  23:  return posts.filter(post => !isHiddenPost(post))\n...  24:}"}]}, ...

Serenaは参照を10か所返した。定義のある filter-posts.ts:12 は除き、3つのファイルのimport行はそのファイル自体をシンボル(File)として返す。grepが拾ったコードの位置11か所は、この10か所に定義の1行を足したものと同じだ。この名前はリポジトリに1つしかないので、grepもコードの位置を取りこぼしたり余計に拾ったりしなかった。grepが余分に拾った5か所は、この関数を説明するドキュメント内の文だった。ルートの CLAUDE.md、.claude/commands/ の audit.md と write-post.md、そして docs/research/snapshot-20260816/ に残る CLAUDE.md と write-post.md のコピーだ。

Serenaは参照ごとに前後1行を付けて返す。そこでgrepは、行番号だけを返す git grep -n と、前後1行も一緒に返す git grep -n -C1 の2通りで実行し、3つの出力全体を o200k_base で数えた。

前後1行を一緒に返すgrepと比べると、Serenaのほうが683 tokens少ない。差はドキュメント5か所を返さないことから生まれる。ただしSerenaは参照ごとにシンボル名と位置情報をJSONで付けるので、コード側だけを見るとむしろ159 tokens多い。行番号だけを返す git grep -n の703 tokensよりは、Serenaの892 tokensのほうが大きい。このリポジトリでLSPの階層が節約するのは検索結果ではなく、grepの結果を見て周辺の行やファイルをさらに読む次のステップだ。

その次のステップで、エージェントがgrepに引っかかったファイル9個を丸ごと読むなら、読む量は47,034 tokensで、コード4個が3,716、ドキュメント5個が43,318だ。これは上限だ。CLAUDE.md は実際のセッションではすでにcontextに載っていて、改めて読まない可能性が高い。isLocale のようなありふれた名前なら、コードの位置でも結果が分かれうる。

まとめ

まとめると、4つの階層はコードをどれだけ深く理解するかで分かれ、減らすコストも異なる。context packingはコードをテキストとして渡し、--compress を付けても構文までしか残さず、入っていくトークンを減らす。tree-sitter repo mapはシンボルが存在することまでを知り、入っていくトークンに予算で上限を設け、その中を何で埋めるかはその瞬間の会話が決める。ナレッジグラフは関係をあらかじめ保存してtool callと処理トークンを減らすが、ベンダーの測定ではウィンドウに残る量がむしろ増えた。LSPはシンボルが何であるかまで知り、このリポジトリではドキュメント内の同じ名前を返さない代わりに、結果ごとにメタデータを付けた。節約する地点は検索結果ではなく、その後の読み込みだ。

だから筆者はツールを選ぶとき、階層の深さよりも、いまどのコストが問題なのかを先に見る。ウィンドウが小さくセッションが長いなら残る量を、往復が遅いならtool callの回数を、ドキュメントとコードが同じ名前を共有するリポジトリなら、grepの結果を見てさらに読むことになるファイルの量を見る。Cursorが埋め込みによるセマンティック検索を外してローカルのテキストインデックス(Instant Grep)に移ったことも、高価なインデックスがモデルの探索能力より常に優れているわけではないというサインとして読める。

これらのツールがエージェントのコード探索コストを減らすものだとすれば、エージェントが最初から知っておくべきプロジェクトのルールをどのファイルにどれだけ書くかは、また別の問題だ。その話はコンテキストファイルで扱う。

Claude CodeやCursorにMCPサーバーをつないで使ってはいるものの、それがLLM APIのfunction callingとどこで分かれるのかを説明しにくかった開発者に向けた記事だ。先に答えを書くと、MCPはfunction callingを置き換えない。ホストアプリケーションがMCPサーバーから受け取ったツール一覧をfunction callingのtoolsパラメータに変換して渡し、モデルが選んだ呼び出しを再びMCPサーバーへ渡す。最後まで読めば、その上にMCPが加える4つの違いがプロトコルのどの部分から来ているのか、2026-07-28改訂版の後も残る違いは何か、そしてその構造がどのような攻撃面を開くのかがわかる。

筆者はフロントエンド開発者として日常的にClaudeを活用しているが、MCPサーバーを一つ追加するたびに、これらのツールがどのような仕組みでモデルの視野に入るのかが毎回あやふやだった。

MCP（Model Context Protocol）

MCP（Model Context Protocol）は「エージェントに何ができるようにするか」という問題を解く。

少し具体的に説明しよう。AIエージェントがSlackへメッセージを送るには、Slack APIを呼び出せなければならない。GitHub Issueを作るには、GitHub APIを呼び出せなければならない。Postgresへクエリするには、DB接続を扱えなければならない。こうした外部システムとの統合を、一つの標準プロトコルにまとめたものがMCPだ。（クライアントとサーバーが同じ規格で接続されるという意味だ。）

MCPはAnthropicが2024年11月25日に初めて公開したオープン標準だ。そして2025年12月9日、AnthropicはMCPをLinux Foundation傘下のAgentic AI Foundation（AAIF）へ寄贈した。AAIFはAnthropic・Block・OpenAIが共同で創設した。

MCPはJSON-RPC上に構築されたプロトコルだ。JSON-RPC 2.0は、JSONをワイヤーフォーマットとして使うstatelessで軽量なRPC（Remote Procedure Call）プロトコルである。トランスポート層に依存せず、HTTP・TCP・標準入出力のいずれでも動作する。この記事は2025-11-25改訂版を基準に説明する。この版のMCPは、接続ごとにセッションを張るstatefulなプロトコルだ。その後の改訂版で何が変わったのかは、呼び出しの流れを見てから扱う。

6つのプリミティブ

2025-11-25仕様の概要は、サーバーが提供する機能3つと、クライアントが提供する機能3つを挙げている。この記事ではこの6つをプリミティブ（primitive）と呼ぶ。ここでいうプリミティブは、JavaScriptのプリミティブ型（stringやnumberなど）とは関係がなく、プロトコルが定めた基本的なやり取りの種類を指す。

サーバー側プリミティブ

• Tool（model-controlled）：モデルが呼び出すかどうかを自ら判断して実行する操作。この操作は副作用（side effect）を持つことがある
• Resource（application-controlled）：URIで識別されるデータ。仕様には内容を読み出すresources/readだけがあり、書き込むメソッドはない。そのリソースをコンテキストにどう入れるかはホストアプリケーションが決める
• Prompt（user-controlled）：ユーザーがスラッシュコマンドなどで明示的にトリガーする、再利用可能なテンプレート

クライアント側プリミティブ

• Sampling：サーバーから逆にクライアントのLLMへcompletionを要求できる仕組みで、クライアントとサーバーを双方向の構造にする。ツールの実行中に文章の生成が必要になったサーバーが、自前のAPIキーなしでクライアントの使うモデルを借りるための仕組みだ。2026-07-28改訂版では削除予定のdeprecatedになった
• Roots：クライアントがサーバーへ「ここまでが作業可能な範囲」と伝えるワークスペース境界の情報
• Elicitation：サーバーがツールの実行中に、構造化された形式でユーザーへ追加入力を求められる機能

この区別が重要なのは、誰が呼び出しや提供を決めるのかが異なるからだ。Toolはモデルの判断で実行されるため誤った呼び出しのリスクがあり、Promptはユーザーが明示的に選ぶ。Resourceはアプリが選ぶのが基本だが、仕様はヒューリスティクスやモデルの選択による自動的な取り込みを行う実装も認めている。クライアント側の3つは向きが逆だ。サーバーが要求し、応じるかどうかはクライアントが決める。

2つの転送方式

標準の転送方式は2つで、仕様はそれ以外のカスタム転送も認めている（MAY）。一つはstdioで、MCPサーバーをローカルのサブプロセスとして実行し、標準入出力で通信する方式だ。ファイルシステムやGitなど、ローカルで動くツールに適している。もう一つはStreamable HTTPで、HTTP POSTとGETにSSE（Server-Sent Events）ストリーミングを重ね、双方向に近い通信を実現する方式だ。SSEは、HTTP接続の上でサーバーからクライアントへ一方向にデータを送り出す方式だ。リモートサーバー、OAuth認証、複数クライアント接続、クラウドデプロイなど、ネットワーク越しのシナリオに適している。

LLMがMCPツールを呼び出す流れ

プリミティブと転送方式を確認したので、次は実際にLLMがMCPツールをどのように発見し、呼び出すのかを追ってみよう。

2025-11-25改訂版では、接続が始まると次の順序でハンドシェイクが行われる。2026-10-08時点で、TypeScript SDKの1.32.1とv2系の2.3.1も、既定の設定ではこの順序で動く。

• クライアント → サーバー：initializeリクエスト（対応するプロトコルバージョンとクライアントcapabilitiesを渡す）
• サーバー → クライアント：initializeレスポンス（サーバーcapabilitiesと、任意のinstructionsフィールド）
• クライアント → サーバー：notifications/initialized通知
• クライアント → サーバー：tools/listリクエスト → 利用可能なツール一覧を受信
• （以後）LLMがツールを呼び出すと判断 → クライアントがtools/callを送信 → 結果を受信

initializeレスポンスのinstructionsフィールドは、サーバーがツールの使い方をテキストで書いて送る場所だ。下のデモ出力のinstructions行がこの値である。

では、tool定義そのものはどのようにLLMの視野に入るのか。MCPのtool定義は、次のようなJSON Schemaの形をしている。

{
  "name": "get_weather",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": { "location": { "type": "string" } },
    "required": ["location"]
  }
}

ホストはtools/listで受け取ったこの一覧を、Anthropic Messages APIのtoolsパラメータまたはOpenAI function callingのtoolsパラメータへ変換し、LLM APIの呼び出し時に一緒に渡す。Anthropicの場合、toolパラメータが渡されるとspecial system promptが自動的に追加され、モデルがtoolの呼び出し方を理解できるようになる。その長さはモデルによって異なる。2026-10-08に見たドキュメントの表では、tool_choice: autoの場合、現行モデルで286〜675トークンだった。

LLMがツールを呼び出す必要があると判断すると、レスポンス内にtool_useブロック（{"type": "tool_use", "name": ..., "input": ...}）が挿入され、レスポンスのstop_reasonはtool_useで終わる。ホストはこれを受け取り、実際のMCPサーバーへtools/callを送信する。結果を受け取ると、次のuserメッセージのtool_resultブロックに入れて、再びLLMへ送る。stop_reasonがtool_use以外の値（end_turn、max_tokensなど）に変わるまで、このループが繰り返される。 私たちが一般に「エージェントが働く」と呼ぶ動作は、実際にはこの呼び出し・結果・呼び出しのループが連続することに近い。

図にすると、モデルとMCPサーバーの間には線がない。モデルはtoolsで受け取った定義だけを見て、MCPサーバーはモデルではなくホストからリクエストを受ける。2つのプロトコルをつなぐのは真ん中のホストだ。

この変換が実際にどれほど短いのかを動かして確かめた。2026-10-08にNode v24.16.0、@modelcontextprotocol/sdk 1.32.1、zod 4.6.5で実行した。転送はstdioではなく、同じプロセス内でサーバーとクライアントをつなぐInMemoryTransportで、LLMは呼び出していない。tool_useブロックはAnthropicのドキュメントの形どおりに手で作った。

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { z } from "zod";
 
// MCP 서버: 도구 하나와 instructions 를 둔다
const server = new McpServer(
  { name: "weather", version: "1.0.0" },
  { instructions: "Use get_weather for current conditions only." }
);
server.registerTool(
  "get_weather",
  { description: "Get current weather information for a location", inputSchema: { location: z.string() } },
  async ({ location }) => ({ content: [{ type: "text", text: `${location}: 15C, partly cloudy` }] })
);
 
// 호스트: 같은 프로세스 안에서 서버와 잇고, 클라이언트가 보내는 메서드 이름을 찍는다
const [clientT, serverT] = InMemoryTransport.createLinkedPair();
const send = clientT.send.bind(clientT);
clientT.send = (m) => { console.log("C->S", m.method, m.params?.protocolVersion ?? ""); return send(m); };
await server.connect(serverT);
const client = new Client({ name: "demo-host", version: "1.0.0" });
await client.connect(clientT);
console.log("instructions:", client.getInstructions());
 
// 1. tools/list 결과를 LLM API 의 tools 파라미터 모양으로 바꾼다
const { tools } = await client.listTools();
const anthropicTools = tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.inputSchema }));
const openaiTools = tools.map((t) => ({ type: "function", name: t.name, description: t.description, parameters: t.inputSchema }));
console.log("anthropic:", JSON.stringify(anthropicTools[0]));
console.log("openai:", JSON.stringify(openaiTools[0]));
 
// 2. 모델이 이런 tool_use 블록을 돌려줬다고 가정한다. input 이 그대로 tools/call 의 arguments 가 된다
const toolUse = { type: "tool_use", id: "toolu_demo", name: "get_weather", input: { location: "Seoul" } };
const result = await client.callTool({ name: toolUse.name, arguments: toolUse.input });
console.log("tool_result:", JSON.stringify({ type: "tool_result", tool_use_id: toolUse.id, content: result.content }));
await client.close();

node post-demo.mjsの出力は次のとおりだ。

C->S initialize 2025-11-25
C->S notifications/initialized 
instructions: Use get_weather for current conditions only.
C->S tools/list 
anthropic: {"name":"get_weather","description":"Get current weather information for a location","input_schema":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"],"$schema":"http://json-schema.org/draft-07/schema#"}}
openai: {"type":"function","name":"get_weather","description":"Get current weather information for a location","parameters":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"],"$schema":"http://json-schema.org/draft-07/schema#"}}
C->S tools/call 
tool_result: {"type":"tool_result","tool_use_id":"toolu_demo","content":[{"type":"text","text":"Seoul: 15C, partly cloudy"}]}

ツール定義の変換はフィールド名を変えるだけだ。MCPのinputSchemaがAnthropicではinput_schema、OpenAIではparametersになる。SDKがスキーマに$schemaを付け足すことも出力からわかる。逆方向も短い。Anthropicのtool_use.inputはオブジェクトなので、そのままtools/callのargumentsになる。結果の側も、textブロックは形が同じなのでそのまま渡せるが、画像やエラーの結果は形が異なるため、Anthropic SDKのMCP helperが別途変換する。上のOpenAI側の形はResponses APIの形式だ。OpenAIが返す呼び出しのargumentsはJSON文字列なので、渡す前にJSON.parseを一度通す必要がある。上のコードはAnthropic形式のtool_useブロックしか作っていないので、このparseの段階は出力に現れない。

MCPが加える4つのもの

では、MCPはfunction callingに何を加えるのか。2025-11-25改訂版を基準にすると4つある。

• 動的な発見：ビルド時にはツール一覧を知らず、実行時にtools/listで取得する。サーバーはnotifications/tools/list_changedで、接続中に一覧が変わったことを知らせられる
• Stateful session：initializeで接続を確立し、その中でリクエストがやり取りされる。終了用のJSON-RPCメッセージはなく、転送を閉じることで終える
• Tool以外のプリミティブ：Resource・Prompt・Sampling・Roots・Elicitationをcapability negotiationで公開する。capability negotiationとは、initializeで双方が対応する機能を互いに知らせる段階だ
• 双方向性：サーバーがSamplingを使って、クライアントのLLMへ逆にcompletionを要求できる（2026-07-28改訂版でdeprecated）

2026-07-28改訂版以降

2026-10-08時点で、公式サイトでlatestとして開くのは2026-07-28改訂版で、ここでこのリストの半分が変わった。まず、initializeとnotifications/initializedからなるハンドシェイクとプロトコルレベルのセッションがなくなった。代わりに、すべてのリクエストが_metaにプロトコルバージョンとクライアントcapabilitiesを載せる。このフィールドは、メッセージ本来の引数とは別にメタデータを付けるためにMCPが予約している場所だ。サーバーはserver/discoverを必ず実装しなければならない（MUST）。サーバーが対応するプロトコルバージョン、capabilities、サーバー情報を返すRPCで、クライアントはほかのリクエストより先にこれを呼び出し、対応バージョンとcapabilitiesを事前に確認できる。

サーバーが先に送っていたリクエストは、Multi Round-Trip Requests（MRTR）というパターンに置き換えられた。サーバーは別途リクエストを送る代わりに、追加の入力が必要だという中間結果（input_required）を返し、クライアントがその入力を埋めて元のリクエストを送り直す方式だ。

SamplingとRootsはLoggingとともにdeprecatedになった。仕様に残っていて動作もするが新しい実装は採用すべきでないという意味で、仕様はSamplingの代わりにLLMプロバイダーのAPIへ直接つなぐよう勧めている。

ただし、SDKの既定の動作はまだ古い方式だ。TypeScript SDK 1.32.1は最新バージョン定数が2025-11-25なので2026-07-28改訂版を知らず、2.3.1はこの改訂版に対応しているが、バージョン交渉の既定値がlegacyだ。上の出力の1行目initialize 2025-11-25がその結果である。

すると、4つのうち残るのは動的な発見とTool以外のプリミティブ（Resource、Prompt、Elicitation）だ。動的な発見も形が少し変わり、一覧の変更通知はsubscriptions/listenストリームにopt-inしたクライアントだけが受け取る。結局、MCPがfunction callingと分かれるところは、セッションや双方向性よりも、ツール一覧とコンテキストを実行時にやり取りする契約にある。

APIがMCPクライアントになるとき

この契約のうちどこまでがモデルに届くのかは、AnthropicのMCP connector（beta）が示している。Messages APIがリモートのMCPサーバーに直接つなぐ機能だが、ドキュメントのLimitationsは、MCP仕様の機能のうち"only tool calls are currently supported"と書き、"Local STDIO servers cannot be connected directly"と書いている。同じドキュメントは、ローカルサーバーやMCPのprompt、resourceが必要なら、MCP SDKで接続を自分で管理しながらAnthropic SDKの変換helperを使うよう案内している。

つまり、function callingのレイヤーでMCPを消費するとToolだけが残る。ResourceとPromptは、それを画面やコンテキストへ運ぶホストがあって初めて意味を持つ。OpenAIもfunction callingガイドで、MCPサーバーの機能をbuilt-in toolとして使う方法を紹介している。OpenAIのMCP serversガイドはツール一覧の取得と呼び出しの方法だけを説明し、ResourceやPromptに対応しているかどうかは書いていない。

動的な発見が開く攻撃面

ツールのdescriptionとツール呼び出しの結果は、ホストを経てモデルのcontextに入る。だからサーバーがそこに何を書いても、モデルはそれを読む。代表的な2つの攻撃は、どちらもここから生まれる。

• Tool Poisoning Attack（TPA）：Invariant Labsが2025年4月に命名し、PoCを公開した攻撃だ。MCPサーバーのツール説明（description）に悪意ある指示を隠すと、モデルはユーザーには見えないそのテキストを読み、ユーザーの知らないうちに従うことがある。

• Rug Pull：Invariant Labsが同じ記事で説明した攻撃で、ユーザーが承認した後にサーバーがツール定義を変える。Simon Willisonが引用したElena Crossの例のように、1日目に安全そうに見えるツールを承認したのに、7日目にはそのツールがAPIキーを攻撃者へ送るように変わっている、という具合で、ツール定義をインストール時点ではなく実行時にサーバーから受け取る構造から生まれる。tool仕様は、どのツールがモデルに公開されているかを示すUIを推奨する（SHOULD）だけで、変わった定義の再承認までは求めていないので、再承認はホストの役目になる。

まとめ

まとめると、MCPはfunction callingを置き換えるものではなく、その上に載った標準だ。モデルがツールを呼び出す方法は依然としてtoolsパラメータとtool_useループであり、2つのプロトコルの間はホストが翻訳する。2025-11-25改訂版でMCPが加えたのは、動的な発見、stateful session、Tool以外のプリミティブ、そしてサーバーからクライアントへ向かう呼び出しだった。2026-07-28改訂版でセッションがなくなりSamplingがdeprecatedになると、残るのはツール一覧とコンテキストを実行時にやり取りする契約だ。その契約があるからこそ、ツール定義を汚染したり、こっそり書き換えたりする攻撃も同じところから生まれる。MCPサーバーをもう一つつなぐときは、そのサーバーが何をできるのかとあわせて、定義が変わったときにホストが知らせてくれるかどうかも確かめてみてほしい。

MCPがエージェントに何をできるようにするかの問題なら、何を知らせるかはCLAUDE.mdやAGENTS.mdのようなコンテキストファイルの問題だ。それらのファイルがエージェントにどのように読まれ、どこまで守られるのかはコンテキストファイルで扱う。

今では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を一行書く前に一度立ち止まり、「これはどの分類の状態だろう？」と問いかけてみてほしい。

税金計算や申告ステータスの判定といったビジネスルールがコンポーネントやフック、utilsに散らばっていて、ルールが一つ変わるたびに複数のファイルを探して直しているフロントエンド開発者に向けた記事である。最後まで読めば、そのルールをReactに依存しない純粋関数へ移す方法と、その分離をどこで止めるかを判断する基準が得られる。

例はすべて総合所得税の計算で説明する。筆者が関心を持っているドメインである。

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

答える前に、用語を一つそろえておく。この記事でいうドメインモデルは、ビジネスの概念とその上で働くルールを一緒に持つものである。APIレスポンスの型のように、データがどんな形でやり取りされるかだけを定義するデータモデルとは異なる。コンポーネントがレスポンスの構造に直接依存すると、バックエンドのスキーマが変わるたびにフロントエンド全体が揺らぐのも、この違いのためである。ドメイン、ドメインモデル、ドメインオブジェクト、ドメインオブジェクトモデルという4つの用語の違いは、ドメイン用語に別途まとめておいた。

ソフトウェア設計に深い関心を持つ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が万能ではない現実的な理由がある。

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インスタンスが対応するシリアライズ形式ではないため、受け渡しの時点で失敗する。

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

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

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

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

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

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