TypeScript 6.0 RC移行チェックリストとClaude Code修正

TypeScript 6.0 RCに上げたいけど、CIが赤くなるのが怖くて止まる。この記事は、TypeScript移行でつまずく人に向けて、僕が実務で使っている「移行チェックリスト」と「Claude Codeで型エラーを半自動修正する流れ」をまとめました。僕は福祉事業のIT全般を担当しつつ、AI×SaaS開発もしています。

TypeScript 6.0 RC移行チェックリストを先に固定する

TypeScript 6.0 RC移行で一番きついのは、エラーの量より「進め方が曖昧な状態」です。最初の30分でチェックリストを固定します。先に手順を決めるだけで、移行は“怖い作業”から“分割できる作業”に変わります。

1. 現状固定 — mainのCIを一度グリーンにそろえます。
2. 依存更新 — typescript@rcだけ先に上げます。
3. 検出統一 — ローカルもCIもtsc --noEmitで揃えます。
4. 修正分割 — 1PRあたり50件以内を目安にします。

引っ越し前に荷物を仕分けるのと同じで、順番と粒度を先に決めるのがおすすめです。

• ブランチ — chore/ts6-rc-migrationのように目的を明示
• 完了条件 — CI通過 + 型安全性低下なし
• 除外条件 — 機能追加は別PRへ分離

CIで落ちる型エラーは3分類すると一気に進みます

型エラーが200件を超えると全部同じ重さに見えます。ここで有効なのが3分類です。難しい順ではなく「自動化しやすい順」で処理するのがポイントです。

まず「高い」分類を先に削るのが勝ち筋です。僕はCIログをファイル単位で集計して、同種エラーをまとめて直します。

pnpm tsc --noEmit --pretty false > artifacts/tsc.log || true
rg "error TS" artifacts/tsc.log | wc -l
rg "error TS" artifacts/tsc.log | cut -d"(" -f1 | sort | uniq -c | sort -nr

Claude Codeで型エラーを半自動修正する実践手順

僕の運用は、収集 → 指示 → パッチ適用 → 再検証の4ステップです。完全自動にすると壊れるリスクが上がるので、半自動で人間レビューを残す形にしています。

ステップ1: 1ファイル単位で渡す

対象: src/features/billing/invoice.ts
要件:
- anyは禁止
- public APIの型は変更しない
- null安全を優先

ステップ2: プロンプトを固定する

You are a TypeScript migration assistant.
Fix only TypeScript compile errors in the target file.
Constraints:
1) Do not change runtime behavior.
2) Do not widen types to any.
3) Return unified diff only.

運用メモとして、外部導線ではなく、実測ログ・設定差分・再現手順を同じ場所に残してチーム内で確認できる形にしてください。

ステップ3: CIガードを入れる

- name: Type check
  run: pnpm tsc --noEmit
- name: Lint
  run: pnpm eslint . --max-warnings=0
- name: Prevent large risky diff
  run: test $(git diff --name-only origin/main...HEAD | wc -l) -le 30

「一気に直す」より「小さく何回も通す」ほうが、結果的に早いです。

TypeScript 6.0 RC移行を安定させるPR運用のコツ

移行で失敗しやすいのは、技術より運用です。特に「大きすぎるPR」と「機能追加の混在」が再炎上の原因です。

移行PRに機能追加を混ぜないことが重要です。混ぜると原因切り分けが難しくなります。

## レビュェック
- [ ] anyの新規導入がない
- [ ] @ts-ignoreを増やしていない
- [ ] public APIの破壊的変更がない
- [ ] CIログの該当エラーが消えている

チェック観点を文章化して共有するだけで、再現性はかなり上がります。

実案件での結果: 半自動修正で工数をどう減らせたか

直近のAI×SaaS案件（約4.2万行、TypeScript 5系→6.0 RC）でこの流れを回しました。初回CIでは型エラー214件でしたが、2営業日でCIを戻せました。

• 初日 — エラー214件、分類と優先度付け
• 2日目午前 — Claude Codeで161件解消
• 2日目午後 — 設計不整合53件を手動修正
• 合計 — 想定19時間 → 実績11.5時間（約39%短縮）

運用メモとして、外部導線ではなく、実測ログ・設定差分・再現手順を同じ場所に残してチーム内で確認できる形にしてください。

TypeScript 6.0 RC移行を放置した先に起こること

移行を後回しにしても、すぐ大事故になるとは限りません。ただ、直しにくい負債が静かに積み上がる可能性があります。

• 採用難易度の上昇 — 古い型運用はオンボーディングが長引きます。
• 障害復旧の遅延 — 型の信頼性が低いと調査時間が伸びます。
• 改善スピード低下 — 新機能より保守対応に時間を取られます。

今1日で済む整備が、半年後には1週間になる可能性があります。小さく始めるだけでも未来の負担は減らせます。

この記事を書いている理由

僕はSESで開発を経験し、人材教育のマネジメントを経て、今は福祉領域のITとAI×SaaS開発を並行しています。業界をまたぐたびに、「知っている手順」で成果が変わると実感してきました。

業務効率化ツールで月80時間の工数削減を出せた案件も、派手な技術より「分解して再現できる手順」を徹底した結果でした。だからTypeScript 6.0 RC移行も手順として共有したいんです。

次のアクション

運用メモとして、外部導線ではなく、実測ログ・設定差分・再現手順を同じ場所に残してチーム内で確認できる形にしてください。