📚
Context engineeringの実践例 - システムプロンプトと人間向けドキュメントを共存して管理

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

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

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

 概要本記事では、Context Engineering（コンテキスト・エンジニアリング）の実践例として、人間とAIの両方が効率的に情報にアクセスできるドキュメント管理手法を解説します。
Context Engineeringとは、LLMに対して適切な文脈情報（コンテキスト）を構造化して提供することで、より精度の高い出力を得るための技術体系です。本記事で紹介する手法は、Diátaxis (ディアタクシス)フレームワークを活用したContext Engineeringの具体的な実装例となります。

 背景現在、Claude、Gemini、GitHub Copilotなど多数のLLMサービスが利用されており、それぞれが参照するドキュメントのエントリーポイントが異なります。開発チームは複数のLLMを使い分けることが一般的になっており、統一的なドキュメント管理の必要性が高まっています。
昨日発表されたGemini CLIは GEMINI.md をエントリーポイントとして要求しています。
Context Engineeringの観点から見ると、LLMの出力品質は提供されるコンテキストの質と構造に大きく依存します。適切に構造化されたコンテキストを提供することで、LLMはより正確で有用な支援を行うことができます。

 課題現状のドキュメント管理には、Context Engineeringの視点から以下のような問題があります：

コンテキストの断片化: 各LLMごとに個別の指示書を用意することで、コンテキスト情報が断片化し、一貫性のある文脈提供が困難

情報の重複と不整合: LLM向けの指示と人間向けのドキュメントで同じ内容が重複し、Context Engineeringの基本原則である「Single Source of Truth」が守られていない

構造化の欠如: 情報が体系的に整理されておらず、LLMが効率的にコンテキストを理解・活用できない

メンテナンス性の低下: Context Engineeringの実践において重要な、コンテキスト情報の継続的な改善が困難

 解決アプローチ上記の課題を解決するため、Context Engineeringのベストプラクティスとして、以下の3つの原則に基づいたアプローチを採用します：

構造化されたコンテキスト提供: 人間とLLMで共通利用できる部分と、それぞれに特化した部分を明確に分離し、Context Engineeringの原則に従って情報を構造化

階層的なコンテキスト管理: ドキュメントの階層と参照関係を明確にし、LLMが段階的にコンテキストを理解できるよう設計

標準フレームワークの採用: Diátaxisフレームワークを活用し、Context Engineeringに適した体系的な情報分類を実現

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

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

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

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

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

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

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

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

 提案するドキュメント構成Context Engineeringの実践として、現在のLLMサービスが要求する固有のエントリーポイントファイルを効率的に管理する構成を提案します。
これらのLLMごとのファイルの内容は本質的に大きく異なるものではなく、適切なContext Engineeringによって統一的に管理できます。
人間の開発者にとってのエントリーポイントは従来通りREADME.mdですが、これもContext Engineeringの観点から最適化されています。
これらの要件を満たしつつ、Context Engineeringの原則に基づいてドキュメントの重複を最小限に抑え、保守性を高める構成モデルを設計しました。

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

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

CLAUDE.md: Context Engineeringのマスターファイルとして機能し、LLMに対して構造化されたプロジェクトコンテキストを提供しつつ、.claude/ ディレクトリ内の詳細な知識ベースへリンクします。

知識ベース (.claude/): Context Engineeringの原則に基づき、特定のトピックに関する信頼できる唯一の情報源（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` の内容を提示し、最終的な承認を求めてください。

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

 開発効率の向上
Context Engineeringによる情報検索の最適化: 構造化されたコンテキストにより、LLMと人間の両方が必要な情報に素早くアクセス可能

LLMの出力品質向上: Context Engineeringの原則に基づいた適切なコンテキスト提供により、より精度の高いAI支援を実現

オンボーディングの効率化: 体系的に整理されたコンテキスト情報により、新しいチームメンバーが迅速にプロジェクトを理解できる

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

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

品質の向上: Docs as Codeによるレビュープロセスで、Context Engineeringの品質を継続的に改善

 まとめ本記事では、Context Engineeringの実践例として、LLM時代に対応したドキュメント管理手法を提案しました。
Context Engineeringの主要な実装ポイント：
Diátaxisフレームワークを活用した、Context Engineeringに適した体系的な情報分類
人間とAIの両方に最適化されたコンテキスト提供のためのエントリーポイント設計
Context EngineeringのSingle Source of Truth原則による情報の一元管理
シンボリックリンクを活用した効率的なContext Engineering構成
このContext Engineering手法により、開発チームは複数のLLMを効果的に活用しながら、メンテナンス性の高いドキュメント管理を実現できます。特に、Context Engineeringの原則に基づいて情報の重複を排除し、一貫性のあるコンテキストを維持しながら、人間とAIの両方が効率的に情報にアクセスできる環境を構築できる点が大きな利点です。
今後のLLM技術の発展に伴い、このようなContext Engineeringの手法はますます重要になると考えられます。本記事で紹介したContext Engineeringの実践例を、ぜひ皆さんのプロジェクトでも試してみてください。
株式会社マインディアテックブログPublication
株式会社マインディアのテックブログになります。LLMによってエンジニアリングをレバレッジできると考えているので、Gemini, OpenAI, AnthropicなどのメジャーなLLMはもちろん利用中、その他のLLMサービスも申請すれば基本的に通ります。
3秒まとめ

概要

背景

課題

解決アプローチ

設計思想

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

2. Docs as Code

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

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

構成の概要（Context Engineeringの実装）

実装方法

期待される効果

開発効率の向上

Context Engineeringによるメンテナンス性の向上

まとめ

Discussion
