なぜClaude Code開発で長文プロンプトは限界か。トークン消費を抑え精度を保つ動的コンテキスト設計の理由

静的プロンプトの限界とトークン枯渇の現実

Claude Codeで開発していると必ずぶつかる壁がある。

CLAUDE.mdの肥大化だ。

ルールを書き足すたびにトークン消費が跳ね上がる。

肝心の推論精度は逆に落ちていく。

解決策はプロンプトを削ることではない。

コンテキストの動的設計だ。

AIに「いつ・何を・どう渡すか」を制御するアーキテクチャが必須になっている。

静的なファイル管理から抜け出すための具体的な手法を紐解いていく。

プロンプトエンジニアリングからコンテキスト設計への進化

AIエージェントへの指示手法が根本から変わりつつある。

単一のファイルにルールを詰め込むアプローチは終わった。

現在のトレンドはコンテキスト設計だ。

必要な情報を必要なタイミングでAIに注入する。

背景には2つの深刻な問題がある。

1つ目はトークン消費の爆発だ。

プロジェクト全体の方針、各ディレクトリの規約、テストのルール。

これらをすべてルートのCLAUDE.mdに書くとセッション開始時に大量のコンテキストウィンドウを食いつぶす。

AIが肝心の作業に使えるメモリ容量が減る。

指示が多すぎるとAIのルール遵守率も露骨に下がる。

2つ目はコンテキストの腐敗だ。

プロジェクトが進行すると、古い意思決定と新しい仕様が矛盾し始める。

Markdownファイル内で情報が衝突する。

AIはどちらを信じるべきか迷い、推論精度が静かに、しかし確実に劣化していく。

これを防ぐため、コンテキストの提供には複数の階層が生まれている。

第1階層はファイル分割によるオンデマンド読み込みだ。

第2階層はスキル内の動的変数展開。

第3階層はフックによる行動の強制。

そして最高階層が、MCPを用いた外部DBによる時空間メモリの動的オーケストレーションだ。

静的なMarkdown管理から、動的なツールチェーンへの移行が急務になっている。

しんたろー：
うちのThreadPost開発でも、初期はCLAUDE.mdに全部盛りしてた。
気がついたらAPIのトークン消費がえぐいことになってて笑えない。

※この記事は、Claude Codeで1人SaaS開発しているしんたろーが、海外AI最新情報を開発者目線で解説する「AI活用Tips」です。

AIに「いつ・何を」渡すか。コンテキスト設計の4つの階層

コンテキスト設計は、単なるファイル整理ではない。

AIの認知負荷をコントロールするインフラ構築だ。

レベル1：オンデマンドのファイル分割

用途の異なるMarkdownファイルを適切に配置する。

ルートのCLAUDE.mdにはプロジェクト全体の方針だけを書く。

「管理者として振る舞え」といった役割定義に留める。

特定の領域固有のルールはサブディレクトリに置く。

フロントエンドの規約はフロントエンドのディレクトリ内、テストのルールはテストディレクトリに配置する。

そのファイルを操作した瞬間にだけルールが読み込まれる。

この「連鎖的な読み込み」がコンテキスト節約の鍵だ。

常に意識させたいルール、特定ファイルだけに適用するルール、必要なときだけ参照する手順。

これらを明確に切り分ける。

レベル2：スキル内の動的変数展開

SKILL.mdの本文で組み込み変数を使う。

セッションIDや現在のディレクトリパスを動的に取得する。

インラインでシェルコマンドを実行し、標準出力をプロンプトに埋め込むこともできる。

現在のGitブランチや直近のコミットログをAIに渡す。

静的なテキストではなく、実行時の「今の状態」をコンテキストとして注入する仕組みだ。

変数の展開処理は、スキルの読み込み時ではなく「呼び出し時」に走る。

だから常に最新の状態が取れる。

ただし、これらの変数はBashの環境変数ではない。

TypeScriptのランタイムが正規表現で文字列置換しているだけだ。

シェルスクリプトの中から環境変数として参照しようとしても空文字が返る。

この仕様の違いを理解していないと、スキル開発で確実につまずく。

しんたろー：
変数展開の裏側がただの文字列置換だと知ったとき、ちょっと拍子抜けした。
環境変数として子プロセスに渡せない制約があるのは地味に痛い。

レベル3：フックとプロセスによる行動強制

AIに「一貫した行動」をとらせるためのアーキテクチャだ。

AIは時として楽をしようとする。

テストをスキップしたり、自己レビューを甘くしたりする。

これを防ぐのがAIハーネスと呼ばれる仕組みだ。

ファイルの編集前後に自動で品質ゲートを実行する。

フォーマットや型チェックを人間が意識しなくても走らせる。

TypeScriptの型チェックをパスしないと次のステップに進ませない。

逆に、AIの認知バイアスを構造的に除去するアプローチもある。

セッションの冒頭で特定のスキルを強制的に読み込ませる。

「証明コマンドを実行し、出力全文を確認するまで完了と言わない」という絶対ルールを課す。

外部から動作を制御するか、自発的な動機づけを設計するか。アプローチは違えど、目的は同じだ。

レベル4：MCPによる時空間メモリの動的オーケストレーション

ここが現在の最前線だ。

コードベースの「空間」と、セッションの「時間」を分離して管理する。

空間の理解には、コードの依存関係をグラフ化するツールを使う。

関数の呼び出し元や依存関係を一発で取得する。

何千行もあるファイルを全部読ませる必要はない。

時間の記憶には、作業メモや過去の失敗を記録するローカルDBを使う。

前回のセッションで「なぜその実装を選んだのか」を保存しておく。

次に似たタスクを振られた時、AIが自らその記憶を検索して引き出す。

複数のMCPサーバーを同時起動し、必要な情報だけをAIに引き出させる。

Markdownの手動管理による「コンテキストの腐敗」を完全に回避できる。

これが、AI駆動開発の到達点だ。

静的ファイルから動的オーケストレーションへの移行

僕らの開発にどう影響するのか。

結論から言うと、プロンプトを「書く」仕事から「設計する」仕事にシフトする。

まずやるべきはファイルの分割だ。

すべてのルールをルートのCLAUDE.mdに置くのをやめる。

プロジェクトが大きくなるほど、この分割が効いてくる。

「注文一覧のAPIを追加して」と指示したとき、各ファイルがどの順番で処理されるかを想像する。

管理者がタスクを分解し、バックエンドのエージェントに委譲する。

バックエンドのディレクトリに入った瞬間、専用の規約が読み込まれる。

特定のAPIを触った瞬間に、セキュリティ規約が読み込まれる。

この流れをデザインする。

次に、スキルの動的化だ。

毎回手動でGitの差分をコピペしてAIに渡すのは非効率の極みだ。

スキル内でシェルコマンドをインライン実行する仕組みを作る。

AIが自ら最新のコンテキストを取得できるようになる。

コンテキストは「与える」ものではなく「取りに行かせる」ものに変わる。

しんたろー：
MCPでコードグラフとセッション記憶を分ける構成、めちゃくちゃ理にかなってる。
ThreadPostのコードベースも育ってきたから、そろそろMarkdown管理に限界を感じてる。

そして最終的には、MCPツールの導入を見据える。

プロジェクトの規模が大きくなると、人間の手でコンテキストを整理するのは不可能になる。

依存関係の把握や影響範囲の特定は、専用のツールに任せる。

AIには「どのツールを使って情報を集めるか」だけを指示する。

正しく設計されたメモリ層は、モデルサイズの差を埋めるほどの精度向上をもたらす。

静的なルールに縛られたAIより、動的に記憶を引き出せるAIのほうが圧倒的に賢い。

開発者は「AIの道具箱」をどう設計するか。

そこに全力を注ぐフェーズにきている。

よくある質問（FAQ）

Q1: Claude Codeでコンテキストウィンドウを節約するにはどうすればよいですか？

ルールや指示を単一のCLAUDE.mdに詰め込まず、用途に応じてファイルを分割・配置する。プロジェクト全体の方針のみをルートのCLAUDE.mdに書く。特定のファイル操作時に適用したい技術的なルールは「.claude/rules/」に置く。必要な時だけ呼び出す手順は「.claude/skills/」に配置する。これにより、Claude Codeがオンデマンドで読み込み、トークン消費を大幅に抑えられる。無駄な情報を渡さないことが最大の節約になる。

Q2: スキル（SKILL.md）の中で動的な値を使いたい場合はどう設定しますか？

スキル本文内で組み込み変数を使用できる。「CLAUDE_SESSION_ID」などを指定の書式で記述するだけで実行時に展開される。また、特定の記号を使ってインラインでシェルコマンドを実行し、その標準出力をプロンプトに動的に埋め込むことも可能だ。これにより、実行時の最新のGitブランチやコミットログなどをAIにコンテキストとして渡すことができる。ただしこれらはBashの環境変数ではなく、正規表現による文字列置換で処理されている点には注意が必要だ。

Q3: Markdownファイルでルールを管理し続けるとどのような問題が起きますか？

プロジェクトが進行するにつれて、古い意思決定と新しい仕様がMarkdownファイル内で矛盾し始める。これが「コンテキストの腐敗」だ。AIがどちらを信じるべきか迷い、推論精度が明確に劣化する。長期的にはMCPツールを導入し、コードの依存関係やセッション記憶を動的かつ構造的に管理するアプローチへの移行が求められる。静的なテキスト管理には必ず限界が来る。

振り返り

AIへの指示は、静的なプロンプトから動的なコンテキスト設計へと完全にシフトした。

トークンを節約し精度を保つには、適切なインフラ構築が欠かせない。

👉 ThreadPostでSNS運用を自動化する