はじめに
前回の記事では、CLAUDE.mdを「目次」として使って詳細ルールを別ファイルに分ける設計を紹介しました。
今回はその設計が実際の作業でどう機能しているか、事例ページを追加するときの具体的な手順を使って見せます。
シリーズ3本目です。
最初は「ページ追加して」と直接言っていた
このサイトでは、UIコンポーネントの事例ページ（デモ＋サンプルソース＋AIプロンプト）をひとつひとつ作っています。
最初は「テキストボックスの事例ページを追加して」とチャットで直接指示していました。Claude CodeがHTMLを作ってくれて、動くものが出てくる。最初の1〜2ページはこれでよかったんですが、ページが増えてくると困ったことが出てきました。
「できあがってから、イメージと違う」という手戻りです。
デモのリセットボタンが入っていない。インタラクションの仕様が自分の頭の中と違う。セクション構成がページによってバラバラ。チャットで修正のやり取りをするたびにClaudeの使用量が積み上がっていく。
「作れる」けど「イメージ通りに作れる」かどうかは別の話でした。
間にスペックMDを挟むことにした
対策として、HTMLを作る前に「スペックMD（仕様書のMarkdownファイル）」を挟む3ステップに変えました。
ステップ1：チャットで詰める
「こういうデモを作りたい」というざっくりした話をClaude Codeとチャットで言語化する。どういうインタラクションにするか、どんなパターンを見せるかを会話しながら決めていく。
ステップ2：MDファイルにしてもらう
詰めた内容をClaude CodeにMarkdownファイルとして書き出してもらう。このファイルが「スペックMD」です。プロジェクト内にdoc/examples/フォルダを用意し、1事例1ファイルで保存します。
ステップ3：MDを確認してからHTML作成
出来上がったMDを読んで「これが自分の作りたいもので合ってるか」を確認する。ズレや抜けがあればここで修正する。OKが出たら「このMDを元に事例ページのHTMLを作って」と指示してHTML生成。
ポイントは、MDは人間が読める形式なので「これが作りたいもので合ってるか」を自分で確認できるところです。チャットの会話ログだけだと、どこかに流れてしまって確認しにくい。MDというテキストファイルになってはじめて、落ち着いて見直せます。
スペックMDには何が書いてあるか
例として、バッジ（通知の赤丸）の事例ページで使ったスペックMDを見てみます。
デモのインタラクション仕様はこんな感じです。
- 「+1」ボタンをクリック → 件数が1増える - 「-1」ボタンをクリック → 件数が1減る（最小0で止まる） - 件数が100以上 → バッジ表示が「99+」に切り替わる - 件数が0 → バッジが非表示になる - 「クリア」ボタンをクリック → 件数が0になりバッジが消える
実際の事例ページはこちらで確認できます。
この「99+に切り替わる」「0件で非表示になる」という仕様、チャットで「バッジのデモ作って」と伝えるだけでは出てこないこともあります。MDに書いて確認することで、HTMLを作る前に「ここが抜けてた」を潰せます。
インタラクション仕様のほかに、基本情報・SEOメタ情報・サンプルソースの構造・AI用プロンプトなどもMDに含まれています。基本情報やSEOメタ情報はClaude Codeにお任せで作成します。サンプルソースはできあがったものを事前に見て、命名規則やセキュリティ対策で気になる点をこの段階でAIに確認し、不備があれば修正します。これが全部揃った状態で「HTMLを作って」と指示するので、出力が安定します。
この流れにした2つの理由
スペックMDを挟む理由は主に2つです。
Claudeの使用量削減
仕様のズレによる手戻りのやり取りがなくなります。「イメージと違う」から始まる修正ループがClaudeの使用量をじわじわ食っていたので、ここを潰せたのは地味に効きました。
仕様書として残しておきたい
MDファイルとして残ると、後から見返せます。似たような事例を作るときの雛形にもなる。「あのページどういう仕様だったっけ」がすぐわかる。
おまけで気づいたことがあって、MDを書く（正確には「書いてもらう内容をチャットで詰める」）作業を繰り返していると、最初から「どういうインタラクションにするか」「どんなパターンが必要か」を考える習慣がついてきた気がします。要件を言語化する練習に自然となっているというか。あまり意識していなかったんですが、気づいたら最初の頃より仕様の整理が早くなっていました。
正直なところ：完璧ではない
MDを確認してGOを出しても、実際にデモを動かしてみると「ここが違う」「この挙動が想定外」は出ます。
画面で動くものを見てはじめて気づくことは、MDの段階では防げない。なのでゼロにはなりません。
ただ、大きな手戻り（仕様の認識ズレ・構成のブレ）はほぼなくなりました。発生する問題の規模が小さくなった、という表現が正確かもしれません。
まとめ
AIにコードを作らせる前に、AIに仕様書を書かせる。
この1ステップを挟むだけで、手戻りが減ります。
手戻りが減る = AIとの無駄なやり取りが減る = Claudeの使用量が下がる = コストが下がる
効率よくAIを使いたいと思っていたんですが、行き着いたのは「仕様をちゃんと先に決める」という昔からある話でした。AIを使っていても、設計→仕様→実装の順番は変わらない。
こういう仕様設計・要件整理の考え方を体系的に身につけたいなら、オンライン学習という選択肢もあります。AI開発系のスクールでは無料カウンセリングを受け付けているところも多いので、「どんなことが学べるか」だけでも話を聞いてみるのもいいかもしれません。
最後まで読んでいただきありがとうございました。