migrate-to-shoehorn

migrate-to-shoehorn スキルの概要

migrate-to-shoehorn は、TypeScript のテストコードにある壊れやすい as アサーションを、@total-typescript/shoehorn ベースの書き方へ置き換えるためのスキルです。特に、as Type や as unknown as Type が大量に入り込んだテスト、さらに大きなオブジェクト型のせいでセットアップが冗長かつ意図を見えにくくしているケースで効果を発揮します。

migrate-to-shoehorn は何のためのスキルか

migrate-to-shoehorn を使うべきなのは、「ライブラリの学習」が目的ではなく、テストスイート全体を書き直さずに危険なテスト fixture を整理したいときです。このスキルは、次のような限定的で実務的なリファクタリングに特化しています。

• as Type を fromPartial() に置き換える
• as unknown as Type を fromAny() に置き換える
• テスト用の巨大な入力オブジェクトに含まれる不要なダミー記述を減らす

このスキルを入れるべき人

この migrate-to-shoehorn skill が特に向いているのは、次のようなケースです。

• キャストが多い TypeScript テストを保守している
• より安全に部分的な fixture を扱いたい
• どのアサーションパターンをどの shoehorn helper に対応させるべきか判断したい
• 一般論の TypeScript アドバイスではなく、狙いを絞ったリファクタリングをエージェントに実行・支援してほしい

導入前にいちばん重要な判断ポイント

最大の判断軸は対象範囲です。このスキルは明確にテスト向けであり、本番コード向けではありません。ここは重要です。shoehorn は、テストケースを作るために不完全なデータや、場合によっては不正なデータをあえて使いたい場面で役立ちます。そのうえで、生のアサーションよりも意図が分かりやすく、意識的な型の扱いに寄せられます。

汎用的なリファクタリング用プロンプトではなく migrate-to-shoehorn を使う理由

汎用プロンプトだと、as を機械的に消すだけで終わり、テストの意図を取り違えることがあります。migrate-to-shoehorn が実用的なのは、開発者が実際の移行でよく遭遇するパターンに合わせて調整されているからです。

• 大きなオブジェクト型に対する部分的なテスト入力
• ネガティブテストで意図的に不正データを渡すケース
• テストに関係ないダミープロパティを減らしたいケース

対象を絞っているぶん、推測に頼る場面が減り、安全でない置換も起こりにくくなります。

migrate-to-shoehorn スキルの使い方

migrate-to-shoehorn スキルの導入コンテキスト

プロジェクトで基盤となるライブラリを使うには、まず次をインストールします。

npm i @total-typescript/shoehorn

skills 対応環境にスキルとして導入する場合は、利用しているプラットフォームの通常のスキル導入フローに従ってください。その後、テストのリファクタリング作業時に migrate-to-shoehorn を呼び出します。

まず読むべきファイル

最初に確認すべきなのは、migrate-to-shoehorn フォルダ内の SKILL.md です。このリポジトリではここが主要な一次情報であり、スキルを支える移行パターンがまとまっています。

おすすめの読む順番は次のとおりです。

1. migrate-to-shoehorn/SKILL.md
2. 変更したいテストファイル
3. ローカルで使われている as Type と as unknown as Type の箇所

スキルに渡すべき入力

このスキルは、次の情報があると最もうまく機能します。

• 現在のテストスニペット
• 呼び出している対象の関数またはコンポーネント
• 分かっていれば関連する型名
• テストデータが妥当な値なのか、意図的に不正なのか
• 一度きりの修正をしたいのか、繰り返し使える移行パターンがほしいのか

この文脈がなくても、エージェントは fromPartial() や fromAny() を提案できます。ただし helper の選択を誤る可能性があります。

migrate-to-shoehorn で依頼したい基本の移行パターン

実務上の migrate-to-shoehorn usage パターンはシンプルです。

• as Type → 通常は fromPartial()
• as unknown as Type → 通常は fromAny()
• ほとんどのフィールドが不要な巨大ダミーオブジェクト → fromPartial()

このスキルの核となる価値はここにあります。曖昧な「このテストのキャストをきれいにして」という依頼を、一定のルールに沿ったリファクタリング方針へ落とし込めます。

migrate-to-shoehorn 用プロンプトを強くする書き方

弱いプロンプトの例:

Replace as with shoehorn.

より良いプロンプトの例:

Use the migrate-to-shoehorn skill to refactor this test file. Replace plain as Request casts with fromPartial() where the object is just a partial fixture. Replace as unknown as Request with fromAny() only where the test intentionally passes invalid data. Keep the test behavior unchanged and add imports if needed.

こちらの書き方なら、エージェントに意図・境界・判断ルールを明確に渡せます。

例: 部分的な fixture の移行

Before:

getUser({ body: { id: "123" } } as Request);

After:

import { fromPartial } from "@total-typescript/shoehorn";

getUser(fromPartial({ body: { id: "123" } }));

これは、fixture としては構造が不完全でも、そのテストの文脈では意味の通る入力である場合に使います。

例: 意図的に不正なデータの移行

Before:

getUser({ body: { id: 123 } } as unknown as Request);

After:

import { fromAny } from "@total-typescript/shoehorn";

getUser(fromAny({ body: { id: 123 } }));

これは、バリデーションや失敗系の分岐を通すために、テストで意図的に不正なデータを渡している場合に使います。

大きめのリファクタリングでの最適な進め方

リポジトリ全体を対象にした migrate-to-shoehorn guide としては、何も考えず一括置換するのは避けてください。より安全な進め方は次のとおりです。

1. テストファイル内で as と as unknown as を検索する
2. そのキャストが「部分的だが妥当」か「意図的に不正」か分類する
3. まずは 1 つのテストフォルダだけ移行する
4. テストと typecheck を実行する
5. import スタイルと helper の使い分けをそろえる
6. そのあとで残りのテストスイートへ広げる

こうしておくと、正当なネガティブテスト用のキャストと、通常の fixture 整理とを混同せずに済みます。

出力品質を上げる実務的なコツ

エージェントには、次の点を維持するよう伝えてください。

• 既存のテスト名とアサーション
• 不正入力テストが持つ意味上の意図
• 完全に展開したダミーオブジェクトではなく、最小限の fixture 形状
• 複数 helper を使う場合の import の重複整理

また、できるだけ小さい fixture を優先したい場合は、その希望も明記してください。通常、その方が shoehorn を使ったリファクタリングはすっきり仕上がります。

migrate-to-shoehorn が向かないケース

本当の課題が本番コードの型安全性、ドメインモデリング、API 契約の正しさにあるなら、migrate-to-shoehorn for Refactoring は適切ではありません。このスキルは「あらゆる型の問題を直す」ためのものではなく、あくまでテストリファクタリングに特化した支援ツールです。

migrate-to-shoehorn スキル FAQ

migrate-to-shoehorn はテスト専用ですか？

はい。ここが最重要の境界です。このスキルは、本番コードの型付けパターンではなく、テストの書きやすさとテスト意図に合わせて設計されています。

テストがすでに通っていても shoehorn は必要ですか？

必須ではありません。現在のテストが読みにくい、ノイズの多いダミーオブジェクトだらけ、あるいは意図を隠す unsafe cast に依存しているなら、migrate-to-shoehorn を導入する価値があります。すでにテストセットアップが十分きれいなら、移行コストに見合わないこともあります。

fromPartial と fromAny の違いは何ですか？

fromPartial() は、不完全ではあってもテスト fixture としては自然なデータに向いています。
fromAny() は、より厳密な型チェックをあえて通さず、不正な実行時入力を再現したいテストに向いています。

この使い分けこそが、広すぎる「アサーションを消して」というプロンプトではなく、このスキルを使う主な理由のひとつです。

migrate-to-shoehorn は初心者向けですか？

はい。基本的な TypeScript のテストが分かっていれば扱いやすいです。スコープが狭く、移行ルールも追いやすいからです。初心者が最もやりがちなのは、テスト以外でも shoehorn を使い過ぎてしまうことです。

このスキルでリポジトリ全体を移行できますか？

できます。ただし、カテゴリごとに見直しながら進める場合に限ります。大規模移行で最も起きやすい失敗は、すべてのキャストを同じものとして扱ってしまうことです。部分的な fixture もあれば、意図的に壊した payload もありますし、中には本番コード側に属していて、このパターンで移行すべきでないものもあります。

普通のプロンプトより良いですか？

多くの場合、はい。特にタスクが「テスト内のアサーションを shoehorn に移行すること」なら有効です。通常のプロンプトでもライブラリ自体は理解しているかもしれませんが、古い cast スタイルを適切な helper に一貫して対応付けたいなら、migrate-to-shoehorn usage の方が向いています。

migrate-to-shoehorn スキルを改善する方法

コードだけでなくテスト意図もエージェントに伝える

migrate-to-shoehorn の結果を最も早く改善できるのは、各テストが何を確認しているのかを明示することです。たとえば次のどれに当たるかを伝えてください。

• 部分的なセットアップによる happy-path の挙動
• 意図的に誤った入力によるバリデーション失敗
• 数個のフィールドだけあれば十分なエッジケース

この小さな文脈が、fromPartial() と fromAny() の判断を左右することがよくあります。

最初にテスト専用ファイルだと明示する

ヘルパーコードと本番コードが同じファイルに混在しているなら、その点を先に伝えてください。次のように明示すると、このスキルはかなり安全に使えます。

Only apply migrate-to-shoehorn changes inside test files and test fixtures.

これで、非テスト領域にまで変更が広がる事故を防げます。

変更前に cast の棚卸しを依頼する

散らかったテストスイートでは、いきなり書き換える前に次のように始めるのが有効です。

Using the migrate-to-shoehorn skill, classify each cast in this file as fromPartial, fromAny, or leave unchanged, then explain why.

この「まずレビューして分類する」手順を入れると、実際の書き換え前にエッジケースを拾いやすくなります。

推論しづらいときは周辺の型情報も渡す

スニペットだけでは期待される型が見えないなら、関数シグネチャや関連する型定義も添えてください。型の文脈が強いほど、import の選択は適切になり、不自然な書き換えも減ります。

よくある失敗パターンに注意する

migrate-to-shoehorn install と導入時によくある問題は、次のとおりです。

• 本番コードで shoehorn を使ってしまう
• 意図的に不正なデータを fromPartial() に変換してしまう
• fixture オブジェクトを簡潔にするどころか逆に膨らませてしまう
• 型を「きれいにする」過程でテストの意味まで変えてしまう

これらはライブラリ自体の問題ではなく、プロンプトの出し方とレビュー不足による問題です。

最初の出力を前提にもう一段詰める

1 回目の出力のあとに、さらに次のような refinement を依頼してください。

• 各 fixture を、テストに必要なフィールドだけに最小化する
• import を整理統合する
• そのまま残すべき cast があれば理由を説明する
• 妥当な部分データと不正なテストデータを明確に分ける

こうすることで、単なる移行作業ではなく、長期的に保守しやすいテストパターンへ育てやすくなります。