Claude Codeが苦手な作業パターン5選と実践的な回避策

概要

Claude Codeは多くの開発タスクで高い生産性を発揮しますが、繰り返し失敗するパターンが存在します。2025年10月〜12月にECサイトプロジェクト（Astro ECサイト構築）で経験した実例をもとに、苦手な作業パターン5つと実践的な回避策を記録します。

AIの限界を把握した上で使い分けることで、「修正されていません」を6回繰り返すような非効率を避けられます。

パターン1：CSS微調整の反復失敗

何が起きたか

検索ボックスのレイアウト調整で、以下のやり取りが6回連続しました。

1
私: 「虫眼鏡アイコンの位置がずれています。修正してください」
2
AI: （修正を適用）
3
私: 「修正されていません」
4
AI: （別の修正を適用）
5
私: 「まだ修正されていません」
6
... これが6回繰り返された

具体的には、検索ボックス内の虫眼鏡アイコンの位置、入力テキストとアイコンの重なり、左右の余白調整で何度も失敗しました。

なぜ苦手なのか

CSSの微調整は「数ピクセル単位の差」が問題になります。AIはDOMの構造とCSSプロパティの関係を理解していますが、レンダリング後の視覚的な結果を正確に予測できません。特に以下の条件が重なると失敗率が上がります。

position: absoluteとrelativeの組み合わせ
flexbox内でのmarginとpaddingの相互作用
レスポンシブデザインでのブレークポイント間の挙動

回避策

1
/* NG: 「位置を調整してください」 */
2
/* AIは何をどの方向にどれだけ動かすか判断できない */
3

4
/* OK: 具体的なCSS値を指定する */
5
.search-icon {
6
    position: absolute;
7
    left: 12px;    /* ← 具体的な値を人間が指定 */
8
    top: 50%;
9
    transform: translateY(-50%);
10
}

効果的なやり方: ブラウザのDevToolsで目標の値を確認し、「left: 12pxをleft: 8pxに変更してください」と具体的に指示する。

パターン2：クライアントサイドライブラリのインポートエラー

何が起きたか

Chart.jsを使ったレーダーチャートの実装で、Failed to resolve import "chart.js"エラーが複数回発生しました。

1
Error: Failed to resolve import "chart.js" from "src/components/RadarChart.astro"

SSG（静的サイト生成）環境でクライアントサイドのみで動作するライブラリを使う場合、ビルド時とランタイムの実行環境の違いをAIが正しく扱えないことがあります。

なぜ苦手なのか

Astro/Next.jsのようなSSGフレームワークでは、コードの一部がビルド時（Node.js環境）に実行され、一部がブラウザで実行されます。Claude Codeはこの境界の判断を間違えることがあります。

回避策

1
---
2
// ビルド時に実行されるサーバーサイドコード
3
// ここにクライアントサイドのライブラリをimportしない
4
---
5

6
<!-- クライアントサイドのライブラリはscriptタグ内で動的importする -->
7
<canvas id="radar-chart"></canvas>
8

9
<script>
10
  // ブラウザでのみ実行される
11
  import('chart.js').then(({ Chart, registerables }) => {
12
    Chart.register(...registerables);
13
    // チャートの描画ロジック
14
  });
15
</script>

効果的なやり方: 「このライブラリはクライアントサイドでのみ実行されます。SSGビルド時にはimportされないようにしてください」と明示する。

パターン3：MDXのセクション分割ロジック

何が起きたか

MDXファイルで「h2見出しから次の---区切りまでを<section>で括る」という要件を実装する際、指示とは異なるコードが出力されました。

最初の指示:

1
MDXのコンテンツを、h2見出しごとにsection-containerで括ってください。
2
h2から次のh2（または---）までを1つのsectionとします。

AIが出力したのは、正規表現で文字列を分割するアプローチでした。しかし、MDX内にコードブロック（```）が含まれる場合、コードブロック内の---や##を誤検出します。

最終的な解決策

MDX側でコンポーネントを明示的に使うアプローチに変更しました。

1
<SectionContainer>
2
## セクションタイトル
3

4
セクションの内容...
5
</SectionContainer>
6

7
<SectionContainer>
8
## 次のセクション
9

10
次のセクションの内容...
11
</SectionContainer>

学び: 構文解析が必要な変換処理をAIに任せると、エッジケースで失敗しやすい。人間がアーキテクチャレベルの判断（「文字列分割ではなくコンポーネント化する」）をして、AIには実装を任せるのが良い。

パターン4：視覚的レイアウト判断

何が起きたか

スクリーンショットを送って「この部分の余白が大きすぎるので詰めてください」と指示しても、正確に修正できませんでした。

AIはスクリーンショットを解析できますが、以下の判断が苦手です。

「余白が大きすぎる」の「大きすぎる」がどの程度か
複数要素間のバランス（ヘッダー、コンテンツ、フッターの比率）
デザインシステムとしての一貫性

回避策

1
NG: 「この画面の余白を調整してください」（スクリーンショット添付）
2

3
OK: 「.hero-section の padding-top を 120px から 60px に変更してください。
4
     .card-grid の gap を 32px から 24px に変更してください。」

効果的なやり方:

DevToolsで現在の値を確認する
変更したいプロパティと目標の値を具体的に指示する
「見た目が良くなるように」ではなく「padding: 60pxにして」と伝える

パターン5：既存コードとの整合性チェック不足

何が起きたか

パンくずリストのコンポーネントを新しく追加した際、既存のレイアウトファイルにもパンくず表示のコードがあり、パンくずが二重に表示されるバグが発生しました。

1
ヘッダー
2
パンくず（既存のレイアウトファイル由来）  ← 重複
3
パンくず（新しいコンポーネント由来）      ← 重複
4
コンテンツ

なぜ起きるのか

Claude Codeは指示された作業に集中するため、「この機能は既に別の場所で実装されていないか」を自発的に確認しないことがあります。特に以下の場合に発生しやすいです。

レイアウトファイルが複数層にネストしている
同じ機能が異なるアプローチで実装されている
プロジェクト全体を把握しきれないほどファイルが多い

回避策

新しいコンポーネントを追加する前に、以下の確認を指示します。

1
パンくずリストのコンポーネントを作成する前に、以下を確認してください。
2
1. 既存のレイアウトファイルにパンくず表示のコードがないか
3
2. 同様の機能を持つコンポーネントが既に存在しないか
4
3. グローバル検索で "breadcrumb" を含むファイルを列挙してください

効果的なやり方: 「実装する前に、既存コードで同じ機能がないか確認してください」を定型的な指示として含める。CLAUDE.mdに書いておくとさらに効果的です。

まとめ：苦手パターンの共通点

5つのパターンに共通するのは、AIが「目で見て判断する」必要がある作業が苦手ということです。

パターン	根本原因
CSS微調整	レンダリング結果を予測できない
インポートエラー	実行環境の境界判断が曖昧
セクション分割	エッジケースの構文解析
視覚的レイアウト	「見た目の良さ」の判断基準がない
整合性チェック不足	プロジェクト全体の暗黙知を持たない

回避策の共通パターンは以下の3つです。

具体的な値を人間が指定する（「調整して」ではなく「60pxにして」）
アーキテクチャの判断は人間が行う（「文字列分割」ではなく「コンポーネント化」）
確認作業を明示的に指示する（「実装前に既存コードを検索して」）

Claude Codeの生産性を最大化するには、AIが得意な作業（定型的なコード生成、テスト作成、リファクタリング）に集中させて、苦手な作業は人間が判断してからAIに渡すのが効果的です。