1. はじめに DRE（Data Reliability Engineering）グループ のつざきです。タイミーのデータエンジニアリング部で、BigQuery / dbt / Cloud Composer / Looker といったデータ基盤の開発・運用をしています。 DREチームでは 2026 年 2 月から、AWS が提唱する AI-DLC（AI-Driven Development Life Cycle）というワークフローを運用しています。きっかけは、 1 月末に AWS 主催の研修「Unicorn Gym」で3 日間 AI-DLC を体験したことでした。 AI-DLC 自体とタイミー全体への波及は同部の橋本さんが、Operations フェーズ（リリース後の検証）の独自構築については同じ DRE G の chanyou さんが、それぞれまとめています。 3日間のUnicorn Gymが1ヶ月で組織を変えた —— データで見るAI-DLC導入の波及効果 （橋本さん） 「リリース後」に向き合うAI駆動開発の実践 （chanyou さん） 本記事はこれらの続編的な位置づけで、「DREチーム が Inception と Construction フェーズで何を実装・運用しているか」に絞って書きます。 対象読者 : AI-DLC を個人ではなく、チーム（モブ）で運用したい開発/データ基盤チーム この記事の目的 : 公式の想定（単一プロジェクト/個人運用）を、複数リポジトリ・リモートモブ前提に翻訳した実装パターンを共有する 扱わないこと : Operations フェーズの詳細、全社展開の話、AI-DLC の一般解説 TL;DR DREチームは 2026 年 2 月から AI-DLC を運用中 実装 : Workspace + CLAUDE.md 読み替え、Intent 単位の運用 モブ : 1 日 3 ~ 4 時間のフルリモートモブ。狙いは「フロー効率（承認ゲートで止まらない）」「キーパーソンに頼らない（新基盤導入や新メンバー受け入れに効く）」「AI 出力の欠陥を集合知で減らす」の 3 つ 3 ヶ月の結果 : Intent 完了が月 14〜17 件で推移、PR 数は維持、サイクルタイムに劇的な変化は見えず 記事の立ち位置 : 公式に書かれていない実装の隙間（Mob、複数リポジトリ、パス読み替え等）を自分たちで翻訳した事例として記録 2. AI-DLC をざっくり AI-DLC の全体像は既出記事に譲り、本記事で後から使う概念だけ押さえておきます。 本記事での用語の使い方 Intent : 1 つのゴール（例: あるデータソースを BigQuery で使えるようにする） Unit : Intent を疎結合に分解した作業単位（DDD の Subdomain 相当。例: Terraform 追加、DAG 実装など） Ritual : モブでの儀式的な作業（後述の Mob Elaboration / Mob Programming / Mob Testing） Workspace : ドキュメントとルールを置く専用リポジトリ フェーズと成果物の階層 AI-DLC には 3 つのフェーズがあります。 Inception : 要件分析・設計 Construction : 実装・テスト Operations : デプロイ・監視 3 つの Mob Ritual 各フェーズには対応する儀式（Ritual）が定義されています。 Mob Elaboration （Inception）: 要件分析・分解を全員で Mob Programming （Construction）: 実装を全員で Mob Testing （Construction）: テストを全員で いずれも、公式推奨は「物理集合 + 共有スクリーン + ファシリテーター」です。 Human Oversight = Loss Function AI-DLC は AI が実行主体、人間は各ステップで検証・承認する構造です。公式ペーパーの表現が印象的で: "Each step serves as a strategic decision point where human oversight functions like a 'loss function' - catching and correcting errors early before they snowball downstream." 機械学習の損失関数のように、人間のレビューが早期にエラーを補正する、というメタファーです。後の章でモブワークの話をするときに効いてきます。 3. 公式ドキュメントに書かれていない実装ギャップ chanyou さんの記事では、awslabs/aidlc-workflows リポジトリで Operations フェーズがプレースホルダになっている話が出てきます。実は Inception と Construction の側にも、公式の文書と実装の間にいくつかのギャップがあります。 awslabs/aidlc-workflows の構成 原典の awslabs/aidlc-workflows は MIT-0 ライセンスで公開されている、マークダウンのルールファイル群です。 aidlc-rules/ ├── aws-aidlc-rules/ │ └── core-workflow.md # ワークフロー本体 └── aws-aidlc-rule-details/ ├── common/ # 共通ルール ├── inception/ # Inception 詳細 ├── construction/ # Construction 詳細 └── operations/ # プレースホルダ ギャップ 1: ルール実装に Mob の記述がない AI-DLC 公式ペーパーでは Mob Elaboration / Mob Programming / Mob Testing が中核の儀式として定義されています。しかし原典のルールファイル群を mob で grep してもヒットしません。実装部分は「個人と AI エージェントが 1 対 1 で対話しながら承認ゲートを通す」構造になっており、Mob は想定されていない書き方です。 ギャップ 2: 公式チュートリアルは個人開発の例 AWS 公式ブログの実践記事 Building with AI-DLC using Amazon Q Developer のサンプルは、単一 HTML ファイルの川渡りパズルを個人で作る例だけで、モブで回す実演は出てきません。 ギャップ 3: 複数リポジトリの扱いが明確でない 公式は単一プロジェクト前提です。データチームのように「1 つの機能を作るのに複数リポジトリにまたがる」ケースへの具体的な示唆はほぼありません。 理念と実装の翻訳が必要 つまり、公式ペーパーに書かれた「Mob ワーク」や「複数チームでの協調」を実際に動かすには、自分たちで翻訳する必要があります。DRE では、各ギャップに対応する形で次のように対処しています。 ギャップ 1（Mob がルールにない） → モブでの意思決定を組み込み（章 6） ギャップ 2（単一 Intent 想定） → Workspace + CLAUDE.md 読み替え（章 4） ギャップ 3（複数リポジトリが薄い） → 複数リポジトリを 1 Intent でまとめる（章 5） 次章から具体に入ります。 4. DRE の実装: Workspace + CLAUDE.md 読み替え AI-DLC を Claude Code で回すために、DRE では次の構成にしています。 全体像（先に結論） ルール階層 : aidlc-rules/ （上流）→ .claude/rules/ （上書き）→ CLAUDE.md （入口） パス読み替え : aidlc-docs/requirements.md を aidlc-docs/intents/<YYYY-MM>/<intent_name>/inception/requirements.md に読み替え Intent 箱 : Intent ごとに独立したディレクトリ（ intents/<YYYY-MM>/<intent_name>/ ） 状態管理 : aidlc-state.md に Status と Code Repositories を記録 スキル化 : Intent ライフサイクルを Claude Code のスキルで操作 以下、理由と詳細を順に見ていきます。 なぜこの構成なのか awslabs のリポジトリは単一プロジェクト・単一 Intent 前提で書かれていて、1 つの aidlc-docs/ ディレクトリに成果物を蓄積する想定になっています。 一方で DRE は、Intent という単位で開発を進めていて、完了した Intent もそのまま保存しています（後述しますが 2026 年 3 月は 14 件の Intent が完了しました）。Intent ごとに独立したディレクトリが必要になるので、パス読み替えが不可欠です。 ルール階層（継承構造） aidlc-rules/ : awslabs/aidlc-workflows の中身をそのまま取り込む。手動変更禁止、 /aidlc-rules-update スキルで上流追従 .claude/rules/ : プロジェクト固有のルール。aidlc-rules のオーバーライドや追加ルールを置く CLAUDE.md : エントリポイント。プロジェクト概要とディレクトリ規則を最小限に記述 上流は変えない。プロジェクト固有の振る舞いは派生側で足す。オブジェクト指向の継承に近い発想です。 [入口] CLAUDE.md ├─ 参照: aidlc-rules/ # 上流（awslabs 同期、変更禁止） └─ 参照: .claude/rules/ # 派生（DRE 固有、オーバーライド＋追加） パス読み替えの例 awslabs のルールは、成果物の置き場として aidlc-docs/ というパスを前提に書かれています。DRE ではこれを Intent ごとのディレクトリに読み替えます。 公式: aidlc-docs/requirements.md DRE: aidlc-docs/intents/<YYYY-MM>/<intent_name>/inception/requirements.md この読み替えは .claude/rules/aidlc-workflow.md に定義してあり、Claude Code が実行時に解釈します。ルール本体（aidlc-rules/）は触らずに、パスだけ派生側で書き換える構成です。 Intent ディレクトリの構造 1 つの Intent のディレクトリはこういう構造です。 aidlc-docs/intents/<YYYY-MM>/<intent_name>/ ├── intent.md # Intent の目的・受け入れ基準 ├── aidlc-state.md # Intent の状態管理 ├── audit.md # 監査ログ ├── inception/ │ ├── requirements.md │ ├── stories.md │ └── ... └── construction/ └── <unit_name>/ ├── functional-design.md ├── code-generation.md └── ... aidlc-state.md のカスタマイズ Intent の進捗追跡に使う aidlc-state.md は、公式テンプレートをベースに少し拡張しています。 Status : OPEN / SUSPEND / CLOSED の 3 値を追加 Assignee : 担当者 Code Repositories : 複数のコードリポジトリのブランチ状態を記録 この Code Repositories セクションが次の章（複数リポジトリ運用）の鍵になります。 スキル化 Intent のライフサイクル管理は Claude Code のスキルとして定義しています。 /aidlc-intent-start : 新規 Intent 開始 /aidlc-intent-continue : 既存 Intent の再開 /aidlc-intent-save : 作業内容を PR 化してマージ /aidlc-rules-update : 上流（awslabs）への追従 chanyou さんの記事では /inception のように AI-DLC のワークフローそのものを呼び出すスキルが紹介されています。一方、DRE では「Intent というライフサイクルの入れ物」をスキル側で担う構成にしています。どちらも awslabs のルールに乗りつつ、スキルで扱う粒度が違う、という関係です。 5. 複数リポジトリを 1 Intent でまとめる DRE のようなデータ基盤チームでは、1 つの機能を作るのに複数のリポジトリが絡みます。 典型的なワーク 例えば「ある外部 SaaS のデータを BigQuery に自動転送するパイプラインを構築する」といった Intent だと、以下のようなリポジトリにまたがる変更が必要になります。 GCP Terraform リポジトリ : IAM やデータセットの定義 Composer インフラリポジトリ : Cloud Composer や Secret Manager の Terraform Composer DAG リポジトリ : Cloud Run Job と Airflow DAG のコード dbt リポジトリ : staging モデル これを 1 つの Intent としてまとめます。まず Inception フェーズで全体の要件・設計を固め、その後 Construction フェーズで各リポジトリに Unit を切って進めます。例えば DRE の 2026 年 2 月に動かしたあるパイプライン構築 Intent では、4 ユニット・60 ドキュメント・6 PR で完了しました（規模感の一例として）。 ブランチ戦略の 2 階建て ドキュメントとコードで別々のブランチ戦略を使い分けています。 Workspace リポ : session/<intent_name>/<hex> という短命ブランチ。スキル呼び出し単位で切って都度 main にマージ コードリポ : feature/<intent_name> という長命ブランチ。Intent が完了するまで維持 Workspace 側はドキュメントの進捗を小さくマージして積み上げ、コードリポ側は実装が揃ったタイミングで main に入れる、という二層構造です。 aidlc-state.md に Code Repositories を記録 1 つの Intent が複数リポジトリに触るので、どのリポのどのブランチで作業しているかを aidlc-state.md に記録しておきます。 ## Code Repositories - < dbt-repo > (feature/ < intent _name> ) - < composer-dag-repo > (feature/ < intent _name> ) - < composer-infra-repo > (feature/ < intent _name> ) - < gcp-terraform-repo > (feature/ < intent _name> ) Intent を再開するときも、Claude Code がどのブランチをチェックアウトすればよいか即判断できます。 横断ドキュメントとして蓄積される Inception で作る requirements.md や application-design.md は、複数リポジトリにまたがる機能の「横断的な設計書」になります。公式ペーパーではこうした成果物を "semantically rich context memory" と呼んでいて、AI がライフサイクル全体で参照する知識として機能します。 「1 機能 = 複数リポジトリ」というデータチーム特有の性質と、AI-DLC のコンテキストメモリの思想が、意外とうまくかみ合った部分です。 並列 Unit と audit.md 分散 モブとは別に、1 つの Intent の中で独立した複数 Unit を並列処理で進めるケースもあります。これは、Worktree で複数の Claude Code Agent を同時起動する方式です。このとき地味に困ったのが audit.md の Git コンフリクトです。並列の Agent が 1 つの audit.md に書き込もうとして衝突します。 対策として、 audit.md は Intent レベルのマイルストーンのみ記録する役割に限定し、Unit 内の詳細ログは construction/<unit>/audit.md に分散する運用にしました。このルールは .claude/rules/parallel-unit-audit.md に定義しています。 6. モブでの意思決定: なぜモブにしたか DREチームではメンバー 5〜6 名でモブワークを組み、1 日 3 ~ 4 時間をこれに充てています。全員フルリモートのため、公式ペーパー推奨の「物理集合 + 共有スクリーン」ではなく、Google Meet を接続して画面共有しながら進めています。本章では「なぜモブにしたか」と「どう使い分けているか」を DRE 視点で書きます。 3 つの狙い モブを採用する狙いは、マーク・パール『モブプログラミング・ベストプラクティス』で挙げられている利点と重なります。特に以下の 3 つが今の DRE に効いています。 フロー効率（Loss function を強化する） 章 2 で触れた通り、AI-DLC の各ステップには人間の検証・承認ゲートがあります（"human oversight functions like a 'loss function'"）。この承認が詰まるとフロー全体が止まる構造です。 AI の確認質問（clarifying questions）に即答できる人がその場にいないと、承認ゲートで数時間〜半日止まることもあります。Intent 単位で開発を進める AI-DLC では、並行して複数の Intent を抱えるより、少数に集中する方がリードタイムが短くなります。 少人数のDREチームでモブをやると、WIP は 1〜2 Intent に絞られ、意思決定の待ち時間がほぼゼロになります。モブは AI-DLC の Loss function を強化する実装とも言えます。ただし、外部チームへの依存がある場合はこの限りではなく、PR レビュー待ちや情報提供待ちになることはあります。 キーパーソンに頼らない Cloud Composer の統合や TROCCO から dlt への移行など、DRE は新しい基盤への切り替えを多く抱えています。こうした新基盤は「誰か一人だけが仕組みを分かっている」状態になりがちで、障害対応や次の意思決定がその 1 人に依存するリスクがあります。 モブで設計判断を進めると、全員が同時に基盤の意図を理解していきます。ドキュメントで読むのと、設計を議論しながら作るのとでは、後の理解度の深さが違います。 加えて、Intent の議論は Claude Code の audit.md に自然と記録されていくので、後から加入したメンバーが「なぜこの設計にしたか」を追えるようになります。口頭の議論を議事録に起こす手間が、AI-DLC の運用中に自動で払われる形です。 AI の出力の欠陥を減らす モブで AI の出力をその場でレビューすると、一人では見逃しがちな欠陥が減ります。厳密に比較計測したわけではないのですが、集合知がうまく効いている実感はあります。 AI の提案に対して「そこは業務仕様的にこう違う」「その構成だと監視が弱くなる」「別の選択肢の方が運用が楽」といった指摘が即座に入るので、Intent 完了後に気づく修正が減っていると感じます。 使い分け: 全員モブ / 2 分割 / 個人 タスクの性質に応じて、モブの粒度を変えています。 粒度 想定シーン 全員モブ（チーム全員） Intent の Inception、新基盤の設計判断、障害対応 2 分割モブ（2 ~ 3 人 × 2） 複数 Unit を並列で進められる Construction 個人ワーク 既知パターンの実装、軽微なドキュメント整備 判断基準は「不確実性」と「依存関係」です。不確実性が高いものは全員モブ。独立した Unit に切れるなら 2 分割。どちらも低い軽微な作業は個人。 公式ペーパーでも Mob Elaboration（Inception 相当）は必須、Mob Programming（Construction 相当）は分岐可能、と書き分けられていて、DRE の使い分けもほぼこの原則通りです。 リモートモブの実装と未解決の課題 公式ペーパーが想定するモブは「物理集合 + 共有スクリーン + ファシリテーター」ですが、DRE は全員フルリモートなので、ここを読み替える必要がありました。現在の構成は Google Meet + 画面共有 + 各メンバーのローカルエディタ（VS Code / Zed / Vim など人により様々）+ Claude Code です。 タイピスト交代 タイピスト交代は時間交代式（30 分サイクル）で、現タイピストが /aidlc-intent-save スキルで作業を保存・マージし、次のタイピストが自分のマシンで /aidlc-intent-continue で引き継ぎます。 試して撤退したもの VS Code Live Share : タイピスト交代のスイッチングコストを下げる狙いで試しましたが、ターミナル共有はできても接続環境によって表示が崩れ、肝心の Claude Code 拡張機能自体は Live Share で共有できなかったため断念しました タイマーの Claude Code スキル化 : タイピスト交代を時間で促すスキルを試作したものの、時間ベースで AI セッションに割り込む仕組みが安定せず、一旦撤退。今は Google Meet のタイマー機能で運用しています バットマン 『モブプログラミング・ベストプラクティス』に登場する「バットマン」（モブの外で外部からの問い合わせや割り込みに対応するメンバー）に倣い、その日の障害対応当番はタイピストに入れない運用にしています。データ基盤の障害対応はアラート監視と並行処理が必要で、モブに入ると集中を妨げるためです。 未解決の課題: スイッチングコスト 『モブプログラミング・ベストプラクティス』では 10 分ごとの交代が目安として紹介されていますが、DRE では現状 30 分が限界です。AI-DLC を始めた当初は 1 時間以上かかっていたのを、保存・再開処理の高速化や Google Meet のタイマーで短縮してきました。それでも、各メンバーが自分のマシンで作業するスタイルでは、保存・再開を速くしても、セッションを次の人のマシンに同期し直すスイッチングコストが残ります。10 分にはまだ遠いのが現状で、ここはリモートモブの構成上の制約として残っています。 7. 3 ヶ月の数字 AI-DLC を運用してみて、何が数字で変わったかを見ていきます。 計測の方針 2025 年 10 月〜 2026 年 4 月の PR を集計しました（4 月は 4/24 時点）。対象は、DREチームのメンバー（5〜6 名程度）が author の PR に限定しています。なお、ドキュメント中心の Workspace リポは /aidlc-intent-save で作られる即マージ PR が多く数字を歪めるため、集計は コードリポジトリのみ にしています。また、他チーム調整が必要で構造的に長い PR は、上位 5% を外れ値として除外しています。 Intent 完了数 一番わかりやすい変化は、Intent 単位で開発を進められるようになったことです。 月 完了 Intent ドキュメント成果物 2026-02 0（初月、進行中 1） 60 2026-03 14 263 2026-04（4/24 時点） 17 215 2 月は AI-DLC 導入初月で Intent の完了は 3 月にずれ込みました。3 月は 14 件完了、ドキュメントは 263 ファイルが積み上がりました。4 月は月途中（4/24 時点）で既に 17 件の Intent が完了しています。 PR 数 コードリポジトリのマージ済み PR 数（DRE メンバー author 分）です。 月 コードリポ PR 2025-11 36 2025-12 24 2026-01 43 2026-02 41 2026-03 74 2026-04（4/24 時点） 58 1 日 3 ~ 4 時間をモブに充てているので、「モブで時間を使っている分、実装量は減るのでは?」という懸念もありましたが、少なくとも PR 数の面では減っていません。2026-03 で 74 件、4 月は月途中で既に 58 件のペースです。 PR サイクルタイム DRE メンバーの PR サイクルタイム（作成〜マージ）です。外れ値除外後の値です。 月 PR 数 中央値 P90 2025-10 19 1.5h 64.9h 2025-11 36 10.6h 104.7h 2025-12 24 21.2h 94.5h 2026-01 43 2.1h 89.1h 2026-02 41 6.5h 137.5h 2026-03 74 2.6h 96.5h 2026-04（4/24 時点） 58 2.2h 89.6h 月ごとのばらつきが大きく、AI-DLC 導入前後で劇的な改善があるとは言いにくい数字です。ただ、モブで 1 日 3 ~ 4 時間を使いつつ中央値 2〜3 時間台で安定しているので、モブによる時間投入に見合う速度は維持できているとは言えそうです。 注記 この期間の数字を AI-DLC の効果だけで説明するのは慎重にしたいところです。大型案件の時期的な偏りや、メンバーの稼働割合など、他の要因も混ざっています。 それでも、Intent 単位で開発を進める仕組みが 2 月から稼働し、3 月に 14 件の Intent 完了まで回せるようになったのは定量的な変化です。PR サイクルタイムの劇的改善は見えていませんが、モブで使う時間分の生産性ロスが起きていない点は、少なくともマイナスの兆候は出ていないと言えます。 何が効いていそうか（仮説） PR サイクルタイムが変わっていない一方で Intent 完了数は増えている、という組み合わせから、いくつか仮説を立てられます（断定はできません）。 WIP の削減 : 少数の Intent にチーム全員が集中することで、リードタイムのばらつきが抑えられている可能性 レビュー待ちの削減 : モブで合意してから PR を作るので、PR 段階での非同期レビュー待ちが実質なくなっている（中央値を押し下げる方向） 外部依存が P90 を支配 : P90 は 60〜140h 台で大きく変わっていません。他チームとの調整や権限待ちで止まる PR が混ざっているためと思われ、ここは AI-DLC 単独では改善しにくい部分 記事執筆時点での仮説として記録しておきます。 8. やれていないこと 3 ヶ月で骨格はできた感覚がありますが、まだうまく回せていない領域もあります。 Operations フェーズ : DRE では /aidlc-ops-incident という障害対応スキルに留まっています。chanyou さんの記事で紹介されている Operations ワークフローを取り込むのが次のステップです ハーネスエンジニアリング寄りの自動化 : コードレビューはモブで全員でやっていますが、AI にコードをレビューさせる仕組み、Claude Code の Hooks / Agents の活用、AI 出力の評価ループなど、人間介入を減らす方向（いわゆるハーネスエンジニアリング）の仕組みはまだ薄いです。モブの検証密度は保ちつつ、自動化できる部分はそちらに寄せていきたいと考えています 本記事で触れなかった工夫 本記事は Inception と Construction フェーズの実装に絞ったため、以下のような工夫は紙面の都合で触れていません。続編で書く予定です。 多角的レビュー : コンテキスト分離型のサブエージェントで Inception / Construction 成果物をレビューする仕組み Knowledge Base 体系 : Intent 横断の仕様・運用ノウハウを knowledge-base/ に蓄積し、Intent 完了時に差分提案するルール 他チームとの擦り合わせルールの統合 : 連携する別チームとの合意事項を AI-DLC ワークフローに組み込み、PR 差分の自動準拠レビューも用意 効果計測・導入促進 : 月次効果計測レポートの自動生成と GitHub Discussions 投稿、社内全体の AI-DLC 導入状況レポート 運用ガードレール : 本番環境への破壊的操作を一律禁止するルール、bash コマンド実行規約 9. おわりに 3 ヶ月運用して現時点で落ち着いている構成を書き残しました。完成形ではないですが、この方向で続けるメリットはあると感じています。 公式ドキュメントには書かれていない実装の隙間を埋める例として、同じようにデータチームで AI-DLC を運用している方の参考になれば嬉しいです。 参考 AI-Driven Development Life Cycle: Reimagining Software Engineering — AI-DLC の理念を紹介した AWS DevOps Blog AI-DLC Method Definition（Raja SP, AWS）— https://prod.d13rzhkk8cj2z0.amplifyapp.com/ — 本記事で引用した "Human oversight as loss function" 等の出典 awslabs/aidlc-workflows — AI-DLC ワークフローの原典リポジトリ（MIT-0） Building with AI-DLC using Amazon Q Developer — Amazon Q Developer を使った実践ガイド マーク・パール『モブプログラミング・ベストプラクティス — ソフトウェアの品質と生産性をチームで高める』オライリー・ジャパン タイミーのデータエンジニアリング部 DRE G では、こうしたデータ基盤の構築と AI-DLC の運用に取り組んでいます。興味がある方は、以下よりプロダクト採用サイトをご覧いただけますので、ぜひカジュアル面談などお申込みください！ 株式会社タイミー | プロダクト採用サイト

はじめに 初めまして、RevComm の 楽桑 と申します。 MiiTel Call Center (CC) フロントエンドで React 18 → 19 のアップグレードを実施した。単なるバージョンアップではなく、 Semantic UI の完全削除 と Recoil から Jotai への移行 もまとめて片付けた。 この記事では、AI Agent（Claude Code）を 効率化ツール として活用し、このプロセスをどう加速させたかを紹介する。 背景 プロジェクト構成 Next.js 14 (Pages Router) + Static Export → S3 配信 UI: Semantic UI (semantic-ui-react) + MiiTel Design System (MDS) + Emotion CSS-in-JS 状態管理: Recoil リアルタイム: Apollo Client + GraphQL Subscriptions (WebSocket) React 19 アップグレードの動機 React 19 の新機能が欲しい、というより 周辺事情が同じ方向を指していた : 依存ライブラリが次々と React 19 を前提にし始めた Semantic UI が React 19 未対応かつメンテ停滞。他のアップデートの足枷になっていた Recoil は公式アーカイブ済み ついでに React 19 本体の改善（型、Actions など）も取り込める 1. React 19 本体より、周辺作業のほうが重かった 1-1. 実際に時間を使ったのは実装以外の仕事だった React 19 本体の breaking changes 対応は、実はそこまで重くなかった。 useRef の引数必須化、 RefObject<T | null> の型変更、 Symbol → string の明示変換 — いずれも機械的な修正で、数時間で片付く。 実際に時間を使ったのは 実装以外の仕事 だった: 30 以上ある依存ライブラリの React 19 対応状況を一つずつ調べる Semantic UI の撤去後に全画面で発生する CSS リグレッションを特定・修正する Recoil から Jotai への移行で、60 個以上の atom と多数の hooks 呼び出しを漏れなく置換する セッションをまたいで「前回どこまで進んだか」を記録・引き継ぐ React のメジャーアップグレードは「バージョンを上げる作業」より「上げるために必要な調査と確認」のほうが圧倒的にコストが大きい。 1-2. AI Agent を入れて変わったこと Claude Code を導入して変わったのは、コードを書く速度もだが、それ以上に 判断に入るまでの時間 が短くなった。 「このライブラリは React 19 に対応しているか？」「この CSS の差分は直すべきか受け入れるべきか？」— こういった判断の前提となる情報収集・整理・比較を AI に任せることで、人間は「何を採用するか」「その差分を受け入れるか」の意思決定に集中できた。 2. Claude Code に任せたのは「判断以外」 「判断以外」という境界にたどり着いたのは、最初からではない。まず丸投げして失敗し、そこから「何を任せて、何を任せないか」を学んだ。 2-1. 最初の失敗 ― ボタン移行を “丸投げ” したら崩壊した 最初は役割分担を決めず、AI に全部任せてみるところから始めた。 「Semantic UI の Button を全部 MDS の Button に置き換えて。」 Claude Code は長時間かけて大量のファイルを書き換えた。diff はそれっぽく見えたが、ブラウザで開くとボタンのサイズがページごとにバラバラ、アイコンが消えている箇所があり、Primary と Secondary が入れ替わっている箇所まであった。 実際のコミット履歴がその過程を物語っている: 3/5 refactor: Migrate button components to MDS ← 初回の一括移行 3/5 fix: Match reset and edit button styles ← 即座にスタイル崩れ発覚 3/5 fix: correct edit button text color 3/5 fix: match edit button layout and height 3/10 fix: resolve interactive element nesting 3/11 feat: introduce SecondaryButton component ← ラッパーコンポーネントが必要と判明 3/13 feat: enhance button styling (8コミット連続) 3/14 feat: replace SecondaryButton with StyledButton 3/17 feat: replace LinkIconButton with SupportLinkButton 3/17 fix: unify LinkButton primary colors ← 12日後、やっと安定 合計: 42 コミット / 36 ファイル / +968 -677 行 Semantic UI の Button は props が多彩で、MDS とは一対一で対応しない。つまりこの変換は機械的な一括置換ではなく、各使用箇所で “MDS ではどう表現するか” を決める判断の集合だった: Props マッピング（実際の PR より）: label → children ← 機械的 icon → startIcon ← 機械的 isLoading → loading ← 機械的 isFullWidth → fullWidth ← 機械的 color = "alert" → variant = "negative" + CSS 上書き ← 判断が必要 color = "plain" → variant = "default" + 白背景上書き ← 判断が必要 color = "secondary" → SecondaryButton ラッパー新規作成 ← 判断が必要 isLinkButton → LinkButton / LinkIconButton 新規作成 ← 判断が必要 判断が必要な箇所を丸投げしたので、AI はそれっぽく見える変換を量産しただけになった。 2-2. 学び ― “丸投げ” ではなく “分解して委譲” する この失敗から、移行作業は 3 ステップに組み替えた: 対応が必要なファイルを AI に洗い出させる（この段階では置換しない） ファイルごとに対応コストを分類する（機械的置換 / props 読み替え判断 / 代替なし・自前実装） コスト大きい方から着手し、人間のレビューを必ず入れる この流れに変えた瞬間、型崩れはほぼ消えた。AI Agent は “網羅” と “分類” には強いが、判断が混ざった実装を丸ごと投げると表面的な正しさで走ってしまう。判断は人間が先に固めて、AI にはその方針に沿った実装だけを任せる。これが一番効いた基本動作だった。 2-3. 依存ライブラリ調査を AI に任せる package.json を起点に、全依存ライブラリの React 19 対応状況を横断調査させた。 Claude Code に投げたプロンプト（要約）: package.json を読んで、全依存ライブラリの最新バージョンと React 19 対応状況を調査。対応済み / 未対応 / 要調査 で分類した表を作って。 未対応のものは issue やリリースノートへのリンクも付けて。 返ってきた整理表: ライブラリ 状態 備考 react-hook-form ✅ 対応済み v7.52.0 emotion ✅ 対応済み - react-konva ✅ 対応済み v19.0.1 Semantic UI ❌ 未対応 メンテ停滞 Recoil ❌ アーカイブ済み Jotai へ置き換え react-draggable ⚠️ findDOMNode 依存 自前実装必要 この表があるだけで 意思決定のコストが激減する 。人間は「何から片付けるか」を決めるだけでよくなった。 2-4. Recoil → Jotai の置き換えを AI と分担する Recoil は Meta が公式にアーカイブ済みで、React 19 の concurrent features との相性も怪しくなっていた。このタイミングで Jotai に乗り換えた。 両者とも「atom 単位で状態を管理する」思想は同じなので、API のマッピングは素直。ただし atom が 60 個以上、 useRecoilState / useRecoilValue / useSetRecoilState の呼び出しはそれ以上ある。機械的に置換できる部分を最大化しつつ、微妙に違う箇所だけ個別判断、という進め方にした。 // Before: Recoil import { atom, useRecoilState } from 'recoil' ; const selectedAgentAtom = atom< Agent | null >( { key : 'selectedAgent' , // 一意な key が必須 default : null , } ); const [ agent , setAgent ] = useRecoilState(selectedAgentAtom); // After: Jotai import { atom, useAtom } from 'jotai' ; const selectedAgentAtom = atom< Agent | null >( null ); // key 不要 const [ agent , setAgent ] = useAtom(selectedAgentAtom); 移行の進め方: grep で atom({ / selector({ / useRecoilState / useRecoilValue / useSetRecoilState を全検出 ファイル単位で Claude Code に変換を指示、diff をレビュー 型チェック & テスト → 次のファイルへ この規模の置換はまさに「網羅性が必要な機械的作業」で、AI との分担が効く典型例。 人間がやると「このファイルは変えたっけ、こっちはまだだ」となりがちな作業を、AI が一切こぼさずに進めてくれる。 2-5. Storybook MCP でコンポーネントのバリエーションを網羅する Semantic UI → MDS の移行では、「Semantic UI の Dropdown を MDS では何に置き換えるのか」「どんな props があるのか」「どの Story で確認できるのか」を調べる段階で時間を取られる。 Storybook MCP（ @storybook/mcp / @storybook/addon-mcp ）は、この「コンポーネントを知る」段階を AI Agent に任せるツール。Storybook 上のコンポーネント一覧、各コンポーネントの API・props・Story 情報を AI に提供する。 人間 : 「Dropdown を MDS に移行して」 AI Agent : 1 . Storybook MCP で Dropdown のドキュメント・props・Story 一覧を取得 → MDS Select / Menu が候補、Single / Multi / Searchable のバリエーションがあると把握 2 . Storybook MCP で各 Story のプレビュー URL を取得 3 . chrome - devtools MCP でその URL を開き、getComputedStyle でベースライン取得 4 . コードを置き換え 5 . 再度 chrome - devtools MCP で計測し、差分を比較 Storybook MCP が「何があるか、どこで見られるか」を提供し、chrome-devtools MCP が「実際に開いて計測する」。この 2 つの MCP の組み合わせで、AI Agent がコンポーネントのドキュメント読みからビジュアル検証までを一貫して行える。 2-6. 進捗記録を AI に任せる 作業セッションが終わるたびに、Claude Code に 進捗サマリを Notion に書かせる 運用にしている。 以下は実際に Notion に蓄積された記録の抜粋。Semantic UI 移行状況は、セッションごとに自動更新される: Semantic UI → MDS 移行状況（4/10 更新） ✅ 完了: MDS 代替あり（16ファイル） Popup系（6ファイル）→ MDS Tooltip / Popup Tab系（4ファイル）→ MDS Tabs Dropdown系（6ファイル）→ MDS Select / Menu Input系（2ファイル）→ MDS Input ✅ 完了: MDS 代替なし（4ファイル） List（2ファイル）→ HTML ul/li Statistic（1ファイル）→ HTML div + Emotion CSS Transition（1ファイル）→ CSS animation + useFadeAnimation hook ✅ semantic-ui-react / fomantic-ui-css パッケージ削除済み MDS canary テストの結果もイテレーションごとに記録される: イテレーション 変更内容 結果 1 回目 peer deps + testing-library 更新 ✅ 型チェックパス / ✖ 1 test suite 失敗（React 内部 API に依存したビルド構成が React 19 でエラー） 2 回目 styled-components 6.4.0 ✖ 同じエラー継続 3 回目 vite.config external に react/jsx-runtime 追加 ✅ 117/117 test suites 全パス こういう表が 作業の副産物として Notion に残る 。後から見返す・チームに共有する・引き継ぐ、のどれも低コストでできる。手動で議事録を書く必要がなく、作業しているだけでドキュメントが蓄積される。 この蓄積は人間が確認するときの根拠になるだけでなく、 AI Agent にとっても重要なコンテキスト になる。次のセッションで Claude Code が前回の記録を読み込むことで、「前回どこまで進んだか」「どのアプローチがうまくいった / いかなかったか」を踏まえて作業を再開できる。人間が「これどうだったっけ」と振り返る根拠であり、AI が次の一手を打つための判断材料でもある。 3. 視覚リグレッションを AI と一緒に潰す 3-1. 一番つらかったのは、テストでは拾えない崩れだった main (修正前) PR (移行後) Semantic UI を剥がすと、 コード上は何も壊れていないのに全画面の見た目が微妙に崩れる 。 fomantic-ui-css (Fomantic UI は Semantic UI のコミュニティフォークで、CSS テーマ部分を提供するパッケージ) がグローバルに撒いていた reset CSS、Lato フォント、line-height などが一斉に消えるため。 pnpm ts → PASS、 pnpm build → PASS、 pnpm e2e:run → 40/40 passed。しかしブラウザで開くと、チェックボックスのサイズが違う、日付入力の幅がずれている、行間が微妙に変わっている。 ビルド成功 ≠ UI 正常 。 3-2. 目視の根性論ではなく、差分の観測に寄せた Chrome-devtools MCP（MCP = Model Context Protocol。AI Agent が外部ツールを操作するための標準プロトコル）を使い、main と PR で同じ要素の getComputedStyle を自動取得して比較する方式にした。「何が違うか」を先に機械的に洗い出してから、人間が判断する流れ。 3-3. reset CSS 欠落で input margin が復活した Semantic UI はコンポーネントライブラリであると同時に、 fomantic-ui-css （Fomantic UI は Semantic UI のコミュニティフォークで、CSS テーマ部分を提供するパッケージ）というグローバル CSS もバンドルしていた。この CSS には normalize / reset ルール（ input { margin: 0 } 、 body { overflow-x: hidden } など）が含まれており、アプリ全体が暗黙的に依存していた。Semantic UI のコンポーネントを全て MDS に置き換えた後、 fomantic-ui-css ごと削除したことで、これらのリセットルールが消失した。 上記二つの画像の場合, chrome-devtools MCP 経由で getComputedStyle を main / PR で比較。 実際のアウトプット: // main (/callcenter/report/) - label 内部構造 { " tag ":" LABEL ", " rect ": { " w ": 30 ," h ": 30 } , " margin ":" 0px " } { " tag ":" INPUT ", " rect ": { " w ": 30 ," h ": 30 } , " margin ":" 0px ", " border ":" 1px solid rgb(23, 100, 233) " } { " tag ":" SPAN ", " rect ": { " w ": 14 ," h ": 21 } , " text ":" 日 " } // PR (/callcenter_preview_4868/report/) - 同じ label { " tag ":" LABEL ", " rect ": { " w ": 37 ," h ": 36 } , " margin ":" 0px " } { " tag ":" INPUT ", " rect ": { " w ": 30 ," h ": 30 } , " margin ":" 3px 3px 3px 4px ", " border ":" 1px solid rgb(23, 100, 233) " } { " tag ":" SPAN ", " rect ": { " w ": 14 ," h ": 21 } , " text ":" 日 " } INPUT の margin が 0px vs 3px 3px 3px 4px 。fomantic が提供していた input { margin: 0 } が消え、ブラウザデフォルトの margin が復活していた。label のサイズが 30×30 → 37×36 に膨張。 reset.css に追加して解決。 3-4. 大事だったのは「直す差分」と「受け入れる差分」を分けること Semantic UI と MDS は別物なので、MDS に寄せた時点で見た目が変わる箇所は必ずある。検出された差分のうち、 直さない差分のほうが件数は多い 。 直すべき 受け入れるべき 機能の破壊（クリック領域、要素の重なり） デザイントークン由来の変化（色・余白・書体・ラディウス） 意図しない結果（リセット CSS 欠落、フォールバック） MDS 側の改善（focus ring、ARIA 属性） ユーザーが混乱するレイアウト崩れ UX の改善 ピクセル一致ではなく、 「意図しない破壊がないこと」 を目的にした。 3-5. ここでの AI と人間の境界 AI は差分検出と原因特定の補助が得意。一方、その差分が仕様か不具合かを判断するのは人間の仕事。この分担が、視覚リグレッション対応では特に効いた。AI が差分をピクセル単位で絞り込み、人間がその箇所を重点的に目視確認する。 4. 手順と判断基準を Skill にする アップグレード作業の佳境に入った頃、社内の別チームが Claude Code の Skill を使って移行作業を標準化していることを知った。そのアプローチを参考に、今回の Semantic UI → MDS 移行にも Skill を導入した。 4-1. 単発で使うだけでは、再現性が出ない コンポーネント移行は似た作業の繰り返しになる。そのたびにプロンプトを考えるのは非効率だし、個人技のままだと品質もぶれやすい。 4-2. Semantic UI → MDS 移行の流れを Skill 化した Claude Code の Skill（再利用可能なカスタムコマンド） として、移行ワークフローを標準化した。 実行すると AI Agent が以下を自動で進める: 対象コンポーネントの使用箇所と Storybook を網羅的に検索 chrome-devtools MCP でベースラインの getComputedStyle とスクリーンショットを取得 MDS の対応コンポーネントに置き換え 移行後の getComputedStyle とスクリーンショットを取得し、ベースラインと比較 差分を分類して対応 4-3. Skill に埋め込んだのは、手順だけではない 差分を 3 層に分類する判断基準まで含めて標準化した: 自動修正層: 意図しない破壊（リセット CSS 欠落など）→ AI が修正 人間判断層: デザイントークン由来かもしれない差分 → レポートして人間に判断を戻す 記録のみ層: MDS 仕様として正しい差分 → ログに残す 手順だけでなく 判断基準を埋め込む ことで、別メンバーが別コンポーネントを移行するときも同じ品質で作業できる。この Skill は社内マーケットプレイスに登録しており、チーム内の誰でも同じコマンドで移行作業が回せる。 4-4. AI 活用を「うまく使える人」依存にしない AI を使うこと自体ではなく、 AI が機能する作業設計のほうが重要 だった。再利用可能な形にしておくことで、プロンプトの書き方や AI への指示の仕方を個人に依存させない。 5. まとめ 5-1. AI Agent が速くしたのは、実装そのものより「判断に入るまで」 調査、整理、比較、記録のコストを大きく下げられた。React 19 本体の breaking changes 対応よりも、依存ライブラリ調査・CSS リグレッション検証・レビュー対応の効率化のほうが AI Agent の貢献が大きかった。 5-2. 実務で AI Agent を使うなら、まず任せる範囲を決める AI に任せる: 網羅・比較・記録のような、正確さと量が求められる作業 人間が担う: 意図と責任が伴う判断 この境界を先に決めると、使い方がぶれにくい 5-3. 今回の学び AI は万能ではないが、 作業の前後にある重い仕事 にはかなり効く 特に、大規模移行のような「調査と確認が多い仕事」と相性がよかった 単発活用より、 手順と判断基準を仕組みに落とす ほうが持続的に効く ※ 今回の Skill はアップグレード作業の佳境に入った頃に導入したため、恩恵は限定的だった。最初からあれば、繰り返し作業の品質と速度をもっと引き上げられたはずだ。 使用ツール: Claude Code / chrome-devtools MCP / GitHub CLI / Notion MCP

1. はじめに 今回は、MCP 初心者が MCP サーバを試してみて考えたこと・気づいたことを紹介しようと思います。 MCP は概要だけ知っていたものの今まで使ったことがなかったのですが、GitHub Copilot（筆者は VS Code で利用）の Agent モードを活用すれば簡単に環境を作って試せるのではないかと思いつきました。 そこで、馴染みのないツールの MCP サーバでも手軽に試すことができたら良いなと思い、初めて触る Playwright を用いて UI/UX レビュー&修正のサイクルを自動化させてみました。 なお、この試みの中で私は1行もコードやプロンプトは