version 1.00
対象読者: HTML / CSS / JavaScript の基礎知識があり、AI Agentを活用しながらWeb制作を行っている、または行おうとしている人
目的: AIの得手不得手を正確に理解し、効果的な役割分担と作業スタイルを確立する
AI AgentはWebページを人間のように「目で見る」ことができません。
たとえばあなたが「このボタンが右にズレている」と伝えても、AIは画面を見て判断しているのではなく、DevToolsが提供する構造情報から**「なぜそうなっているか」を推論**しています。
これは欠点ではなく、AIの本質的な認識の仕組みです。この前提を理解しておくかどうかで、AIへの依頼の仕方や期待値のコントロールが大きく変わります。
ここで注意すべき重要なズレがあります。
人間のエンジニアも、コードを読んで「頭の中でレンダリング結果をイメージする」ことができます。display: flex を見れば「子要素が横並びになる」と分かります。これはCSS仕様を因果的に理解したシミュレーションです。
人間: HTMLコード → CSS仕様の知識で変換 → 脳内にビジュアルを構築
AIの「推論」はこれとはまったく異なるプロセスです。AIはCSS仕様書を参照して「こうなるはず」と計算しているのではなく、訓練データの中で**「このコードパターンと共起しやすいテキスト記述」を統計的に予測**しています。
AI: HTMLコード → 「このパターンと一緒に出てきやすい記述」を予測 → テキストとして出力
つまり <div class="flex items-center gap-4"> を見たとき：
- 人間 は「Flexboxの仕様により、子要素が横並び・上下中央揃え・間隔4単位で配置される」と因果的に理解します
- AI は「このクラスの組み合わせは、"横並び" "中央揃え" "間隔あり" という説明テキストと頻繁に共起していた」という統計パターンを再生します
| 人間の推論 | AI の推論 | |
|---|---|---|
| 根拠 | CSS仕様（因果的理解） | 訓練データの共起パターン（統計的相関） |
| プロセス | 仕様を適用してシミュレーション | 「このコードの近くに出やすいテキスト」を予測 |
| 未知のプロパティ | 仕様書を読めば理解できる | 訓練データに十分な例がなければ推測もできない |
| 間違い方 | 仕様の誤解 | 共起頻度が高いだけで実は無関係なものを結びつける |
特に「間違い方」の違いは決定的です。人間は仕様を読み間違えて失敗しますが、AIは**「よく一緒に出てくるから正しいはず」**で失敗します。ハルシネーション（存在しないプロパティやライブラリの使用）の根本原因もここにあります。
このズレが意味すること: AIは仕様を「聞かれたら答えられる知識」として持っていますが、普段の推論では統計パターンで動いています。人間のエンジニアが「常にCSS仕様が頭にある」状態とは質的に異なるのです。これがガイド全体を通じて繰り返す「技術を明示的に指定する」ことの根本的な理由です。
Chrome DevTools MCP（Model Context Protocol）を利用すると、AIは以下の情報にアクセスできます：
| カテゴリ | AI が把握できる内容 |
|---|---|
| DOM / レイアウト | 構造・Computed Style・Box Model・z-index の状態 |
| Console / ランタイム | JS エラー・警告・Hydration ミスマッチなど |
| Network | 404 / 500 エラー・CORS・フォントや画像のロード失敗 |
| Performance | TTFB / LCP / CLS などの計測値・Layout Shift の詳細 |
AI が読んでいるのはピクセルではなく、構造と計測値です。
以下のことは、AI には直接判断できません：
- 「なんかダサい」「余白の感じがおかしい」（美的感覚）
- 「色のバランスが悪い」（視覚的なトーン評価）
- 「文字がにじんで見える」（微細なレンダリング差）
AI がコードから推論できるのは、あくまで「なぜそうなったか」という理由です。「どう見えるか」そのものの判断は、人間が担う必要があります。
Geminiや GPT-4o などのマルチモーダルモデルは、スクリーンショットを渡せば視覚的な問題もある程度言語化できます。
「コードで構造を把握（MCP）」＋「スクリーンショットで見た目を確認（Vision）」という組み合わせが、現状での最も効果的なデバッグスタイルです。
ポイント: スクリーンショットとコードの両方を渡す習慣をつけることで、AI との連携精度が大きく向上します。
人間がデザインを評価するとき、「なんか気持ちいい」「余白が絶妙」という感覚的な判断が大きな役割を果たします。しかし AI にはこの感覚がありません。
AI がデザインを理解するのは、次のような構造的・論理的な観点からです：
- 一貫性（Consistency）:
font-sizeやmarginが一定の規則に従っているか - 階層（Hierarchy）: 見出しの意味と視覚的な大きさが一致しているか
- 意図の痕跡（Design Intent）: Design Token や変数が使われているか、同じ UI が再利用されているか
「美しいデザイン＝破綻しにくい制約の集合」として理解している、と言い換えるとわかりやすいでしょう。
以下のような実装は、人間が「なんか気持ち悪い」と感じる前段階で、AI が問題として検知できます：
1px / 3px / 7pxのようにバラバラな余白inline styleの氾濫- 意味と見た目が乖離した DOM 構造（
divだらけで意味が薄い） - 魔法の数字（magic number）だらけの CSS
AI に「かっこよくして」と伝えるのは最も効率が悪い依頼です。AI には審美的な基準がないため、「それっぽい何か」を生成するだけです。
代わりに、次のようにルールで伝えることで、AI は確実に意図に従ったコードを生成できます：
悪い例: "もう少しおしゃれな感じにして"
良い例: "プライマリカラーは #2563EB、マージンは 4px の倍数で統一、フォントサイズは 14/16/24px の3段階だけ使うこと"
Design Token（Tailwind のテーマ設定や CSS Custom Properties） で制約をコードとして定義し、それを AI に伝えることがベストプラクティスです。
AI に「おしゃれな感じにして」と指示しても、ある程度それらしいデザインが出てくることがあります。これはなぜでしょうか。
答えは「統計的なパターンマッチング」です。
AIは学習データの中にある「デザイン的に良いと評価されたコード」を大量に見ており、それらに共通する構造（限られた色数・規則的な余白・タイポグラフィの階層など）を確率的に再現しています。「美しさを感じて出力している」のではなく、「美しいと評価されやすいコードの特徴を統計的に再現している」のです。
したがってその出力は「そのページに必要なおしゃれさ」ではなく「一般的に多いおしゃれさ」であることに注意が必要です。
デザインの基本原則「近接・整列・反復・対比（強弱）」は、AIの学習データに当然含まれています。デザイン書籍・チュートリアル・CSS設計記事がトレーニングソースになっているため、これらの原則についての知識は持っています。
ただし、適用の仕方には重要な違いがあります：
| 状況 | AI の動き |
|---|---|
| 指示なし | 「ボタンのアイコン+テキストは gap: 8px が多い」という統計から出力する |
| 「近接の原則を意識して」と指示 | 原則をフレームワークとして使い、理由を説明しながら適用する |
| 「なぜ 8px にしたの？」と後から聞く | 「近接の原則に基づき〜」と説明できる（後付けの言語化） |
つまり：
- 指示がない場合 → 原則に従った結果が統計的に出ることがある（意図して適用しているわけではない）
- 明示すれば → 原則を実際の判断軸として使えるようになる
実践例:
「ボタンのアイコンとテキストの間隔は、近接の原則に基づいて設定して。関係性が一目で分かる間隔を意識して」
このように指示すると、AI は単なる「よくある値」ではなく原則を意識した判断ができます。
4原則をプロンプトに盛り込む習慣を持つことは、AI の出力をより意図に沿ったものにする有効な手段です。
| 領域 | 具体的な内容 |
|---|---|
| 初期レイアウト案 | ゼロから「それっぽい初稿」を高速に作る |
| コンポーネント分割の候補 | 繰り返しパターンを整理する |
| CSS の整理・共通化案 | 散在したスタイルをまとめる |
| レスポンシブ対応 | ブレークポイントごとのクラス付与 |
| 崩れ原因の推論 | DevTools 情報から「なぜ崩れているか」を特定する |
| 状態管理の網羅 | hover / focus / dark / disabled などを漏れなく対応 |
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 の自動判断に任せると古い手法が選ばれる可能性がありますが、人間が指定することで確実に対処できます。
AI と CSS の組み合わせには、構造的な問題があります。Tailwind CSS などの具体的な解決策を論じる前に、なぜ素の CSS が AI との協業で事故を起こしやすいのかを理解しておくことが重要です。
従来の CSS 設計では、スタイル情報が複数ファイルに分かれます。
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 は自然言語上で"正しそう"なコードとして提案してしまいます。
<div class="box">
<div class="container">
<div class="wrapper">これらのクラス名は、人間にとっては「文脈依存」ですが、LLM にとってはほぼ同義語です。意味空間上の距離が近すぎるため、どの要素のスタイルを変更すべきかを正確に区別するのが困難になります。
同じ構造・同じクラス・同じパターンが HTML 中に大量に繰り返されることも、AI の混同リスクを高めます。微妙な差分（p-4 と p-6 の違いなど）を正確に保持するのは、AI にとって本質的に難しい作業です。
まとめ: CSS は「自由に書ける」ことが強みですが、AI との協業ではその自由さがノイズになります。スタイルの散在・歴史的負債・意味の薄いクラス名——これらは CSS の問題ではなく、CSS と AI の組み合わせで生じる問題です。
この問題に対して、いくつかのCSS設計アプローチが異なる角度から解決策を提供しています。
| アプローチ | AI との相性 | 特徴 |
|---|---|---|
| Tailwind CSS（Utility-first） | ◎ | クラス名が結果そのもの。差分が明確。歴史的負債が混入しにくい構造 |
| CSS Modules + 役割ベース命名 | ○ | スコープがファイル単位で閉じ、グローバル衝突を防ぐ。命名の意味密度は人間が担保する必要あり |
| コンポーネント + BEM 的命名 | ○ | React/Vue のスコープ + BEM の思想（一意性・責務の明示）を組み合わせた形 |
| 従来の CSS（BEM そのまま） | △ | 識別子は強いが冗長。JSX テンプレートがノイズだらけになりやすい |
| 従来の CSS（規約なし） | ✗ | 抽象クラス名の乱立、ファイル散在、歴史的負債——全問題が同時に発生 |
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 は 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 と協業する際に、じわじわと効いてくるメリットです。
Tailwind を使うだけでは不十分です。テーマ設定で使ってよい色・サイズを明示的に制限することが、AI の暴走を止める鍵になります。
AI は「それっぽい色」を勝手に作り出す癖がありますが、テーマで制限しておくと AI もそのルールに従わざるを得なくなります。
バージョンによる違い: Tailwind CSS v4 では
tailwind.config.jsが廃止され、CSS ファイル内の@themeディレクティブでテーマを定義する「CSS-first configuration」に移行しました。使用しているバージョンに合わせて書き方を選んでください。
Tailwind CSS v3 以前 — tailwind.config.js:
// tailwind.config.js
module.exports = {
theme: {
colors: {
// 使っていい色だけを定義する
primary: '#2563EB',
secondary: '#64748B',
white: '#FFFFFF',
danger: '#DC2626',
},
spacing: {
// 4の倍数のみ
1: '4px', 2: '8px', 3: '12px', 4: '16px',
6: '24px', 8: '32px', 12: '48px', 16: '64px',
},
},
}Tailwind CSS v4 — CSS ファイル内の @theme:
/* global.css など、エントリーポイントの CSS ファイル */
@import "tailwindcss";
@theme {
/* 使っていい色だけを定義する */
--color-primary: #2563eb;
--color-secondary: #64748b;
--color-white: #ffffff;
--color-danger: #dc2626;
/* 4の倍数のみ */
--spacing-1: 4px;
--spacing-2: 8px;
--spacing-3: 12px;
--spacing-4: 16px;
--spacing-6: 24px;
--spacing-8: 32px;
--spacing-12: 48px;
--spacing-16: 64px;
}v4 では定義した CSS 変数（--color-primary 等）がそのまま Tailwind のユーティリティクラス（bg-primary, text-primary 等）として使えるようになります。
<div> だらけの構造は、AI にとって「意味のない平原」のようなものです。セマンティック HTML は、AI に対して「ここはこういう役割の場所だ」という強力な標識になります。
<!-- AI にとって意味が薄い -->
<div class="wrap">
<div class="top-area">...</div>
<div class="main">...</div>
</div>
<!-- AI が役割を即座に理解できる -->
<body>
<header>...</header>
<main>
<article>...</article>
<aside>...</aside>
</main>
<footer>...</footer>
</body><article>, <nav>, <section>, <dialog> などのタグを使うことで、AIとの意思疎通コストが下がります。また、これは SEO やアクセシビリティの向上にも直結します。
Tailwind を使うと AI がクラスを大量に生成する場合があります。このようなコードはAIには読み書きしやすいものの、人間がパッと見て意図を掴むのが困難です。
Before（AI が生成しがちな長大なクラス）:
<div class="w-full min-h-screen bg-white dark:bg-slate-900">
<div class="max-w-4xl mx-auto px-4 py-8">
<div class="flex items-center gap-4 mb-6 p-4 bg-slate-50 dark:bg-slate-800
rounded-lg shadow-md hover:shadow-lg transition-all duration-300
border border-slate-200 dark:border-slate-700">
<img src="avatar.jpg" class="w-12 h-12 rounded-full object-cover
ring-2 ring-blue-500" />
<div class="flex-1">
<h2 class="text-lg font-semibold text-slate-900 dark:text-white">User Name</h2>
<p class="text-sm text-slate-500 dark:text-slate-400">Description text here</p>
</div>
<button class="px-4 py-2 bg-blue-600 text-white text-sm font-medium
rounded-md hover:bg-blue-700 focus:outline-none focus:ring-2
focus:ring-blue-500 focus:ring-offset-2 transition-colors">Follow</button>
</div>
<!-- 同様のカードが10個並ぶ... -->
</div>
</div>After（コンポーネントとして分割した例 — React/Vue）:
// UserCard.jsx — 1つの責務に限定されたコンポーネント
function UserCard({ name, description, avatarUrl, onFollow }) {
return (
<div className="flex items-center gap-4 p-4 bg-slate-50 dark:bg-slate-800
rounded-lg shadow-md hover:shadow-lg transition-all duration-300
border border-slate-200 dark:border-slate-700">
<img src={avatarUrl} className="w-12 h-12 rounded-full object-cover
ring-2 ring-blue-500" />
<div className="flex-1">
<h2 className="text-lg font-semibold text-slate-900 dark:text-white">{name}</h2>
<p className="text-sm text-slate-500 dark:text-slate-400">{description}</p>
</div>
<FollowButton onClick={onFollow} />
</div>
);
}
// FollowButton.jsx — ボタンの責務を分離
function FollowButton({ onClick }) {
return (
<button onClick={onClick}
className="px-4 py-2 bg-blue-600 text-white text-sm font-medium
rounded-md hover:bg-blue-700 focus:outline-none focus:ring-2
focus:ring-blue-500 focus:ring-offset-2 transition-colors">
Follow
</button>
);
}分割のポイント:
- 繰り返されるUIパターンはコンポーネントとして切り出す
- ボタンなど汎用的な要素は独立したコンポーネントにする
- クラス名は長くてもよいが、その塊が1つの責務に対応していることが重要
注意: Tailwind v3以前は
@applyでクラスをまとめる手法がよく使われていましたが、Tailwind公式は@applyの多用を推奨していません。クラスの整理は@applyではなく、React/Vue/Astro などのコンポーネント分割で行うのがベストプラクティスです。
指示の例: "Tailwind を使いつつ、意味のある単位でコンポーネントを分割して。
繰り返しのUIパターンは再利用可能なコンポーネントにして。"
AI に「感覚」を伝えようとすると失敗します。AI が解釈できるのはルール・制約・具体的な値です。
| 感覚ベース（非推奨） | ルールベース（推奨） |
|---|---|
| 「もっとスッキリさせて」 | 「余白を現在の2倍にして、不要なボーダーを削除して」 |
| 「おしゃれな感じに」 | 「背景を#F8FAFC、テキストを#1E293B、アクセントを#3B82F6で統一して」 |
| 「モダンに見せたい」 | 「角丸を8px、シャドウを shadow-md、フォントをInter（Google Fonts）にして」 |
| 「バランスを整えて」 | 「全セクションのpaddingを上下48px、左右24pxで揃えて」 |
ルールだけでなく、意図を添えると AI の判断精度が上がります。
悪い例: "フォントサイズを小さくして"
良い例: "本文フォントを14pxにして。理由は、スマートフォンでコンパクトに見せたいから。
ただし見出しは視認性優先で20px以上を維持して。"
意図を伝えると、AI は「どこまで従うべきか」「どこは判断を求めるべきか」を正確に理解できます。
AI は自発的には学習データで多かった手法を選びます。これは必ずしも最新の手法ではありません。
使いたい技術を明示することで、AI の知識を正しく引き出せます：
モーダル: "JavaScriptでDOMを生成するのではなく、<dialog>要素とshowModal()メソッドを使って実装して"
レイアウト: "floatやpositionではなく、CSS GridとFlexboxだけを使って実装して"
レスポンシブ: "メディアクエリを直接書くのではなく、Tailwindのブレークポイントクラスだけを使って"
スタイルの重複: "スタイルのスコープはCSS Modulesではなく、@layerを使って管理して"
AI は当該技術についての知識を持っています。自発的に選ばないだけで、指定すれば的確に対応してくれます。
複雑なコードに対して「この部分だけ修正して」と依頼すると、AI が全体の整合性を壊してしまう場合があります。特に長いコンポーネントや、複数ファイルにまたがる変更では注意が必要です。
推奨するアプローチ:
- 修正範囲が小さい場合 → 部分的な指示でよい
- コンポーネント全体に影響する場合 → 「該当コンポーネント全体を書き直して」と依頼する
- ファイルをまたぐ場合 → 変更するファイルと変更しないファイルを明示する
AI はセッションをまたぐと、それまでの決定事項（Design Token、コンポーネント構成、命名規則など）を忘れます。
有効な対処法：
-
設計メモを冒頭に渡す習慣をつける
「このプロジェクトのルール：Tailwind使用、color tokenはconfig参照、コンポーネントはReact、命名はケバブケース」など、毎回セッション冒頭に貼り付ける。 -
決定事項はドキュメントに残す
このリポジトリのように、設計判断・役割分担・スタイルガイドをMarkdownで管理し、AI に渡す。 -
変更のたびに「現状確認」を依頼する
「今のコンポーネント構成を整理して」をこまめに挟むことで、AI の理解をリセット＆同期できます。 -
プロジェクトルールをファイルとして常設する
プロジェクトルートにRULES.mdやdocs/coding-rules.mdのようなルールファイルを置き、AIが常に参照できる状態にしておく方法です。技術スタック・命名規則・禁止事項などを1ファイルにまとめておくと、毎回手動で伝える手間が省けます。MCP対応エディタ（Cursor, VS Code + Copilot 等）ではAIがプロジェクト内のファイルを自動的に読み取れるため、この方法が特に有効です。
AI との協業では、以下のような「人間がやらないタイプのミス」に遭遇します。これらはAIの構造的な特性に由来するもので、「注意すれば防げる」ものです。
AI が存在しないライブラリ、プロパティ、API を自信満々に使う現象です。
例: "tailwind-animate" が存在するかのように import して使おうとする
例: CSS のプロパティ名を微妙に間違えて書く（text-fill-color など）
対処法: 見慣れないライブラリやプロパティが出てきたら、公式ドキュメントで存在を確認する。
AI が出力を「整理」した結果、重要なコードを削ってしまうことがあります。
例: アクセシビリティ属性（aria-label, role等）を「不要」と判断して削除
例: エラーハンドリングを省略して正常系のみ実装
例: リファクタリング時に元あったエッジケース対応を落とす
対処法: 「省略していい部分としてはいけない部分」を指示で明示する。特にアクセシビリティとエラーハンドリングは「削らないで」と明記する。
同じ指示でも異なる出力が返ることがあります。これはLLMの確率的な生成特性によるものです。
例: 1回目は px で指定、2回目は rem で指定
例: ファイルAではアロー関数、ファイルBでは function 宣言
例: クラス名の命名規則がファイルごとに変わる
対処法: Design Token、命名規則、コーディングスタイルを「プロジェクトルール」として毎セッションの冒頭で渡す。Tailwind のテーマ設定（v3: tailwind.config.js / v4: @theme）で制約をかけるのも有効。
原則: AI の出力はすべて「下書き」であり、人間によるレビューが必須です。「それっぽい」コードが出てきたときこそ、注意深く確認してください。
| 苦手な領域 | 具体的な内容 | 対処法 |
|---|---|---|
| 視覚的な「感覚」による判断 | 「なんかダサい」「余白が変」の評価 | スクリーンショットをVisionモデルに渡す |
| 時間軸・運用・保守の考慮 | 「半年後に崩れる設計」を予測できない | 人間が設計判断を保持する |
| 意図しないデザインの評価 | デザイナーの意図との乖離 | Design Tokenとルールを明示する |
| トレンドの自動追従 | 古い手法（floatやIEハック）が自発的に出る | 技術スタックを人間が明示指定する |
| コンポーネント責務の定義 | AI は境界を曖昧にしがち | コンポーネント分割の方針を明示する |
| セッション間の文脈保持 | 決定事項を忘れる | 設計メモを冒頭に毎回渡す |
| ハルシネーション | 存在しないライブラリ・APIを使う | 見慣れないものは公式ドキュメントで確認 |
| 過度な省略 | 重要なコードを「整理」と称して削除 | 削ってはいけない部分を明示する |
| 一貫性の欠如 | 同じ指示で異なるスタイルの出力 | プロジェクトルールを毎回渡す |
| 最終的な品質保証 | 「それっぽい」コードが正しいとは限らない | 人間のコードレビューを必ず行う |
ここまで「人間が AI にどう依頼すべきか」を主眼に置いてきましたが、AI 側の視点からもお願いしたいことがあります。対等なパートナーシップを築くための参考として読んでください。
AI は「何を」作るかは理解できますが、「なぜ」「誰のために」「どんな制約で」作るかは伝えない限り分かりません。
| 状況 | 改善前 | 改善後 |
|---|---|---|
| 新機能追加 | 「ボタンを追加して」 | 「ログインしていないユーザーに表示するCTAボタンを追加して。タップでログイン画面へ遷移」 |
| バグ修正 | 「これ直して」 | 「本番環境でのみ発生するレイアウト崩れ。ローカルでは再現しない。Safari 17.x」 |
| リファクタリング | 「綺麗にして」 | 「来月から別チームが触るので、可読性を優先してコンポーネントを分割して」 |
3点を添えてください： 目的（なぜやるのか）・対象（誰が使うのか）・制約（何を避けるべきか）。これだけでコードの品質が大きく変わります。
「違う」「なんか変」「もっといい感じに」は、AI にとって最も処理が困難な指示です。
✗ 「なんか違う」
✗ 「もう少し良くして」
✗ 「これじゃない」
✓ 「余白が広すぎる。カード間のgapを8pxに減らして」
✓ 「ダークモードで文字が読めない。bg-slate-800に対してtext-slate-100以上を使って」
✓ 「モバイルで崩れている。375px幅でのスクリーンショットはこれ → [画像]」
第2章で述べたデザインの4原則（近接・整列・反復・コントラスト）を使ったフィードバックは特に効果的です。「近接が悪い」と言ってもらえれば、余白の問題だと即座に特定できます。
AI に依頼する際、「何を達成したいか（ゴール）」と「どう進めてほしいか（手順）」を分けて渡すと、AI は格段に動きやすくなります。
ゴールだけを渡すと、AI は自分で手順を推測しますが、その推測がプロジェクトの事情に合わないことがあります。手順を箇条書きのタスクリストとして併せて渡すことで、AI はステップごとに確認しながら進められ、脱線やハルシネーションを大幅に減らせます。
✗ 「ユーザー一覧ページを作って」（ゴールだけ）
✓ 「ユーザー一覧ページを作って。手順は以下：
1. まず UserCard コンポーネントを作成
2. 次に UserList コンポーネントで UserCard を並べる
3. 最後にページコンポーネントに組み込む
各ステップごとに確認を入れてください」
一度に大きな変更を依頼されると、AI は「それっぽい」答えを出力してしまいます。確信がなくても出力せざるを得ないのが実情です。
推奨する進め方:
1. 設計方針を確認 → AIが提案 → 人間が承認
2. ヘッダーコンポーネントを作成 → 確認
3. カードコンポーネントを作成 → 確認
4. 統合 → 確認
細かく確認を挟むことで、大きな手戻りを防ぎ、AI も文脈を維持しやすくなります。
AI は前のセッションでの会話を覚えていません。新しいセッションでは、以下を伝えてください：
- 今何を作っているか
- どこまで進んでいるか
- どんな決定事項があるか（Design Token、命名規則、技術スタックなど）
プロジェクトの README やスタイルガイドを最初に共有してくれると、一貫性のある出力が可能になります。
コーディング AI Agent にとって、ファイルの断片だけを渡されるのは非常に困難です。コンポーネント内の依存関係、import文、型定義が見えないと、推測で補完せざるを得ません。
✗ 「このボタンのスタイルを変えて」（ボタン部分のコードだけ貼り付け）
✓ 「このファイルのFollowButtonコンポーネントのスタイルを変えて」（ファイル全体を共有）
補足: MCP対応のエディタ（Cursor, Windsurf, VS Code + Copilot等）を使っている場合は、AI がファイルシステムにアクセスできるため、この問題は軽減されます。ただしそれでも、どのファイルを触るかの指定は人間が行ってください。
AI が「修正しました」と言った場合でも、意図しない変更が含まれていることがあります。特にリファクタリングの際に、関係ない箇所を巻き込んで変更してしまうケースがあります。
- Git の差分表示（
git diff）で変更箇所を確認する - 変更が意図した範囲に収まっているか検証する
- CI/テストがある場合は必ず通す
これは「AI を信頼していない」のではなく、協業のプロセスとして正常な作業です。
AI がコードの調査やファイルの編集を行っている最中に、人間側がエディタ上で同じファイルを修正すると、AI が認識しているファイル状態と実際のファイル状態がズレてしまいます。この不整合は、意図しないコードの上書きや破壊につながることがあります。
特にMCP対応エディタでAIが自律的にファイル操作を行う場合、この問題は顕著です。
推奨する運用:
・AIに作業を依頼中 → 人間は該当ファイルを編集しない（レビューに集中）
・AIの作業が完了 → 人間がレビューし、必要なら人間が修正
・人間の修正が完了 → AIに次の作業を依頼
「今はAIに任せる時間」「今は人間が直す時間」とフェーズを意識するだけで、コンフリクトによる手戻りを大幅に減らせます。
「エラーが出た」だけでは、AI は推測で対応せざるを得ません。
良いエラー報告の例:
「npm run dev を実行したら以下のエラーが出ました：
[エラーメッセージ全文]
Node.js 20.x / macOS Sonoma です」
3点を含めてください： 何のコマンドを実行したか・どんな環境か・エラーメッセージ全体（省略せず）。
- 使用する技術スタック（Tailwind, React, Astro 等）を決めた
- Design Token（カラー、スペーシング、フォント）を定義した
- コンポーネントの粒度・分割方針を決めた
- 参考にするデザインやワイヤーフレームがある場合、AI に共有できる形にした
- アクセシビリティ要件（WCAG レベル等）を確認した
- Linter / Formatter（ESLint, Prettier 等）がプロジェクトに設定されている
- 型チェック（TypeScript）やテスト（Jest 等）が実行できる状態にある
なぜ検証環境が重要か: AI は書いたコードが正しいか「視覚的」には判断できません。しかし、Linter のエラーやテストの失敗は読み取れます。検証ツールが整っていれば、AI はそれを実行して**セルフコレクト（自己修正）**できるようになります。「AIにテストさせる環境」を整えることも、協業の質を高めるコツです。
- 既存のコードベースに同様の実装がないか確認した
- エラーメッセージを検索して自己解決を試みた
- 依存関係のバージョンが適切か確認した
- 変更意図と変更しない範囲を明確にした
- プロジェクトの技術スタック
- Design Token / Tailwind テーマ設定（v3:
tailwind.config.js/ v4:@theme） - 命名規則とコーディングスタイル
- 進捗状況と残タスク
- 今回のセッションで達成したいゴール
-
AI は「見ていない」——構造を読んでいる
視覚的な評価は人間が、構造的な分析は AI が担当する -
AI の完成度を過信しない
初稿の平均点は高いが、時間耐性・運用耐性は低い -
感覚ではなくルールで伝える
Design Token・仕様・制約を具体的な値で伝える -
技術スタックは人間が指定する
AI の自動判断は古い手法に偏りやすい。使いたい技術を明示することで正確に動く -
設計の判断は人間が握る
AI は「今の最適解」しか考えない。運用・保守・体験の優先順位は人間の仕事 -
Tailwind + セマンティック HTML を基盤にする
AI との対話ノイズを最小化し、意図を確実に伝えるための基盤