upstream-dependency-debug

バグ修正としての依存関係のアップグレード

役割：バグに対する最もすっきりした修正が、ローカルな回避策を書くことではなく、依存関係をアップグレードすることである場合の、判断と実行の方法論です。これは方法論の強化であり、単独で呼び出すことも、PDCA ホストの技術分析フェーズで（「実行可能な解決策がない」分岐に対する楽観的な選択肢として）参照することもできます。

このスキルが必要な理由

エンジニア（および AI エージェント）がバグに遭遇すると、反射的にローカルでパッチを当てようとします。ガードを追加したり、タイマーを調整したり、要素を隠したり、CSS ルールを上書きしたりします。しかし、根本原因が上流の依存関係にある場合、この反射はしばしば間違いです。ローカルパッチは、他人のバグを覆い隠す回避策となり、回避策が積み重なっていきます。

このスキルが断ち切ることを目指すパターンは次のとおりです。

バグの本当の修正は「ライブラリをアップグレードすること」なのに、誰も上流のチェンジログを確認しません。その代わり、ローカルな回避策が3層も積み重なります。マジックナンバーのタイマー、UX の劣化、プラットフォームに黙って無視される CSS の上書きです。それぞれの層は、実機で少しずつ異なる形で失敗します。数週間後、ようやく誰かがチェンジログを読み、修正が2つ前のマイナーバージョンでリリースされていたことに気付きます。そして、package.json の1行のバージョン変更で、3つすべての回避策が置き換えられます。

実例（情報を加工済み）：リッチテキストエディターのタスクリスト項目で、iOS の IME 入力中に異常な選択ハイライトが表示されていました。ローカルな回避策を3つ試しましたが、いずれも実機では失敗しました。最後の回避策が失敗した理由は、iOS が入力中にネイティブの ::selection 背景を強制的に描画し、CSS では上書きできないためです。実際の修正は、エディターライブラリをマイナーバージョン2つ分アップグレードすることでした。そのバージョンでは、上流側ですでに入力中のウィジェット再利用に関する問題が修正されていました。ローカルコードの変更はゼロです。

この事例から得られる教訓は次のとおりです。

回避策を書く前に、「このバグはすでに上流で修正されていないか？」と確認してください。依存関係を1行でアップグレードするほうが、ローカルパッチよりも安価で、正確で、長持ちすることがよくあります。

使用する場面

有力な兆候（どれか1つで十分です。「まず上流を確認する」という習慣を忘れてしまいがちなので、このスキルは積極的に呼び出すことを想定しています）。

• バグが名前の分かっているサードパーティ製ライブラリ、フレームワーク、または APIに関係し、特定のバージョンとの相関がある。
• 症状がプラットフォームまたはライブラリに固有です。たとえば、デスクトップ版 Chrome では再現しないのに iOS では再現する、特定のフレームワークの描画経路でのみ発生する、または最近の依存関係のアップグレード後にのみ発生する。
• 気付かれにくい失敗：呼び出しの流れは完全に見え、パラメーターも正しく、ログにも実行が記録されているのに、動作が誤っている。この場合、ライブラリが処理するはずのプラットフォームまたはランタイムによる介入が原因であることがよくあります。
• 回避策が積み重なっている：すでにローカルパッチを1つか2つ書いたものの、それぞれ部分的にしか機能しない、または新たな劣化を招いている（マジックナンバーによるタイミング調整、UX の低下、効果のない CSS など）。
• 特定のプラットフォームで !important による上書きが気付かれないまま失敗する CSS／レイアウトのバグ。CSS では修正できない、プラットフォームが強制する描画が原因である可能性を強く示しています。

4 段階の判断順序

上記のシグナルが確認されたら、ローカルの修正を加える前に、次の順序で判断してください。

1. バグの原因を特定する：上流側と自分たちのコードのどちらに原因がある可能性が高いでしょうか。上流側が原因であることを示すシグナルは、プラットフォームやライブラリ固有の挙動に症状が関連している、特定の環境でのみ再現する、問題のあるレイヤー（選択、合成、描画）をライブラリが担っている、といったものです。
2. 上流側が原因である可能性が高い場合は、依存関係の Changelog / Release Notes / Issues を確認し、該当する修正を探します。症状に関連するキーワード（例：composition、selection、Safari、iOS、widget、cursor）で依存関係の変更履歴を検索します。修正が含まれるバージョンがあるか、またプロジェクトが現在それより古いバージョンを使用しているかを確認してください。
3. ローカルの回避策を書くよりも、依存関係のアップグレードを優先します（パッチ／マイナーアップデートはセマンティックバージョニング上のリスクが低いため）。セマンティックバージョニングに従うライブラリでは、同じメジャーバージョン内のマイナー／パッチアップデートに、契約上、破壊的変更はありません。
4. アップグレードが実行できない場合にのみ、回避策を検討します。唯一利用可能な修正バージョンに破壊的変更がある、プロジェクトのバージョンが固定されている、または上流側でまだ修正されていない場合などです。回避策が必要な場合は、発動条件と追跡対象の上流の Issue を記載し、一時的なものとして明示してください。

アンチパターン（禁止事項）

1. Changelog を確認せずに回避策を重ねる — 最もよくある失敗です。上流の修正がすでに存在する可能性があります。
2. プラットフォームが描画を制御する経路で、「CSS の !important で対処できる」と決めつける — 一部のプラットフォームの挙動（例：iOS で合成中の ::selection）は、CSS を完全に無視します。
3. マジックナンバーを使ったタイミングの回避策（compositionend の 120ms 後に setTimeout を実行するなど）— 症状を覆い隠し、負荷が高い状況で機能しなくなり、原因には対処できません。
4. UX を損なう回避策（合成中にウィジェットをソースコードのマーカーに置き換えるなど）— ユーザー体験を犠牲にしてバグを隠し、多くの場合、完全に隠すこともできません。
5. Changelog の破壊的変更に関する記載を実際に読まずに、「アップグレードはリスクがありそうだ」という理由だけで回避策を選ぶ — 通常、そのリスクは回避策の保守コストよりも小さいものです。

アップグレードの実施規律

アップグレードすると決めたら、安全に実施してください。以下の確認項目は、それぞれ実際に発生した失敗に対応しています。

• パッケージマネージャーの一貫性：プロジェクトで実際に使用されているパッケージマネージャーを使用します。システムレベルの packageManager フィールドではなく、追跡対象のロックファイル（git ls-files package-lock.json yarn.lock pnpm-lock.yaml）から判断してください。システムが pnpm を強制していても、プロジェクトでは npm を使用している場合があります。両者を混在させると、ロックファイルが汚染され、重複するパッケージバージョンが生じます。混在させないでください。
• アップグレード後の検証手順：typecheck + build + 単体テスト一式 + 実機／対象環境での検証を行います。型チェックに合格しても、対象デバイスで実行時に問題が発生する依存関係のアップグレードは、完了したとは言えません。
• セマンティックバージョニング上のリスク評価：同じメジャーバージョン内のパッチ／マイナーアップデートは、セマンティックバージョニングに従うライブラリではリスクが低いものです（ライブラリが実際にセマンティックバージョニングに従っているか確認してください。多くのライブラリは従いますが、そうでないものもあります）。メジャーバージョンを上げる場合は、破壊的変更の一覧を読み、項目ごとに影響を評価する必要があります。
• 重複排除の確認：アップグレード後に npm ls <pkg>（またはプロジェクトのパッケージマネージャーに相当するコマンド）を実行し、解決されたバージョンが 1 つだけであることを確認します。古い 1.5.0 のエンティティが新しい 1.5.2 と共存するなど複数バージョンが混在すると、型の非互換性や原因を追跡しにくい不可解なエラーが発生します。

結果表

結論	アクション
✅ 上流で修正済みで、アップグレードのリスクが低い	依存関係をアップグレードすることを推奨する解決策とします。アップグレードを推奨案として、解決策の検討に進みます。
⚠️ アップグレードにリスクがある（メジャー変更／破壊的変更）	解決策の検討では、アップグレードと回避策を並べて提示し、リスクのトレードオフに基づいて判断します。
❌ 上流で未修正、またはアップグレードが実行不可能（バージョン固定／破壊的変更）	回避策に切り替えます。ただし、一時的な対応であること、適用条件、および追跡対象の上流の問題を明記します。

他のスキルとの関係

スキル	関係
PDCA hosts	技術分析の段階でPDCAホストから参照されます（「業界全体に実行可能な解決策がない」分岐に対する、楽観的な対となるものです）。ホスト経由で呼び出された場合は、ホストがすでに特定した根本原因を起点として、4ステップの判断順序に従ってください。この点についてはホストが信頼できる情報源です。
effective-web-research	ステップ2（変更履歴の確認）では、このスキルの調査手法が役立ちます。まず公式情報源（ライブラリ独自の変更履歴サイト）を確認し、情報の新しさを確認して、重要な主張を複数の情報源で検証してください。
runtime-evidence-debug	変更履歴を確認した後も根本原因の確度が曖昧な場合、このスキルの次善策（既知のプラットフォーム／フレームワークの問題をウェブで調査すること）は、このスキルのステップ2と重複します。このスキルは修正方針の判断を担い、runtime-evidence-debugは証拠収集の方法論を担います。

ドメイン固有の知識の境界

このスキルが扱うのは、一般的な方法論のみです。特定のエディターフレームワークのどのバージョンでどの構成上の不具合が修正されたか、あるいはUIライブラリにおけるバージョン固有の描画上の癖など、ライブラリ固有の知識は、各プロジェクトのドキュメント（AGENTS.mdまたは修正ログ）に記載してください。この理由は、ライブラリ固有の変更履歴のキーワードやバージョン番号は古くなりやすく、そのライブラリを使用するプロジェクトにしか関係しないためです。これらを汎用スキルに含めると、保守の負担が増え、話題が分散します。

このスキルを適用する際、プロジェクトのドキュメントに対象の依存関係に関するライブラリ固有の変更履歴のキーワードが記載されている場合は、それを検索語句の選定に活用してください。このスキルが示すのは変更履歴を確認することであり、プロジェクトのドキュメントが示すのは何を検索するかです。

単独での呼び出し

ワークフローを介さずに直接呼び出す場合は、使用するタイミングから始めます。該当するシグナルを確認してから、4ステップの判断順序に従ってください。出力は、結果表の結論と、アップグレードを選択した場合のアップグレード時のエンジニアリング規律チェックリストです。