dev-context-engineering

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

このスキルは、移植性が高く、シグナル密度に優れ、保守しやすい、リポジトリに適したエージェントコンテキストを設計するために使用します。AGENTS.md、ランタイム固有のレイヤー、仕様、ルール、フック、コンパイル済み Markdown ナレッジベース、関連アーティファクト全体にわたるコンテキストモデル、移行パス、成熟度評価、コンテキストグラフの運用指針を扱います。

クイックリファレンス

タスク	使用するもの
移植可能なリポジトリ指示	agents-memory スキル、references/fast-track-guide.md
仕様と計画のフロー	docs-ai-prd、dev-workflow-planning
コンテキストグラフの設計	references/context-graph-guide.md、python3 scripts/scan_context_artifacts.py --help、python3 scripts/validate_context_graph.py --help
ホットティアの陳腐化と置き換えの整合性チェック	scripts/validate_context_graph.py（check_stale_tiers、check_supersession_integrity をチェックします）
コンテキストグラフのクエリ（PPR、BFS、ファンイン、ティア予算）	python3 scripts/query_context_graph.py <graph> --help（モード：--node、--impact、--rank、--ppr --seed、--tier-budget）
コンパイル済み Markdown ナレッジレイヤー	docs-notes-retrieval スキル、references/context-graph-guide.md、references/multi-repo-strategy.md
マルチリポジトリ戦略	references/multi-repo-strategy.md、dev-context-multi-repo
フレームワークの選択（superpowers、GSD、Spec Kit、OpenSpec など）	references/framework-selection-matrix.md
規制対象環境への導入	references/regulated-environment-patterns.md、assets/ai-agent-governance.md、assets/compliance-fca-emi.md

使用する場面

• AGENTS.md、CLAUDE.md、Copilot の指示、フック、エージェントルールレイヤーを設定または最新化するとき。
• 場当たり的なプロンプトから、永続的なエージェントコンテキストへリポジトリを移行するとき。
• 常時有効なコンテキストと、ドキュメント、検索、オンデマンドのアーティファクトのどれに含めるか判断するとき。
• リポジトリ向けのコンテキストグラフと読み込みティアのモデルを構築するとき。
• 1 つのリポジトリまたはポートフォリオ全体で、AI 支援開発の成熟度向上の道筋を定めるとき。
• エージェントが構造化アーティファクトからリポジトリの説明、インデックス、レポートを作成・更新する、大規模なコンパイル済みリポジトリナレッジベースの運用モデルを設計するとき。

他のスキルを使う場面

• 移植可能なリポジトリ指示そのものを書く場合：agents-memory スキルを使用します。
• リポジトリポートフォリオの調査とハブの生成： dev-context-multi-repo を使用します。
• シンボルレベルのコードグラフと影響範囲： dev-context-code-graph を使用します。
• タスクの分解と検証計画： dev-workflow-planning を使用します。
• フック、MCP、またはサブエージェントの実装詳細： agents-hooks、agents-mcp、または agents-subagents を使用します。

デフォルト

• AGENTS.md をポータブルなベースラインとして維持します。
• 実際の機能を実現できる場合にのみ、ランタイム固有のレイヤーを追加します。
• 常時読み込むコンテキストには、推測できない制約だけを記載します。
• 巨大なマニフェストを1つ用意するのではなく、小さなホット指示レイヤーと、より大きなコンパイル済み Markdown ナレッジベースを使います。
• テキストを増やすより、状態と構造を改善します。
• コールドなナレッジレイヤーと派生ノートの維持は LLM に任せ、ポリシー、安全性、アーキテクチャ上の制約は人間がレビューします。
• チャット履歴だけに残すのではなく、リポジトリのコンテキストに戻せる永続的なファイルとして出力します。
• 新しい Markdown を作成する前にドキュメント配置のゲートを実行します。単発のファイルを追加するより、正規のドキュメントや生成済みコンテキストアーティファクトの更新を優先します。
• コンテキストの変更もコード変更と同様に扱い、レビュー、検証、整理を行います。
• リポジトリが構造化コンテキストの成熟段階に達したら、context-graph.json を生成します。
• ツールセットの最小化：エージェントには実際に必要なツールだけを与えます。人間のエンジニアが特定のタスクにどのツールを使うべきか言えないなら、AI エージェントがより適切に判断できることはありません。まずは小さく始め、必要に応じて拡張します。
• 積み増しよりリゾルバー：新たなエッジケースに対応するためにホットレイヤーが肥大化し始めたら、説明に基づいてスキルを選択し、必要に応じて適切なドキュメントを読み込むポインタ型リゾルバーを優先します。references/context-resolver-pattern.md を参照してください。

2026年5月の検証方針

現在のコンテキストエンジニアリングでは、コンテキストを巨大なプロンプトではなく、進化するシステムとして扱う必要があります。ソースに裏付けられた最も確かな原則は次のとおりです。

• コンテキストは有限の作業メモリーです。結果に影響するシグナルの強いトークンを最小限に抑え、必要なときに深い根拠を読み込みます。
• コンテキストへの適応は、第一級のエンジニアリングループです。反復的な要約によって詳細が失われないようにしながら、更新の生成、振り返り、精選、検証を行います。
• 生の証拠は引き続き取得できる状態に保つ必要があります。要約、メモリー、グラフノードはルーティングレイヤーであり、ソースファイル、トランスクリプト、アーティファクト、一次資料のドキュメントの代わりにはなりません。
• メモリーにはライフサイクルのセマンティクスが必要です。出所、新しさ、置き換え、矛盾への対処、ユーザーまたはテナントのスコープを管理します。時間的な推論、関係性の変化、セッションをまたぐ継続性が重要な場合にのみ、時間的グラフメモリーを使用します。
• グラフ検索を常に使う必要はありません。単純な検索には直接読み込みや字句検索を使い、関係性に関する質問、複数ホップの質問、全体的な把握を求める質問には、グラフ走査、PPR、コミュニティ要約を使います。
• ツールとコンテキストの領域は最小限に保ち、適切に管理する必要があります。選択基準が明確でなければ、ツールや常時適用ルールを増やすほど曖昧さが増します。

複数ツールの組み合わせ

最も速くリリースするチームは、1つのエージェントにすべてを任せるのではなく、各タスクに適したツールを使います。2026年5月現在、最も効果的なパターンは次のとおりです。

ツール	最適な用途	コンテキストモデル
Cursor / IDE agent	日常的な編集、インライン補完、Tabキーでの確定、手早いリファクタリング	IDE ネイティブ：開いているファイル＋プロジェクトインデックス
Claude Code	複雑なエージェントタスク、複数ファイルの変更、エージェントチーム、コードレビュー、アーキテクチャ	CLI：AGENTS.md + .claude/rules + skills + subagents
Codex	並列バックグラウンド作業、バッチ処理、CI に関連するタスク	スレッド：AGENTS.md + .codex/agents + サンドボックス化されたワーカー

ツール間でコンテキストの一貫性を保つ方法：

1. AGENTS.md は移植可能なベースラインです。3つのツールすべてがこれを読み込みます。
2. ランタイム固有のレイヤー（.claude/rules/、.codex/agents/、.cursor/rules/）で、各ツールの強みに合わせてベースラインを拡張します。
3. リポジトリ内の docs/ は、どのツールからも読み取れます。ツール固有のメモリではなく、ここに知識を蓄積してください。
4. dev-context-multi-repo を使い、ツール間で複数リポジトリのコンテキストを同期させます。

アンチパターン：Cursor のルール、Claude のルール、Codex エージェントで規約を重複させることです。AGENTS.md または docs/ に一度だけ記述し、そこを参照してください。

規律のばらつきや機能の曖昧さがボトルネックになっている場合は、IDE レイヤーの上に積み重ねてください。

レイヤー	役割	選択肢
L0 移植可能なベースライン	ツール間で共通の規約	AGENTS.md
L1 ランタイム固有	ツール固有の拡張	.claude/rules/、.codex/agents/、.cursor/rules/、.github/copilot-instructions.md、.clinerules/、Aider CONVENTIONS.md
L2 機能／方法論	必要に応じて適用、または強制する規律	Claude Code Skills · superpowers (obra/superpowers) · GSD (gsd-build/get-shit-done)
L3 成果物パイプライン	仕様 → 計画 → タスク → コード	GitHub Spec Kit (.specify/specs/) · OpenSpec (Fission-AI, openspec/changes/)

L0 は必須です。AGENTS.md を標準で読み込まないツールでは L1 も必須です。L2 と L3 は任意ですが、該当する兆候が見られる場合には大きな効果があります。完全な判断マトリックス、スタックのレシピ、避けるべきスタックについては、references/framework-selection-matrix.md を参照してください。

ワークフロー

1. ツールチェーン、リポジトリの構造、影響を与える必要のある動作を特定します。
2. 移植可能なベースライン、コンパイル済み知識レイヤー、必要最小限のランタイム固有レイヤーを定義します。
3. 頻繁に使う指示、コンパイル済みの知識、エージェントが必要に応じて調査できる生の証拠を分けます。
4. コンパイル済みレイヤーをたどりやすくする仕様、計画、フック、ルール、サブエージェント、ドキュメント、インデックスページなど、適切な補助成果物を導入します。
5. 使い捨てのチャット出力ではなく、永続的な Markdown ファイル、図、レポートにすべき回答や分析を決め、リポジトリのドキュメントガバナンスモデルに従って配置します。
6. リポジトリに十分な成果物があり、コンテキストグラフを作る価値がある場合は、生成して検証します。
7. コンテキストシステムのヘルスチェックを実行し、古くなった依存関係、欠落した要約、矛盾する記述、リンク切れがないか確認します。
8. 成熟度を評価し、次のステップをオンボーディング、整理、または自動化のいずれにするか決めます。

ASCII フロー

context engineering request
  -> identify toolchain, repo shape, and target agent behaviors
  -> define portable baseline in AGENTS.md
  -> split layers
     +-- hot -> non-inferable execution policy
     +-- warm -> compiled docs, hubs, indexes, context graph
     +-- cold -> raw evidence and primary artifacts
  -> add runtime-specific rules only where they unlock capability
  -> run docs placement and context hygiene gates
  -> validate graph, freshness, links, and contradictions
  -> decide onboarding, pruning, automation, or maturity next step

主な判断事項

ツール横断コンテキストモデル

レイヤーを意図的に使い分けます。

• AGENTS.md には、頻繁に参照する共通の実行ポリシーを記載します
• CLAUDE.md と .claude/* は Claude 固有の動作にのみ使用します
• .github/* は GitHub または Copilot 固有の動作にのみ使用します
• コンパイル済みの Markdown ハブ、インデックスページ、コンテキストグラフには、再利用可能なリポジトリ知識をまとめます
• 生のエビデンスパックには、記事、リポジトリ、トランスクリプト、スクリーンショットなどのソース記録を保管します
• ドキュメントや仕様書は、必要に応じて参照するコンテキストとして扱います
• 外部知識は、スキル、MCP、または実行時の情報取得を通じて利用します

あるツールのメモリモデルが別のツールにもそのまま適用できるとは限りません。

コーパスの規模が小～中程度であれば、メンテナンスされたインデックスと簡潔な要約で十分なことがよくあります。ナレッジベースがあるというだけで、RAG を追加しないでください。

コンテキストに含める情報

常時参照するコンテキストには、次の情報を含めます。

• カスタムコマンドとリポジトリのワークフロー
• 安全性やコンプライアンス上の制約
• 変更に注意が必要なアーキテクチャ上の境界
• 既知の失敗パターンと承認ルール
• ローカルでの推測が難しい、リポジトリ間のデータフロー

コンパイル済みナレッジベースには、次の情報を含めます。

• ドメインの要約と概念ページ
• リポジトリ間のマップとアーキテクチャの俯瞰図
• 再確認が必要だが、保存する価値のある、変化しやすいツールや製品に関する調査結果
• 時間とともに蓄積するレポート、図表、スライド用メモなどの派生成果物

次のものは含めないでください。

• README のような要約
• 大規模なファイル一覧
• エージェントが自分で確認できる依存関係の一覧
• 重複するコーディングスタイルの理念
• 実行上の制約を追加しないドキュメント
• 頻繁に参照する指示レイヤーではなく、エビデンスフォルダーに置くべき生のソースダンプ

ドキュメント配置の判断基準

コンテキスト用の成果物を作成する前に、永続性を確保できる範囲で最も小さな保存先を選びます。

• 頻繁に参照する指示：短い実行ポリシーと参照先のみを記載する AGENTS.md / CLAUDE.md
• 正式なドキュメント：安定した正確な情報を記載する docs/tech/、docs/architecture/、docs/api/、または同等の場所
• 運用ドキュメント：手順やインシデント／リリースの対応手順を記載する docs/operations/ または docs/runbooks/
• レポートと計画：ライフサイクルの状態と統合先を明記する docs/reports/、docs/specs/、または docs/plans/
• 生成されるコンテキスト：構造化された入力と再構築コマンドを含む docs/context/ または context/
• 生のエビデンス：頻繁に参照するコンテキストから除外する raw/、evidence/、またはリポジトリ固有の記録

成果物に管理者、ライフサイクル、インデックスからのリンク、または再構築手順がない場合、新しい Markdown ファイルは作成しないでください。最も近い正式なドキュメントを更新するか、結果をタスクのスレッドに残してください。

ナレッジベースのパターン

最も強力な標準形は、リポジトリに根ざした次の3層システムです。

• 頻繁に参照するレイヤー：移植可能な指示と実行ポリシー
• コンパイル済みレイヤー：要約、バックリンク、概念ページ、インデックスファイルを含む、LLM がメンテナンスする Markdown
• 生データレイヤー：コンパイル済みの情報を再検証する必要があるときにエージェントが参照できる、ソース記録とエビデンス

人間は主に頻繁に参照するレイヤーを編集し、コンパイル済みレイヤーをレビューします。検証とレビューのゲートを設ければ、コンパイル済みレイヤーと生データレイヤーの大部分はエージェントが管理できます。

ポートフォリオハブには、さらに次の実践的なルールを追加します。

• プロファイル JSON、グラフ JSON、鮮度レポートなどの構造化された成果物は、独立して乖離するサイドカーではなく、Markdown ページを生成するコンパイラーへの入力として扱います

これにより、リポジトリの説明、概念メモ、システムマップを大規模にわたって同期できます。

コンテキストグラフ

コンテキストグラフを使って、次の要素間の関係をマッピングします。

• 指示
• ルール
• 仕様
• 計画
• フック
• サブエージェント
• 参照資料とアセット

リポジトリが L2 以上の成熟度に達したらコンテキストグラフを生成し、コア成果物を変更する前に、読み込みティア、影響範囲、古くなった依存関係の評価に使用します。

コンテキストグラフは、コンパイル済み Markdown レイヤーを補完します。関係の整合性と読み込みティアの分析にはグラフを使い、有用な知見を Markdown のノートやレポートに反映します。

リポジトリがネイティブ／モバイルのコードベースである場合は、このスキルを次と組み合わせます。

• project.yml、.xcodeproj、Package.swift などのプロジェクトファイルからリポジトリを正しく分類するには、dev-context-multi-repoを使用します
• 生成されたビルドツリーを除外した後、Swift または複数言語のソースから単一リポジトリのシンボルグラフを構築するには、dev-context-code-graphを使用します

仕様駆動開発

曖昧さによってエージェントの動作が逸れる可能性がある場合は、完全な仕様駆動開発を行います。

• 何を作るかを仕様化する
• どのように作るかを計画する
• 範囲を限定したタスクに分解する
• 適切なコンテキストを添えて実装する

小規模な修正や曖昧さの少ない作業には、直接プロンプトを使用します。

ハブを定期的に保守する場合は、ページ生成をコンパイラのパスとして扱います。

• ソース成果物を定義する
• 生成するページの形式を定義する
• 増分的に再生成する対象を定義する
• 公開をブロックするリントや健全性チェックを定義する

規制対象環境

規制対象環境では、コンテキストエンジニアリングに次の要件を維持させる必要があります。

• 監査可能性
• 職務分掌
• 機密データの境界
• プロバイダーのポータビリティ
• 責任を負う人間の明示

これらが実際の要件である場合は、コンテキスト成果物を単なる補助ドキュメントではなく、統制の一部として扱います。

出力モード

次のいずれかをデフォルトとして使用します。

• リポジトリコンテキストパッケージ： ポータブルなベースライン、ランタイム固有のレイヤー、サポートする成果物のマップ。
• ナレッジベース運用モデル： ホットな指示、コンパイル済み Markdown レイヤー、生のエビデンスの配置、メンテナンスループ。
• ハブコンパイラの設計： ソース成果物、生成されるページの種類、増分再ビルド戦略、検証ゲート。
• 移行計画： 現状の問題、目標とする構成、段階的な展開、検証手順。
• 成熟度評価： 現在のレベル、阻害要因、次に必要なインフラストラクチャの手順。
• 規制対象環境への展開概要： 統制要件、成果物の配置、レビューゲート。

よくある落とし穴

• 常時有効な指示にポリシー、プロセス、リポジトリの知識を詰め込みすぎて、エージェントが本当に重要なレイヤーを無視したり切り詰めたりする。
• ポータブルなベースラインが安定する前にランタイム固有のルールスタックを構築し、ツール間のずれを確実に招く。
• コンパイル済み Markdown ハブを、鮮度維持と検証のループを持つ保守対象のプロダクトではなく、静的なドキュメントとして扱う。
• 明確な読み込みティアのモデルなしに大規模なコンテキスト変更をリリースし、ホットな指示とコールドなエビデンスを混在させる。
• ツールが多ければ自動的に役立つと思い込み、チームが実際に管理できる最小限の構成までツールセットを絞り込まない。
• 有用な回答を得るたびに新しい Markdown ファイルを作成し、既存のドキュメント、レポート、生成コンテキストのライフサイクルに適切に組み込まない。
• 運用ランブック、エージェントのホットメモリ、正規ドキュメント、生成コンテキストを混在させ、どのファイルにも明確な権威がなくなる。
• 検索する前に、生のエビデンスを LLM で要約する。実測された失敗例：LongMemEval では、原文そのままの検索が R@5 で 96.6% を記録する一方、ConvoMem では LLM 抽出メモリシステムが 30〜45% にとどまります。先回りした要約は、回答を見つけやすくしていたコンテキストを捨ててしまいます。生のレイヤーは生のまま維持してください。(ソース benchmarks/BENCHMARKS.md)

アンチパターン

• 巨大なコンテキストファイルを1つだけ用意する。
• AGENTS.md を、即時に使う指示レイヤーではなく、汎用ナレッジベースとして使う。
• ドキュメントから、整理せずにコンテキストを生成する。
• 状態や構造を修正する代わりに、テキストを増やす。
• ポリシーを単一ベンダーの形式に固定する。
• コンテキストを、継続的に管理するシステムではなく、静的なものとして扱う。
• 実行に不可欠なガイダンスをリポジトリの外に置く。
• 役立つ回答をチャット内で埋もれさせ、コンパイル済みレイヤーに反映しない。
• 役立つ回答を、所有者、ライフサイクルの状態、正式な親ドキュメントのない、インデックス未登録の単発の Markdown ファイルとして保存する。
• インデックス、要約、基本的な健全性チェックを維持する前に、重厚な検索インフラストラクチャを追加する。
• JSON、グラフ、Markdown ページをコンパイラーパイプラインではなく、別個の真実の情報源として扱う。

ナビゲーション

• 基本リファレンス：references/fast-track-guide.md、references/framework-selection-matrix.md、references/information-routing-rules.md、references/context-resolver-pattern.md
• コンテキストグラフとマルチリポジトリ戦略：references/context-graph-guide.md、references/multi-repo-strategy.md
• 規制対象環境とガバナンスに基づくロールアウト：references/regulated-environment-patterns.md、assets/ai-agent-governance.md、assets/data-handling-gdpr-pci.md、assets/compliance-fca-emi.md、assets/pr-template-ai-disclosure.md、assets/fca-compliance-gate.yml
• スクリプトとスキーマ：scripts/scan_context_artifacts.py、scripts/validate_context_graph.py、scripts/query_context_graph.py、schemas/context-graph.schema.json
• 関連スキル：agents-memory スキル、docs-ai-prd、dev-workflow-planning、agents-hooks、agents-mcp、agents-subagents、agents-swarm-orchestration、dev-context-multi-repo、dev-context-code-graph

ファクトチェック

• 既知のバグ、リグレッション、フレームワーク／コンパイラー／ランタイムに関する落とし穴、バージョン固有のクラッシュや回避策のガイダンスは、現時点で有効な事実として扱う前に、最新の一次ウェブソースで検証する必要があります。
• 外部ソースのマッピングは data/sources.json にあります。
• 製品の機能、ランタイムのセマンティクス、規制当局のガイダンスは変わりやすいため、ツールやコンプライアンスのスケジュールについて断定する前に、最新の一次ソースで検証してください。
• 一次ソースで再検証できない主張は削除するか、その旨を明記してください。