@インポートの活用

CLAUDE.mdが長くなりすぎた場合、@path/to/file 構文を使って外部ファイルを参照できます。これにより、CLAUDE.mdをスリムに保ちつつ、必要な情報を網羅できます。

基本構文

CLAUDE.md内で以下のように記述すると、指定ファイルの内容が参照されます。

# MyProject

## 概要
React + TypeScript のWebアプリケーション。

## 技術スタック
@docs/tech-stack.md

## コーディング規約
@docs/coding-conventions.md

## API仕様
@docs/api-spec.md

相対パス・絶対パスの使い分け

<!-- 相対パス（推奨） -->
@docs/architecture.md
@.claude/rules/security.md

<!-- プロジェクトルートからの相対パス -->
@src/README.md

相対パスはCLAUDE.mdが配置されているディレクトリからの相対になります。チームで共有する場合は相対パスが安全です。

ネストの最大深度

@ インポートは最大5段階までネストできます。

CLAUDE.md
  → @docs/overview.md        (1段目)
    → @docs/details/arch.md  (2段目)
      → @docs/details/...    (3段目)
        → ...                (4段目)
          → ...              (5段目・上限)

深くネストしすぎると追跡が困難になるため、実用上は2〜3段階に収めることを推奨します。

大きなCLAUDE.mdの分割テクニック

Before（1ファイルに全部入り）:

CLAUDE.md (300行)

After（分割後）:

CLAUDE.md (50行)
  @docs/architecture.md      (60行)
  @docs/coding-conventions.md (40行)
.claude/rules/
  security.md                (30行)
  testing.md                 (30行)
  api-design.md              (25行)

分割のポイントは、CLAUDE.mdには「何があるか」のインデックスを残し、詳細は別ファイルに移すことです。Claudeは必要な時に参照先を読みに行くため、常にすべてがコンテキストに載るわけではありません。これがコンテキストウィンドウの節約につながります。