💡

CLAUDE.mdに図解指示を追加してAIとの対話をスムーズにする

に公開
AI
Tips
Productivity
Claude
tech

結論

AIアシスタント（Claude CodeやGemini CLIなど）への指示ファイル（CLAUDE.md や GEMINI.md）に、 「説明時にテキストベースの図解（ASCII Art等）を用いること」 という指示を追加しましょう。
これにより、複雑な構造やデータの流れを瞬時に理解でき、開発効率が劇的に向上します。

背景と課題

Claude CodeなどのCLIツールやチャットAIと対話している際、ディレクトリ構造の提案や、システム間のデータの流れについて説明を受けることがよくあります。

しかし、すべてが文章だけで説明されると、以下のような問題が発生します。

▼ 文字だけの説明例（わかりにくい...）

「Monthlyディレクトリの下にはsourcesとai-analysisとreflectionsというフォルダがあります。sourcesにはgithub_2025-08.jsonのような生データが入り、ai-analysisにはそれをもとにした2025-08.mdのような分析結果が入ります。そして最終的な振り返り記事はreflectionsディレクトリの中に同じく年月の日付がついたMarkdownファイルとして保存されます。」

これだと、階層構造やファイルの関係性を脳内で再構築するのにコスト（認知負荷）がかかります。
これを「図解」させることで、一瞬で理解できるようにします。

解決策：指示ファイルへの追加

プロジェクトのルートにある CLAUDE.md（または GEMINI.md や .cursorrules など、使用しているツールの設定ファイル）に、以下の指示を追加します。

CLAUDE.md
## 図解の指示
- ユーザーに何かを説明する際は、簡単な図解を用いてわかりやすく説明すること
- ASCII アートやテキストベースの図を活用して視覚的に理解を助けること

これだけで、AIの回答スタイルが視覚的なものに変わります。

具体的な出力例

例えば、月次の振り返り用ディレクトリ構造を相談した際、以下のような回答が得られるようになります。

1. ディレクトリ構造の提案

文章だけでなく、ツリー形式で直感的に示されます。

  Monthly/
  │
  ├── sources/              # 📥 AIへの入力（生データ）
  │   ├── github_2025-08.json
  │   ├── slack_2025-08.json
  │   └── ...
  │
  ├── ai-analysis/          # 🤖 AIが出力した分析結果
  │   ├── 2025-08.md
  │   ├── 2025-09.md
  │   └── ...
  │
  └── reflections/          # ✍️ 自分で書いた振り返り
      ├── 2025-08.md
      ├── 2025-09.md
      └── ...

2. データの流れ（シーケンス）の解説

処理のプロセスも一目でわかるようになります。

  ┌─────────────────────────────────────────────────────┐
  │                   データの流れ                        │
  ├─────────────────────────────────────────────────────┤
  │                                                     │
  │  sources/          ai-analysis/      reflections/  │
  │  ┌────────┐       ┌────────────┐    ┌───────────┐  │
  │  │ GitHub │──┐    │            │    │           │  │
  │  │ Slack  │  ├──▶ │ AI分析結果  │──▶ │ 自分の考察 │  │
  │  │ etc... │──┘    │            │    │           │  │
  │  └────────┘       └────────────┘    └───────────┘  │
  │    入力              処理結果          最終成果物     │
  │                                                     │
  └─────────────────────────────────────────────────────┘

注意点・ポイント

  • 複雑にしすぎない: AIへ複雑すぎる図を求めると、レイアウトが崩れたりトークンを消費したりすることがあるため、「簡単な図解」と指定するのがコツ。
  • 指示の場所: Claude Codeなら CLAUDE.md、Gemini CLIなら GEMINI.md、Cursorなら .cursorrules など、各ツールが参照する設定ファイルに記述する。

まとめ

  • CLAUDE.md 等に図解の指示を入れるだけで、AIの回答が「読むもの」から「見るもの」に変わる。
  • 構造やフローの理解が早まり、認知負荷が下がる。
  • テキストベース（ASCIIアート）なので、ターミナル上でも崩れず確認できる。

ちょっとした工夫ですが、日々のAIとの共同作業が非常にスムーズになるのでおすすめです。

Discussion