記事のサマリー（TL;DR）
- SmartHR UI が約20バージョン遅延していたことが CSS 1行の修正をきっかけに判明し、内定者インターンが自ら手を挙げて対応
- 2026年5月〜6月の約1ヶ月半、13本の PR・総変更ファイル約950件・追加6,500行／削除6,900行規模を完遂
- Claude Skill にアップデート専用ワークフローを書き起こし、チームメンバーも同じフローで再現できる仕組みに昇華
kintone・Salesforce 連携など内製 UI を持つ SaaS 開発チームが参考にすべき点
UIライブラリの大幅バージョン遅延は、SmartHR に限った話ではありません。社内共通 UI ライブラリを持つ SaaS プロダクト、あるいは kintone や Salesforce の独自 UI を Rails で補完しているチームでも、同様の「バージョン塩漬け」問題は起きやすい構造です。今回の事例が示すのは、「AI への丸投げ」でも「手作業一辺倒」でもなく、変更パターンを先に整理し、型定義・リリースノートを参照させながら段階的に進めるというハイブリッドなアプローチです。
注目すべきは Claude Skill の設計思想です。「新しい API を推測で対応しない」「ユーザー確認なしに複数メジャーバージョンを一度に上げない」という禁止事項を Skill に明示することで、AI が暴走するリスクを構造的に排除しています。これは、業務 SaaS の UI 変更など「間違えたときのコストが高い」作業に AI を組み込む際の設計パターンとして応用しやすいものです。また、動作確認項目をコンポーネント単位ではなく「変更パターン単位」でテーブル出力する工夫は、レビュー依頼先への引き継ぎコストを大幅に下げる実用的な知見です。
詳細
1行の CSS を書こうとしたら、20バージョンの遅れが判明した
きっかけは、ある画面のレイアウト修正でした。大きい画面でコンテンツの横幅を制限しようとしたとき、SmartHR UI の最新版には対応コンポーネントが用意されていましたが、プロダクトで使用しているバージョンが古く利用できない状態でした。
やむなく自前の CSS を1行書いて対応したところ、チームメンバーのコメントで SmartHR UI が約20バージョンも遅延していることが判明。このまま放置すると自前実装が積み重なり続けると感じた著者（内定者インターンの na2kera 氏）が、自らアップデートを申し出ました。
UIライブラリ「SmartHR UI」とは
SmartHR UI は、SmartHR が OSS として公開している React 製の UI コンポーネントライブラリです。プロダクト間で UI のデザインや操作感を統一できるほか、アクセシビリティ対応もコンポーネント側で実装済みのため、各プロダクトが個別に実装する必要がありません。ライブラリ側のアップデートで継続的にバグ修正・新機能が追加されるため、バージョンを最新に保つことには明確なメリットがあります。
アップデートの規模を数字で振り返る
今回の対応スケールは以下のとおりです。
| 項目 | 内容 |
|---|---|
| バージョン | v75.4.1 → v96（約20バージョン） |
| 期間 | 2026年5月12日〜6月26日（約1ヶ月半） |
| PR 本数 | 13本 |
| 総追加行数 | 約6,500行 |
| 総削除行数 | 約6,900行 |
| ファイル変更延べ数 | 約950ファイル |
週3稼働で他のタスクと並行しながらこの規模を完遂した点は特筆に値します。途中、複数コンポーネントにまたがる props 変更やコンポーネント廃止など、1バージョンに複数の破壊的変更が重なるケースもあり、影響範囲の洗い出しと動作確認に時間を要する場面もありました。
最初はうまくいく AI への指示の仕方がわからなかった
約20バージョン分の更新を AI の助けを借りて進める方針を取りましたが、最初は思い通りに進みませんでした。典型的な例が、複数に分かれていた props が1つのオブジェクト prop に統合される変更です。
一見シンプルな置き換えに見えますが、プロダクト内では props の組み合わせが箇所ごとに異なっていました。
// Before（パターン例）
Component label="操作" iconOnly size="s"
// After
Component trigger={{ children: '操作', iconOnly: true, size: 's' }}
実際には label のみ、label + size、label + iconOnly + size など複数パターンが混在しており、AI に修正を任せても組み合わせごとのオブジェクト組み立てがうまくいかず、変更漏れが残るケースが続きました。
リリースノートの PR を1本ずつ渡して内容を把握させ、影響範囲を1ステップごとに確認させるなど細かく指示を出しながら、何度もやり直す試行錯誤が続きました。
何度もやるうちに「うまくいく流れ」が見えてきた
試行錯誤の末、安定して機能するワークフローが固まりました。プロダクトにはすでに Claude Skills（コードレビュー・PR 作成などを担う各 Skill）が充実しており、それらを組み合わせることでプロダクトのコンテキストを踏まえたフローを構築できました。
確立したステップは以下の8段階です。
- 現在のバージョンを確認し、リリースノートから破壊的変更を影響度付きで整理する
- 破壊的変更が少ない範囲を提案し、どこまで上げるかを決める
- リリースノートとライブラリの型定義から新しい API を把握し、影響箇所を特定。変更パターンごとに Before → After の修正プランを作成する
- 依存関係を更新し、破壊的変更をパターンごとに修正。型チェックで漏れを検出する
- コードレビューを実施し、問題があれば修正する
- 変更パターンごとに、どの画面で何を確認するかの動作確認項目を洗い出す
- 目視確認の結果を受けて、必要な修正を行う
- 動作確認結果を含めた PR を作成する
うまくいく流れを Claude Skill に書き起こした
確立したワークフローを「SmartHR UI アップデート専用 Claude Skill」として書き起こしました。実際の Skill の構成（簡略版）は以下のとおりです。
---
name: update-ui-library
description: UIライブラリのバージョンアップを実施する。リリースノート確認・コード修正・レビュー・PR作成・動作確認項目の洗い出しまで一貫して行う。
argument-hint: "[target-version]"
---
主な手順（抜粋）
- 手順1 バージョン確認とリリースノート調査：現在のバージョンを確認し、リリースページから各バージョンの破壊的変更を影響度付きテーブルで提示する
- 手順2 対象バージョンの決定：破壊的変更が小さい範囲を提案し、どのバージョンまで上げるかをユーザーに確認する
- 手順3 影響範囲の調査とプラン作成：型定義・リリースノートから新 API を把握し、変更パターン（Before → After）ごとに修正プランを作成する。破壊的変更がない場合は依存関係だけ更新して「次のバージョンへ進みますか？」とループする
- 手順4〜8 実装・レビュー・動作確認・PR作成：パターンごとに修正 → レビュー Skill / PR 作成 Skill を呼び出す → 動作確認テーブルを出力 → PR 説明に反映
Skill に明記した禁止事項
- 新しい API を推測で対応しない。必ず型定義かリリースノートで確認する
- 動作確認は個別のコンポーネント名ではなく、変更パターン単位で書く
- ユーザー確認なしに複数メジャーバージョンを一度に上げない
動作確認項目は以下のようなテーブル形式で出力するよう設計されています。
| 画面 | 確認方法 | 確認箇所 |
|---|---|---|
| ユーザー一覧画面 | 「操作」ボタンを表示する | ラベル・アイコン・サイズが変更前と同じ見た目になっている |
| 設定画面 | 「追加」ボタンを表示する | ラベルのみのボタンが正しく表示されている |
変更パターン単位でテーブルをまとめたことで、似た確認内容の重複が排除され、依頼先が「どのパターンのどこを見ればよいか」を迷わずに済む構成になっています。
Skill 運用後もリリースノートだけでは把握しきれないケースに遭遇し、型定義の参照追加や「削除する API」だけでなく「新 API での書き換え方」まで調べるステップの明示など、都度改善を重ねました。モブプログラミングでチームに Skill の使い方を共有し、フィードバックをもとに内容を見直すサイクルも設けています。
スムーズに進んだ背景にはチームの文化があった
ワークフローと Skill だけが成功要因ではありません。チームの文化的な土台も大きく寄与しました。
開発における Skills が充実していた
担当プロダクトには、実装パターン・ワークフロー・テスト・調査など開発のあらゆる場面をカバーする Skills がすでに整備されていました。参加したばかりの内定者インターンでも、手探り状態が続かずに作業を進められた理由のひとつです。特に、E2E テスト環境を整備してくれる Skill や、複数の評価観点でサブエージェントがレビューを行う Skill は、動作確認とコードレビューの待ち時間を短縮するうえで有効でした。
Working Out Loud（WOL）文化が助けをくれた
SmartHR 社内の多くのチームには「Working Out Loud（WOL）」—— これからやること・今やっていることを周囲に宣言する——という文化が根付いています。リモート中心のチームでは特に重要で、着手前の共有や作業ログを残す習慣があったことで、他チームから過去の類似事例を教えてもらったり、詰まったときにサポートを得やすい状態を保てたりしました。
詰まったらすぐモブプロで確認できた
動作確認で再現できない挙動が出たときや修正の方向性に迷ったときは、気軽にモブプログラミングを申し込める環境が背中を押しました。認識のズレをその場で解消でき、大きな手戻りなく進められたと著者は振り返っています。近年は AI 活用を促進する「AI モブプロ」も積極的に実施されており、実際のタスクを進めながら使い方を共有する場になっています。
まとめ
1行の CSS 修正から始まった今回の取り組みは、約20バージョン分という広い影響範囲を、内定者インターンが Claude Skill と WOL 文化・モブプロの組み合わせで完遂した事例です。AI に「何を・どう伝えるか」の試行錯誤の末に確立したワークフローを Skill として言語化し、チーム全体で再現できる資産に変えた点が、単なる個人の武勇伝に終わらない実用的な示唆を持っています。