みなさん、こんにちは☀️ プロダクト開発部の ねぎちゃん です🌱 スタメンは、先日開催された フロントエンドカンファレンス名古屋 2026 にプラチナスポンサーとして、出展・協賛させていただきました！ フロントエンドカンファレンス名古屋2026 日時：2026年5月9日(土) 場所：ウインクあいち(〒450-0002 愛知県名古屋市中村区名駅4丁目4-38 ) fec-nagoya-org.github.io プラチナスポンサーとしてブース出展いたしました💪 今回のカンファレンスには、専門領域がそれぞれ異なるスタメンのエンジニアたちが参加しました。 バックエンドメインのメンバーから、AI活用に注目するメンバーまで、多角的な視点でセッションを聴講した結果、「一見地味な罠」への対策から「5年におよぶ刷新劇」の舞台裏、さらには「AIインストールのリアルな地獄」まで、濃厚で痺れる知見がたくさん集まりました✨ このブログでは、参加メンバーが「いちばん印象に残った！」と語る、厳選セッションの感想レポートをそれぞれの視点でお届けします🔥 🔥 スタメンエンジニアが痺れたセッション5選 おしん 💭印象に残ったセッション： 「見た目は同じなのに検索でヒットしない」 ( @wabi_1318 ) wabiさんの「見た目は同じなのに検索でヒットしない」という発表が私にとって特に印象に残りました。 MacOS（NFD）からのアップロードと手入力（NFC）の差分でファイル名検索がヒットしなくなるというバグは、原因究明が難しそうで沼にハマりそうだと感じました。ブラウザやライブラリ側で自動解決されない問題を、Issueの議論などを交えてリアルに語ってくださり、面白かったです。 こうした「一見地味だけど踏むと痛い落とし穴」は中々表に出てこないと思うので、貴重な知見でした。 システムの入力境界でしっかり検証・正規化して、型を活用して素の文字列と区別するという設計思想の重要さを学べたので、今後のプロダクト開発に活かしていきたいと思います。 鈴木 雄一郎 💭印象に残ったセッション：「デザインとコードの境界を溶かす」( @kskwtnk ) 綿貫さんの基調講演「デザインとコードの境界を溶かす」という発表がとても印象に残りました。 私は、普段バックエンドメインで書いており、キャッチアップとしてTypeScript, Reactの学習はしているのですが、デザイン周りの語句もキャッチアップしておくべきという気づきを得ました。 また、デザインシステムを現場に導入したがチームが慣れておらず、うまくワークできなかったという話も、実体験をもとにした話で現場感がありました。こういう失敗談みたいなものはなかなか話しづらいと思うので、共有してくれてとてもありがたかったです。 「プロジェクトの初期はデザイントークンのグローバルトークンを導入するだけでもデザインの統一感が出て、コスパ良く導入できて良い」という話も明日から仕事で即使えそうなナレッジとして参考になりました。 ちぇる 💭印象に残ったセッション： 「いつか誰かが、と思っていた フロントエンド刷新5年間の実践知」 ( @kiichi_sugihara ) 長期的なリアーキテクチャに取り組みたいけど、目の前の改善業務に追われて時間が取れないという、現場でよくある課題への向き合い方が非常に面白かったです。 kiiさんの現場では、当初「業務時間の10%を自由に使えるシステム健全化枠」を設けていたそうですが、機能的な改善の方がチームや社内からも喜ばれやすく、「改善 → 喜ばれる → やめられない」というループに入り、枠を使い切ってしまっていたという失敗談には非常に共感しました。そこから学び、枠ではなく「丸1日システム改善しかやらない『システム健全化デー』」を設けることで集中の分断を防いだ点や、あえて残業時間を減らしてその余白を勉強に充てることが、長期的に組織やシステムへの良い投資になるというお話が印象的でした。 また、技術的負債という目に見えづらい課題を解決するためには、機能開発以上に周囲への説明と合意形成が必要となります。リアーキテクチャに伴うバックエンド側のAPI分離や、デザイントークン作成の必要性など、各ステークホルダーを巻き込む壁があった中で、「理想を描いて、事業プロジェクトのついでに段階的に仕込んでいく」という立ち回りは、どんな仕事においても通じる突破口だと感じました。 必要性の吟味に始まり、周囲の課題と自分の理想をマッチさせながら、最終的に覚悟を持ってプロジェクトを完遂させる姿勢は、まさに「Get things done」の体現だなと思いました。 伊賀本 衛 💭印象に残ったセッション： 「AIと乗り切った1500ページ超のヘルプサイト基盤刷新」 ( @mugi_uno ) 「AIと乗り切った1500ページ超のヘルプサイト基盤刷新」のセッションを聞いて、AIへの過信の危うさを改めて実感しました。 AIがあれば何でもできると思いがちですが、実際に掘り進めると「地獄への始まり」とも言える複雑さが待っています。コードを変えるだけでなく、プロダクトのフェーズに応じた判断が求められ、刷新前後の差分を完全に排除することの難しさも痛感しました。TDDの徹底やドキュメントの積み重ねによってナレッジを蓄積し、誰でも編集できる状態を作るというアプローチはとても参考になりました。 また、AIを使うことで自分の観測範囲に閉じた局所最適に陥りやすいという指摘も刺さりました。自社でも個人スキルの向上は進む一方、プロジェクト横断的なナレッジ共有の仕組みはまだ整備途上です。この課題に向き合い、チーム全体のスキルを底上げする仕組みを作ることが急務だと感じています。自社プロダクトをより多くの人に使いやすく届けるためにも、AIを活用しながらスピード感を持って動いていきたいと思います。 taro 💭印象に残ったセッション： 「いつか誰かが、と思っていた フロントエンド刷新5年間の実践知 」 ( @kiichi_sugihara ) 最も印象に残ったのはこちらのセッションです。 「いつか経験豊富なエンジニアが来て、一緒に刷新を進めてくれるだろう」と思いながら目の前の開発で精一杯だった、というところから始まる 5 年間の物語でした。 何より心を動かされたのは、登壇者の 仕事に対する熱量 です。5年かけて少しずつ信頼と専門性を積み上げ、最終的にフロントエンド刷新をやり切るまでの軌跡は、聞いている自分まで熱くなるものでした。 セッションを聞いて自分も取り入れたいと思ったのは、次の2つです。 1日の時間の使い方 責任者・関係者の巻き込み方 1日の時間の使い方についてです。毎日の業務を同じようにこなすのではなく、「もっと良いやり方があるのではないか」と問い続け、 時間の使い方そのものを設計する 。その積み重ねが複利のように効いてきて、未来を決めるのだという考え方は強く印象に残りました。 責任者・関係者の巻き込み方については、検証が進まない時期に、技術顧問との定例ミーティングを先に設定し、「 検証の進捗を共有する場を作る → 否応なく前進せざるを得ない構造」を作ってしまうという話が象徴的でした。また、1人だと曖昧になりやすい部分が、説明する過程で言語化されてクリアになる、という副次効果も語られていました。 さらに、刷新を「自分の余白」だけでやろうとせず、 事業ロードマップを見据えて事業 PJ に段階的に仕込む という発想にも痺れました。「場を作ってから埋める」アプローチを社内のあらゆる関係者に対して実践している姿勢は、今の自分にとても必要だと感じました。 このような規模のカンファレンスに参加するのは初めての経験でしたが、ブース運営もセッション聴講も、どちらもモチベーションを大きく引き上げてくれる時間でした。次回も機会があればぜひ参加したいですし、いつかは聴く側ではなく発表する側として登壇できるよう、日々の業務と学びを積み重ねていきたいと思います。 おわりに 以上、フロントエンドカンファレンス名古屋 2026の参加レポートでした！ 専門領域が異なるメンバーがそれぞれの視点でセッションを聴講したことで、技術的なナレッジはもちろん、チームビルディングやプロジェクト推進のヒントまで、本当に多くの刺激と学びを得ることができました🔥 スタメンでは、こうして得た最先端の知見や現場の実践知を日々のプロダクト開発に還元し、ユーザーの皆さまにより良い価値を届けていけるよう、これからもチーム一丸となって突き進んでいきます💨 改めまして、素晴らしいカンファレンスを企画・運営してくださったスタッフの皆様、そして当日ブースにお立ち寄りいただいた皆さま、本当にありがとうございました💐 それでは、次回のテックブログもお楽しみに🌷 herp.careers

はじめに こんにちは、ZOZOTOWN開発1部iOSブロックの荻野です（ @juginon ）。 みなさんに日々使っていただいているZOZOTOWN iOSアプリのホーム画面ですが、実は2024年秋から2026年の年初まで約1年半、水面下でリアーキテクチャを行っていました。 リアーキテクチャに着手する前の当時の私はアーキテクチャ設計への理解がまだ浅く、「実際に手を動かしながら身につけたい」という動機でこのリアーキテクチャを主導しました。自分にとってはチャレンジングな取り組みで、アーキテクチャ設計やテスト設計への理解が実践を通して大きく深まったプロジェクトになりました。 本記事では、そのリアーキテクチャのすべての軌跡と、そこで得た学びをお伝えします。 なお、本記事で紹介するホーム画面リファクタリングは、iOSチーム全体で取り組んでいるアーキテクチャ刷新の具体的な事例の1つでもあります。チームとしての取り組みや知識共有の仕組みについては ZOZOTOWNのiOSアーキテクチャとチーム進化の軌跡 にもまとめています。本記事と合わせて読むと、個々の取り組みとチーム全体の文脈をより立体的に理解できます。 目次 はじめに 目次 ホーム画面について タブ モジュール ホーム画面が抱えていた課題 当初の設計と、その後の運用実態の乖離 継承構造が不要になった ログ管理の複雑化 MVCによるViewControllerへの責務集中 高い改修頻度 リファクタリングの設計方針 方針1: 影響範囲を最小化しながら段階的に進める 方針2: 段階的に責務を分離する Step1: Objective-Cレガシー型への依存を剥がす Step2: 最も独立性の高いAPIを対象に、ViewModel/UseCaseを部分導入する 小さく始めることの重要性 Step3: MallHomeViewController全体にViewModel/UseCaseを導入する 問題1. Swift Concurrencyへの移行 問題2. モジュール構築メソッドの整理 Step3完了後にログに関するバグが発覚 バグを引き起こした原因 Step3-ex: 命名整理とユニットテストの追加 命名の整理 ユニットテストの追加 不確かさに気づいた時点でテストを書く Step4: HomeViewControllerにViewModel/UseCaseを導入する TDDによる設計の共有 オンボーディング周りの状態管理 リファクタリング前の課題 ステートマシンによる再設計 長期リファクタリングを進める上でのポイント おわりに ホーム画面について ZOZOTOWN iOSアプリのホーム画面は以下のように、主にタブとモジュールによって構成されています。 タブ 画面上部に表示されている「すべて」「コスメ」部分を指します。タブは切り替えが可能で、すべてタブではアパレル・シューズ・コスメ等すべての商品が、コスメタブではコスメ商品特化の画面表示になります。 実装上は以下の2種類のViewControllerで構成されています。 HomeViewController : ホームタブのルート画面となる画面全体を管理するViewController ヘッダーや検索窓など、両方のタブで共通して表示する部分、ホーム画面全体の管理を担う MallHomeViewController : すべてタブ/コスメタブのコンテンツを管理するViewController それぞれのタブで表示が変わる部分の管理を担う モジュール 各タブのコンテンツは、複数の「モジュール」と呼ばれるブロックが縦に並んだ構成です。モジュールとは、性別選択・バナー・チェックしたアイテムといった、個々のコンテンツ単位のことです。 ユーザーがホーム画面をスクロールすると、これらのモジュールが順番に表示されます。 ホーム画面が抱えていた課題 当初の設計と、その後の運用実態の乖離 ホーム画面の複雑さを理解するには、2021年のフルリニューアル時の背景を知る必要があります。 2021年3月のZOZOTOWNフルリニューアルで初めてタブ構成が導入されました。当時は3つのタブがあり、 MallHomeViewController を基底クラスとした3つのサブクラスによる継承構成を採用しました。各タブで固有の処理が発生することを見越した設計です。 当時の取り組みについては ZOZOTOWNアプリ Home画面のリニューアルにおけるアーキテクチャ再設計 でも詳しく紹介されています。 しかし、フルリニューアルから3年以上が経過し、運用を重ねる中で当初の設計前提が変わっていきました。 継承構造が不要になった 従来では MallHomeViewController を継承する各タブのクラスを作成していましたが、各タブで固有の処理は実際にはほとんど発生しませんでした。 タブの種類を保持するだけで十分な状態で、各タブで専用のクラスを作成する構造はかえって全体像の把握を難しくしていました。 ログ管理の複雑化 リニューアル当初はGA（Google Analytics）のみだったログ送信を専用のLoggerクラスが管理していました。しかしその後、社内分析用ログなど複数種別のログが追加されていく中で、Logger自身が複雑な状態管理を担うようになっていきました。 複数のフラグがLoggerの内部に積み重なり、 MallHomeViewController が持つ状態と常に同期させる必要が生じました。また、ログに関する責務分離が適切に行われていない部分もあり、こういった構造がコードを読む際のコストを高める要因の1つになっていきました。 MVCによるViewControllerへの責務集中 2021年当時はMVCアーキテクチャを採用していたため、API呼び出し・UI状態管理・ビジネスロジックの調整が MallHomeViewController に集中していました。前述のLoggerクラスとの状態同期もVCが直接担っており、改修を加えるたびにVC・Logger双方への影響を考慮しなければなりませんでした。こうした積み重ねで行数は再び1000行を超えるまでに膨らんでしまっていました。 特に問題だったのは、UICollectionViewへのデータ構築と商品押下時のログデータ作成が混在する500行弱の巨大なメソッドです。どこを触れば何が変わるのか把握するだけで大きなコストがかかる状態でした。 高い改修頻度 ZOZOTOWNのホーム画面は平均月1ペースで改修案件が入り、多い時期には3案件が同時並行で走ることもあります。 このリアーキテクチャが開始してから現在まででも、ホーム画面のモジュールを無限スクロールできる機能や、モジュール内のアイテムで動画を表示する機能など、規模の大きな案件がリリースされています。 影響範囲の把握が困難なFat ViewControllerは、改修のたびにリスクを伴い、チームの開発速度を下げる原因になっていました。 リファクタリングの設計方針 課題は明確でしたが、1000行超のVCを一気に書き換えるのはリスクが高すぎます。そこで以下の方針を立てました。 なお、このリファクタリングは通常の機能開発と並行して進めており、稼働の約2割をこの取り組みに充てながら進めていました。1年半という期間はそのためです。 方針1: 影響範囲を最小化しながら段階的に進める 各ステップの影響範囲を小さく保つことで、問題発生時の修正コストを抑えられ、PRの変更量も少なくなりレビューの負担を減らせます。また各ステップを独立してリリース可能な単位とすることで、他案件の進行をブロックしません。 以上のメリットを意識しながら以下のステップで進める計画を立てました（当初は4ステップ、結果として5ステップになりました）。 ステップ 内容 Step1 Objective-Cレガシー型への依存を剥がす Step2 最も独立性の高いAPIを対象に、ViewModel/UseCaseを部分導入する Step3 MallHomeViewController全体にViewModel/UseCaseを導入する Step3-ex Step3完了後にバグが発覚し、命名整理とユニットテストを追加 Step4 HomeViewControllerにViewModel/UseCaseを導入する　 ステップを設計する上でのポイントを3点紹介します。 Step1を最初に行った理由 MallHomeViewController にはObjective-Cのレガシーな型への依存がありました。MVVM化を先に進めると、ViewModel/UseCaseはObjCの型を扱う設計になります。その後ObjC依存を除去すると、ViewModel/UseCaseの設計変更も必要になり手戻りが発生します。そのため、MVVM化の前段階として依存の除去を最初のステップとしました。 MallHomeViewControllerから先に着手した理由 タブの中身を管理している MallHomeViewController は、着手開始から間もなく後続案件の改修が入る予定でした。そのため、それより前にMVVM化を完遂させることを優先しました。 Step2とStep3を分けた理由 ホーム画面では複数のAPIを呼び出しており、最初から全APIを対象とするとMVVM化の影響範囲が大きくなりすぎます。まず独立性の高い一部のAPIに絞ってViewModel/UseCaseを導入することで、アーキテクチャの全体像を小さな変更で確認でき、問題が発生した際の修正コストも抑えられます。 方針2: 段階的に責務を分離する UseCase → ViewModel → ViewControllerの順で責務を分離していき、最終的に以下の構成を目指しました。当時のアーキテクチャガイドラインではUseCaseの採用が定められていました。またAPIリクエスト・ログ送信・ビジネスロジックが複合的に絡むホーム画面の規模感においても、ViewModelの肥大化を防ぐうえで適切な設計判断でした。 ここで紹介している大まかな全体方針は、以前チームメンバーの なんしー さんが行った 商品詳細画面のリアーキテクチャにおける進め方 を参考にしています。 Step1: Objective-Cレガシー型への依存を剥がす MallHomeViewController では、商品情報を表示する部分がObjective-Cで書かれたレガシーな型に依存しており、APIレスポンスからレガシーな型へ変換する不要な依存がありました。そのため、最初のステップはMVVM化でなく 不要な依存の除去 から始めました。 以下の3段階で依存を剥がしました。 商品の情報表示において必要な情報を持つUIModelを作成 APIレスポンスをそのUIModelに変換するTranslatorを作成 Translatorは外部APIのレスポンス型をUIModelの型に変換する責務を持つ 外部APIの型定義が変更されてもViewModelやVCへ直接影響しない構造になる レガシーな型を使わない新しいセルを実装し、移行 最終的に MallHomeViewController からObjective-Cレガシー型への依存を完全に除去しました。 Step2: 最も独立性の高いAPIを対象に、ViewModel/UseCaseを部分導入する Step1でクリーンな基盤ができたため、いよいよMVVM化に着手します。設計計画で「最も独立性が高い」と判断した 世代別ランキングモジュール から始めました。 世代別ランキングモジュールとは、ユーザーが世代（~10代、20代など）を選択すると、その世代の人気アイテムがランキング形式で表示されるモジュールです。 ヘッダーの世代選択ボタンをタップして切り替えると、対応するランキングが再取得・再表示されます。 以下の特徴があったため、ホーム画面のMVVM化における最初のステップとして工数がかからず、アーキテクチャの全体像を実装しながら理解できる最適な題材と判断し、着手しました。 世代別ランキング専用の独立したAPIを持つ ユーザーが世代を選択したときだけ更新される 他のモジュールの更新と独立して動作する 小さく始めることの重要性 Step2は全部で7つのPRを作成しました。UseCase作成→UIModel作成→ViewModel作成→ViewControllerからUseCase/ViewModelへ処理を移動する流れで修正を加えていきました。 巨大なViewControllerを一気に書き換えようとすると、変更が大きくなりすぎてレビューが困難になり、バグ混入リスクも高まります。Step2でOpenした7つのPRのほとんどが100行未満のコード追加に収まっており、レビューでの指摘もほとんどなくスムーズにマージできました。 また、Step2を通して PRの分割方法 や 変更を加えるレイヤーの順番 が明確になり、次のステップであるモジュール更新全体のリアーキテクチャへの自信がつきました。大規模なリファクタリングに着手する際は、最も独立性の高い部分から始めることで、レビューでの問題検知やバグ混入の防止に直結します。最初の小さなステップを通じてPRの分割方法や変更を加えるレイヤーの順番を把握しておくと、後続の大きなステップをより自信を持って進められます。 Step3: MallHomeViewController全体にViewModel/UseCaseを導入する ホーム画面では、世代別ランキングモジュールの取得API以外に合計4つのAPIを並行して呼び出しています。Step3ではそれらの主要APIを呼び出している部分すべてにViewModel/UseCaseを導入しました。Step3はStep2のようにスムーズには行かず、いくつかの問題に直面しました。代表的な問題を紹介します。 問題1. Swift Concurrencyへの移行 当時の MallHomeViewController では、一部分のAPI呼び出しに BrightFutures を使っていました。このライブラリは2022年にEOLとなっており、チーム内でも新規実装では非推奨としていたため、このタイミングでSwift Concurrencyへ移行しました。 Swift Concurrency対応に関してもこのときが初めての経験で、その中で色々と学びがありました。 並行処理によるビュー表示時の表示順担保 クロージャベースのコードでは、複数のモジュール取得APIを直列で呼び出しており、すべてのレスポンスが揃ってから一括で描画していました。Swift Concurrencyへ移行して並行呼び出しにしたことで、どのAPIレスポンスが先に返ってくるかが不定になります。レスポンスを受け取った順にUIModelを積んでいく実装のままでは表示順が変わってしまいますが、実装当初はこの問題に気づいていませんでした。 UIModelの配列に常に決まった順序で格納する実装に修正することで解決しました。すべてのAPIレスポンスが揃ってから正しい順序でまとめて描画するという基本的な流れは変わらず、並行取得による速度改善と表示順の保証を両立しています。 withCheckedThrowingContinuation にキャンセルが伝播しなかった 特定のAPI呼び出しにはタイムアウト処理が必要でした。 withThrowingTaskGroup を使い、 データ取得タスク と 一定時間後にタイムアウトエラーを投げるタスク を並走させました。どちらかが完了したら group.cancelAll() でもう一方をキャンセルする実装を採用していました。 しかし実際にはキャンセルが正しく機能していませんでした。通信が切断された状態でリロードを繰り返すと、タイムアウトが発生して group.cancelAll() が呼び出されているにもかかわらず、ローディングが永遠に続く不具合が発生していました。 原因は、コールバック型のサードパーティSDKを withCheckedThrowingContinuation でブリッジしていた部分にありました。このSDKは通信切断時にコールバックを呼び出さない場合があります。タスクグループのキャンセルは withCheckedThrowingContinuation 内には自動で伝播しません。コールバックが呼ばれない限り、continuationは解決されないままとなります。 // 修正前: キャンセルが continuation に伝播しない func fetchData () async throws -> Response { try await withCheckedThrowingContinuation { continuation in legacySDK.fetch { result in // 通信切断時はここが呼ばれない場合がある // group.cancelAll() されても continuation は resolve されないまま continuation.resume(with : result ) } } } // 修正後: withTaskCancellationHandler を追加し、キャンセル時に continuation を resolve する func fetchData () async throws -> Response { let holder = ContinuationHolder() return try await withTaskCancellationHandler { try await withCheckedThrowingContinuation { continuation in holder.continuation = continuation legacySDK.fetch { result in holder.continuation?.resume(with : result ) } } } onCancel : { // タスクがキャンセルされたとき、onCancel でエラーを投げて continuation を解決する holder.continuation?.resume(throwing : APIError.cancelled ) } } 対応方法は withTaskCancellationHandler を追加することでした。タスクがキャンセルされると onCancel クロージャが呼ばれ、そこでcontinuationにエラーを投げることで、コールバックが返ってこない状態でもタスクを終了できます。continuationへの参照を class で保持しているのは、 onCancel クロージャが別コンテキストで実行されるためです。 var ではSwift Concurrencyの警告が出ます。 withCheckedThrowingContinuation はコールバック型APIを async/await に変換する手段として有効ですが、タスクキャンセルは自動では伝播しません。キャンセルに対応させるには withTaskCancellationHandler と組み合わせて、 onCancel 時に明示的にcontinuationを解決する必要があります。 問題2. モジュール構築メソッドの整理 Step3の終盤では、ViewControllerに置かれていた500行弱の巨大なモジュール構築メソッドを整理しました。 このメソッドには2つの責務が混在していました。 UICollectionViewに表示するデータソースの作成（VC側の責務） 商品押下時のログ送信に必要なモジュール内位置情報の計算（VM側の責務） 後者をViewModelへ移動し、各モジュールの同一性比較を可能な構造とすることで、位置情報を適切に取得できるようにしました。 やること自体は一文で書けるようにとてもシンプルなものです。実装当時の自分の認識も同様で、この整理に関してはスムーズに進み、そのままStep3をリリースしました。 しかし、ここで今回のリアーキテクチャにおける最大の壁にぶつかってしまいます。 Step3完了後にログに関するバグが発覚 Step3のリリース後、モジュールを管理しているチームから「カルーセルバナーのタップログで、バナーの位置が正常に送られていない」という問い合わせが届きました。 調査の結果、カルーセルバナーのタップ時のログに含まれる「バナーの位置」として、 ホーム画面全体におけるセクションの表示位置 を誤って送信していたことが判明しました。本来送るべき値は カルーセル内のバナーの位置（何枚目のバナーか） でした。 バグを引き起こした原因 モジュール/セクション/インデックスなどの位置に関する命名の曖昧さ ホーム画面は複数のコンテンツを縦に並べた構成です。「画面上の表示順（セクション位置）」と「各コンテンツ内の位置（インデックス）」という2種類の"位置"が存在しますが、コード上でこれらを区別する命名が不明確でした。 APIから取得したレスポンス名/ログ送信用パラメーター名/内部で使用している変数名のそれぞれの使い分けが曖昧なまま実装を積み重ねており、コードを読む際に混同しやすい状態でした。 ログの値の正しさをテストで検証できていなかった 「ログが送信されること」は手動確認で検証していましたが、「送信されたログの値の正しさ」まで検証できていませんでした。 当時はユニットテストが整備されていなかったため、コードレビューだけでは防ぎきれませんでした。ユニットテストがあれば、このバグはリリース前に検知できたはずです。 これらを検知できなかった背景として、Swift Concurrency対応での想定外の工数による焦りと、ログの重要度を甘く見積もっていたことが挙げられます。 Step3の終盤のPRはStep2とは打って変わって500行を超える大きなPRになってしまい、レビュアにも大きな負担をかけてしまいました。「小さく分割して進める」という当初の方針を貫けなかった点も反省の1つです。 Step3-ex: 命名整理とユニットテストの追加 バグを迅速に修正した後、Step3の延長として命名の整理とユニットテストを追加しました。 命名の整理 Step3でのバグ原因の1つが「ログ送信コードの読みにくさ」にあったため、まず命名を整理してからテストを書くという順序を選びました。 モジュール・セクション命名の統一 UICollectionView上の概念の呼び方と変数の型を整理し、「モジュール」と「セクション」の使い分けルールを明確にしました。 ログ送信の位置情報に関する命名統一 セクションの表示位置とセクション内の商品位置を表す変数名を、それぞれ明確に区別できる名前に統一しました。 ユニットテストの追加 バグを引き起こしてしまったログ送信時のセクション位置に関するテストをはじめとして、モジュールの取得、性別変更、画面遷移、ライフサイクルイベントなど多数のシナリオをカバーしました。Step2, Step3でUseCaseをプロトコルでDIできる構造になっていたため、Mockを使ったテストが書けるようになっています。 ユニットテストを新規で書いていくのも初めての経験だったため、テストに関する知識が豊富なチームメンバーにモブレビューを行ってもらいました。 命名整理とテスト追加を終えた時点で、MallHomeViewModelのテストカバレッジは38％から99％に向上しました。 不確かさに気づいた時点でテストを書く Step3では「アーキテクチャを整備してからテストを書けばいい」という考えからバグを引き起こしてしまい、その考えの危うさを実感しました。バグや不確かさに気づいたタイミングでテストを書くことで、結果的に次のステップを安心して進める力になります。 Step4: HomeViewControllerにViewModel/UseCaseを導入する 最終ステップのStep4ではホーム画面全体を管理している HomeViewController のリアーキテクチャを行いました。このステップでは、Step3までの失敗と学びを活かして TDD（テスト駆動開発） を採用しました。また、Step3でのPR分割の粒度ミスを踏まえ、レビューしやすい粒度でPRを作成しレビュアへの負担も考慮したPR戦略を取りました。 TDDによる設計の共有 Step4で特筆すべきは、 UseCase/ViewModelのテストケースをProtocol/実装より先に作成した ことです。UseCase/ViewModelのテスト雛形作成 → テストケースの作成 → UseCase/ViewModelとProtocolの作成 → 実装、という順番で進めました。 このTDDアプローチが特に威力を発揮したのが、 ログ送信周りの仕様整理 でした。 HomeViewController のログ送信ロジックは複雑で、起動経路（通常起動・プッシュ通知・Deeplink）やタブ切り替えに応じてどのログをどのタイミングで送るかが変わります。また、同じ画面遷移でも複数のライフサイクルイベントが連続して発火するため、ログの二重送信を防止する制御も必要です。このような仕様では実装者ごとに解釈が分かれやすく、Step3と同じ轍を踏む可能性もありました。 そこで実装に先立ち、起動経路ごとのログ送信フローをドキュメントとして整理し、 チームで仕様を合意した上でテストケースを設計する というプロセスを踏みました。ドキュメントには どの動線でどのログが何回送られるべきか を網羅的に記述し、それをそのままテストの仕様として共有しました。 テスト設計において重要な方針として、 内部のフラグ状態ではなくユーザーの動線単位でテストを記述する ことを採用しました。例えば以下のようなシナリオをそのままテスト名として記述しています。 通常のアプリ起動でホーム画面を表示したとき、ログが1度だけ送信されること プッシュ通知でアプリを起動したとき、特定のログは送信しないこと Deeplinkでホーム画面に遷移したとき、viewWillAppearでのログ送信はスキップすること 「どの動線で何が起きるべきか」という形でテストを書くことで、テストが仕様書として機能するようになります。内部実装がリファクタリングで変わっても、動線ベースのテストはそのまま維持できるため、保守性も高まりました。 テストを先に書くことで、「このUseCaseは何をすべきか」をチームで議論しながら設計を進めることができました。Step3でロジックの漏れがバグにつながったという反省が、ここで活きています。 オンボーディング周りの状態管理 HomeViewController は オンボーディング （初回起動時の案内フロー）周りの状態管理も複雑です。 リファクタリング前の課題 初めてZOZOTOWNアプリをインストールしたユーザーは、ホーム画面が表示されるまでに複数の案内画面を経由します。 問題は、この一連のフローを管理するために 5つ以上のBoolフラグ が複数のファイルにまたがって散在していたことでした。例えば「ログイン画面の表示が完了したか」「プッシュ通知許諾を表示したか」「訴求バナーの表示が必要か」といったフラグが各所に分散していました。それらを組み合わせた条件分岐によって次の表示内容が決まる構造になっていました。これにより、「今どのフラグがどの状態のとき何が起きるのか」を把握するだけでもかなりのコストがかかっていました。 このような複雑さが原因の1つとなり、オンボーディングに関する不具合が発生したこともありました。 ステートマシンによる再設計 Step4ではこのオンボーディングフローをステートマシンとして再設計しました。 オンボーディングは以下の4つの状態（State）と、それぞれを遷移させるイベント（Event）によってモデル化されます。 ViewModelはこの状態を購読し、状態に応じてどの画面を表示するかを宣言的に記述します。 この設計により、「現在のフローのどこにいるか」が状態として一点に集約され、遷移のトリガーとなるイベントも明示的になりました。それまでのフラグの組み合わせによる暗黙的な状態管理から脱却し、コードを読むだけでオンボーディングフローの全体像が把握できるようになりました。 また、「どのイベントでどの状態に遷移するか」をテストで直接検証できるようになりました。将来的にオンボーディングのステップが追加・変更されても、状態遷移の定義を修正するだけで対応できます。 こうして、約1年5か月にわたるホーム画面リアーキテクチャが完了しました。Step4に関しては、ホーム画面に起因する障害や問い合わせは発生しませんでした。 Step3で体験したバグと、その後段階的に整備したテストが、実際の品質保証として機能している結果だと感じています。 ホーム画面リアーキテクチャ完了後、後続案件でホーム画面を触った他のメンバーから「実装が楽になった」というフィードバックをもらいました。これは、責務が適切に分割されたことで改修の影響範囲が把握しやすくなったことを示しています。 また、ログ周りの修正が入ったときも「テストで挙動が担保できるようになった」という声がありました。Step3で体験したバグに対して、Step3-ex以降で構築したテストが実際に機能している瞬間でした。 長期リファクタリングを進める上でのポイント 今回のリアーキテクチャを通しての学びやポイントは各ステップで紹介しましたが、全体を通じて特に重要だと感じた点として、 設計ドキュメントの継続的な整備 を挙げます。 設計計画（段階的なステップ計画、インタフェース設計）を文書化しておくことは、長期にわたるプロジェクトをチームで共有する土台になります。「なぜこの設計にしたか」が残っていることで、後続のステップでも一貫した判断ができます。また、AIを活用したコーディングが一般的になった現在では、設計方針が文書化されていることはより一層重要です。AIへの指示の精度が上がるだけでなく、生成されたコードがプロジェクトの設計意図と一致しているかの検証にも役立ちます。 おわりに このリアーキテクチャを振り返ると、最初は「アーキテクチャについての理解を深めたい」という動機から始まりました。しかし実際には、「テストの重要性」「段階的な変更の価値」「失敗を次に活かすこと」という、より本質的なことを学んだプロジェクトになりました。 特に、Step3後のバグ発覚→Step3-exのテスト追加→Step4でのTDD採用でバグ0を達成できたことは、自分の成長を強く実感できたポイントでした。 ZOZOTOWN iOSアプリのリアーキテクチャはまだ続いています。このホーム画面での経験をチームの資産として積み上げながら、より良いアプリを作り続けていきたいと思います。 ZOZOでは、一緒にサービスを作り上げてくれる方を募集中です。ご興味のある方は、以下のリンクからぜひご応募ください。 corp.zozo.com

こんにちは。エンタープライズ第一本部 戦略ソリューション 1 部の英です。 普段はWebアプリやスマホアプリの案件などを担当しています。あと、趣味でAIを勉強しています。 世間ではClaude Codeが幅を利かせるなか、なぜかCodexにこだわり続けている私。 そろそろ流行りに乗らねばと思い、今回はClaude Codeの記事を書いてみます。 しかも、巷ではsuperpowersなんてものが話題になっているらしいじゃないですか。 エンジニアの英知を結集したAI駆動開発のベストプラクティス、superpowers。 これがあれば、Claude Code初心者の私でもプロ並みの開発ができるはずです。 この記事を書き終わっているころには、きっとCodex派からClaude派に寝返っているでしょう。 では、さっそくやっていきましょう。 1.Claude Codeとは 2.superpowersとは 3.Claude Codeの初期セットアップ 4.superpowersのインストール 5.superpowers-brainstorming 6.superpowers-using-git-worktrees 7.superpowers-writing-plans 8.superpowers-subagent-driven-development or executing-plans 9.superpowers-test-driven-development 10.superpowers-requesting-code-review 11.superpowers-finishing-a-development-branch 12. 動作確認 Plan2について さいごに Codexとの比較 開発効率とコスト 採用情報 1.Claude Codeとは Claude Codeは、Anthropic社が提供しているAIコーディングエージェント。 ターミナル上で動作し、コードの生成・修正・調査・テスト実行などを対話形式で進めることができる。 「AIにコードを書いてもらう」だけでなく、開発作業そのものを一緒に進めることができるツール。 2.superpowersとは superpowersは、Claude Codeをよりうまく活用するためのワークフロー集。 ブレスト、計画作成、TDD、コードレビュー依頼など、開発の各フェーズで使える“型”が用意されている。 Claude Codeに任せきりにするのではなく、人間とAIがうまく役割分担するためのベストプラクティス集。 これにより、Vibe CodingやSpec駆動開発の品質の底上げが期待できる。 参考： superpowers ※MITライセンス superpowersは以下のワークフローで構成されています。 要件を整理する 作業環境を分ける 実装計画を立てる テストを書きながら実装する(TDD) レビューする ブランチを仕上げる まず、 brainstorming で実装したい内容を整理します。 いきなりコードを書き始めるのではなく、Claude Codeが質問をしながら、目的・仕様・代替案・懸念点を明確にします。 ここで固めた内容が、後続の設計や実装計画の土台になります。 次に、 using-git-worktrees で作業用の独立した環境を作成します。 新しいブランチとworktreeを用意することで、既存の作業環境を壊さずに実装を進められます。 AIに実装を任せるうえで、安全に試行錯誤できる状態を作る工程です。 その後、 writing-plans で実装計画を作成します。 変更するファイル、実装手順、検証方法を小さなタスクに分解します。 READMEでは、プロジェクト理解が浅いジュニアエンジニアでも進められるくらい明確な計画を作る、と説明されています。 After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste 計画ができたら、 subagent-driven-development または executing-plans で実装を進めます。 前者はタスクごとにサブエージェントを割り当て、仕様準拠とコード品質を確認しながら進める方式です。 後者は計画に沿ってバッチ単位で実行し、人間の確認ポイントを挟みながら進める方式です。 実装中は、 test-driven-development によってTDDの流れが重視されます。 テストを先に書く、まだプロダクトコードがないのでテストが失敗する、テストがグリーン(正常に通過)するように実装を追加していくというRED-GREEN-REFACTORの流れです。 期待する振る舞いを先に定義することで、AIが「それっぽく動くコード」を書いて終わるのではなく、テストで確認可能な形で実装を進められます。 タスクの合間には、 requesting-code-review でコードレビューを行います。 実装が計画に沿っているか、バグや設計上の問題がないかを確認します。 重大な問題がある場合は、次に進む前に修正する流れになります。 最後に、 finishing-a-development-branch で開発ブランチを仕上げます。 テスト結果を確認し、マージするのか、Pull Requestを作るのか、ブランチを残すのか、破棄するのかを選択します。 不要になったworktreeの片付けまで含めて、開発作業を完了させます。 つまりsuperpowersは、 「考える → 分ける → 計画する → テストする → 実装する → レビューする → 仕上げる」 という 堅実な開発プロセスをAIエージェントに守らせるための仕組み です。 READMEにも “The agent checks for relevant skills before any task. Mandatory workflows, not suggestions.” とあるように、強制力を持ったワークフローとして設計されています。 3.Claude Codeの初期セットアップ 社内でClaude Enterpriseのライセンスを貰ったばかりでまっさらな状態。 とりあえず挨拶してトークンを無駄遣いしておきます。 VSCodeにClaude Codeの拡張機能を入れます。 ちなみに、CodexとClaude Codeのインストール数とレビューはこんな感じ。 Claude Codeのほうがシェアも評価も高い現状。 インストールが完了すると、ログイン方法を問われます。 先ほどのClaude Enterpriseのアカウントでログインします。 接続確認が表示されるので、「承認する」を押下します。 認証コードが吐かれたので、VSCodeに戻って貼り付けます。 通りました。何やら可愛らしいキャラクターが浮かんでいます。 挨拶して無駄にトークンを消費しておきましょう。 ちなみに彼は何という名前なんだろうと調べてみたところ、「Clawd(クロード)」というそうです。 Crab(蟹)のキャラクターか。かわいいですね。よろしくね、Clawd。 次はターミナルで使うためのインストール。 Pathを通し、インストール確認。 さあ、初めての起動だ。 ターミナルの色合いを選択します。(Dark mode) ログイン方法を選択します。 認証に成功しました。 読み飛ばす人も多いかもしれませんが、ここにとっても大事なことが書いてあります。 そんなmistakesを極力減らすのがこれから紹介するsuperpowersですね。 今回は初めての利用なので、推奨設定を選択します。 カレントディレクトリに対する権限を聞かれてます。ここは自由に操作していいのでYesを選択します。 セットアップが完了しました。 4.superpowersのインストール 公式のマーケットプレイスからインストールします。 このrepoだけでのインストールを選択します。 superpowersを手に入れました。 有効化します。 5.superpowers-brainstorming さて、準備が整ったのでAIとブレストしてみます。 superpowers「何について議論したいんだい？」 日本語もいけるのだろうか？ ただのToDoアプリじゃつまらないので、組織向けのタスク管理ツールをテーマにしてみます。 日本語で返ってきました。 なるほど、モックを見ながら方針を決めていく方法があるそうです。せっかくなので使ってみます。 brainstorming のスキルが読みたいと言っているので許可します。 ブレストが始まりました。 中規模を選択します。 ToDoタスクの振り方、ユースケースを問われています。全部必要そうなので、そのように回答します。 あとでClaude Codeが教えてくれるのですが、「一斉12人」は「一対多」の誤字とのこと。 タスクのリマインド方法ですが、自動を選択してみます。 通知方法はサービス内にしましょう。 認証はサービス独自を選択します。 デプロイ先はAWSを想定しているのでクラウドを選択します。 タスクの進捗確認をできる人ですが、複数選択可とのことで3つ選択してみます。 スコープが広すぎるようで、MVPを聞かれています。 まあいったん一斉送信の実装から入ってほしいですね。 ※MVP（Minimum Viable Product） これは絶対に聞かれると思っていました。完了の定義です。 ここはサービス上で「対応済み」を押させる仕組みで良いでしょう。 設計の確認が始まりました。 デモアプリでMulti-AZはリッチすぎますが、プロダクト開発に使えるか評価したいので、リッチな構成でいきましょう。 「違和感ないです。」と回答します。 次はデータモデルです。 Assignmentという中間テーブルで人とタスクを紐づけていますね。そしてここでステータス管理もしています。 Notificationで通知レコードを管理する構成になっています。良いと思います。 リマインドは複数回発生する可能性があるため、このテーブルで管理します。 良い設計ですね。自分で設計するにしてもこうすると思います。 兼務とかあるとややこしくなりますが、今回はシンプル構成でいきましょう。 次はユースケースのレビューです。 ちょっと、初期開発では不要な部分があるので省略を依頼します。 次は認証・認可周りの確認です。 ここの実装を削りたいので指示します。 次はエラーハンドリング周りの確認。 次はテスト戦略です。 初期開発としては十分すぎる計画だと思います。 ここまでの内容を設計書にまとめてくれるようです。 設計書の作成が始まりました。 6.superpowers-using-git-worktrees ローカルにgitを入れてもらい、writing-plansに引き継ぎます。 7.superpowers-writing-plans 引継ぎが終わりました。 今回はPlan1とPlan2に分かれ、Plan1でMVPを開発し、Plan2の方でデプロイ周りを計画しているようです。 ちなみに、ここまでの作業をccusageで確認。約$7でした。 $7か...個人利用だと厳しいな...。 8.superpowers-subagent-driven-development or executing-plans 次はこの計画を実行に移してもらいます。 進め方は1つのエージェントで逐次実行するか、サブエージェントを駆使してパラレルに開発するかが選べます。 今回はフルパワーが見たいので、サブエージェントを選択します。 サブエージェントのスキルが読み込まれました。 9.superpowers-test-driven-development こっから、基本的にはYesを叩く作業になるのでスクショは一部割愛します。 (AIエージェントに許可する権限を確認しつつ) Task 0.1が完了しました。ここまで30分くらい。 業務PCにdockerが未インストールだったため、ここで人間側にボールが渡ってきました。 ご丁寧に手順まで記載してくれているので、対応してAIエージェントにボールを戻します。 インストールが完了したので、続きを依頼します。 wslのバージョンが古くてDockerが起動できずに人間に返ってきたので、対応して続きを依頼します。 ローカルでPostgres起動、接続確認まできました。ここまで40分くらいでしょうか。 TDD用の環境セットアップが始まりました。 環境のセットアップが終わったので、ここからサブエージェントを駆使してコーディング部分を進めてもらいます。 サブエージェントでの開発に関するスキルが読み込まれました。 パスワード認証部分の仮実装が終わったようです。 TDDでテストコード→プロダクトコードの順番でコーディングが進んでいることがファイルからもわかります。 テストコードにはハッシュ化、パスの検証の正常系、異常系が書かれてます。 ちょっとテストが少ない気もしますが、あとで伏線回収するのでスルーしてください。 10.superpowers-requesting-code-review 部品の開発のたびに、コードレビューを呼んでいますね。 画像の中央付近にテスト品質に関する記載があります。 先ほどのテストケースはこの観点に通過する品質になっていることがわかります。 Test quality — Does the test verify behavior (not implementation)? Does it cover both happy path and one negative case (wrong password)? Does it avoid mocking the thing being tested? 次は権限部分のTDDが始まりました。 先に今回の3つの権限でのテストケースを作成していることがわかります。 失敗テストの作成、失敗確認、実装、成功確認というRED-GREENのサイクルを繰り返して開発が進んでいきます。 コードレビューで、prisma側の権限とアプリ内での権限で重複管理になるから、この書き方はやめてほしいとレビューで指摘を受けてますね。 そのイシューをもとに実装者が修正に入ってます。 なんだか、チーム開発っぽくなってきましたね。 11.superpowers-finishing-a-development-branch Plan1のPhase1が終わったタイミングで、finishing-a-development-branchのスキルを読ませました。 マイグレーションテストを通してくれました。 12. 動作確認 動作確認方法を聞いて、その通りに起動します。 ログイン画面が開いたのでログインしてみます。 ログインできました。 まだ最小限の機能しかないので、引き続き開発を続けます。 全体でPhase7のうち、まだPhase1の状態です。 Phase2はタスク作成周り。 1時間かからないくらいで、Phase2が完了。 Phase3は通知周りの実装。 Phase4はリマインダー周りの実装。 Phase5はダッシュボード周りの実装。 Phase6はE2Eテストの環境構築。 E2Eを実行したところ、1件passして、2件failedになりました。 結果をコピペして、Claude Codeに返します。 2件passして、1件failedになっていました。 再度、エラーログをClaude Codeに連携して修正を依頼しました。 再実行したろころE2Eにすべて合格しました。 ちなみに、E2Eの1つ目の中身はこんな感じです。 「依頼作成 → 担当者が対応済みにする → 依頼者が進捗を確認する」一連の業務フローをブラウザ上で確認するテストになっています。 2つ目はこんな感じ。 部署管理者向けダッシュボードのE2Eテストです。 「DBを初期化→ユーザーを作成→タスクを直接DBに作成→2人分の割り当てを作成→部署管理者でログイン→ダッシュボードを開く→表示を検証(棚卸、1/2 が見えること)」という流れになっています。 3つ目はこんな感じ。 リマインダー機能のE2Eテストです。 「DBを初期化→ユーザーを作成→タスクを直接DBに作成→担当者への割り当てを作成→リマインダーAPIを実行→担当者でログイン→通知画面を確認」という流れになっています。 E2Eに通過したことを伝えると、Phase7に取り掛かりました。 数時間後、Plan1がすべて完了しました。 ちなみに、ここまでかかったコストは約$98(≒1万5千円)でした。 Plan2について AWSへのデプロイはCodexでも容易にできるので、今回の記事では割愛させていただきます。 そのあたりの権限移譲周りについては 過去の記事 を参照してください。 さいごに Codexとの比較 Codexと比べて計画立てて自律的に走る能力が高い Codexと比べてコストが高い 自走してくれるから1日当たりの作業量が多い 計画を立てることにもトークンを消費する サブエージェントを使うと稀にハングする ハングした際にはctrl+oで状態を確認し、ctrl+cで止めてから、再実行を依頼する必要があった。 さらに、この際にsuperpowersのサイクルから外れることがあった。 この場合、以下のように命令してsuperpowersのフローに強制的に戻してもらう必要があった。 プロンプト：ハングしているから一時停止しました。superpowersのスキルを確認してTDDでの開発を継続してください。 開発効率とコスト ここまで約1～2日間でした。(ほかの作業をしながら裏で動かしただけ) コストも1～2万円程度でした。 BtoC/BtoB案件の一般的な開発ではプロダクトの初期開発にかなりの時間とコストがかかります。(技術的につまることが多々ある) これが大幅に削減できると思うと、人力開発の時代にはもう戻れないなと感じます。 採用情報 先日Xで「JTCでは社内のAI利用が進んでおらず働きにくい」みたいなのが話題になってましたが、弊社はこの数年間で各種AIツールのライセンスや申請周りがかなり整備され、めちゃくちゃ働きやすいです。AIを使って仕事したいSIの方はぜひご検討ください。。 ↓ のスターを押していただけると嬉しいです。励みになります。 最後まで読んでいただき、ありがとうございました。 エンタープライズ第一本部では一緒に働いてくださる仲間を募集中です。以下のリンクからお願いします。 私たちは一緒に働いてくれる仲間を募集しています！ 中途採用-エンタープライズ第一本部 新卒採用-エンタープライズ第一本部 執筆： 英 良治 (@hanabusa.ryoji) レビュー： @miyazawa.hibiki （ Shodo で執筆されました ）