📚

CLAUDE.mdとGEMINI.mdを共存！システムプロンプトと人間向けドキュメントの共存手法

Matsukura Yuki

2025/06/26に公開

 3秒まとめ
課題: 複数のLLM（Claude、Gemini、GitHub Copilot）ごとに個別の指示書を管理するのは非効率

解決策: Diátaxis (ディアタクシス)フレームワークで情報を体系化し、シンボリックリンクでエントリーポイントを統一

効果: 人間とAI両方が効率的にアクセスできる、メンテナンス性の高いドキュメント管理を実現

 概要本記事では、人間とAIの両方が効率的に情報にアクセスできるドキュメント管理手法を、Diátaxis (ディアタクシス)フレームワークを活用して構築する方法を解説します。

 背景現在、Claude、Gemini、GitHub Copilotなど多数のLLMサービスが利用されており、それぞれが参照するドキュメントのエントリーポイントが異なります。開発チームは複数のLLMを使い分けることが一般的になっており、統一的なドキュメント管理の必要性が高まっています。
昨日発表されたGemini CLIは GEMINI.md をエントリーポイントとして要求しています。

 課題現状のドキュメント管理には以下のような問題があります：

管理コストの増大: 各LLMごとに個別の指示書を用意・維持する必要がある

情報の重複: LLM向けの指示と人間向けのドキュメントで同じ内容が重複している

一貫性の欠如: 複数のドキュメントが存在することで情報の不整合が発生しやすい

メンテナンス性の低下: 情報が分散しているため、更新時の漏れが発生しやすい

 解決アプローチ上記の課題を解決するため、以下の3つの原則に基づいたアプローチを採用します：

共通化と差別化の明確化: 人間とLLMで共通利用できる部分と、それぞれに特化した部分を明確に分離

階層構造の整理: ドキュメントの階層と参照関係を明確にし、情報の迷子を防ぐ

標準フレームワークの採用: Diátaxisフレームワークを活用した体系的な情報分類

 設計思想本手法は、以下の確立されたドキュメント管理のベストプラクティスを組み合わせています：

 1. Diátaxis フレームワーク技術文書をその目的に応じて4つのタイプに分類するフレームワークです：

チュートリアル (Tutorials): 学習者を手引きするレッスン

ハウツーガイド (How-to guides): 特定の目標達成のための具体的手順

解説 (Explanation): 背景や設計思想の理解のための説明

リファレンス (Reference): 技術的に正確で網羅的な情報

 2. Docs as CodeすべてのドキュメントをGitでコードと共に管理し、Markdownで記述、Pull Requestでレビューするアプローチです。これにより、ドキュメントとコードの同期を保ち、品質を担保します。

 3. アーキテクチャ・デシジョン・レコード (ADR)ソフトウェアアーキテクチャに関する重要な意思決定とその理由、選択肢、背景、結果などを時系列で記録するドキュメント手法です。これにより、設計や技術選定の経緯を後から追跡でき、プロジェクトの知識共有や意思決定の透明性が向上します。

 提案するドキュメント構成現在のLLMサービスは、それぞれ固有のエントリーポイントファイルを要求します。
これらのLLMごとのファイルの内容は本質的に大きく異なるものではありません。
人間の開発者にとってのエントリーポイントは従来通りREADME.mdです。
これらの要件を満たしつつ、ドキュメントの重複を最小限に抑え、保守性を高める構成モデルを設計しました。

 構成の概要
開発者 (人間): README.md から読み始め、プロジェクトの概要やセットアップ手順を把握します。詳細なコマンドやコードのレシピについては、.claude/cookbook.md を参照します。

LLM (Claude, Gemini, Copilot): それぞれの入口となるファイル (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md) を使用します。これらのファイルはすべて、中心となる CLAUDE.md に繋がっています。

CLAUDE.md: LLM向けのマスター指示ファイルとして機能し、プロジェクトのコンテキストを提供しつつ、.claude/ ディレクトリ内の詳細な知識ベースへリンクします。

知識ベース (.claude/): 特定のトピックに関する信頼できる唯一の情報源（Single Source of Truth）として機能し、情報の重複を防ぎます。

knowledge.md: アーキテクチャの決定や技術的な背景（なぜ）。

cookbook.md: コマンドやコードパターンを網羅したレシピ集（やり方）。

history.md: プロジェクトの改善履歴や背景（変遷）。

この構成により、情報は論理的に整理され、保守が容易になり、人間とAIの両方が明確な入口から情報にアクセスできます。

 実装方法この構成を実際のプロジェクトに導入するための具体的な手順を示します。以下のプロンプトをLLMに提供することで、自動的に構成を構築できます。
# 標準ドキュメント構成 構築プロンプト (Diátaxis準拠 最終版)

## 目的
プロジェクトのドキュメントを、人間とAIの両方にとって分かりやすく、メンテナンス性の高い標準構成に再構築します。特に、[Diátaxisフレームワーク](https://diataxis.fr/)の考え方を全面的に採用し、ドキュメントをその目的に応じて明確に分類します。

## 指示
以下の手順に従って、プロジェクトのドキュメントを **日本語で** 再構築してください。

---

### フェーズ1: 現状分析と情報整理

1.  **既存ドキュメントの分析**:
    現在の `README.md` や、その他存在するすべてのドキュメントを読み込み、内容を完全に把握してください。

2.  **情報の分類 (Diátaxis)**:
    分析した内容を、Diátaxisフレームワークの4つのカテゴリに分類・整理してください。
    -   **チュートリアル (Tutorials)**: プロジェクトのセットアップ手順など、学習者を手引きするレッスン。
    -   **ハウツーガイド (How-to guides)**: コマンド実行、デバッグ、リリース手順など、特定の目標を達成するための具体的な手順。
    -   **解説 (Explanation)**: アーキテクチャ、設計思想、技術選定の理由、過去の経緯など、背景や文脈を理解するための説明。
    -   **リファレンス (Reference)**: API仕様、重要なログ、技術的に正確で網羅的な情報。

---

### フェーズ2: 新しいドキュメント構造の構築

1.  **知識ベース用ディレクトリの作成**:
    プロジェクトのルートに `.claude` という名前のディレクトリを作成し、その中にDiátaxisのカテゴリに対応するサブディレクトリを作成します。
    ```bash
    mkdir -p .claude/tutorials .claude/how-to-guides .claude/explanation .claude/reference
    ```

2.  **知識ベースの作成**:
    分類した情報を基に、対応するディレクトリ内にファイルを日本語で作成・記述してください。
    -   `.claude/how-to-guides/cookbook.md`: **ハウツーガイド**を集約します。
    -   `.claude/explanation/knowledge.md`: **解説**（アーキテクチャや設計思想）を集約します。
    -   `.claude/explanation/history.md`: **解説**（プロジェクトの歴史と変遷）を集約します。
    -   `.claude/reference/debug-log.md`: **リファレンス**（重要なデバッグログなど）を集約します。

3.  **マスタードキュメントの作成 (`CLAUDE.md`)**:
    -   プロジェクトのルートに `CLAUDE.md` というファイル名で、日本語で作成します。
    -   このファイルには、プロジェクト概要と、Diátaxisフレームワークに基づいた新しいナレッジベースへの案内を記述します。以下のテンプレートを参考にしてください。
        ```markdown
        ## ナレッジベース (Diátaxisフレームワーク準拠)

        このプロジェクトの知識は、Diátaxisフレームワークに基づき、`.claude/` ディレクトリ内で目的別に分類・管理されています。

        - **[解説 (Explanation)](./.claude/explanation/)**: なぜそうなっているのか、背景や設計思想を理解するためのドキュメントです。
        - **[ハウツーガイド (How-to guides)](./.claude/how-to-guides/)**: 特定のタスクを達成するための具体的な手順を示します。
        - **[リファレンス (Reference)](./.claude/reference/)**: 技術的に正確で網羅的な情報です。
        - **チュートリアル (Tutorials)**: この役割は主に `README.md` が担っています。
        ```
    -   プロジェクトのコンテキストやアーキテクチャの概要もここに含めます。

4.  **人間向け `README.md` の再構築**:
    -   `README.md` を、Diátaxisにおける**チュートリアル**として再定義します。
    -   内容は、プロジェクトのセットアップと基本的な操作に限定し、シンプルに保ちます。
    -   冒頭に、より詳細な情報への入口として `CLAUDE.md` へのリンクを目立つように配置します。

5.  **各種AI向けシンボリックリンクの作成**:
    -   `CLAUDE.md` へのシンボリックリンクを作成します。
        ```bash
        ln -sf CLAUDE.md GEMINI.md
        mkdir -p .github
        ln -sf ../CLAUDE.md .github/copilot-instructions.md
        ```

---

### フェーズ3: 仕上げ

1.  **ドキュメント構成図の作成と追記**:
    -   以下のDiátaxisベースのMermaid図を、「ドキュメント構成」セクションとして `README.md` と `CLAUDE.md` の両方の末尾に追記します。
        ```mermaid
        ---
        title: ドキュメント構成図 (Diátaxis準拠)
        ---
        graph TD
            subgraph "アクター"
                direction LR
                A["開発者 (人間)"]
                B["Claude"]
                C["Gemini"]
                D["GitHub Copilot"]
            end

            subgraph "入口となるドキュメント"
                direction LR
                README("README.md<br>[チュートリアル]")
                CLAUDE_MD("CLAUDE.md<br>[マスター文書]")
                GEMINI_MD("GEMINI.md")
                COPILOT_MD(".github/copilot-instructions.md")
            end

            subgraph "知識ベース (.claude/)"
                direction TB
                subgraph "解説 (Explanation)"
                    KNOWLEDGE("knowledge.md")
                    HISTORY("history.md")
                end
                subgraph "ハウツー (How-to)"
                    COOKBOOK("cookbook.md")
                end
                subgraph "リファレンス (Reference)"
                    DEBUG("debug-log.md")
                end
            end

            A -- "参照" --> README
            README -- "詳細はこちら" --> CLAUDE_MD
            B -- "参照" --> CLAUDE_MD
            C -- "参照" --> GEMINI_MD
            D -- "参照" --> COPILOT_MD

            GEMINI_MD -.-> |シンボリックリンク| CLAUDE_MD
            COPILOT_MD -.-> |シンボリックリンク| CLAUDE_MD

            CLAUDE_MD -- "参照" --> KNOWLEDGE & HISTORY & COOKBOOK & DEBUG

            style README fill:#cde4ff,stroke:#333,stroke-width:2px
            style CLAUDE_MD fill:#e1f7d5,stroke:#333,stroke-width:2px
        ```

2.  **最終確認**:
    -   作成した新しいファイル構造と、更新された `README.md` および `CLAUDE.md` の内容を提示し、最終的な承認を求めてください。

 期待される効果この手法を導入することで、以下のような効果が期待できます：

 開発効率の向上
情報検索時間の短縮: 統一されたエントリーポイントにより、必要な情報に素早くアクセス可能

LLM活用の最適化: 各LLMが適切なコンテキストを持つことで、より精度の高い支援を受けられる

オンボーディングの効率化: 新しいチームメンバーが迅速にプロジェクトを理解できる

 メンテナンス性の向上
情報の一元管理: Single Source of Truthにより、情報の重複と不整合を防止

更新作業の簡素化: 一箇所の更新で複数のエントリーポイントに反映される

品質の向上: Docs as Codeによるレビュープロセスでドキュメント品質を担保

 まとめ本記事では、LLM時代に対応したドキュメント管理手法を提案しました。
主なポイント：
Diátaxisフレームワークによる体系的な情報分類
人間とAIの両方に配慮したエントリーポイント設計
Single Source of Truthによる情報の一元管理
シンボリックリンクを活用した効率的な構成
この手法により、開発チームは複数のLLMを効果的に活用しながら、メンテナンス性の高いドキュメント管理を実現できます。特に、情報の重複を排除し、一貫性を保ちながら、人間とAIの両方が効率的に情報にアクセスできる環境を構築できる点が大きな利点です。
今後のLLM技術の発展に伴い、このような統合的なドキュメント管理手法の重要性はさらに高まると考えられます。ぜひ、皆さんのプロジェクトでも試してみてください。

株式会社マインディアテックブログPublication

株式会社マインディアのテックブログになります。LLMによってエンジニアリングをレバレッジできると考えているので、Gemini, OpenAI, AnthropicなどのメジャーなLLMはもちろん利用中、その他のLLMサービスも申請すれば基本的に通ります。

3秒まとめ

概要

背景

課題

解決アプローチ

設計思想

1. Diátaxis フレームワーク

2. Docs as Code

3. アーキテクチャ・デシジョン・レコード (ADR)

提案するドキュメント構成

構成の概要

実装方法

期待される効果

開発効率の向上

メンテナンス性の向上

まとめ

Discussion