stalemap

インストール · 使用例 · 仕組み · 結果 · 変更履歴

コーディングエージェントは、カットオフ日で途切れるトレーニングデータからライブラリを学習します。プロジェクトでそれより新しいバージョンを固定すると、エージェントは古い API に対応したコードを書きます。たとえば、AI SDK 7 に対して maxSteps、zod 4 に対して required_error、Next 16 に対して middleware.ts を使います。

stalemap は、モデルのトレーニングのカットオフ以降に変更された依存関係を見つけ、次の 3 つの方法で変更内容をエージェントに伝えます。

• ノート： 変更点を短くまとめ、優先度順に並べたリストを AGENTS.md または CLAUDE.md に書き込み、エージェントが作業を始める前に読めるようにします。
• 編集時ガード： 編集のたびに、プロジェクト自身の型チェックを実行します。カットオフ以降に変更された API をコードが使っている場合、コンパイラエラーと、それに該当するノート（または説明しているリリースノートやアップグレードガイドのセクション）をエージェントにすぐ提示します。コンパイルは通るものの、移動された機能を使っているコードも報告します。
• search_changes： エージェントが「next.config のエイリアスを解決する」のように自分の言葉で問い合わせると、該当する変更とその情報源を返す MCP ツールです。

JavaScript と TypeScript のプロジェクトで、Claude Code、Cursor、Codex、OpenCode、または任意の MCP クライアントと連携します。

事前登録されたブラインドベンチマークでは、2026 年 6 月以降にリリースされた変更から作成した 66 個のタスクにおいて、stalemap を使用した claude-sonnet-5-5 エージェントはセッションの 89% に合格しました。支援なしでは 68%、各編集後に通常の tsc --noEmit フックを実行した場合は 73% でした。結果をご覧ください。

ステータス

• npm： 最新リリースは stalemap 0.4.1 です。これは保留された v4（0.4.0）でテストされたビルドに、ノートブロックのフッターを 1 行追加したものです。npx stalemap、Claude Code プラグイン、GitHub Action はすべてこのバージョンを実行します。変更履歴をご覧ください。
• プロジェクトはまだ初期段階で、1 人でメンテナンスしています。

インストール

Claude Code プラグイン

/plugin marketplace add Umair/stalemap
/plugin install stalemap@stalemap

プラグインには以下が追加されます。

• SessionStart フック。セッションで使用するモデル向けのノートを Claude のコンテキストに追加します（起動時、/clear の後、コンパクションの後に実行され、ファイルは書き込みません）。
• PostToolUse フック。Write または Edit の後に編集時ガードを実行します。
• stalemap MCP サーバーと 2 つのスキル（/stalemap:sync はノートブロックを書き込み、upgrade はパッケージを使用またはアップグレードする前に変更を調べるよう Claude に指示します）。

フックと MCP サーバーは npx -y stalemap@latest を実行するため、npm の最新リリースを使用します。MCP ツールは search_changes、package_changes、project_changes、check_notes です。

コマンドライン

npx stalemap            # preview what changed and the block it would write
npx stalemap sync       # write the block into AGENTS.md or CLAUDE.md
npx stalemap check      # for CI: exit 1 when the block is missing or stale
npx stalemap guard src/**/*.ts   # run the guard by hand

このブロックは と の間に配置します。その外側のテキストには一切触れません。Claude Code は CLAUDE.md を読み込みます。メモが AGENTS.md にある場合は、CLAUDE.md に @AGENTS.md を追加するか、--target CLAUDE.md を渡してください。

その他のエージェント：setup --agent

stalemap setup --agent cursor             # or codex, opencode, claude
stalemap setup --agent codex --dry-run    # print the changes, write nothing

エージェントごとにコマンドを1つ実行すると、メモを書き込み、MCP サーバーを登録し、ガードをエージェントの編集後フックとして、コミット可能なプロジェクトファイルにインストールします。既存の設定ファイルにマージし、書き込んでいないエントリはそのまま保持します。また、再実行しても変更はありません。

注意点が1つあります。実際の Cursor、Codex、OpenCode のインストール環境ではまだ試されていません。Cursor は現時点で postToolUse フックのコンテキストをモデルに渡さないため、setup は未報告の検出結果をフォローアップメッセージとして送信するストップフックのフォールバックを追加します。

任意の MCP クライアント

{ "mcpServers": { "stalemap": { "command": "npx", "args": ["-y", "stalemap@latest", "mcp"] } } }

GitHub Action

- uses: Umair/stalemap@main
  with:
    model: claude-opus-5-5          # fail CI when the notes are missing or stale
    # mode: comment                 # or comment on PRs that change dependencies

コメントモードには permissions: pull-requests: write が必要です。変更された依存関係（モデルが把握している内容 → 固定されたバージョン）をそれぞれのメモとともに一覧表示し、後続のプッシュではコメントを更新します。

メモの内容

Next.js + AI SDK アプリと claude-sonnet-4-5（カットオフ日 2025-07-31）の場合の抜粋：

**ai** 4.3.16 → 7.0.142 (major)
- `CoreMessage` was removed; use `ModelMessage`. [types]
- `convertToCoreMessages` was removed; use `convertToModelMessages`. [types]
- `streamText()` options no longer accept `maxTokens`, `maxSteps`, `toolCallStreaming`, … [types]

**next** 15.4.0 → 16.4.2 (major)
- `revalidateTag()` now requires `profile` (in `next/cache`) [types]
- `NextMiddleware` is deprecated: Use `NextProxy` instead. Middleware has been renamed to Proxy. (in `next/server`) [types]

出力全体：examples/next-ai-app.claude-sonnet-4-5.md。

仕組み

1. どのモデルですか？ --model、Claude Code、Codex、OpenCode、Gemini CLI 用に設定されたモデル、または $ANTHROPIC_MODEL を使用します。学習のカットオフ日は models.dev から取得します（組み込みのフォールバック表もあります）。または、--cutoff YYYY-MM-DD を指定してください。
2. モデルは何を知っていましたか？ 各依存関係について、カットオフ日より少なくとも30日前に公開された最新の安定版を確認します（--margin）。
3. どの依存関係が対象ですか？ コードがインポートする直接依存関係（ローカルでスキャン）に加え、設定ファイルが設定する依存関係（tsconfig.json、next.config.*、Prisma スキーマ、Vitest と ESLint の設定など）も対象です。--all を指定すると、すべての直接依存関係を確認します。固定されたバージョンは node_modules またはロックファイル（npm、pnpm、yarn、bun）から取得します。
4. 何が変わりましたか？
   • 型： 両バージョンの .d.ts ファイルをダウンロードし、TypeScript コンパイラー API で比較します。削除、名前変更、移動されたエクスポート、新しい必須パラメーター、削除または新たに必須となったオプション、新しい @deprecated タグとそのヒントを確認します。
   • リリースノート： パッケージの変更履歴または GitHub Releases を、破壊的変更の兆候と使用中の API に基づいて評価します。削除された項目には、変更履歴で告知された名前変更から置き換え先を示します。
   • アップグレードガイド（--guides）：新しいデフォルト値や名前が変更されたファイル規則など、型シグネチャーに反映されない変更を対象とします。Claude が各ガイドを短いメモにまとめ、ガイドからの引用が含まれる場合にのみ、そのメモを残します。
   • 検証済みの例（--examples）：先頭のメモの下に Before → After の行を追加します。Claude が作成し、固定したバージョンに対してコンパイルできた場合にのみ残します。
5. 予算に合わせます。 プロジェクトで使用しているものに関するメモを優先します。インポートされた API、メンバー、プロパティ、設定する設定キー、ファイル名が対象です。デフォルトの予算は1,800トークンです（--budget）。

ガードは編集のたびに実行されます。プロジェクト独自の tsc を実行し、次の順序で検出結果を報告します。

1. カットオフ日以降に変更された依存関係に起因するコンパイルエラーと、修正方法を示す対応するメモ。エラーを説明するメモがない場合は、エラーとその周辺コードを使って検索し、パッケージの型変更、リリースノート、またはアップグレードガイドから該当する箇所を表示します。
2. 型チェックは通るものの、変更された項目：
   • 移動された設定キー（Next 16 の experimental.ppr など）；
   • 移動されたメンバー（axios 1.20 の HttpStatusCode.PayloadTooLarge → ContentTooLarge など）；
   • 名前が変更されたファイル規則（middleware.ts → proxy.ts など）；
   • プロジェクトの TypeScript が受け付けない tsconfig.json のオプション。
3. コンパイラーが検出したその他のエラー：編集したファイル内のエラー、それをインポートするファイルで新たに発生したエラー、および他のファイルで発生した一部のエラー。これらは依存関係が変更されたことを示すものではありません。

そのため、通常の型チェック用フックはガードの一部にあたります。STALEMAP_GUARD_TSC=0 を設定すると、ガードは依存関係の変更のみを対象にします。非推奨の報告は STALEMAP_GUARD_DEPRECATIONS=1 を設定した場合にのみ行われます。

search_changes（stalemap search <query> でも実行できます）は、stalemap がプロジェクトの依存関係について検出したすべての内容を検索します。すべての型変更、すべてのリリースノート項目、キャッシュされたアップグレードガイドのメモ、および新しいメジャーバージョンの場合はガイドの本文が対象です。順位付けには、単語と分割した識別子（resolveAlias は「resolve alias」に一致します）を対象とする BM25 を使用し、プロジェクトで使用されているものを重視します。最初の検索では分析キャッシュからインデックスを作成し、以降の検索はオフラインで高速に実行されます。

stalemap probe は、モデルが実際に必要とするメモを測定します。変更ごとにモデルにコードを書かせ、固定したバージョンに対して回答の型をチェックし、メモを付けて再実行します。モデルがすでに正しく対応できるメモは、ブロックから除外されます。Probe のタスクでは古い API の名前を示すため、モデルが変更に気付かず自発的に認識する能力ではなく、変更箇所を示されたときに把握できるかを測定します。これは、事前に示されずに気付くより簡単です。

すべてのコマンドとオプション（Claude が作成する要約用の --llm や、動きの速い約200のパッケージを対象とする事前計算済みレポート（まだホストされていません）など）については、stalemap --help を実行してください。

お使いのマシンから送信される情報

• パッケージ名とバージョンは、npm レジストリ、GitHub（変更履歴とリリース。利用可能な場合は GITHUB_TOKEN または gh のログイン情報を使用します）、および models.dev に送信されます。
• ソースコードがアップロードされることはありません。インポートのスキャンはローカルで行われます。
• --llm、--examples、または --guides を使用すると、型の差分、リリースノートの抜粋、ガイドのテキスト、およびインポートする API の名前が Claude（Anthropic API または claude -p）に送信されます。コードは含まれません。
• probe を使用すると、プローブのプロンプトが選択したプロバイダーに送信されます。
• $STALEMAP_PRECOMPUTED_URL が設定されている場合、パッケージ名のみがそのホストに送信されます。バージョンは送信されません。

キャッシュは ~/.cache/stalemap に保存されます（$STALEMAP_CACHE を設定すると保存先を変更できます）。

結果

すべての結果は、エージェントには見えない非公開テストで評価した、ヘッドレスの Claude Code セッションから得られたものです。各タスクは 2 つのモードで実行されます。ワンショット（ファイルツールのみ）とチェックあり（エージェントは npm test と tsc も実行できます）です。信頼区間は、2 段階のブートストラップ（タスク、次に実行）から算出しています。信頼区間がゼロを含まない場合に限り、差を勝ちとみなします。

保留データ v4（プロトコル、claude-sonnet-5-5 の結果、claude-sonnet-4-5 の結果）は、ブラインド方式で事前登録されています。

• 2026 年 7 月から 10 月にかけて、人気のある npm パッケージ 33 個がリリースした、破壊的変更、非推奨化、動作変更のすべてから、シードを使って抽出した 66 件のタスク。
• タスク、条件、モード、モデルごとに 3 セッション。
• v4 の結果が出る前に、ビルドを freeze/v4-final として凍結。

構成	claude-sonnet-5-5	claude-sonnet-4-5
エージェント単独	68%	46%
編集ごとに通常の tsc --noEmit フックを実行	73%	53%
+ stalemap（メモ、編集時のガード、search_changes）	89%	64%
+ 変更内容を示す手書きの 1 行ヒント（上限）	98%	78%

事前登録された 4 つの比較すべてで勝ちました。

比較	モデル	差	信頼区間
stalemap 対単独（主要比較）	claude-sonnet-5-5	+20.7 ポイント	[13.6, 28.3]（95%）
stalemap 対 tsc フック	claude-sonnet-5-5	+16.4 ポイント	[7.6, 26.0]（98.3%）
stalemap 対単独	claude-sonnet-4-5	+17.9 ポイント	[7.6, 28.8]（98.3%）
stalemap 対 tsc フック	claude-sonnet-4-5	+10.6 ポイント	[0.3, 21.7]（98.3%）

• 最も効果が大きいのはワンショットです。 claude-sonnet-5-5 では、stalemap ありで 89%、支援なしで 60% です。チェックありの場合は、89% 対 77% です。
• 古い API を使った編集が減少： stalemap を使った claude-sonnet-5-5 セッションでは、エージェントの最初の編集で古い API が使われた割合は 11% でした。支援なしでは 27% でした。
• コスト：
  • claude-sonnet-5-5：セッションあたりの中央値は 0.050 ドルで、支援なしでは 0.041 ドルです。ターン数はほぼ同じです（7 対 8）。
  • claude-sonnet-4-5：より高く、0.124 ドル対 0.085 ドル、79 秒対 47 秒です。
• 最新のモデルでも必要です。 claude-sonnet-5-5 でさえ、単独ではこれらのタスクの 3 分の 1 に失敗し、1 行のヒントでほぼすべてを解決できました。stalemap はその差の約 3 分の 2 を埋めます。
• サードパーティ製ツールとの比較結果は公開していません。

以前のテストスイート（すべて claude-sonnet-4-5）：

• 保留データ v1（事前登録、10 件のタスク）：単独の 50% に対し 83% で、勝ちです。
• 保留データ v2（ブラインド、10 件のタスク）：単独の 23% に対し 35% で、引き分けです。
• 保留データ v3（ブラインド、59 件のタスク）：単独の 43% に対し 53% で、勝ちです。通常の tsc フックとは引き分けでした。0.3 と 0.4 での変更は、v3 のトランスクリプトで明らかになった問題、つまりガードがプロジェクト独自の TypeScript を実行していなかったこと、メモと検索から修正内容のテキストが失われていたこと、検索の使用頻度が低すぎたことを受けて行われました。v4 は、これらの変更を検証する初のブラインドテストです。

留意点：

• 同一の作成者です。 stalemap、ハーネス、プロトコルの作成者は同じです。v4 のタスクは、stalemap のコード、メモ、結果を一度も見ていない別のセッションで作成されました。同等のブラインド条件で独立したレビュアーがタスクを確認し、パイロットルールを適用しました。タスク、非公開テスト、サンプリングファイル、レビュー、パイロット、セッションごとの結果は bench/ にあり、確認できます。
• JavaScript と TypeScript、Claude モデル 2 種です。 ほかのエージェントやモデルは測定していません。
• 事前登録と事後分析： 主張の根拠となるのは、実行前にプロトコルで固定された比較のみです。v3 後に行った変更は事後分析にあたるため、v4 が必要でした。

制限事項

• JavaScript と TypeScript のみが対象で、package.json は 1 つです（ワークスペースの探索にはまだ対応していません）。
• 型定義がバンドルされていないパッケージは、リリースノートに関する注記のみが対象です（@types/* は差分比較されません）。
• 使用状況の追跡は、インポートされた名前と x.member へのアクセスまでです。client.messages.create({ temperature }) のようなインスタンスチェーンは追跡されません。
• 型シグネチャに現れない動作変更は、リリースノートと（--guides を指定した場合は）アップグレードガイドからのみ取得されます。どちらにも設定名が記載されていなければ、stalemap でも特定できません。
• リリースノートのランキングはヒューリスティックであり、文章中心の変更履歴ではノイズが多くなります。
• エージェントが正しい注記を無視する場合もあります。ガードはコンパイルに失敗するものと、コンパイルは通るものの一部（移動されたキーやメンバー、名前が変更されたファイル）を検出します。それ以外の、コンパイルが通る古いコードは、注記に記載されている場合にのみ検出されます。

ベンチマークの実行

ハーネス、タスク、プロトコル、結果は bench/ にあります。概要は次のとおりです。

npm install && npm run build
mkdir -p bench/.work/template-heldout-v4-latest && cp bench/heldout-v4/templates/latest/*.json bench/.work/template-heldout-v4-latest/
(cd bench/.work/template-heldout-v4-latest && npm install --ignore-scripts)
npx tsx bench/heldout-v4/validate.ts      # reference solutions pass, stale versions fail
npx tsx bench/run.ts --suite heldout-v4 --model claude-sonnet-5-5 --arms alone,stalemap-full,tsc-hook,oracle --examples --guides --reps 3
npx tsx bench/analyze.ts bench/results/<dir>

セッションは、サインイン済みの Claude Code で実行されます。v4 の全実行ではモデルごとに約 1,600 セッションが必要なので、まずは --reps 1 または --tasks を指定してください。トランスクリプトは bench/results/<dir>/runs/ に出力されます。このディレクトリは Git の追跡対象外です。実行方式、分離、シャーディング、コストについては、bench/README.md を参照してください。

開発

git clone https://github.com/Umair/stalemap && cd stalemap
npm install
npm run build       # → dist/cli.js
npm test            # node:test via tsx
node dist/cli.js scan --cwd test/fixtures/next-ai-app --model claude-sonnet-4-5
npm link            # optional: put your local build on your PATH

ライブラリとしての使用方法：

import { runStalemap, packageChanges, checkBlock } from "stalemap";

const { rendered } = await runStalemap({ cwd: ".", model: "claude-opus-5-5" });

貢献

バグ報告、誤った注記や不足している注記の報告、新しいベンチマークタスクの提案を歓迎します。CONTRIBUTING.md を参照してください。セキュリティ上の問題を報告する場合は、SECURITY.md を参照してください。

ライセンス

MIT