本当に AI に使わせてみた — 文脈ゼロのエージェントに @gunjo/ui で設定画面を作らせる（やってみた #1）

やってみたシリーズ: 自作のデザインシステム @gunjo/ui（群青）で、AI エージェントに実際の UI を作らせていく連載。各回がそのまま「gunjo でこう作る」のハウツーにもなります。第1回は 設定画面。

@gunjo/ui を作るとき、僕は「AI から使えるように設計した」と書きました。typed entry point、機械可読メタデータ、AI-handoff ドキュメント——エージェントが「眺める」のではなく「読んで、使う」ための面を最初から組み込んだ、と。

でも、それはただの主張です。書くだけなら誰でも書ける。だから確かめました。

実験の条件 — 本物の採用者と同じ「コールド」

この文脈をまったく知らない AI エージェントを1体用意して、次の条件だけ渡しました。

• 公開済みの npm パッケージ @gunjo/ui と gunjo.jp の docs だけ
• ソースリポジトリは見せない（中身を読ませない＝本物の採用者と同じ）
• まっさらな Next.js（React 19 / Tailwind v4） アプリ
• ゴールは「動くものを npm run build まで自力で」

お題は設定画面。タブで Profile / Notifications を切り替え、プロフィールフォーム（名前・メール・Avatar）、ロール選択の Select、通知トグルの Switch——実アプリで誰もが一度は作る画面です。

やってみた

エージェントはまず docs を読み、3行のセットアップを引いてきました。

/* app/globals.css (Tailwind v4) */
@import "tailwindcss";
@config "../node_modules/@gunjo/ui/tailwind-preset.js";
@source "../node_modules/@gunjo/ui/src/**/*.{ts,tsx}";
@import "@gunjo/ui/styles";

そして——ここが効いた——必要なコンポーネントを単一の barrel から一気に import してきました。

import {
  Avatar, AvatarFallback, AvatarImage,
  Button, Card, CardContent, CardHeader, CardTitle,
  Container, FormField, FormLabel,
  Input, Select, Separator, Switch,
  Tabs, TabsContent, TabsList, TabsTrigger,
} from "@gunjo/ui";

迷子になっていない。@gunjo/ui 一点を見れば、何が在って何を組み合わせればいいかが分かる。組み立ても docs どおりでした。

<Tabs defaultValue="profile">
  <TabsList className="w-full">
    <TabsTrigger value="profile" className="flex-1">Profile</TabsTrigger>
    <TabsTrigger value="notifications" className="flex-1">Notifications</TabsTrigger>
  </TabsList>
  <TabsContent value="profile">
    <Card>{/* プロフィールフォーム */}</Card>
  </TabsContent>
</Tabs>

結果 — 動いた（4/5）

npm run build は通り、実機でタブ切り替えもフォームもトグルも動作、コンソールエラーなし。動く設定画面が完成しました。


エージェントの総合評価は 4/5。一番効いたものとして挙げたのは、やはり typed barrel export でした。曰く「API が1ファイルで全部見える——Inputs / Display / Navigation と分類済みで、最良の発見面」。設計の狙いが、文脈ゼロの相手にちゃんと届いていた。

そして、粗さも正直に見つかった

満点ではなく 4/5。残りの1点は、エージェントが率直に報告してきた粗さです。

• いくつかのフォーム部品が固定幅を焼いていて、カードいっぱいに広げるのに className での override が要った
• パッケージが同梱していない docs にリンクが張られていた（採用者の手元では 404）

「AI に使わせた」と気持ちよく書いて終わりにもできました。でも、この1点こそが価値です。本物の採用者が最初に踏む小石を、先に踏んでくれた。

直した — 報告をそのまま設計に戻す

報告を受けて、#47 で直しました。

• 固定幅プリミティブ（Input / Select / Tabs / Separator）を流体デフォルトに変更。w-full max-w-full を基本にして、狭めたいときだけ縛る形に
• ここで効くのが SSOT。固定幅は .pen（デザインソース）由来の style-hint なので、デザインソース → 実装 → ショーケース → サムネイルまで揃えて直さないと npm run design:verify が落ちる。直し漏れが構造的に許されない
• 同梱漏れの docs・リンク切れも埋めた

つまり「使わせて見つけた粗さ」が、思いつきの一箇所修正ではなく、3軸そろった一貫した修正として戻る。これが gunjo の背骨です。

学び — 「使わせて、見つけて、直す」ループ

AI に使わせる → 粗さが出る → SSOT で一貫して直す → また使わせる

AI-consumable は「そう設計した」と宣言するものではなく、実際にコールドな相手に通して、出た粗さを潰し続けることでしか証明できない——というのが今回の結論です。盛らない、隠さない。alpha のいま、この透明なループ自体を作り方として見せていきたい。

次回予告（やってみた #2 以降）

設定画面は入口です。続けて、実アプリで頻出のものを同じコールド条件で作らせていきます。

• モーダルでの告知バナー（Dialog / Toast の出し分け）
• カルーセルの設置（メディア一覧・LP のヒーロー）

各回、そのまま「gunjo でこう作る」ハウツーとして読めるようにします。

試す

• gunjo.jp — docs・ショーケース・パターン
• npm: @gunjo/ui ／ GitHub
• 母艦記事: 群青（@gunjo/ui）— SSOT で design / code / docs がズレないデザインシステム
• GunjoUI by UIXHERO

まだ alpha、粗削りな青です。フィードバックも Issue も歓迎。

---

<!-- 公開前: 母艦記事URL差込／スクショ差込／#48反映後の流体幅で再確認／EN(dev.to)ミラー -->