msd-core/docs/ja-JP/explanation/context-engineering.md

コンテキストエンジニアリング

GSD Core が存在する理由、そして解決しようとしている問題。

---

問題：コンテキスト腐敗

AI コーディングセッションは常に新鮮な状態から始まります。モデルは質問を読み取り、それについて推論し、返答します。しかしセッションが一度のやり取りで終わることはほとんどありません。追加の質問をし、エラーメッセージを貼り付け、コードを繰り返し修正し、モデルが脱線したときに軌道修正します。ターンを重ねるたびに、モデルが一度に「見える」有限のテキストバッファであるコンテキストウィンドウにトークンが積み重なっていきます。

そのウィンドウが満たされると、微妙なことが起きます。モデルは明らかには失敗しません。答え続けます。しかしその品質は静かに低下していきます。最初の指示はモデルが注意を向けられる範囲の端へと追いやられます。最初のやり取りで確立したニュアンス——述べた制約、合意したアーキテクチャ、指摘したエッジケース——が後から積み重なったすべてのものと注意を奪い合います。研究者たちはこれを コンテキスト腐敗 と呼びます。

コンテキスト腐敗はいくつかの形で現れます：

• モデルが以前に認めた決定と矛盾し始める。
• セッション開始時に確立したコーディングスタイルの規約からコードが外れていく。
• 計画が、明確に述べられていたが履歴の奥深くに埋もれた要件を無視し始める。
• モデルが 20 メッセージ前に正確に把握していたファイル名や関数シグネチャを誤って出力する。

これはモデルのバグではありません。トランスフォーマーアテンションが長いシーケンスに対してどう機能するかという根本的な性質です。モデルは「忘れて」いるわけではありません——人間的な意味での「記憶」は最初からありません。有限のウィンドウ全体で関連性を重み付けしており、そのウィンドウに蓄積されたノイズが増えるにつれて、シグナル対ノイズ比が低下するのです。

単純な対応策は /clear してやり直すことです。しかしそれでは連続性が失われます。コンテキストを再説明し、関連ファイルを再貼り付けし、制約を再度述べなければなりません。セッションは実質的にゼロにリセットされます。

---

GSD Core の答え：フレッシュコンテキストサブエージェント

GSD Core の核心的な洞察は、コーディングセッションの作業の ほとんど はメインコンテキストで行う必要がそもそもないということです。調査、計画立案、コード作成、検証はそれぞれ独立した、境界が明確なタスクです。それぞれを専門化されたサブエージェントに渡すことができます。そのエージェントはクリーンで慎重にスコープされたコンテキストウィンドウで開始し、結果をスリムなオーケストレーターに報告します。

これはコンテキスト腐敗への迂回策ではありません。構造的な解決策です。

オーケストレーター——あなたのメインセッション——はソースファイルに触れません。エージェントを生成し、その結果を収集し、共有状態を更新し、次のステップへとルーティングします。自身がほとんど何もしないため、そのコンテキストウィンドウはゆっくりと予測可能に拡大します。重い作業はそれぞれ新鮮な状態で開始し、タスクに必要なコンテキストだけを受け取り、完了したら終了するエージェントの中で行われます。

これが実際にどういう意味かを考えてみましょう。/gsd-plan-phase を実行すると、オーケストレーターは：

1. コンパクトな JSON コンテキストペイロード（プロジェクト概要、フェーズ目標、関連設定）を読み込む。
2. 200k トークンのクリーンなウィンドウで調査エージェントを生成する。
3. 調査出力とフェーズ要件でプランナーエージェントを生成する。
4. 実行前に計画を検証するプランチェッカーエージェントを生成する。

各エージェントはセッション履歴の蓄積に邪魔されることなく、最大限の能力で動作します。プランナーが PLAN.md ファイルを .planning/phases/ に書き込むと、その出力は永続的なアーティファクト——共有コンテキストウィンドウの中の脆弱な記憶ではなく——になります。

---

仕様駆動開発とメタプロンプティング

コンテキストエンジニアリング単体では不十分です。エージェントが新鮮な状態で開始しても、曖昧な指示を受け取れば、曖昧な出力を生み出します。GSD Core はフレッシュコンテキストサブエージェントと 2 つの補完的な規律を組み合わせています。

仕様駆動開発 とは、すべてのフェーズが実行開始前に構造化されたアーティファクトを生成することを意味します。CONTEXT.md は Discuss ステップでの実装上の決定を記録します。RESEARCH.md は調査エージェントが見つけたものを記録します。PLAN.md は作業を独立した、依存関係の順序に従ったタスクに分解し、明確な受け入れ基準を持ちます。エグゼキューターエージェントがファイルに触れる時点では、長い会話の再解釈ではなく、正確な仕様から作業します。

メタプロンプティング とは、エージェント定義自体が慎重に設計されたプロンプトであり、アドホックな指示ではないことを意味します。gsd-core/workflows/ および agents/ 内のファイルは、タスクのスコープの決め方、何を検証するか、いつ人間のチェックポイントにエスカレートするかについての実践的な知識をエンコードしています。ユーザーはこの知識をセッションごとに再説明する必要はありません。それはシステム自身のプロンプトに組み込まれています。

この組み合わせは意図的です。フレッシュコンテキストは各エージェントが明確に推論することを保証します。仕様駆動のアーティファクトは各エージェントが 正しい ことについて推論することを保証します。メタプロンプティングは各エージェントが うまく 推論する方法を知っていることを保証します。

---

.planning/ の役割

コンテキストエンジニアリングには、知識がコンテキストリセットを超えて生き残ることが必要です。GSD Core はこのためにファイルシステムを使用します。すべての意味のある出力は、人間が読める Markdown または JSON として .planning/ に書き込まれます。これが意味することは：

• セッションを再起動しても（またはモデルがクラッシュしても）作業が失われない。
• 後続のエージェントは共有された会話履歴に依存せず、以前のアーティファクトを直接読み取ることができる。
• 計画アーティファクトを検査、編集、または git にコミットできる——それらはプレーンテキストであり、データベース内の不透明な状態ではない。

STATE.md はこのシステムの背骨です。プロジェクトの現在位置（どのマイルストーン、どのフェーズ、どの計画が完了しているか）、アクティブな決定とブロッカー、進捗メトリクスを記録します。ワークフローが開始されると、まず STATE.md を読み取って方向を確認します。ワークフローが意味のあるステップを完了すると、STATE.md に書き戻します。エージェントは記憶に頼りません。ファイルに頼ります。

---

トレードオフ

ここではトレードオフについて正直に述べることが重要です。

オーバーヘッド。 フェーズループには実際の摩擦があります。/gsd-discuss-phase、/gsd-plan-phase、/gsd-execute-phase を別々のステップとして実行することは、普通のセッションに「この機能を書いて」と入力するよりも多くの経過時間がかかります。小さくてよく理解された変更に対しては、そのオーバーヘッドは正当化されません。

レイテンシ。 新鮮なコンテキストで複数のサブエージェントを生成することは、単一のインコンテキスト編集より遅くなります。調査、計画立案、実行のそれぞれにラウンドトリップのコストが発生します。

シンプルなタスクへの過剰な手続き。 変数名を変更したり、タイポを修正したり、欠落しているインポートを追加したりする場合、フェーズループは過剰です。GSD Core は完全なフェーズを必要としないアドホックな作業のために /gsd-quick と /gsd-fast を提供します。クイックタスクとファストタスクの処理 を参照してください。

フェーズループは、コンテキスト腐敗が本当のリスクになるほど作業が複雑な場合——マルチファイル機能、横断的なリファクタリング、時間やセッションをまたぐ作業——に価値を発揮します。それ以外のすべてには、より軽量なプリミティブを使ってください。

経験則として役立つのは：タスクが単一の短いプロンプトで完全に仕様化でき、さらなる明確化なしに 1 エージェントターンで完了できるなら、フェーズループをスキップしてください。タスクが調査を必要とし、最近読んでいないファイルを含むか、まだ確定していない決定に依存している場合は、フェーズループが保護してくれます。

---

Related

• フェーズループ — Discuss → Plan → Execute → Verify → Ship サイクルがコンテキストエンジニアリングをどう実践するか
• マルチエージェントオーケストレーション — サブエージェントがどのように生成、スコープ設定、調整されるか
• アーキテクチャ — システムアーキテクチャ、エージェントモデル、データフロー
• ドキュメント索引