ln-33-code-modernizer

コードのモダナイゼーション

目標： 新しい設計によって、人のワークフローにおける摩擦、保守作業、リスク、依存関係の重複、または納品物のコストが測定可能な形で減る場合に限り、対象範囲を限定した機能をモダナイズします。動作を維持し、移行を分離し、正味の価値を生まない変更は元に戻します。

実行契約： 順序付きのチェックボックスは完了の定義です。各項目を内部で、具体的な証拠がある場合は PENDING、条件が存在しない証拠がある場合は CLEARED、不足がある場合は UNPROVEN として管理してください。読むこと、委任すること、ツールが失敗することは証明にはなりません。各セクションの後に項目を再評価してください。回答を返す前に、すべての PENDING を解消し、PROVEN と CLEARED のみを数えます。すべての不足について、このスキルの判定ルールと承認ルールを適用してください。 ユーザーの意図、範囲、既存の承認を維持してください。承認された作業は続行し、重大な未解決の選択肢、または必要な外部承認がある場合に限り、確認してください。重大なリスクに応じて調査の深さを調整し、確認項目を黙って省略しないでください。依存関係と安全性の順序を維持してください。それ以外の場合は、各要件に適した検証方法を選択してください。

ツールの使い分け

必要なこと	推奨ツール	使用する場面	代替手段
現在の仕組みと利用箇所の把握	ネイティブのファイル検索と、言語サーバーまたはホストネイティブのコードインテリジェンス	契約、呼び出し元、設定、データ、ライフサイクル、テストのマッピング	インポート、シンボル、ルート、設定を対象とする絞り込み検索と、該当箇所の直接確認
既存のプラットフォーム機能	マニフェスト、ロックファイル、ランタイム API、最新の公式ドキュメント	すでに利用可能な機能に対する、新たな依存関係やカスタムコードの追加を避ける	リポジトリ内の例とソースコードの確認。最新のドキュメントが入手できない場合は、機能を UNVERIFIED と記録
外部の置き換え候補	公式パッケージレジストリ、ソースリポジトリ、ドキュメント、リリース情報、アドバイザリー、ライセンス情報	保守されているソフトウェアとカスタム実装の比較	一次情報に基づくウェブ調査。人気ランキングだけに頼らない
ベースラインと価値	ビルド出力、バンドル分析、コードの棚卸し、ベンチマーク、不具合、保守の証拠	モダナイゼーションで改善すべき内容の定義	範囲と制約を記録した、再現可能な静的カウント
安全な移行	Git による分離、対象を絞った編集、ネイティブのパッケージマネージャー、リポジトリの生成コマンド	対象範囲を限定した 1 つの機能とその利用箇所の置き換え	ユーザーによる変更や生成状態を保護できない場合は停止
検証	リポジトリで定義されたビルド、lint、型、テスト、スモーク、パッケージング、ランタイムの各チェック	移行前および変更を維持する各ステップの後	既存の証拠で重要な契約を証明できない場合は、最小限のポートフォリオ対応を選択
納品物の分析	既存のバンドルアナライザー、サイズレポート、起動プロファイル、依存関係レポート	バンドルサイズ、読み込み経路、またはランタイムコストが目標に含まれる場合	再現可能なファイルおよび圧縮のルールによるビルド成果物の比較

外部パッケージが存在するというだけで、動作中のカスタムコードを置き換えないでください。保守されていない依存関係を導入したり、互換性のないライセンスを受け入れたり、すべての利用箇所とロールバック条件を把握する前に旧経路を削除したりしないでください。

証拠のルール

• システム全体の複雑さを比較してください。削減されたコードとリスクから、新たな依存関係、アダプター、運用、移行のコストを差し引きます。
• 外部候補に関する主張には、保守状況、セキュリティ、ライセンス、ランタイムサポート、API との適合性について、最新の一次情報による裏付けが必要です。
• バンドルまたはパフォーマンスの価値には、比較可能な測定が必要です。行数の削減だけでは、より良い設計の証明になりません。
• 依頼で契約の移行が明示的に許可されていない限り、公開された動作を維持してください。

チェックリスト

1. モダナイゼーションの対象を定義する

• 範囲を限定した機能、保護すべき成果、現在の課題、影響を受けるユーザー・開発者・運用担当者、成功指標、制約、明示的な対象外事項を特定し、根拠のない意図の推測にはその旨を明記します。
• リポジトリの指示を読み、Git の状態、生成ファイル、パッケージマネージャーの方針、現在のユーザー変更を確認します。
• 現在の実装、公開契約、利用者、設定、永続化データ、ランタイム登録、テスト、運用手順を一覧化します。
• 改善が必要なワークフロー、保守、セキュリティ、互換性、重複、バンドル、起動、またはデリバリーのコストを特定します。
• コード変更の前に、動作と関連する定量的なベースラインを確立します。人が関わるワークフローでは、必要な手順や概念、最初の有意な結果が得られるまでの時間、エラーの理解しやすさ、復旧にかかる労力など、再現可能な観察結果を用います。
• 各移行手順を、無関係な変更やユーザー所有の変更に触れずに取り消せるよう、作業を分離します。
• 作成した絶対パス、ワークツリー、プロセス ID、キャッシュ、レポート、一時成果物をすべて記録する、この実行専用のリソース台帳を作成します。既存のリソースをクリーンアップ対象として登録してはいけません。
• 根拠から対象範囲内に価値あるモダナイゼーションがないと判断した場合は NO_CHANGE を使用します。不可欠な根拠が入手できず、妥当な依頼上のメリットを評価できない場合は BLOCKED を使用します。

2. 最もシンプルで信頼できる設計を評価する

• 新しいパッケージを探す前に、言語、ランタイム、フレームワーク、プラットフォーム、およびすでに宣言されている依存関係の機能を確認します。
• 直接削除できる、古い互換性対応経路、並行する仕組み、未使用の拡張ポイント、重複した統合、移行途中のアダプターを特定します。
• 外部の候補について、機能の適合性、API の安定性、メンテナンス状況、セキュリティ履歴、ライセンス、所有者、リリース頻度、サイズ、ランタイムのサポート、エコシステムとの互換性を評価します。
• 想定するバージョンに合致する公式ドキュメント、リポジトリのリリース情報、勧告、パッケージメタデータから、候補の主張を検証します。
• 移行ガイド、破壊的変更、設定モデル、ライフサイクル、障害時の挙動、推移的依存関係、撤退方針を確認します。
• 置き換え候補について、セマンティクスの差異に関する台帳を作成します。入力の正規化、Unicode／時刻／日付の挙動、精度、順序、エラー、キャンセル、ストリーミング、並行処理、セキュリティ制限、および現在の契約に関わるその他のエッジケースを記録します。
• それぞれが妥当な選択肢である場合は、現状維持、その場での簡素化、既存のプラットフォーム機能の利用、外部ソフトウェアの採用、機能の削除を比較します。真実や制御を隠すことなく手間を減らせる、安全な経路の中で最短のものを優先します。
• 関連する場合は、削減されるワークフローの手順と概念、結果が得られるまでの時間と復旧時間の差、削除されるコード、追加されるアダプター、依存関係とバンドルの差、移行の労力、運用上の変更、ロールバックの難しさ、残るロックインを見積もります。
• 最も新しい、または最も人気のある選択肢ではなく、根拠に裏付けられた価値対リスク比が最も高い選択肢を選びます。
• 選択した案には SELECTED、検討したものの選ばなかった案にはすべて REJECTED と記し、各判断を決めた根拠やトレードオフを記録します。
• ライセンス、公開契約、永続化データの移行、ベンダーへのコミットメント、または取り消せない運用上のトレードオフによって製品の意図が変わる場合は、ユーザーの指示を求めます。使い捨て環境以外で移行を適用するには、必ず明示的な承認が必要です。

3. 範囲を限定して移行する

• 現在の外部コントラクト、重要な障害、データや設定との互換性を既存の証拠に照らして把握し、承認済みのテスト範囲内で KEEP、ADD、UPDATE、MERGE、DELETE、または根拠のある NO_TEST を実施します。役目を終えたテスト資産を削除し、一時的な特性評価や互換性の証拠には削除条件を設定します。
• 共通の代表的な入力と敵対的な入力を使って、差分テストや特性評価テストを実施します。既知の欠陥や明示的に変更された動作について、旧実装は比較の証拠であり、判断基準ではありません。差異は意図されたコントラクトに照らして解決します。
• コードベース全体で旧方式と新方式を混在させるのではなく、明確な境界を1つ設けて置き換えます。
• 依存関係と生成状態には、パッケージマネージャーや生成コマンドの標準機能を使用します。ロックファイルや生成された成果物を手作業で編集しないでください。
• 範囲を限定した機能に必要な呼び出し元、型、設定、依存性注入、ルート、イベント、シリアライズ、テスト、ビルドスクリプト、ドキュメントを更新します。
• 実際の利用者が必要とする場合に限り、後方互換性を維持します。一時的なアダプターごとに削除条件を定めます。
• 永続データや設定の移行は、明示した順序、再開可能性、異なるバージョンが混在する場合の動作、バックアップと復元の証拠、ロールバック、障害復旧を含めて、使い捨てのコピーに対して準備・テストします。ユーザーが対象環境を指定し、リハーサル済みの操作を承認した場合に限り、ほかの環境にも適用します。
• 未使用と報告された依存関係やモジュールを削除する前に、静的なインポート検索では見落とされる動的インポート、リフレクション、プラグインや設定の登録、コード生成、ビルドスクリプト、CLI、任意のランタイムパスを確認します。
• 検索とランタイムの配線確認によって利用者が残っていないと分かった後でのみ、旧実装を削除します。
• 差分を確認し、無関係なリファクタリング、過剰なフォーマット変更、依存関係の重複、デバッグコード、意図しない公開コントラクトの変更がないか調べます。

4. 検証し、維持するか破棄する

• 移行の各ステップの直後に、対象を絞ったコントラクトテストと回帰テストを実行します。
• リポジトリで必須のビルド、リント、型、テスト、スモークテスト、パッケージング、アプリケーション起動の各チェックを実行します。
• 合意したワークフロー、保守性、依存関係、バンドル、起動、パフォーマンス、または不具合の指標を、同等の条件でベースラインと比較します。
• バンドル関連の作業では、パッケージのメタデータだけでなく、実際のビルド構成、解析後および圧縮後のサイズ、チャンク分割、読み込み動作、ソースマップを比較します。
• エントリーポイントとルートのクリティカルパスを個別に評価します。合計バイト数が減っても、初回転送、リクエストのウォーターフォール、展開、解析／コンパイル、実行、キャッシュ無効化が悪化する場合があります。
• インポートやパッケージのメタデータを変更する前に、実際のバンドラーグラフ、モジュール形式、エクスポート、副作用メタデータ、対象ブラウザー／ランタイムに照らして、ツリーシェイキングや重複排除の主張を確認します。
• 採用する設計について、セキュリティ勧告、ライセンス、ランタイムのサポート状況、パッケージの出所、新たな推移的依存関係を確認します。
• 移行の失敗が高コストまたは検知困難になる場合は、ロールバックや削除の手順を実際に試します。
• 必要な動作と検証に合格し、定義した正味の価値が得られた場合に限り、移行を KEEP とします。
• 最終判断の前に、範囲を限定した移行の欠陥を解決し、影響するチェックを再実行します。価値が証明できない場合、回帰が残る場合、または正味の複雑さが合意したトレードオフを超える場合は、移行を DISCARD として範囲を限定した変更を元に戻します。
• 保持しないアダプター、計装、機能フラグ、パッケージ、生成された成果物は、その所有権が証明されている場合に限り削除します。実行所有の台帳パスと正確なプロセス ID のみをクリーンアップし、変更のある作業ツリーや既存の作業ツリーを保全して、報告された証拠を保持します。

5. 最終化と報告

• 保持した移行後に、古い実装、インポート、登録、設定、ドキュメント、依存関係が残っていないことを確認します。
• 関連する検証が最終的に保持された状態をカバーしていることを確認し、依然として有効な結果は再利用し、変更または未解決の失敗によって無効となったチェックは再実行します。最終的な差分を当初のモダナイゼーションスコープと比較します。
• オプションと移行の台帳を、最終的なコード、依存関係、測定値、ロールバック状態と照合します。
• 残存するカスタムコード、互換性アダプター、移行ステップ、運用上の変更、外部依存関係のリスクを特定します。
• 選択した境界付き設計が完全に保持され検証されている場合は MODERNIZED を使用します。独立して安全なサブセットが保持され、残作業が明示されている場合は PARTIAL を使用します。すべての移行が破棄されベースラインが復元された場合は NO_CHANGE を使用します。承認、安全性の証拠、または必要な検証が入手できない場合は BLOCKED を使用します。

セルフチェック

• 返す前に照合します。 項目レベルの証拠、要件のカバレッジ、矛盾、スコープ、判定、該当するクリーンアップを確認します。レポートまたは承認された成果物を修正します。有効な証拠は再利用し、リポジトリを自動的に再スキャンしたり、成功したコマンドを再実行したりしないでください。関連する変更、失敗、または未解決の証拠についてのみチェックを繰り返します。残っているギャップを開示します。

出力契約

ユーザーの言語で、この順序で報告します。5 つのフィールドをすべて保持し、各事実は一度だけ記載します。小規模な結果ではフィールドごとに 1 行を使用してもかまいません。空の表は省略し、リンクされた成果物はコピーしないでください。

1. 結果: スキル固有の判定とサポートされた成果。
2. スコープ: レビュー/変更したスコープ、除外、ベースライン、および重要な前提。
3. 証拠: 以下に示すスキル固有のフィールド。事実、推論、未検証の主張を区別します。成果物をリンクし、有用な場合は表を使用します。
4. 検証: チェック/結果、入手できない証拠、該当するクリーンアップ/外部状態。
5. 完了: Checklist: X/Y complete、Incomplete: None または各 UNPROVEN 項目の理由、成果への影響、および正確な次のアクション。残存リスクと必要な決定。

スキル固有の証拠: ケイパビリティ、保護された契約、コンシューマー、現在のコスト、および行動/価値のベースライン。検討した代替案と SELECTED / REJECTED の理由を比較します。移行ごとに: 変更、検証、比較可能な価値指標、および KEEP / DISCARD。コード/依存関係とワークフローの差分、影響を受けるテストアクション、残存するカスタムコード/互換性、未完了の移行作業、および実行が所有する測定/差分/ロールバック/クリーンアップの証拠を含めます。