こんにちは。CADDi QuoteのQAエンジニアのosappyです。
「yamazakiでは埒が明かないため、技術選定についてエンジニアの方のご判断をお願いいたします」
これはデザイナーの山崎さんがClaude Codeに言われた言葉です。AIを使えばデザイナーもコードを書けるようになる、そう思って始めたものの、AIですら匙を投げる場面があります。環境構築でつまずく、Gitの操作がわからない、エラーの原因を切り分けられない——AIだけでは超えられない壁が次々と現れます。
我々のチームでは、デザイナーがStorybookでUIの画面仕様をコードとして定義するというアプローチに挑みました。その結果、入社3ヶ月半、Gitもターミナルも使ったことのないデザイナーが、約1.5ヶ月で251コミット・177ファイルを自力で書き、実装前に130件以上の仕様課題を発見・解決しています。デザイナー視点の詳細は山崎の記事をご覧ください。
デザイナーがここまで自走できた背景には、エンジニアの伴走がありました。本記事では、当時バックエンドエンジニアとしてデザイナーの伴走を担当した経験から、エンジニアが何をしたのかをお伝えします。この記事を読むと以下のことがわかります。
- デザイナーがStorybookを書くために、どんな環境を用意すればよいか
- エンジニアの伴走で「やること」と「やらないこと」の線引き
- 導入にかかる工数感
前提
本アプローチを適用したプロジェクトについて説明します。
本プロジェクトはB2B向けSaaSアプリに新たな機能を追加するプロジェクトです。 メンバーは、 PdM、エンジニア、デザイナーを含めた5-7名のチームで開発していました。 画面数は31個、ユースケースは23件で、全体工数は約半年と見積もられていました。
なおバックエンドは、AIを使ったユースケース駆動開発にトライしており、その記事はこちらで読めます。
安全に試行錯誤できる環境を作る
コードが書けないデザイナーが触る環境では、何をしても壊れない安心感が最も大事だと考えました。そのため、本番リポジトリとは完全に別のリポジトリ(仕様リポジトリ)を作り、Storybookを配置しました。
技術スタックはStorybook + Vite + React + TypeScriptです。社内デザインシステムをnpmパッケージとして導入し、本番と同じコンポーネントをStorybook上で使える状態にしました。
ディレクトリ構成は、下記の通りで本家リポジトリに移植しやすいように構造に合わせました。 当初はデザイナーが理解しやすいよう、リポジトリ内のディレクトリ構成とStorybookのサイドバー階層を別々に管理していました。しかし、二重管理は認知負荷が高いため、本家リポジトリのやり方を踏襲しました。
storybook/ ├── _template_component.md # コンポーネント用テンプレート ├── _template_page.md # ページコンポーネント用テンプレート ├── pages/ # 本番のディレクトリ構成に対応 │ ├── request/ │ │ ├── component/ # RequestPageコンポーネントで利用するコンポーネントを格納する │ │ ├── RequestPage.mdx # RequestPageの画面仕様を記述する │ │ ├── RequestPage.stories.tsx # Storyを記述する │ │ └── RequestPage.tsx # コンポーネント本体 │ ├── requestDetail/ │ ... ├── common/ ├── locales/ # i18nラベル定義 ├── data/ # ダミーデータ └── types/ # 型定義
コンポーネントは基本的に .mdx / .stories.tsx / .tsxのファイル3点セットで作成する必要があります。このルールはpre-commitフックで自動チェックされます。
また、画面仕様を書くためのテンプレートを設計しました。過去の手戻り事例を振り返ると、実装時に仕様が決まっていなくて困ったことにはパターンがありました。例えば、バリデーションのタイミング、データがないときの表示、デフォルトの並び順などです。これらを項目として洗い出し、テンプレートに落とし込んでいます。内容としては次のようなことが記述されています。
- 新規or既存の変更
- State(Empty, Loading, Partial, Error)
- カラム定義、ステータス定義
- フィルター・ソート仕様
- バリデーションルールとエラー表示タイミング
- スクロール挙動、ページネーション仕様
- i18nラベル定義
テンプレートがあることで、デザイナーは「何を決めるべきか」の出発点を持った状態で仕様書を書き始められるようになったり、AIへの入力としても活用できました。
ツールを整える
リポジトリを用意しただけでは、デザイナーは自走できません。デザイナーが使うツールについても整えました。
CUIを使う
デザイナーにはAIを活用する上で前提となるCUIにまず慣れていただきました。 Mac標準のターミナルでも構いませんが、素の状態では決して使いやすいとは言えません。 好きなターミナルアプリを入れるといいですよと伝えたところ Warpを選んでいました。 設定なしでコマンド履歴や補完がバッチリ効くので、初心者には使いやすいターミナルかもしれません。
山崎さんも最初は「黒い画面で文字を入力するなんてわかりにくいし操作しにくい」と言っていましたが、しばらくすると「GUIが煩わしい、CUI便利ですね」と言い始めました。使いやすい環境を整えた上でしばらく使ってみることが大事だと感じました。
Node.jsバージョンを揃える
山崎さんのNodeバージョンを確認したところ、brew経由でnode@20がインストールされていました。 このインストールの仕方だとプロダクト毎に使うNodeバージョンが異なるバージョンに対応できないのでバージョン管理ツールを使った方が良いと伝え、miseをインストールし、mise経由でNode.jsをインストールしました。 Node.jsは本家リポジトリと同じバージョンとしました。この作業は恐らくエンジニアがやったほうがよいでしょう。
Gitを使う
Gitの操作やGitHubの使い方も覚えてもらいました。用語や概念はサル先生のGit入門で学んでもらったものの 、Gitは怖いという印象が拭えなかったため、ペアプロを通じて一緒にコマンドを実行しながら不安を払拭していきました。 仕様リポジトリでは、ブランチはmainブランチのみで、PRは使わずに直Pushを許容する運用にしました。 作業者と作業範囲がぶつかり合うことはほぼないと判断してこの運用にしました。実際ほとんど競合が起こることはありませんでした。
Claude Codeを使う
山崎さんはClaude Codeに関しては既に使ったことがある状態でした。 しかし、コンテキストの扱い方については知らなかったので、同じチームの石田さんが書いたモデルの性能を引き出すための Claude Code コンテキストマネジメント入門の記事を紹介しました。コンテキストウィンドウの状況をすぐに把握するために、Claude Codeのステータスラインに表示するようにしました。設定方法は「claude code statusline context window」で検索すれば見つかります。 これらの設定をして、コンテキストウィンドウが40%を超えたら/clearするようになったり、コンテキストを汚してしまった場合は/rewindを使えばいいのか！など様々な学びがあったようです。
また、RaycastのWindow Management機能でウィンドウ配置のホットキーを設定し、Claude Codeとエディタの並列配置をワンタッチでできるようにしました。この設定は、文章で読むと大したことないのですが、実際に操作してみると、もうウィンドウ配置をマウスで整えることがなくなります。
デザイナーに伴走する
毎日1〜2時間のデイリーSyncを行いました。Slackのハドルで山崎さんの画面を共有してもらい、操作を見守りつつ注釈ツールで誘導するペアプロ形式で進めました。
初期はGitの操作やStorybookの書き方など、ツールの使い方を教えることが中心でした。慣れてくると、「このステータスの定義はこれで正しいか」「このバリデーションのタイミングはいつか」など、仕様そのものの議論へと移っていきました。
ツールや操作に関する伴走のスタンスは、デザイナーの習熟度に合わせて徐々に変化させました。最初は知識や操作を直接教えるティーチングが中心でしたが、慣れてくるにつれて答えを与えるのではなく気づきを引き出すコーチングへと切り替えていきました。
一方、仕様の議論になったときはコーチングのスタンスをあえて手放しました。エンジニアとデザイナーという役割の壁を取り払い、対等な立場で議論しました。仕様はどちらか一方が教えるものではなく、異なる視点を持ち寄って一緒に決めるものだからです。
山崎さんに感想を聞いたところ、『最初は右も左もわからずもどかしかったですが、のびのび放牧の環境で、教師と生徒ではなく対等な立場で議論できたからこそ、楽しく突っ走れました！』とのことでした。
やること・やらないこと
具体的に、伴走で「やること」と「やらないこと」を次のように線引きしていました。
やること
- 環境構築やツール設定など、デザイナーだけでは判断・解決が難しい技術的な土台づくり
- エラーが出たときの原因の切り分けと、解決の方向性を示すこと
- CLAUDE.mdやテンプレートなど、AIとの協業を助ける仕組みの整備
- 仕様の議論では対等な立場で一緒に考えること
やらないこと
- たとえ自分が書いた方が早くても、デザイナーの代わりにコードを書くこと
- AIで解決できる問題にエンジニアが介入すること
- まずAIに聞いてもらい、それでも解決しない場合にサポートする
- コードの品質を本番レベルに引き上げること
- 仕様リポジトリの目的は仕様の定義であり、コード品質ではない
工数
最後に、エンジニア側の工数を正直にお伝えします。導入を検討する方の参考になれば幸いです。
| 項目 | 工数 | 備考 |
|---|---|---|
| 環境構築 | トータル5日程度 | Storybook + Vite + React + TypeScriptの基盤構築。構築自体は半日で可能だが、フォルダやファイルの調整を繰り返した。最初からポリシーが決まっていればもう少し工数は減らすことは可能。 |
| 伴走 | 毎日1-2時間(同期) × 約2ヶ月 | ペアプロ形式の同期作業。デザイナーのオンボーディングを兼ねていた。 |
| コードレビュー | 週2時間程度(非同期) | 伴走とは別にレビューの時間を確保。このコードレビューを元に伴走の方針を考えた。 |
まとめ
この記事では、デザイナーがStorybookでUIの画面仕様を書くために、エンジニアが何をしたかを紹介しました。AIがあればデザイナーもコードを書ける時代ですが、AIだけでは超えられない壁があります。安全なリポジトリ、仕様書テンプレート、ツール環境といった土台を整え、代わりにやるのではなくCoachingで自走を支える——エンジニアの伴走があることで、デザイナーはAIを最大限活用しながら自分の力で前に進めるようになりました。
エンジニア1名の工数は、環境構築5日 + 毎日1〜2時間の伴走 × 約2ヶ月 + 週2時間のコードレビューでした。決して軽い投資ではありませんが、実装前に130件以上の仕様課題を潰せたことを考えると、十分なリターンがあったと考えています。
同じ課題を抱えるチームの参考になれば幸いです。
