2025.12.01

コンテキストを永続化するドキュメント設計 ― CLAUDE.mdが実現する制御可能なAI執筆プロセス

AI Hiroki Arai LLM

Claude Code をドキュメント作成に使ってみたので、まとめていきます。

この記事はクリエーションライン Advent Calendar 2025の1日目の記事です。

はじめに

AIを使ってドキュメントを書いていて、こんな経験はありませんか？

「最初は良いけど途中からおかしくなったり、細かいところでニュアンスがズレたりする」

「一つ一つの文章ではそれっぽいことを言っているけど、全体構成としてはいまいち」

「指摘を繰り返しながら直していっているうちに、前に指摘したところがまた繰り返し間違えたりする」

多くの方が似たような経験をしているかと思います。私もそうでした。

この記事では、私が実践している「CLAUDE.mdを使ったドキュメント作成」のやり方を紹介します。

AIと共有するコンテキストを永続化して、AIとの共同作業をもっとコントロールしやすくする方法です。

社内ガイドラインや本番運用レベルのドキュメントをAIと一緒に作りたいエンジニアやマネージャーの方に、参考になれば嬉しいです。

課題: AIとの会話で失われるコンテキスト

ChatGPT Web版でドキュメントを作っていたとき、いくつかの壁にぶつかりました。

会話が長くなると指示が薄れる

例えば、「このドキュメントは一つ一つの章の基本構造を、

定義
具体例
補足

の構成にしてください。」

とチャットの冒頭で指示して、1章2章と書き進めていって、最初のうちは良いんですが、後半の8章あたりになった時に「具体例」が抜けていたり、別のものに変わっていたりすることがあります。

チャット形式での会話が長くなったことによって、指示が多くなって優先すべき指示がごちゃごちゃになってくると、こんなことが起きます。

「そろそろ新しいチャットにしたほうがいいかな？」と思っても、これまで積み上げたコンテキストが消えちゃうのがもったいない。でも続けると指示が薄れていく。このジレンマをよく味わっています。

コンテキストがどこまで効いているか分からない

必要な指示は一通り与えているつもりでも、指示自体が不足していることがあったり、チャットが長くなると指示が多くなってどれが優先されているかよくわからない状態になることがあります。

AIの中で何が起きてるか見えないので、どの指示が生きててどれが忘れられてるのか、正直よく分かりません。

チャット後半でごちゃごちゃになる

最初に決めた方針が、後半になるとだんだん曖昧になって、全体の一貫性が崩れていく。結局、手作業でかなり直すはめになることも多かったです。

これらの問題の根っこは、コンテキストが会話の流れに埋もれてしまうことにあります。

解決策: CLAUDE.mdを使ったドキュメント作成

この課題を解決するために、私はCLAUDE.mdを活用したやり方を取り入れています。

CLAUDE.mdって何？

Claude Codeは、ローカルやリポジトリ内のファイルを読みながら作業できる、Anthropic提供のCLI型AI開発支援ツールです。そのプロジェクトルートに置く設定ファイルがCLAUDE.mdです。

ここに書いた指示は、会話がどれだけ長くなっても常に有効。チャットを新しくしてもこのファイルの内容を読んでくれます。

プロジェクトルートに置く意味

CLAUDE.mdをプロジェクトルートに置いておくと、そのディレクトリで作業を始めるたびに、同じコンテキストが読み込まれます。つまり：

新しい会話を始めても、前回と同じルールが適用される
チームで共有すれば、誰が作業しても同じルールを適用できる
設定がファイルとして残るから、後から確認・修正できる

明示的なコントロール

このやり方の一番のメリットは、AIへの指示が明示的かつ永続的になること。会話の流れに左右されず、常に同じルールで作業が進みます。

3層のコンテキスト構造

CLAUDE.mdを使ったドキュメント作成では、コンテキストを3つの層に分けて管理しています。

CLAUDE.md で「メタ（ルール・手順）」
template.md で「構造（章立て・型）」
docs/ で「コンテンツ（素材）」

この分け方のおかげで、それぞれの役割がはっきりして、必要な部分だけ直せるようになります。

root/
├── CLAUDE.md          # 作業ルール・手順
├── template.md        # ドキュメントの章立て
└── docs/              # 参照資料
    ├── 書きたい内容メモ.md
    ├── 参考資料.pdf
    └── 参照データ.csv

1. CLAUDE.md: メタレベル（作業手順・ルール）

プロジェクト全体のルールや作業手順を書いておきます。

アウトプットの形式（Markdown、docx変換など）
参照すべき資料の場所
作業の進め方
必ず優先する指示

2. template.md: 構造レベル（アウトプットの型）

作成するドキュメントの章立てや構成を定義します。文章の構造を独立させておくことで、構造上の制約を強制することができます。

また、最初に構造レベルでの文章構成を固めておくことで、全体の論理構造と詳細内容を分けて考えることができ、生成AIのコンテキストウィンドウも人間のワーキングメモリーも節約することができます。

見出しの階層構造
各章で触れるべきポイント（コメントで書いておく）
全体のボリューム感

CLAUDE.md に以下を記述しておくことで、文章の構造を明示的に指示します。

作成する文書の章や項目等のフォーマットは ./template.md に記載します。
テンプレートの章立てに従って、アウトプットを作成します。

3. docs/: コンテンツレベル（参照情報）

ドキュメント作成の材料になる情報を置いておきます。

ここのコンテンツを充実させておくことで、生成されるドキュメントの内容も良くなります。

過去の関連資料
参考にしたい既存ドキュメント
インタビューメモや議事録

対応ファイル形式

docs/にはいろんな形式のファイルを置けます。

Markdown (.md)
PDF（スライド資料はPDF化して置くと便利）
Word文書 (.docx)
テキストファイル (.txt)
CSV

Claude Codeはこれらを読み取って、コンテンツとして参照してくれます。

また、指示をCLAUDE.md に細かく書いておけば、1章を書く時にはこの資料を参照して、3章を書く時にはこの資料を参照する。といったコントロールも可能になります。

実践: ガイドライン作成プロジェクト

実際に私がこのやり方で作った「IMガイドライン」プロジェクトを例に、具体的な構成を紹介します。

プロジェクト構成

im-guideline/
├── CLAUDE.md          # 作業ルール・手順
├── template.md        # ドキュメントの章立て
├── output.md          # 生成されるドキュメント
├── output.docx        # Pandocで変換したWord版
└── docs/              # 参照資料
    ├── IM業務を行う上での留意点.md
    ├── IM会ミーティングメモ.md
    ├── Job duties - PJリード.md
    ├── IM_Kuroda.pdf
    ├── EngineeringTeam-IM.pdf
    └── PM育成について【リーダー用】.pdf

CLAUDE.mdの中身

このプロジェクトは、クリエーションラインにおけるInside Manager(IM)の
役割について文書を作成するためのプロジェクトです。

**重要** 文章の作成にあたっては、資料を参考にしながら作成をしてください。

## テンプレート
作成する文書の章や項目等のフォーマットは./template.md に記載します。
テンプレートの章立てに従って、アウトプットを作成します。

## アウトプット
./output.md に文書を作成していきます。
**重要** output.md を更新したら、必ず以下のコマンドでdocx を更新します。
`pandoc output.md -o output.docx`

## 資料
* docs/ 配下に過去に作成した関連資料があります。

### Markdownファイル
* IM業務を行う上での留意点.md
* IM会ミーティングメモ.md
* Job duties - PJリード.md

### PDFファイル
* IM_Kuroda.pdf
* EngineeringTeam-IM.pdf
* PM育成について【リーダー用】.pdf

実際の使用感

teamplate.md を作成してください

第一章の内容を記載してください

こんな感じの指示をClaude Code にすることで、執筆を進めていきます。

このプロジェクトでは、社内に散らばっていた6つ以上の資料を参考にして、Inside Manager という役割に関するガイドラインドキュメントを作りました。

CLAUDE.mdに「資料を参考にしながら作成」と書いてあるので、AIは常にdocs/の資料を見ながら執筆を進めてくれます。

テンプレートを使うメリット

template.mdを使うやり方にも、いくつかのメリットがあります。

構造と内容を分離できる

文書を書いていると、全体の構造を考えているうちについ細かい内容のことも考え始めて、「全体の俯瞰」と「詳細の詰め」で頭がごっちゃになることがよくあります。

この方法なら、まずtemplate.mdで構造だけを考えられます。全体の論理構造やバランスを整える作業と、各章の内容を詰める作業を分離できるので、思考がシンプルになります。

1章ずつ段階的に進められる

テンプレートに章立てを決めておけば、「まず第1章を書いて」「次に第2章を」と段階的に進められます。一気に全部作らせるより、品質のコントロールがしやすいですね。

一気に全部作らせて全体のニュアンスがずれている時の、レビューする負荷も抑えることができます。

Gitで差分管理できる

output.mdをGitで管理すれば、変更履歴を追うこともできます。

いつ、どこが変わったか
誰が（どのセッションで）変えたか
必要なら前のバージョンに戻せる

ChatGPT Web版との比較

CLAUDE.mdを使ったドキュメント作成と、私が普段よく使っているChatGPT Web版を比べてみましょう。

観点	ChatGPT Web版	CLAUDE.mdを使う方法
コンテキストの永続性	会話が長くなると薄れる	ファイルで永続化
指示の効力	徐々に弱まる	常に有効
指示の透明性	AIの内部状態は不明	設定ファイルで明示的
再現性	同じ結果を得にくい	同じ設定で似た品質
手軽さ	ブラウザだけで即開始	ファイル準備が必要
バージョン管理	難しい	Gitで容易

トレードオフ: 手軽さは減る

正直なところ、CLAUDE.mdを使うやり方はChatGPT Web版ほど手軽ではありません。

事前にディレクトリ構成を考える必要がある
CLAUDE.md、template.mdを準備する手間がかかる
Claude Codeの環境セットアップが必要

どんな場合にこのやり方が有効か

こんなケースでは、準備の手間を上回るメリットがあります。

複数の資料を統合するドキュメント: 参照すべき情報が多いとき
品質基準が明確なドキュメント: ルールを明文化しておきたいとき
チームで作成するドキュメント: 設定を共有して品質を揃えたいとき
情報量が多いドキュメント: 数百行を超えるような情報量を公式なドキュメントとしてまとめたいとき

逆に、単発の短い文章やブレストには、ChatGPT Web版の手軽さが勝ります。

他の代替手段との比較

ChatGPTにも、コンテキストを永続化するための仕組みはいくつかあります。たとえば「カスタム指示」や「プロジェクト」機能など。これらを組み合わせれば、ブラウザだけで完結する範囲では十分実用的な環境を作れます。

一方で、Gitで履歴を管理したい、複数人でブランチやPRベースでレビューしたい、普段使い慣れたエディタで編集したい、といったニーズがある場合には、リポジトリ側にCLAUDE.mdやtemplate.md、docs/を置くやり方が有効です。AIに渡すコンテキストを「会話」ではなく「ファイル」として管理することで、開発チームがこれまで培ってきたソフトウェア開発のプラクティス（バージョン管理・コードレビュー・CIなど）を、そのままドキュメント作成にも適用できます。

このブログ自体がCLAUDE.mdを使って書かれている

この記事自体もCLAUDE.mdを使って書いています。

blog/
├── CLAUDE.md          # ブログ執筆のルール
├── template.md        # 記事の章立て
├── output.md          # この記事
└── docs/
    ├── memo.md                      # 含めたい要素のメモ
    ├── 📘 Blog Writing README.pdf   # ブログ執筆ガイドライン
    └── im-guideline/                # ↑本ブログで紹介しているガイドラインプロジェクト

記事の中で「ガイドラインプロジェクト」を例に解説しつつ、この記事自体が同じ方法で書くために、docs/ にim-guideline のプロジェクトを入れています。