create-next-appがCLAUDE.mdなどとコンフリクトする問題と回避策

概要

create-next-app を既存ディレクトリで実行すると、README.md や CLAUDE.md などの既存ファイルと衝突してエラーになることがあります。

特に最近、AIアシスタント(Claude Code等)を使った設計先行型の開発スタイルが広がり、CLAUDE.md などの設定ファイルが先に存在しているケースが増えました。この記事では、この問題の仕組みと回避策を紹介します。

なぜこの問題が起きるのか

AI支援開発の時代背景

Claude CodeやCursorといったツールが普及した結果、開発の進め方が変わってきました。

従来は「create-next-app でプロジェクトを作って、その後にREADMEを書く」流れでしたが、AI支援開発の現在は「まずAIアシスタントと相談して設計ドキュメントを書く → その後で実装環境を構築する」という流れが当たり前になりつつあります。

つまり、create-next-app を実行する時点で、すでに CLAUDE.md や README.md が存在していることが普通になったわけです。

実際にコンフリクトしたケース

私自身、こんな構成で開発を始めようとしてエラーに遭遇しました。

study-platform/
├── CLAUDE.md       ← Claude Code用のプロジェクト指示書
├── README.md       ← プロジェクト概要(先に書いていた)
└── docs/
    └── *.md

この状態で npx create-next-app@latest . を実行すると:

The directory study-platform contains files that could conflict:

  CLAUDE.md
  README.md

Either try using a new directory name, or remove the files listed above.

「消せ」と言われても、自分で書いたドキュメントを消したくない。

仕組み: 安全リストとは何か

create-next-app は、プロジェクトのルートに**「安全リストに含まれない非空ファイル・ディレクトリ」**が存在しないかをチェックします。

ソースコード(is-folder-empty.ts)を見ると、以下のようなリストがハードコードされています。

const validFilesOrFolders = [
  '.claude',           // Claude Code 用ディレクトリ
  '.cursor',           // Cursor 用ディレクトリ
  '.DS_Store',
  '.git',
  '.gitattributes',
  '.gitignore',
  '.gitlab-ci.yml',
  '.hg',
  '.hgcheck',
  '.hgignore',
  '.idea',             // JetBrains 系IDE
  '.npmignore',
  '.travis.yml',
  '.vscode',           // VS Code
  '.zed',              // Zed エディタ
  'LICENSE',
  'Thumbs.db',
  'docs',              // ★ ここがポイント
  'mkdocs.yml',
  'npm-debug.log',
  'yarn-debug.log',
  'yarn-error.log',
  'yarnrc.yml',
  '.yarn',
]

const conflicts = readdirSync(root).filter(
  (fileOrFolder) =>
    !validFilesOrFolders.includes(fileOrFolder) &&
    !/\.iml$/.test(fileOrFolder)
)

ソース: https://github.com/vercel/next.js/blob/canary/packages/create-next-app/helpers/is-folder-empty.ts

このリストから読み取れる重要なポイント:

• .claude、.cursor、.vscode、.zed など、AI支援開発ツールやエディタ用ディレクトリは含まれている
• docs も含まれている
• 一方で、README.md や CLAUDE.md などのファイルは含まれていない

つまり、ファイルがコンフリクト対象になるかは「安全リストに完全一致するか」で決まります。.bak 拡張子に変えたり、隠しファイルにしたりしても、安全リストに完全一致するキーにはならないので回避できません。

回避策: docs/ サブディレクトリに退避する

docs/ は安全リストに含まれており、しかも create-next-app のチェックは readdirSync(root) でルート直下しか見ないため、docs/ の中身までは再帰的にチェックされません。

これを利用すれば、容易にこの問題を回避できます。

# Step 1: 退避(リネーム不要、元のファイル名のまま)
mv CLAUDE.md docs/CLAUDE.md.bak
mv README.md docs/README.md.bak

# Step 2: 中身確認(docs/ と .DS_Store だけ見えればOK)
ls -la

# Step 3: create-next-app 実行
npx create-next-app@latest .

# Step 4: 復旧
mv docs/CLAUDE.md.bak CLAUDE.md
rm README.md  # create-next-app が生成したテンプレREADMEを破棄
mv docs/README.md.bak README.md

戻し忘れチェック

ls docs/*.bak 2>/dev/null
# 何も表示されなければOK

予防策: そもそもこの問題を起こさないために

新規プロジェクトを設計から始める時は、最初からこの構造にしておくと、退避作業が最小限で済みます。

my-project/
├── CLAUDE.md          ← ルート配置(Claude Codeの慣習)、退避が必要
├── README.md          ← create-next-appが生成するため衝突、退避が必要
└── docs/              ← 安全リスト入り、中身も含めて影響なし
    ├── implementation_plan.md
    ├── design_decisions.md
    └── ...

ルートに置く必要があるのは CLAUDE.md と README.md くらいなので、それ以外は最初から docs/ 配下にまとめておく運用がおすすめです。

まとめ

• AI支援開発の普及で、CLAUDE.md などが先に存在する状態で create-next-app を実行する機会が増えた
• create-next-app は「安全リストに含まれない非空ファイル・ディレクトリ」が存在するとエラーになる
• 安全リストには .claude や docs などのディレクトリが含まれている一方、README.md や CLAUDE.md などのファイルは含まれていない
• docs/ の中身は再帰チェックされないので、ここに退避すれば容易に回避できる
• 設計ドキュメントは最初から docs/ 配下にまとめる運用にしておくと、退避対象が減って楽

動作確認環境

• macOS Sequoia 15.x
• Node.js v22.22.2(Volta経由)
• create-next-app: 2026年5月時点の最新版

参考リンク

• Next.js公式ドキュメント - Installation
• is-folder-empty.ts(安全リストの定義)