開発の経緯

毎回デザインを指示しながら作ることに煩わしさを感じていました。その時、再利用できるデザインをあらかじめ定義しておけば、指示の負担を減らせるうえ、プロジェクト全体でデザインに一貫性を持たせられるはずと考えました。 その後、まず基盤となるテンプレートを自作しようとしていたときに react-shadcn(shadcn/ui)を発見し、これをベースとして採用しました。そのうえで、テンプレートをプロジェクトごとに最適な形へ変更しながら管理できるデザインシステムを作ろうと考え、開発に着手しました。現在の形では、brief から画面実装までを FlowSpec → SelectionSpec → BuildReport という3つの契約に分解し、AIが facets 付きの registry 在庫から選定理由つきでパターンを選ぶ仕組みになっています。このポートフォリオ自体も、そのシステムが選定・実装した成果物です。

詰まったところ

• 単独テンプレートの限界: 最初は1画面=1テンプレートで生成していましたが、実際のアプリは「一覧の上に詳細のDrawerが載る」「設定はDialogで開く」のような階層でできています。golden flow を通して画面を量産した際、この構造の欠如が原因で画面同士の整合が取れず問題が多発しました。ここで一度立ち止まり、画面を Page / ChildRoute / Drawer / Dialog の階層として設計し直し、アプリ全体の正本を studioAppSpec(docs/apps/studio/)に一本化しました。
• Radix と base-ui の混同: この registry は base-ui ベースですが、AIは学習データの Radix API(asChild など)を書きがちで、存在しないAPIによるビルドエラーが繰り返し起きました。「コンポーネントAPIに迷ったらソースを読む」を規約に明文化して抑え込みました。
• 検証の自己申告問題: AIの「できました」は完全には信用できません。契約のスキーマ検証に加え、生成物に provenance sidecar(入力digestの記録)を添えることで、「この画面はこの入力から作られた」を機械的に照合できるようにしました。

学んだところ

一番大きいのは、AIに対する解像度が上がったことです。開発を始める前は「漠然と指示を出していれば、AIがいい感じに作ってくれる」と思っていましたが、実際はそうではありませんでした。

• 自由記述の指示は毎回結果が揺れる。JSON Schema で入出力の形を契約として固定するなど、出力を安定させるための工夫が必要
• AIの「できました」は自己申告にすぎず、スキーマ検証や provenance のような機械的に裏取りできる仕組みを用意しないと品質を主張できない
• すべてを任せるのではなく、要所は人間が責任をもって判断する設計が、速度と品質を両立させる

指示の出し方・検証のさせ方・任せる範囲の切り方など、AIを使いこなすにはこうした多くの工夫が要ることを、実際に手を動かして知りました。

また、バグがないことと実用的であることは別問題だと学びました。今回の開発ではテストと検証をこまめに行い、バグを出さないよう努めていましたが、それは「そのシステムが実際に使いものになるか」を保証してくれません。単独テンプレートで開発を進めていた頃は、テストと検証が通っていることに満足してしまい、実用性そのものに問題があることへ気づけませんでした。これからはまず最小構成で一度動かしてみることを大切にします。あわせて、どこまでを機械的な契約で縛り、どこからをAIの推論に任せるか——その塩梅の難しさも実感しました。

さらに、AIのトークン使用量に対する感覚もかなり掴めました。

• 探索させず、対象のファイル名やパスを最初から指定する
• 具体化できる部分は人間側で具体化し、抽象的な部分は推論能力の高いAIに質問を重ねて詰めてもらう。やることが具体化できたら、それを実行役のAIに渡して実行させる
• 細かいテストと検証を後でまとめて行う場合は、途中の検証を省略させる
• 出力形式を固定して、余計な報告文を書かせない
• スクリプトで代用できる処理は AI にやらせず計算で済ませる

こうした工夫の積み重ねで、トークン使用量を抑えつつ意図どおりに作業させる力を、この開発を通じて身につけることができました。

今後

• 本開発ではタスク管理がすべて手動だったため、そこも同じように GUI を使ったシステムで管理できるようにしたい
• AIの効率的な使い方をさらに学び、使いこなせるようになる。今回得た「工夫が要る」という気づきを、再現可能なワークフローに育てていきたい