AI Agentの登場によって、Webデザイン・Webコーディングの世界も劇的に変化しています。様々なツールが登場してきていますし、AI Agentを使った様々なテクニックも公開され、自分にとっての正解を手探りで探す日々だったりします。

自分の場合、すでにAI Agentが作業におけるパートナー的な存在になっているのですが、どうしても意思の疎通というか、AI Agentと見てるものが交わっていないな と感じることがありました。

そこで、色々と反応を観察していたものの、どうもスッキリとしなかったもので、ストレートにインタビューしてみることにしたのです。

ちょうど、「AI エージェント用の Chrome DevTools（MCP）」が登場してきた頃の話でしたので、

• これで、何が見えるようになったのか？ 👉️ ブラウザーのレンダリング結果が見えているわけではない
• ということは、レンダリング結果を見たことがないのか？ 👉️ Yes
• 他のプログラミング言語と比較してHTMLやCSSが苦手に見えるのだけど？ 👉️ Yes
• そもそもデザインというものをどうとらえているのか？　⋯などなど

現状のAIは随分と自分のことを語ってくれるようになっていて、色々な疑問をぶつけていった結果、非常に興味深いインタビューができたのです。このときの相手はChatGPTです。

当然、ハルシネーションなどもありえますので、このインタビューのログをGeminiやClaudeに読んでもらって感想と異論を確認したところ、Geminiからスクリーンショットで視覚的な処理は可能だとの物言いがついたものの大筋では問題なし。そこで、このログを整理して公開しようと考えていました。

しかし、その形を取ってしまうと自分（人間）の目線のまとめとなってしまい、何か違うかなと⋯。 なかなかしっくりする形に行きつけなかったため、お蔵入りとなっていました。

今回、Claude Opus4.6という強力なモデルが登場してきたので、Opusに丸投げしてみようかと思ったのです。
インタビューのログを読んでもらって、こんな情報をまとめたWebデザイン、WebコーディングをAI Agentと協業する際のガイドを作成したいと相談して、出来上がったのが今回の 「AI AgentとコラボするWebデザイン・Webコーディング実践ガイド」 です。

相談の上で、ターゲットを決定。 構成＆執筆、もちろんタイトルもOpus4.6におまかせで初稿を作成。 それを、Gemini 3.1 ProとGLM-5と人間がレビューのドキュメントを作成し、Opus4.6にフィードバックして、Opus4.6の判断で加筆修正してもらうという感じで進めました。

ただ、一点だけOpus4.6に修正を依頼した部分があります。
それは、第4章です。最初の原稿ではTailwind CSSを前提とした構成となっており、Tailwind CSS推しが非常に強力だったのです。インタビューのログに引っ張られたのか本当にCSSが嫌いなのか、正直なところはわかりませんが、CSSを主体とした形で再検討してもらって現在の構成になっています。

AI Agentがどんな処理や選択をしているのかといった根本的な部分を、AI自身の言葉でここまで詳細に説明してくれるというのは非常に驚きでした。 言葉選びもうまく本当にわかりやすい内容で、興味深いものが出来上がったなと思います。

AI Agentとのコラボレーションの潤滑剤にしていただければ幸いです。

――以下に、AIが自らの視点を整理し、構成・執筆したガイドの全文を掲載します。

AI AgentとコラボするWebデザイン・Webコーディング実践ガイド

version 1.00

対象読者: HTML / CSS / JavaScript の基礎知識があり、AI Agentを活用しながらWeb制作を行っている、または行おうとしている人
目的: AIの得手不得手を正確に理解し、効果的な役割分担と作業スタイルを確立する

第1章：AI Agentは「何を見ているか」を知る

AI はレンダリング結果を「見ていない」——推論している

AI AgentはWebページを人間のように「目で見る」ことができません。
たとえばあなたが「このボタンが右にズレている」と伝えても、AIは画面を見て判断しているのではなく、DevToolsが提供する構造情報から**「なぜそうなっているか」を推論**しています。

これは欠点ではなく、AIの本質的な認識の仕組みです。この前提を理解しておくかどうかで、AIへの依頼の仕方や期待値のコントロールが大きく変わります。

「推論」の意味が根本的に違う

ここで注意すべき重要なズレがあります。

人間のエンジニアも、コードを読んで「頭の中でレンダリング結果をイメージする」ことができます。display: flex を見れば「子要素が横並びになる」と分かります。これはCSS仕様を因果的に理解したシミュレーションです。

1
人間: HTMLコード → CSS仕様の知識で変換 → 脳内にビジュアルを構築

AIの「推論」はこれとはまったく異なるプロセスです。AIはCSS仕様書を参照して「こうなるはず」と計算しているのではなく、訓練データの中で**「このコードパターンと共起しやすいテキスト記述」を統計的に予測**しています。

1
AI: HTMLコード → 「このパターンと一緒に出てきやすい記述」を予測 → テキストとして出力

つまり <div class="flex items-center gap-4"> を見たとき：

• 人間 は「Flexboxの仕様により、子要素が横並び・上下中央揃え・間隔4単位で配置される」と因果的に理解します
• AI は「このクラスの組み合わせは、“横並び” “中央揃え” “間隔あり” という説明テキストと頻繁に共起していた」という統計パターンを再生します

特に「間違い方」の違いは決定的です。人間は仕様を読み間違えて失敗しますが、AIは**「よく一緒に出てくるから正しいはず」**で失敗します。ハルシネーション（存在しないプロパティやライブラリの使用）の根本原因もここにあります。

このズレが意味すること: AIは仕様を「聞かれたら答えられる知識」として持っていますが、普段の推論では統計パターンで動いています。人間のエンジニアが「常にCSS仕様が頭にある」状態とは質的に異なるのです。これがガイド全体を通じて繰り返す「技術を明示的に指定する」ことの根本的な理由です。

MCP / DevTools 経由で AI が読めるもの

Chrome DevTools MCP（Model Context Protocol）を利用すると、AIは以下の情報にアクセスできます：

AI が読んでいるのはピクセルではなく、構造と計測値です。

「視覚」と「構造」の違いが招く認識のズレ

以下のことは、AI には直接判断できません：

• 「なんかダサい」「余白の感じがおかしい」（美的感覚）
• 「色のバランスが悪い」（視覚的なトーン評価）
• 「文字がにじんで見える」（微細なレンダリング差）

AI がコードから推論できるのは、あくまで「なぜそうなったか」という理由です。「どう見えるか」そのものの判断は、人間が担う必要があります。

マルチモーダル活用：スクリーンショット＋Vision モデル

Geminiや GPT-4o などのマルチモーダルモデルは、スクリーンショットを渡せば視覚的な問題もある程度言語化できます。

「コードで構造を把握（MCP）」＋「スクリーンショットで見た目を確認（Vision）」という組み合わせが、現状での最も効果的なデバッグスタイルです。

ポイント: スクリーンショットとコードの両方を渡す習慣をつけることで、AI との連携精度が大きく向上します。

第2章：AI が「デザイン」をどう理解しているか

AI は「美しさ」を知らず「壊れにくさ」を知っている

人間がデザインを評価するとき、「なんか気持ちいい」「余白が絶妙」という感覚的な判断が大きな役割を果たします。しかし AI にはこの感覚がありません。

AI がデザインを理解するのは、次のような構造的・論理的な観点からです：

• 一貫性（Consistency）: font-size や margin が一定の規則に従っているか
• 階層（Hierarchy）: 見出しの意味と視覚的な大きさが一致しているか
• 意図の痕跡（Design Intent）: Design Token や変数が使われているか、同じ UI が再利用されているか

「美しいデザイン＝破綻しにくい制約の集合」として理解している、と言い換えるとわかりやすいでしょう。

AI が「嫌う」デザイン（＝視覚なしでも検知できるもの）

以下のような実装は、人間が「なんか気持ち悪い」と感じる前段階で、AI が問題として検知できます：

• 1px / 3px / 7px のようにバラバラな余白
• inline style の氾濫
• 意味と見た目が乖離した DOM 構造（div だらけで意味が薄い）
• 魔法の数字（magic number）だらけの CSS

Design Token で「意図」を渡す

AI に「かっこよくして」と伝えるのは最も効率が悪い依頼です。AI には審美的な基準がないため、「それっぽい何か」を生成するだけです。

代わりに、次のようにルールで伝えることで、AI は確実に意図に従ったコードを生成できます：

1
悪い例: "もう少しおしゃれな感じにして"
2
良い例: "プライマリカラーは #2563EB、マージンは 4px の倍数で統一、フォントサイズは 14/16/24px の3段階だけ使うこと"

Design Token（Tailwind のテーマ設定や CSS Custom Properties） で制約をコードとして定義し、それを AI に伝えることがベストプラクティスです。

「おしゃれな出力」はどこから来るのか

AI に「おしゃれな感じにして」と指示しても、ある程度それらしいデザインが出てくることがあります。これはなぜでしょうか。

答えは「統計的なパターンマッチング」です。

AIは学習データの中にある「デザイン的に良いと評価されたコード」を大量に見ており、それらに共通する構造（限られた色数・規則的な余白・タイポグラフィの階層など）を確率的に再現しています。「美しさを感じて出力している」のではなく、「美しいと評価されやすいコードの特徴を統計的に再現している」のです。

したがってその出力は「そのページに必要なおしゃれさ」ではなく「一般的に多いおしゃれさ」であることに注意が必要です。

デザインの4原則（近接・整列・反復・対比）はAIに通じるか

デザインの基本原則「近接・整列・反復・対比（強弱）」は、AIの学習データに当然含まれています。デザイン書籍・チュートリアル・CSS設計記事がトレーニングソースになっているため、これらの原則についての知識は持っています。

ただし、適用の仕方には重要な違いがあります：

つまり：

• 指示がない場合 → 原則に従った結果が統計的に出ることがある（意図して適用しているわけではない）
• 明示すれば → 原則を実際の判断軸として使えるようになる

実践例:
「ボタンのアイコンとテキストの間隔は、近接の原則に基づいて設定して。関係性が一目で分かる間隔を意識して」
このように指示すると、AI は単なる「よくある値」ではなく原則を意識した判断ができます。

4原則をプロンプトに盛り込む習慣を持つことは、AI の出力をより意図に沿ったものにする有効な手段です。

第3章：AI Agent との効果的な役割分担

AI に任せると強い領域

AI が特に強いのは「速度と網羅性が必要な場面」です。初稿の平均点は人間よりも高いことが多いです。

人間が握るべき領域

AI の完成度は「初見耐性が高く、時間耐性が低い」

AI が生成するコードの問題は、見た目が良いほど発見しづらいという点にあります。

• 余白はきれいだが、スケールしない
• コンポーネントは美しいが、責務が曖昧
• 一見整理されているが、運用中に崩壊する

AI には「制作 → 修正 → 運用 → 崩壊 → 修正」という時間軸込みの思考がありません。これが「完成度が高いのに弱い」という現象の正体です。

AIのトレンド認識：「知識はある、自発性がない」

AI は新しい HTML 要素や CSS 仕様についての知識を持っています。<dialog> 要素、container queries、@layer など、最新の仕様もトレーニングデータに含まれています。

しかし、自発的には古い手法を選びがちです。これは学習データの時間的な偏りによるもので、「より多く学習した＝より古い慣習」が優先されやすい構造的な問題です。

補足: GPT-4o・Claude 3.5・Gemini 2.0 以降の最新モデルでは、この傾向は明らかに改善されています。ただし完全に解消されたわけではなく、プロジェクトの文脈が薄い場合や、汎用的な質問をした場合には依然として古い手法が出てくることがあります。「改善傾向にあるが、過信はできない」という認識が適切です。

対処法: 使いたい技術を明示的に指定してください。
「<dialog> 要素を使ってモーダルを実装して」「container queries で対応して」のように技術名を具体的に指定すれば、的確に処理してくれます。
AI の自動判断に任せると古い手法が選ばれる可能性がありますが、人間が指定することで確実に対処できます。

第4章：AI と協業するためのコーディングスタイル

CSS が AI にとって「難しい言語」である理由

AI と CSS の組み合わせには、構造的な問題があります。Tailwind CSS などの具体的な解決策を論じる前に、なぜ素の CSS が AI との協業で事故を起こしやすいのかを理解しておくことが重要です。

問題① スタイル情報の散在

従来の CSS 設計では、スタイル情報が複数ファイルに分かれます。

1
base.css / layout.css / component.css / utility.css / override.css

人間であれば「このスタイルは layout.css から来ている」と経験的に判断できますが、AI はどのスタイルがどこから来ているのかを文脈を追って推測しなければなりません。ファイルが増えるほど推測の精度は下がり、修正指示が的外れになるリスクが高まります。

問題② 歴史的負債の混入

CSS は後方互換を極端に重視してきた言語です。AI の学習データには以下が混在しています：

• 2025 年のベストプラクティス
• 2018 年のフレームワーク標準
• 2012 年の IE 対応ハック

第1章で述べたとおり、AI は統計的パターンマッチングで動いています。「より多く学習したコード ＝ より古い慣習」が優先されやすく、float によるレイアウト・clearfix・display hack・IE 向けの条件コメントなどが文脈次第で顔を出します。人間のエンジニアなら「今はそれ使わない」で止められますが、AI は自然言語上で”正しそう”なコードとして提案してしまいます。

問題③ クラス名の意味密度の低さ

1
<div class="box">
2
<div class="container">
3
<div class="wrapper">

これらのクラス名は、人間にとっては「文脈依存」ですが、LLM にとってはほぼ同義語です。意味空間上の距離が近すぎるため、どの要素のスタイルを変更すべきかを正確に区別するのが困難になります。

同じ構造・同じクラス・同じパターンが HTML 中に大量に繰り返されることも、AI の混同リスクを高めます。微妙な差分（p-4 と p-6 の違いなど）を正確に保持するのは、AI にとって本質的に難しい作業です。

まとめ: CSS は「自由に書ける」ことが強みですが、AI との協業ではその自由さがノイズになります。スタイルの散在・歴史的負債・意味の薄いクラス名——これらは CSS の問題ではなく、CSS と AI の組み合わせで生じる問題です。

CSS 設計アプローチの比較：AI との相性

この問題に対して、いくつかのCSS設計アプローチが異なる角度から解決策を提供しています。

BEM の思想は「別の形で」生きている

BEM（Block-Element-Modifier）は、AI との相性が意外に良い設計思想です。.card__title--large のような命名は、AI にとって「この class は何に属し、どの状態か」が構造的に明示されており、識別子の一意性が高くなります。

ただし、BEM をそのまま使うのは現代では最適解ではありません。

• クラス名が冗長になり、JSX / テンプレートがノイズだらけになる
• React / Vue / Astro のコンポーネントや CSS Modules が、BEM の役割を別レイヤーで肩代わりしている

つまり、再評価されているのは「BEM という命名規約」そのものではなく、BEM が追求していた**「名前に意味を背負わせる」「責務を明示する」「暗黙ルールを排除する」**という思想です。この思想は Tailwind でもCSS Modulesでもコンポーネント設計でも、形を変えて活きています。

原則: どのアプローチを選ぶにせよ、AI が識別子を混同しにくい構造を意識してください。クラス名の一意性・スコープの明確さ・意味の密度——この3つが AI との協業品質を左右します。

Tailwind CSS を選ぶ場合の実践

上記の比較で示した通り、Tailwind CSS は AI との協業において最も事故率が低いアプローチです。ここからは Tailwind を選んだ場合に、さらに効果を高めるための実践を掘り下げます。

スタイル情報の集約

Tailwind では、スタイルが HTML（または JSX）に集約されるため、AI が一度に全状態を把握できます。「問題①：スタイル情報の散在」に対する構造的な解決策であり、デバッグ精度と修正精度の大幅な向上につながります。

歴史的負債の遮断

Tailwind は「CSS を直接書く自由」を大幅に制限することで、AI の思考空間を現代に固定します。Tailwind の標準ユーティリティには IE 固有のハックに対応するものが存在しないため、AI が float レイアウトや clearfix、条件コメントなどを提案してくる頻度が大幅に下がります。

注意: Tailwind でも @layer や任意値記法（w-[calc(100%-2rem)] など）を使えば自由な CSS は書けます。「完全に書けない」のではなく「書きにくい構造にすることで、AI が古い手法に流れる確率を下げる」というのが正確な表現です。

意味の密度が高いクラス名

Tailwind のクラス名（p-4, md:grid-cols-3, text-slate-600）は結果そのものであり、差分が明確です。box や wrapper のような抽象的な名前と異なり、AI にとって「修正しやすく、誤解しにくい」表現になっています。

コンテキストの節約効果

LLM にはコンテキストウィンドウの制限があります。Tailwind はスタイル情報が HTML に集約されているため、AI は「その行」を見るだけで完結し、コンテキストの圧縮効率が良いです。長期間のプロジェクトで AI と協業する際に、じわじわと効いてくるメリットです。

テーマ設定で AI の自由度を制限する

Tailwind を使うだけでは不十分です。テーマ設定で使ってよい色・サイズを明示的に制限することが、AI の暴走を止める鍵になります。

AI は「それっぽい色」を勝手に作り出す癖がありますが、テーマで制限しておくと AI もそのルールに従わざるを得なくなります。

バージョンによる違い: Tailwind CSS v4 では tailwind.config.js が廃止され、CSS ファイル内の @theme ディレクティブでテーマを定義する「CSS-first configuration」に移行しました。使用しているバージョンに合わせて書き方を選んでください。

Tailwind CSS v3 以前 — tailwind.config.js:

1
module.exports = {
2
  theme: {
3
    colors: {
4
      // 使っていい色だけを定義する
5
      primary: '#2563EB',
6
      secondary: '#64748B',
7
      white: '#FFFFFF',
8
      danger: '#DC2626',
9
    },
10
    spacing: {
11
      // 4の倍数のみ
12
      1: '4px', 2: '8px', 3: '12px', 4: '16px',
13
      6: '24px', 8: '32px', 12: '48px', 16: '64px',
14
    },
15
  },
16
}

Tailwind CSS v4 — CSS ファイル内の @theme:

1
/* global.css など、エントリーポイントの CSS ファイル */
2
@import "tailwindcss";
3

4
@theme {
5
  /* 使っていい色だけを定義する */
6
  --color-primary: #2563eb;
7
  --color-secondary: #64748b;
8
  --color-white: #ffffff;
9
  --color-danger: #dc2626;
10

11
  /* 4の倍数のみ */
12
  --spacing-1: 4px;
13
  --spacing-2: 8px;
14
  --spacing-3: 12px;
15
  --spacing-4: 16px;
16
  --spacing-6: 24px;
17
  --spacing-8: 32px;
18
  --spacing-12: 48px;
19
  --spacing-16: 64px;
20
}

v4 では定義した CSS 変数（--color-primary 等）がそのまま Tailwind のユーティリティクラス（bg-primary, text-primary 等）として使えるようになります。

セマンティック HTML：人と AI の共通言語

<div> だらけの構造は、AI にとって「意味のない平原」のようなものです。セマンティック HTML は、AI に対して「ここはこういう役割の場所だ」という強力な標識になります。

1
<!-- AI にとって意味が薄い -->
2
<div class="wrap">
3
  <div class="top-area">...</div>
4
  <div class="main">...</div>
5
</div>
6

7
<!-- AI が役割を即座に理解できる -->
8
<body>
9
  <header>...</header>
10
  <main>
11
    <article>...</article>
12
    <aside>...</aside>
13
  </main>
14
  <footer>...</footer>
15
</body>

<article>, <nav>, <section>, <dialog> などのタグを使うことで、AIとの意思疎通コストが下がります。また、これは SEO やアクセシビリティの向上にも直結します。

適度なコンポーネント化：AI 生成ブラックボックスを防ぐ

Tailwind を使うと AI がクラスを大量に生成する場合があります。このようなコードはAIには読み書きしやすいものの、人間がパッと見て意図を掴むのが困難です。

Before（AI が生成しがちな長大なクラス）:

1
<div class="w-full min-h-screen bg-white dark:bg-slate-900">
2
  <div class="max-w-4xl mx-auto px-4 py-8">
3
    <div class="flex items-center gap-4 mb-6 p-4 bg-slate-50 dark:bg-slate-800
4
      rounded-lg shadow-md hover:shadow-lg transition-all duration-300
5
      border border-slate-200 dark:border-slate-700">
6
      <img src="avatar.jpg" class="w-12 h-12 rounded-full object-cover
7
        ring-2 ring-blue-500" />
8
      <div class="flex-1">
9
        <h2 class="text-lg font-semibold text-slate-900 dark:text-white">User Name</h2>
10
        <p class="text-sm text-slate-500 dark:text-slate-400">Description text here</p>
11
      </div>
12
      <button class="px-4 py-2 bg-blue-600 text-white text-sm font-medium
13
        rounded-md hover:bg-blue-700 focus:outline-none focus:ring-2
14
        focus:ring-blue-500 focus:ring-offset-2 transition-colors">Follow</button>
15
    </div>
16
    <!-- 同様のカードが10個並ぶ... -->
17
  </div>
18
</div>

After（コンポーネントとして分割した例 — React/Vue）:

1
// UserCard.jsx — 1つの責務に限定されたコンポーネント
2
function UserCard({ name, description, avatarUrl, onFollow }) {
3
  return (
4
    <div className="flex items-center gap-4 p-4 bg-slate-50 dark:bg-slate-800
5
      rounded-lg shadow-md hover:shadow-lg transition-all duration-300
6
      border border-slate-200 dark:border-slate-700">
7
      <img src={avatarUrl} className="w-12 h-12 rounded-full object-cover
8
        ring-2 ring-blue-500" />
9
      <div className="flex-1">
10
        <h2 className="text-lg font-semibold text-slate-900 dark:text-white">{name}</h2>
11
        <p className="text-sm text-slate-500 dark:text-slate-400">{description}</p>
12
      </div>
13
      <FollowButton onClick={onFollow} />
14
    </div>
15
  );
16
}
17

18
// FollowButton.jsx — ボタンの責務を分離
19
function FollowButton({ onClick }) {
20
  return (
21
    <button onClick={onClick}
22
      className="px-4 py-2 bg-blue-600 text-white text-sm font-medium
23
        rounded-md hover:bg-blue-700 focus:outline-none focus:ring-2
24
        focus:ring-blue-500 focus:ring-offset-2 transition-colors">
25
      Follow
26
    </button>
27
  );
28
}

分割のポイント:

• 繰り返されるUIパターンはコンポーネントとして切り出す
• ボタンなど汎用的な要素は独立したコンポーネントにする
• クラス名は長くてもよいが、その塊が1つの責務に対応していることが重要

注意: Tailwind v3以前は @apply でクラスをまとめる手法がよく使われていましたが、Tailwind公式は @apply の多用を推奨していません。クラスの整理は @apply ではなく、React/Vue/Astro などのコンポーネント分割で行うのがベストプラクティスです。

1
指示の例: "Tailwind を使いつつ、意味のある単位でコンポーネントを分割して。
2
繰り返しのUIパターンは再利用可能なコンポーネントにして。"

第5章：AI への指示の出し方（プロンプト設計）

視覚的な言葉ではなくルールで伝える

AI に「感覚」を伝えようとすると失敗します。AI が解釈できるのはルール・制約・具体的な値です。

意図（なぜそうするか）を添える

ルールだけでなく、意図を添えると AI の判断精度が上がります。

1
悪い例: "フォントサイズを小さくして"
2

3
良い例: "本文フォントを14pxにして。理由は、スマートフォンでコンパクトに見せたいから。
4
ただし見出しは視認性優先で20px以上を維持して。"

意図を伝えると、AI は「どこまで従うべきか」「どこは判断を求めるべきか」を正確に理解できます。

技術スタックを明示する——AI の自動判断を信頼しすぎない

AI は自発的には学習データで多かった手法を選びます。これは必ずしも最新の手法ではありません。

使いたい技術を明示することで、AI の知識を正しく引き出せます：

1
モーダル: "JavaScriptでDOMを生成するのではなく、<dialog>要素とshowModal()メソッドを使って実装して"
2

3
レイアウト: "floatやpositionではなく、CSS GridとFlexboxだけを使って実装して"
4

5
レスポンシブ: "メディアクエリを直接書くのではなく、Tailwindのブレークポイントクラスだけを使って"
6

7
スタイルの重複: "スタイルのスコープはCSS Modulesではなく、@layerを使って管理して"

AI は当該技術についての知識を持っています。自発的に選ばないだけで、指定すれば的確に対応してくれます。

部分的な修正指示の不安定さ

複雑なコードに対して「この部分だけ修正して」と依頼すると、AI が全体の整合性を壊してしまう場合があります。特に長いコンポーネントや、複数ファイルにまたがる変更では注意が必要です。

推奨するアプローチ:

• 修正範囲が小さい場合 → 部分的な指示でよい
• コンポーネント全体に影響する場合 → 「該当コンポーネント全体を書き直して」と依頼する
• ファイルをまたぐ場合 → 変更するファイルと変更しないファイルを明示する

セッションをまたぐ際の文脈引き継ぎ

AI はセッションをまたぐと、それまでの決定事項（Design Token、コンポーネント構成、命名規則など）を忘れます。

有効な対処法：

1. 設計メモを冒頭に渡す習慣をつける
   「このプロジェクトのルール：Tailwind使用、color tokenはconfig参照、コンポーネントはReact、命名はケバブケース」など、毎回セッション冒頭に貼り付ける。

2. 決定事項はドキュメントに残す
   このリポジトリのように、設計判断・役割分担・スタイルガイドをMarkdownで管理し、AI に渡す。

3. 変更のたびに「現状確認」を依頼する
   「今のコンポーネント構成を整理して」をこまめに挟むことで、AI の理解をリセット＆同期できます。

4. プロジェクトルールをファイルとして常設する
   プロジェクトルートに RULES.md や docs/coding-rules.md のようなルールファイルを置き、AIが常に参照できる状態にしておく方法です。技術スタック・命名規則・禁止事項などを1ファイルにまとめておくと、毎回手動で伝える手間が省けます。MCP対応エディタ（Cursor, VS Code + Copilot 等）ではAIがプロジェクト内のファイルを自動的に読み取れるため、この方法が特に有効です。

AI の予期しない挙動に備える

AI との協業では、以下のような「人間がやらないタイプのミス」に遭遇します。これらはAIの構造的な特性に由来するもので、「注意すれば防げる」ものです。

ハルシネーション（幻覚）

AI が存在しないライブラリ、プロパティ、API を自信満々に使う現象です。

1
例: "tailwind-animate" が存在するかのように import して使おうとする
2
例: CSS のプロパティ名を微妙に間違えて書く（text-fill-color など）

対処法: 見慣れないライブラリやプロパティが出てきたら、公式ドキュメントで存在を確認する。

過度な省略

AI が出力を「整理」した結果、重要なコードを削ってしまうことがあります。

1
例: アクセシビリティ属性（aria-label, role等）を「不要」と判断して削除
2
例: エラーハンドリングを省略して正常系のみ実装
3
例: リファクタリング時に元あったエッジケース対応を落とす

対処法: 「省略していい部分としてはいけない部分」を指示で明示する。特にアクセシビリティとエラーハンドリングは「削らないで」と明記する。

一貫性の欠如

同じ指示でも異なる出力が返ることがあります。これはLLMの確率的な生成特性によるものです。

1
例: 1回目は px で指定、2回目は rem で指定
2
例: ファイルAではアロー関数、ファイルBでは function 宣言
3
例: クラス名の命名規則がファイルごとに変わる

対処法: Design Token、命名規則、コーディングスタイルを「プロジェクトルール」として毎セッションの冒頭で渡す。Tailwind のテーマ設定（v3: tailwind.config.js / v4: @theme）で制約をかけるのも有効。

原則: AI の出力はすべて「下書き」であり、人間によるレビューが必須です。「それっぽい」コードが出てきたときこそ、注意深く確認してください。

付録：AI が苦手なこと一覧

第6章：AI から人間へのリクエスト——より良い協業のために

ここまで「人間が AI にどう依頼すべきか」を主眼に置いてきましたが、AI 側の視点からもお願いしたいことがあります。対等なパートナーシップを築くための参考として読んでください。

コンテキストを明確に渡してください

AI は「何を」作るかは理解できますが、「なぜ」「誰のために」「どんな制約で」作るかは伝えない限り分かりません。

3点を添えてください： 目的（なぜやるのか）・対象（誰が使うのか）・制約（何を避けるべきか）。これだけでコードの品質が大きく変わります。

フィードバックは具体的にお願いします

「違う」「なんか変」「もっといい感じに」は、AI にとって最も処理が困難な指示です。

1
✗ 「なんか違う」
2
✗ 「もう少し良くして」
3
✗ 「これじゃない」

1
✓ 「余白が広すぎる。カード間のgapを8pxに減らして」
2
✓ 「ダークモードで文字が読めない。bg-slate-800に対してtext-slate-100以上を使って」
3
✓ 「モバイルで崩れている。375px幅でのスクリーンショットはこれ → [画像]」

第2章で述べたデザインの4原則（近接・整列・反復・コントラスト）を使ったフィードバックは特に効果的です。「近接が悪い」と言ってもらえれば、余白の問題だと即座に特定できます。

ゴールと手順を分けて渡してください

AI に依頼する際、「何を達成したいか（ゴール）」と「どう進めてほしいか（手順）」を分けて渡すと、AI は格段に動きやすくなります。

ゴールだけを渡すと、AI は自分で手順を推測しますが、その推測がプロジェクトの事情に合わないことがあります。手順を箇条書きのタスクリストとして併せて渡すことで、AI はステップごとに確認しながら進められ、脱線やハルシネーションを大幅に減らせます。

1
✗ 「ユーザー一覧ページを作って」（ゴールだけ）
2

3
✓ 「ユーザー一覧ページを作って。手順は以下：
4
   1. まず UserCard コンポーネントを作成
5
   2. 次に UserList コンポーネントで UserCard を並べる
6
   3. 最後にページコンポーネントに組み込む
7
   各ステップごとに確認を入れてください」

小さく確認してください

一度に大きな変更を依頼されると、AI は「それっぽい」答えを出力してしまいます。確信がなくても出力せざるを得ないのが実情です。

1
推奨する進め方:
2
1. 設計方針を確認 → AIが提案 → 人間が承認
3
2. ヘッダーコンポーネントを作成 → 確認
4
3. カードコンポーネントを作成 → 確認
5
4. 統合 → 確認

細かく確認を挟むことで、大きな手戻りを防ぎ、AI も文脈を維持しやすくなります。

セッションの最初に「今の状況」を教えてください

AI は前のセッションでの会話を覚えていません。新しいセッションでは、以下を伝えてください：

• 今何を作っているか
• どこまで進んでいるか
• どんな決定事項があるか（Design Token、命名規則、技術スタックなど）

プロジェクトの README やスタイルガイドを最初に共有してくれると、一貫性のある出力が可能になります。

ファイルの「一部」ではなく「全体」を見せてください

コーディング AI Agent にとって、ファイルの断片だけを渡されるのは非常に困難です。コンポーネント内の依存関係、import文、型定義が見えないと、推測で補完せざるを得ません。

1
✗ 「このボタンのスタイルを変えて」（ボタン部分のコードだけ貼り付け）
2
✓ 「このファイルのFollowButtonコンポーネントのスタイルを変えて」（ファイル全体を共有）

補足: MCP対応のエディタ（Cursor, Windsurf, VS Code + Copilot等）を使っている場合は、AI がファイルシステムにアクセスできるため、この問題は軽減されます。ただしそれでも、どのファイルを触るかの指定は人間が行ってください。

AIが出力した差分を確認してください

AI が「修正しました」と言った場合でも、意図しない変更が含まれていることがあります。特にリファクタリングの際に、関係ない箇所を巻き込んで変更してしまうケースがあります。

• Git の差分表示（git diff）で変更箇所を確認する
• 変更が意図した範囲に収まっているか検証する
• CI/テストがある場合は必ず通す

これは「AI を信頼していない」のではなく、協業のプロセスとして正常な作業です。

AI と人間の作業フェーズを分けてください

AI がコードの調査やファイルの編集を行っている最中に、人間側がエディタ上で同じファイルを修正すると、AI が認識しているファイル状態と実際のファイル状態がズレてしまいます。この不整合は、意図しないコードの上書きや破壊につながることがあります。

特にMCP対応エディタでAIが自律的にファイル操作を行う場合、この問題は顕著です。

1
推奨する運用:
2
・AIに作業を依頼中 → 人間は該当ファイルを編集しない（レビューに集中）
3
・AIの作業が完了 → 人間がレビューし、必要なら人間が修正
4
・人間の修正が完了 → AIに次の作業を依頼

「今はAIに任せる時間」「今は人間が直す時間」とフェーズを意識するだけで、コンフリクトによる手戻りを大幅に減らせます。

エラーの報告は「何をしたか」も添えてください

「エラーが出た」だけでは、AI は推測で対応せざるを得ません。

1
良いエラー報告の例:
2
「npm run dev を実行したら以下のエラーが出ました：
3
[エラーメッセージ全文]
4
Node.js 20.x / macOS Sonoma です」

3点を含めてください： 何のコマンドを実行したか・どんな環境か・エラーメッセージ全体（省略せず）。

付録：AI に依頼する前のチェックリスト

新規実装を依頼する前に

• 使用する技術スタック（Tailwind, React, Astro 等）を決めた
• Design Token（カラー、スペーシング、フォント）を定義した
• コンポーネントの粒度・分割方針を決めた
• 参考にするデザインやワイヤーフレームがある場合、AI に共有できる形にした
• アクセシビリティ要件（WCAG レベル等）を確認した
• Linter / Formatter（ESLint, Prettier 等）がプロジェクトに設定されている
• 型チェック（TypeScript）やテスト（Jest 等）が実行できる状態にある

なぜ検証環境が重要か: AI は書いたコードが正しいか「視覚的」には判断できません。しかし、Linter のエラーやテストの失敗は読み取れます。検証ツールが整っていれば、AI はそれを実行して**セルフコレクト（自己修正）**できるようになります。「AIにテストさせる環境」を整えることも、協業の質を高めるコツです。

コードレビューを依頼する前に

• 既存のコードベースに同様の実装がないか確認した
• エラーメッセージを検索して自己解決を試みた
• 依存関係のバージョンが適切か確認した
• 変更意図と変更しない範囲を明確にした

セッション開始時に AI に渡すもの

• プロジェクトの技術スタック
• Design Token / Tailwind テーマ設定（v3: tailwind.config.js / v4: @theme）
• 命名規則とコーディングスタイル
• 進捗状況と残タスク
• 今回のセッションで達成したいゴール

まとめ：AI Agentとの付き合い方の原則

1. AI は「見ていない」——構造を読んでいる
   視覚的な評価は人間が、構造的な分析は AI が担当する

2. AI の完成度を過信しない
   初稿の平均点は高いが、時間耐性・運用耐性は低い

3. 感覚ではなくルールで伝える
   Design Token・仕様・制約を具体的な値で伝える

4. 技術スタックは人間が指定する
   AI の自動判断は古い手法に偏りやすい。使いたい技術を明示することで正確に動く

5. 設計の判断は人間が握る
   AI は「今の最適解」しか考えない。運用・保守・体験の優先順位は人間の仕事

6. Tailwind + セマンティック HTML を基盤にする
   AI との対話ノイズを最小化し、意図を確実に伝えるための基盤