LLM時代のリファクタリング戦略：AIエージェ ントによる段階的・安全なTS移行方法 

名古屋大学大学院 情報科学研究科 修士課程終了 富士ゼロックス株式会社 入社 2014 2020 2015 2019 2022 株式会社PLAY 入社 動画配信プラットフォーム の視聴分析基盤や コンテンツ管理のCMSである の0→1フ ェーズの開発をリード クラウド上の文書管理サービスの開発 新規サービスの開発 PLAY CLOUDの複数プロダクトのマネージャーに従事 2025 テックリードとしてプロダクトを横断して技術的な課題 解決やオブザーバビリティの向上などに務める 株式会社 PLAY プラットフォーム 本部 技術基盤部 技術推進グループ テックリード 市川 賢 

No content

サービス概要 

PLAY Tech Blogで検索 

本日お話しすること 01 AI Agentを用いたTypeScript移行の方法 02 SDKの型情報を一次情報源とした型推論の精度向上 04 AI Agentのrules / agents / skillsの設定 05 まとめ 03 実際のAI Agentの動き 

AI Agentを用いたTypeScript移行方法 01 

移行の方針 互換性 allowJs: true で JS / TS を共存。依存されていない / 依存が少ないファイルから変換 API側はOpenAPIを書くことがルール付けられており、OpenAPI Generatorで SDKを作成/配布。それを型推論の一次情報源として利用 一括変換スクリプトは作らず、AI Agentが 1 ファイルずつ test-first フローを実行・検証 test-first: 変換前にテストを書き、JS で green → TS 化 → greenを確認 安全性の確保 (デグレ防止) 変換方式 精度向上の工夫 あるプロダクトの管理画面(フロント)の例 テスト駆動的に順次変換、型推論の精度向上のため OpenAPI Generatorで生成したSDKの型情報を利用！！ 

SDKの型情報を一次情報源とした 型推論の精度向上 02 

OpenAPI によるSDK生成と、その効果 「SDK を一次情報源にする」が成立する仕組み 2 openapi-express でスキーマを読み 込みAPI作成 › 1 OpenAPI 定義 openapi.yaml API スキーマの形式記述 › 3 SDK 自動生成 openapi-generator TypeScript 型 + クライアント › 4 GitHub Packages npmモジュールとして配布 API 利用側で npmモジュール として利用 5 バリデーションが定義される › AI が型を推測しなくてよい セッション間で同じ関数に違う型が付く問題が消える APIの変更(バージョンアップ) = 型エラーでわかる npm パッケージのバージョンを上げるだけで型が変わった部分 はチェックされ、APIもその変化に気付ける APIスキーマの形式言語として効く snsType = "instagram" | ... のような union 網羅性を その場で検証可能 AIへの適用が簡単 rulesに「SDKの型情報を確認して」 と1行書くだけで効く 

実際のAI Agentの動き 03 

AI Agentによる処理の流れ 1/2 1 移行対象を抽出 import 元 / 呼び出し元をagentがgrepして確認。 依存の少ないものから進める。 2 SDKの型情報の確認 SDK 型を優先的に確認し、 AIが自分で推論しないようにする 1 2 指示としてはTS化を進めてと入力するだけ！ 

3 テストを書く .test.ts を JS インポートで作成 → yarn test で green git mvでファイル名変更 しコミット 4 .js → .ts (履歴を辿るため git mv + コミット必須) 5 TS化を実行 極力既存ロジックは変えないように 型情報をつけることだけに注力させる 6 型チェック、再度テストを実施 ts化後にエラーしないことを確認し 変換による安全性を担保 AI Agentによる処理の流れ 2/2 

AI Agentの rules / agents / skillsの設定 04 

.claude/ にまとめて置く 4 種類のファイル .claude/ ├── rules/ # プロジェクト規約の Markdown 群 │ ├── typescript-migration.md # HARD RULE 12 個 │ ├── typescript-style.md # 型付け作法 │ ├── testing.md # テスト方針 + 妥協ライン │ ├── imports.md # パスエイリアス運用 │ └── jstyling.md # CSS 命名規約 │ ├── agents/ # サブエージェント (役割 + モデル) │ ├── ts-migrator.md (opus) │ ├── test-writer.md (sonnet) │ ├── ts-build-doctor.md (opus) │ ├── props-typer.md (sonnet) │ └── migration-scout.md (haiku) │ ├── skills/ # スラッシュコマンド化されたワークフロー │ ├── ts-status/ # 進捗集計 │ ├── ts-check/ # yarn tsc/lint/test 一括 │ ├── ts-migrate-file/ # ファイル単位 test-first 変換 │ └── ts-migrate-dir/ # ディレクトリまとめて │ └── settings.json # hooks など (Stop イベントで通知) 

rules/ : 規約は Markdown で「不変条件」として書く typescript-migration.md の HARD RULE (抜粋) 1. 新規ファイルは .ts / .tsx のみ 2. 1 ファイル変換 = 1 コミット 4. 変換後は3. テストを先に書く(test-first) yarn tsc && yarn lint && yarn test がすべてがグリーン 5. 依存先 (import 元) から先に変換 (葉から進める) 6. API 型は SDK の型を参照する。極力自分で推論しない 7. any 禁止 8. @ts-nocheck / @ts-ignore / @ts-expect-error の新規追加禁止 9. 既存の振る舞いを変えない (型付けと等価リファクタを混ぜない) 10. ロジック・構造は極力変更しない 11. ファイルリネームは git mv を使う (履歴を辿れるように) 12. React component の Props / State 型は export する 安全性の担保 （デグレ防止） 型推論の向上 意図せぬ変更 差分の抑制 

agents/ : 役割ごとにエージェントを切り出す モデルを役割に応じて使い分ける → コスト効率と品質を両立 AGENT ROLE MODEL TYPE ts-migrator 単一ファイルを test-first フローで変換 Opus 深く考える系 ts-build-doctor tsc のビルドエラーを分析・修正 Opus 深く考える系 test-writer 既存挙動を観察して Vitest テストを書く Sonnet 定型作業系 props-typer Component Props を呼び出し元から逆算 Sonnet 定型作業系 migration-scout 依存グラフから次の変換対象を提案 (RO) Haiku スキャン系 Opus = 型を考える / Sonnet = 定型作業 / Haiku = 集計・スキャン 

まとめ 01 AI × ルールで「安全な段階移行」を実施 02 SDK 型を一次情報源にして AI の推測を排除 03 test-first で既存の振る舞いを壊さない 04 rules / agents / skills で属人化しない再現可能なフローに 

「見たい」と「見せたい」がつながる世界を作る