はじめに
Tailwind CSS v4が2025年1月22日に正式リリースされて以降、Claude Codeに書かせたCSSやPostCSS設定がビルドエラーになるという報告が増えている。原因はシンプルだ。Claude Codeの学習データにv4が十分に含まれていないためv3の記法が生成される。毎回プロンプトで「v4で書いて」と指示しても根本解決にならない。CLAUDE.mdに禁止パターンとv4の正しい記法を書けば、最初から正しいコードが生成されるようになる。
Claude CodeがTailwind v4で出力するv3コードを正す
`@tailwind`ディレクティブの誤使用
v4では@tailwindディレクティブは廃止。Claude Codeはデフォルトで3行を書きやすい。
/* ❌ v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;
/* ✅ v4: 1行のみ */
@import "tailwindcss";
@import "tailwindcss"の1行がbase・components・utilitiesをすべて含む。postcss-importとautoprefixerもv4に内蔵されたため設定不要だ。
`tailwind.config.js`の`theme.extend`によるカスタマイズ
v4ではtailwind.config.jsは自動検出されない。テーマカスタマイズはCSSファイルの@themeブロックに移行した。
// ❌ v3: tailwind.config.js
module.exports = {
content: ['./src/**/*.{js,ts,tsx}'],
theme: { extend: { colors: { brand: '#3b82f6' } } },
darkMode: 'class',
}
/* ✅ v4: globals.css */
@import "tailwindcss";
@theme {
--color-brand: #3b82f6;
}
@custom-variant dark (&:where(.dark, .dark *));
content配列はv4で廃止。ソースは自動検出される。darkMode: 'class'は@custom-variant darkに変更。
PostCSS設定の誤記述
// ❌ v3
export default {
plugins: { 'postcss-import': {}, tailwindcss: {}, autoprefixer: {} },
}
// ✅ v4 PostCSS使用時
export default { plugins: { '@tailwindcss/postcss': {} } }
ViteプロジェクトではPostCSS設定を用意せず@tailwindcss/viteプラグインを使う。
// ✅ v4 Vite使用時（推奨）
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({ plugins: [tailwindcss()] })
廃止されたユーティリティクラス
| v3（使用禁止） | v4 |
|---|---|
| bg-opacity-50 | bg-black/50（スラッシュ記法） |
| bg-gradient-to-r | bg-linear-to-r |
| flex-grow / flex-shrink | grow / shrink |
| !flex（important修飾子） | flex! |
| shadow-sm / shadow | shadow-xs / shadow-sm |
CLAUDE.mdでv4ルールを強制する
.claude/rules/tailwind-v4.mdとして配置する。pathsでCSSと設定ファイルに限定するとトークンを節約できる。
---
paths:
- "**/*.css"
- "postcss.config.*"
- "vite.config.*"
- "tailwind.config.*"
---
# Tailwind CSS v4 ルール
## インポート
- ✅ `@import "tailwindcss";`（1行のみ）
- ❌ `@tailwind base;` `@tailwind components;` `@tailwind utilities;` 禁止
## テーマ
- ✅ CSSファイルの`@theme`ブロックでCSS変数を定義
- ❌ `tailwind.config.js`のtheme.extend禁止・新規作成禁止
## PostCSS / Vite
- Vite: `@tailwindcss/vite`を使う
- PostCSS: `@tailwindcss/postcss`（`tailwindcss`ではない）
- `postcss-import`と`autoprefixer`は不要（内蔵済み）
## ダークモード
- ❌ `darkMode: 'class'`禁止
- ✅ `@custom-variant dark (&:where(.dark, .dark *));`をCSSに追加
## 廃止（使用禁止）
- `bg-opacity-*` → `bg-{color}/{opacity}` 例: `bg-black/50`
- `bg-gradient-to-r` → `bg-linear-to-r`
- `flex-grow` / `flex-shrink` → `grow` / `shrink`
- `!{class}`（important） → `{class}!`
- `shadow-sm` → `shadow-xs` / `shadow` → `shadow-sm`
PostToolUseフックでv3記法を自動検出する
CSSファイル編集後に@tailwindディレクティブを検出するフックを.claude/settings.jsonに追加する。
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "bash -c 'f=\"$TOOL_RESULT_FILE_PATH\"; [[ \"$f\" == *.css ]] && grep -q \"@tailwind base\\|@tailwind utilities\" \"$f\" && echo \"⚠️ v3記法を検出。@import \\\"tailwindcss\\\"; に修正してください\" && exit 1; exit 0'"
}]
}]
}
}
v3記法が混入するたびにClaude Codeがその場で修正する。
EM視点──移行をチームの設定として管理する
公式のnpx @tailwindcss/upgradeが依存関係の更新・tailwind.config.jsのCSS変換・廃止クラスの一括置換を自動化する。ただしAIが将来v3コードを生成するリスクは消えないため、移行PRに必ず.claude/rules/tailwind-v4.mdの追加を含める運用を徹底する。
個々の開発者が毎回「v4で書いて」と指示するのは持続しない。ルールファイルをリポジトリにコミットしておけば、新メンバーのオンボーディング時からAIが正しいコードを生成する。フレームワークのメジャーバージョンが上がるたびにCLAUDE.mdを更新する。その習慣を今から作っておくと、AIが古いコードを生成し続ける問題を防ぎ続けられる。
まとめ
Claude CodeがTailwind v4で踏む地雷は@tailwindディレクティブ・tailwind.config.jsのtheme.extend・PostCSS設定だ。.claude/rules/tailwind-v4.mdを今すぐ作成してリポジトリにコミットしてほしい。PostToolUseフックを併用すれば、v3記法が混入した瞬間にClaude Codeが自己修正する。
コメント