M
masaki.work

AIとの対話術 — コンテキスト管理の実践

ai claude-code productivity workflow

★この記事の全文をコピーして、AIに「この通りに設定をガイドして」と渡すと便利です

📊この記事の図解版があります。内容を視覚的にまとめたページで、全体像をサッと把握できます

図解を見る

AIとの対話術 — コンテキスト管理の実践

はじめに

AIコーディングツールの「取扱説明書」を書くとか、仕様を先に書いてから実装するとか。どちらも「なぜそうするのか」には触れられていても、実際にAIと長時間対話する中でどう使い分けるかは見えにくい。

この記事は、AIコーディングツールに「取扱説明書」を書いたら、開発が変わった と なぜあなたの仕事はうまく進まないのか？ — AI時代の「仕様駆動」に学ぶ、今日から使える仕事術 の実践編にあたる。先にそちらを読んでおくと、本記事の内容がより深く理解できる。

この記事では、AIとの対話を「体力管理」として捉える考え方と、その考え方から導かれる6つの実践を紹介する。

HP（体力ゲージ） — コンテキストウィンドウは有限

AIにはコンテキストウィンドウという制約がある。これは「一度に処理できる情報量の上限」で、会話が長くなるほど古い情報が押し出されていく。

あるAI活用コミュニティでは、この制約を**「HP（体力ゲージ）」**と呼んでいた。ゲームのキャラクターと同じように、HPが満タンな状態と残り少ない状態では、パフォーマンスが変わるという直感的なたとえだ。

  • 新しいセッション = HPが満タン
  • 会話が長くなる = HPが減る
  • HPが減った状態 = 初期の指示や重要な文脈を「忘れた」ように見える

「なぜかさっきまで正しく動いていたAIが、急に意図と違う出力をし始めた」という経験はないだろうか。多くの場合、AIの能力が落ちたわけではない。HPが減って、最初に渡したルールや文脈が押し出されてしまっているだけだ。

ポケモンセンター理論

HPが減ったらどうするか。ゲームならポケモンセンターに行って回復する。AIならセッションをリセットして新しい状態で始め直す。

このとき重要なのが、リセットしても大丈夫な状態を事前に作っておくことだ。具体的には次のような準備が必要になる。

  • 計画はファイルに書き出しておく（次のセクションで詳しく解説する）
  • 途中経過もコミット（保存）しておく
  • 次のセッションでは「このファイルを読んで、続きをやって」と伝えるだけで復帰できる

「もったいない」と感じるかもしれない。しかし、HPが減りきった状態で続けても、ズレた出力の修正に時間を取られてトータルでは遅くなる。きれいな状態で始め直すほうが、結果として速い。

HPの管理は、AIとの対話の質を決める基盤だ。 これを知らないと「なぜかAIの精度が落ちた」と漠然と感じるだけで終わる。コンテキストウィンドウという仕組みを知っていれば、「今はHPが減っているからリセットしよう」と意識的に判断できる。

セルフコンテインドプラン — 計画と実装を分離する

HPの概念がわかると、計画フェーズでHPを使い切ってから、リセットして実装フェーズに入るという運用が自然に導かれる。

ここで重要なのがセルフコンテインドプラン（それだけで完結するプラン）の概念だ。「セルフコンテインド」とは「自己完結している」という意味で、そのプランを見るだけで、他の情報がなくても作業を進められる状態を指す。

なぜ「セルフコンテインド」が必要なのか

計画フェーズで作ったプランは、セッションリセット後のAIが唯一の手がかりにするものだ。つまりプランには、以下がすべて含まれている必要がある。

  • 何をするか（タスク一覧）
  • なぜするか（目的・背景）
  • どこを触るか（対象ファイルのパス）
  • どう判断するか（設計上の決定とその理由）
  • 完了条件（何ができたらOKか）

計画フェーズの会話の中で「さっき話した通り〜」と省略していた部分も、プランにはすべて書き出す。なぜなら、リセット後のAIは「さっきの会話」を一切知らないからだ。計画フェーズの会話がどれだけ充実していても、リセットすればそれはすべて消える。

セルフコンテインドプランの実践例

## タスク: ユーザープロフィールページの作成

### 目的
会員登録済みユーザーが自分の情報を確認・編集できるページを追加する。

### 対象ファイル
- `src/pages/profile.astro`（新規作成）
- `src/components/ProfileForm.tsx`（新規作成）
- `src/types/user.ts`（既存・型追加）

### 設計判断
- React（use client）を使う理由: フォームの状態管理が必要なため
- DBへの反映はSupabase client-side SDKを使用

### 完了条件
- /profile にアクセスすると、ログインユーザーの名前・メールが表示される
- 「保存」ボタンで変更がDBに反映される

このプランがファイルとして保存されていれば、新しいセッションでも「このプランを読んで実装して」の一言で始められる。計画フェーズの議論の成果が、ファイルという形で外部メモリに保存されているからだ。

計画と実装を「別のセッション」にする

重要なのは、計画と実装を意識的に別のセッションとして分けることだ。

計画フェーズでは、既存コードの調査、設計の議論、ファイルパスの確認など、多くの情報をやり取りする。このフェーズが終わったら、プランをファイルに保存してセッションをリセットする。実装フェーズは新しいHPで、プランを手がかりに作業を進める。

「計画と実装を同じセッションでやってしまいたい」という誘惑は当然ある。しかし、計画の議論でHPが大幅に減った状態で実装に入ると、実装の後半で「最初に決めたルールを守れていない」「設計の一貫性が崩れている」という問題が起きやすい。計画フェーズで消費したHPのツケが、実装の質に影響するのだ。

仕組みで守る — Plan モード・Hooks・自動注入

セルフコンテインドプランの重要性がわかった。次は、それを仕組みとして自動化する方法を見ていく。手動の運用は、忙しいときほど崩れる。仕組み化すれば、品質は勝手に担保される。

Plan モード — 計画→クリア→実装が自動化された

2026-03-22 追記: v2.1.81（2026-03-20）で、この自動クリアはデフォルト非表示に変更された。復元方法と変更の背景は「Claude Code の Plan モードから「clear context」が消えた理由と復元方法」を参照。

「計画と実装を別のセッションにする」と書いたが、Claude Code にはこれを自動でやってくれる機能がすでにある。

Plan モード（/plan コマンドまたは Shift+Tab で切り替え）を使うと、AIは計画だけを出力する。計画を確認して承認すると、コンテキストがクリアされ、計画フェーズの議論がリセットされる。新しいHPの状態で実装が始まる。2026年1月、Claude Code を開発する Boris Cherny がこの機能をアナウンスした（Threads / X）。

つまり、手動でセッションをリセットしていた「ポケモンセンター回復」が、ボタン一つで完了する。計画フェーズでHPをどれだけ使っても、承認すれば実装は新鮮な状態で始まる。

ただし、自動クリアには副作用がある。計画フェーズの議論を忘れすぎるのだ。手動リセットなら「何を残すか」を自分で選べたが、自動クリアではほとんどの詳細が失われる。だからこそ、プランがセルフコンテインドであることがより重要になった。クリア後のAIが頼れるのは、ファイルに書かれた計画だけだ。

Hooks でプランの品質を自動チェックする

セルフコンテインドプランが重要だとわかっても、つい手を抜く。「対象ファイルは後で書こう」「完了条件は明らかだから省略しよう」。忙しいときほど、プランが雑になる。

Claude Code の Hooks を使えば、この問題を仕組みで解決できる。Hooks とは「特定のイベントが起きたとき、自動でスクリプトを実行する」仕組みだ。Web開発でコードをプッシュするたびにテストが自動で走るCI（継続的インテグレーション）と同じ発想で、プランの品質チェックを自動化できる。

僕の環境では、Plan モードでプランファイルが書き出されるたびに、以下の7つの必須セクションをチェックするバリデーションスクリプトが自動で走る。

  1. Context（背景・目的）
  2. 使用スキル（どのAIスキルを使うか）
  3. Scope（変更範囲）
  4. 変更ファイル（具体的なファイルパス）
  5. 実装ステップ（作業手順）
  6. 検証（完了条件・テスト方法）
  7. 実施方針（実装時の行動指針）

1つでも欠けていると、AIにフィードバックが返り、不足セクションの追記を促す。AIはフィードバックを受けてプランを書き直す。これが繰り返されることで、プランの品質が確保される。

以下はプランバリデーションに関する設定の抜粋だ（実際のプロジェクトでは他の Hooks も共存する）。自分のプロジェクトに合わせて修正して使ってほしい。

以下の JSON は「プランファイルが書き出されるたびに、validate-plan.py を自動実行する」という設定だ。

.claude/settings.json（抜粋）:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/validate-plan.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

次のスクリプトは、プランファイルに7つの必須セクションが含まれているかをチェックし、不足があればAIにフィードバックを返す。

validate-plan.py（バリデーションスクリプトの要点）:

import json, re, sys

# 必須セクション定義 — 自分のプロジェクトに合わせて変更してください
REQUIRED_SECTIONS = [
    ("Context",      r"^#{1,4}\s*Context"),
    ("使用スキル",    r"^#{1,4}\s*(使用スキル|Agent\s*Skills)"),
    ("Scope",        r"^#{1,4}\s*Scope"),
    ("変更ファイル",  r"^#{1,4}\s*(変更ファイル|Files)"),
    ("実装ステップ",  r"^#{1,4}\s*(実装ステップ|Steps?)"),
    ("検証",         r"^#{1,4}\s*(検証|Verif|Test)"),
    ("実施方針",     r"^#{1,4}\s*(実施方針|Execution\s*Policy)"),
]

MIN_LINE_COUNT = 15  # これ未満は探索メモとみなしてスキップ

data = json.load(sys.stdin)

# Plan モード以外は素通り
if data.get("permission_mode") != "plan":
    sys.exit(0)

# .md ファイル以外は素通り
file_path = data.get("tool_input", {}).get("file_path", "")
if not file_path.endswith(".md"):
    sys.exit(0)

content = data.get("tool_input", {}).get("content", "")

# 短いファイルはスキップ（探索メモなどを誤検知しない）
if len(content.splitlines()) < MIN_LINE_COUNT:
    sys.exit(0)

# 必須セクションのチェック
missing = [name for name, pattern in REQUIRED_SECTIONS
           if not re.search(pattern, content, re.MULTILINE)]

if missing:
    sys.stderr.write(
        f"⚠ 必須セクション不足: {', '.join(missing)}\n"
        "追記してから再度書き出してください。\n"
    )
    sys.exit(2)  # exit(2) = AIにフィードバックを返す

sys.exit(0)  # 全セクション揃い = パス

ポイントは exit(2) だ。Claude Code の Hooks では、終了コード 2 を返すと stderr のメッセージがAIへのフィードバックとして伝わる。AIはそのフィードバックを受けて自動的に修正を試みるため、品質の低いプランのまま実装に進むことが防がれる。

補足: 上記の REQUIRED_SECTIONS は僕のプロジェクト向けの設定だ。セクション名やパターンは自分のプロジェクトに合わせて書き換えてほしい。Hooks の仕組み自体はどのプロジェクトでもそのまま使える。

セッション開始時の自動注入

Plan モードでコンテキストが圧縮されても、Hooks でプランの品質が担保されていても、もう一つ考えるべきことがある。次にセッションを開始したとき、AIは「今何をやっているか」を知らないということだ。

僕の環境では、変更計画を Markdown ファイル（タスク一覧、設計ドキュメント）として管理している。これにより、コンテキストが圧縮されても計画はファイルとして残り続ける。ここまでは「セルフコンテインドプラン」の話と同じだ。

その上で、Claude Code の SessionStart Hook を使って、セッション開始時に進行中の計画一覧を自動でコンテキストに注入している。

以下の設定は「セッション開始時・コンテキストクリア時・コンテキスト圧縮時に、inject-context.py を自動実行する」という意味だ。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/inject-context.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

matcher の値に注目してほしい。SessionStart Hook は startup（セッション開始）、resume（セッション再開）、clear（コンテキストクリア）、compact（コンテキスト圧縮）の4つのイベントをサポートしている。上記の設定では startup|clear|compact を指定しているため、HPがリセットされるたびに、AIに「今何が進行中か」が自動で伝わる。

注入スクリプトの仕組みはシンプルだ。進行中のタスク一覧を取得して、Markdown テーブルとして stdout に出力する。SessionStart Hook では、stdout の出力がそのままコンテキストに注入される。以下は考え方を示す疑似コードだ。

# inject-context.py（疑似コード — 実装は自分のプロジェクトに合わせて書き換える）
import json, subprocess, sys

# 進行中タスクの一覧を取得
# 例: ファイルシステムから読む、APIから取得する、CLIツールを呼ぶ、など
tasks = get_active_tasks()  # ← 自分の実装に置き換え

if not tasks:
    sys.exit(0)  # 進行中タスクがなければ何も注入しない

# Markdown テーブルで stdout に出力 → コンテキストに自動注入
print("## 進行中のタスク一覧")
print("| タスク | 進捗 | ファイル |")
print("|---|---|---|")
for task in tasks:
    print(f"| {task['name']} | {task['progress']} | {task['path']} |")

補足: get_active_tasks() の実装は自分のプロジェクトに合わせる。ファイルシステムからタスクファイルを検索する、プロジェクト管理ツールの API を叩く、CLI ツールを呼ぶ、など方法は何でもいい。重要なのは「stdout に出力された内容がコンテキストに注入される」という SessionStart Hook の仕組みだ。

この仕組みの本質は、**「AIの記憶に頼らず、ファイルに書く。そしてファイルから自動で読み込む」**という運用だ。コンテキストウィンドウは有限で、いずれ圧縮される。だからこそ、計画はファイルに永続化し、必要なときに自動で注入する。HP管理の根本的な解決策は、HPが減ることを前提にした仕組みを作ることだ。

手で編集するとAIが気づかない — AIに見える履歴を残す

AIコーディングツールを使っていると、「これくらい自分で直したほうが早い」と思ってエディタで手動修正したくなる場面がある。小さなtypoの修正、インデントの整形、変数名の変更。確かに、自分でやれば数秒で終わる。

しかし、手動で編集するとAIのコンテキストにその変更が残らない。

AIは自分が行った編集の流れを把握している。しかし、人間が外部エディタで変更した内容は自動的にはわからない。次にAIが作業を再開したとき、「えっ、このファイルこうなってたっけ？」という状態が生まれる。

なぜ情報の非対称性が問題なのか

たとえば、AIがファイルAを編集して「完了しました」と報告した直後に、自分でそのファイルを少し修正したとする。次の指示でAIは「さっき自分が書いたはずのコード」を前提に作業を進める。ところが実際のファイルは自分が手を加えた後の状態だ。

小さな差異が積み重なると、AIの認識と実際のコードの状態がじわじわとズレていく。「なんか変な修正が入ってきた」「指示していない部分が変更された」という現象は、このズレから来ることが多い。

対策: AIに編集させるか、変更を伝える

  • 原則: ファイルの編集はAIに指示して行わせる。「3行目のXXをYYに変えて」と頼む
  • やむを得ず手動で変更した場合: 次の指示で「このファイルのX行目を手動で変更した」と明示的に伝える

これは「AIとの共同作業において、情報の非対称性を作らない」という原則だ。人間とAIが同じ情報を見ながら作業を進めることで、認識のズレを防ぐ。

慣れてくると、「このくらい自分でやろう」という判断の閾値が上がってくる。それよりも「AIに頼む」を基本にして、手動で変更した場合は必ず伝える習慣をつけるほうが、長い目で見て混乱が少ない。

コンテキストはリポジトリに溜まる — ツールは変えても知識は残る

AIコーディングツールは次々に新しいものが登場する。Cursor、Claude Code、GitHub Copilot、Windsurf。どれを使うべきか迷う人は多い。毎月のように「新しいツールが最強」という記事が出てくる。

しかし本質的に重要なのは、知識がどこに蓄積されるかだ。

答えはリポジトリ。ツールの中ではない。

  • CLAUDE.md（ルールファイル）はリポジトリに保存される
  • 仕様書・設計書はリポジトリに保存される
  • スキル定義はリポジトリに保存される
  • コミット履歴はリポジトリに残る

つまり、ツールを乗り換えても知識は持ち運べる。あるツールで育てたCLAUDE.mdは、別のツールでもそのまま使える。今日のツールが明日なくなっても、リポジトリに蓄積された知識は失われない。

UIの変化に動揺しない

あるAI活用コミュニティでは、AIツールの進化速度が速すぎて「また画面が変わってる！」「そんなボタンありましたっけ？」という場面が頻発した。コミュニティの講師はUIの変化に動揺せず、こう語ったという。

「ツールは変わっても、リポジトリに書いたルールや仕様は変わらない。だからリポジトリに知識を集約する」

ツールへの依存度を下げ、リポジトリへの依存度を上げる。これがツールの変化に振り回されない戦略だ。

「ツールではなくリポジトリ」を意識した設計

この考え方は、知識の書き場所の選択に影響する。

たとえば、AIへの指示を毎回チャットで書くのではなく、ルールファイルに書いてリポジトリに保存する。プロジェクトの設計判断をメモアプリではなくリポジトリのドキュメントとして管理する。チームメンバーへの引き継ぎ情報もリポジトリに置く。

こうすることで、ツールが変わっても、メンバーが変わっても、知識はリポジトリに残り続ける。コンテキストの蓄積先をリポジトリに集約する。 これがツールの変化に振り回されない最善の戦略だ。

図解で認知コストを下げる — 構造化→可視化のパワー

最後に、コンテキスト管理のもう一つの側面を紹介する。人間の認知コストを下げるための工夫だ。

あるAI活用コミュニティで、約1年半にわたってSlackや会議で断片的に議論してきた事業のフィロソフィーを、仕様駆動のワークフロー（proposal → specs → design → tasks）で構造化した。その構造化されたドキュメントをAIに渡して「図解にして」と指示しただけで、議論の全体像が一目でわかる図が生成された。

コミュニティの講師自身が「感動しました」と語るほどの出来栄えだった。チームに共有すると「これまでの議論が整理されて、一目でわかる」と好評だった。

なぜ図解が効果的なのか

テキストの情報を処理するとき、読者は頭の中で「構造」を組み立てる必要がある。箇条書きを読みながら、それらがどう関係しているかを把握しようとする。これが認知コストだ。図解はその構造を視覚的に提示することで、読者の認知コストを大幅に下げる。

認知コストが下がると何が変わるか。会議の場でドキュメントを読みながら議論するのと、図解を見ながら議論するのでは、理解のスピードが違う。図解があれば「この部分はどこに位置づけられるのか」をすぐに確認できるので、議論が本質に集中しやすくなる。

構造化なしに図解は生まれない

ここで重要なのは、図解を最初から作ろうとしたわけではないということだ。

  • 約1年半の議論をまず構造化した
  • 構造化されたドキュメントをAIに渡した
  • 「図解にして」と指示した

この順番が正しい。構造化されていないドキュメントをAIに渡しても、良い図解は生まれない。情報の関係性が整理されていて初めて、それを視覚的に表現できる。

つまり、仕様駆動で整理されたドキュメント → 図解、という流れが最も効率がいい。図解は「構造化の副産物」であり、理解が深まると自然に生まれる。 最初から図解を作ろうとするのではなく、構造化を丁寧にやれば、図解は後からついてくる。

まとめ

AIとの対話を生産的にする6つの実践を振り返る。

  1. HPの管理: コンテキストウィンドウは有限。減ったらリセットして「ポケモンセンター回復」する。HPが減った状態で続けても品質は落ちる一方だ
  2. セルフコンテインドプラン: 計画はファイルに書き出し、リセット後のAIが単独で作業できる状態にする。「さっき話した通り」が通じない前提で書く
  3. 仕組みで守る: プランの品質チェックと進行中タスクの自動注入を仕組み化して、「AIが忘れても大丈夫」な状態を自動的に保つ
  4. AIに編集させる: 手動編集はコンテキストの断絶を生む。AIに変更させて履歴を残す。やむを得ず手動で変更した場合は次の指示で明示的に伝える
  5. リポジトリに知識を溜める: ツールではなくリポジトリに知識を蓄積する。ツールは変えても知識は持ち運べる
  6. 図解で認知コストを下げる: 構造化された情報を可視化し、チーム全員の理解を揃える。図解は構造化の副産物として生まれる

これらの実践は、すべて**「AIのコンテキストウィンドウは有限である」という制約から導かれる**。計画をファイルに書き出すのも、セッションをリセットするのも、品質チェックを自動化するのも、リポジトリに知識を蓄積するのも、根本にある問いは同じだ。「AIが忘れても、作業が続けられる状態になっているか？」

制約を理解し、その制約と上手に付き合う方法を身につけること。それがAIとの対話術の本質だ。

関連記事