context-consultant

Hex コンテキストコンサルタント

Hex のエージェントが信頼できる回答を返せるよう、コンテキストを構築、管理、改善します。重要なのは、エージェントの性能は与えるコンテキスト次第であり、コンテキストは積み重なっていくということです。用途を一つに絞り、改善を繰り返しましょう。初日から完璧を目指す必要はありません。

このスキルはディスパッチャーです。最初に一度だけ環境を確認し（以下を参照）、あとはタスクに必要なワークフローだけに進みます。毎回すべてを実行する必要はありません。

---

最初に一度だけ環境を確認する — 環境を検出し、何度も聞き直さない

ユーザーにセットアップについて説明してもらうのは一度だけです。多くは検出でき、残りは記憶されるため、再び利用するユーザーはすぐにタスクに取りかかれます。

1. 検出する（質問はせず、確認するだけ）：

hex connection list                    # data connections + IDs
hex context semantic-project list      # semantic projects + IDs (and whether repo-synced or Hex-authored)
hex suggestion list                    # is there real usage signal yet?

リポジトリがある場合は hex_context.config.json も読み込みます。このファイルには、リポジトリで管理されているガイドやセマンティックプロジェクト、およびその場所が記載されています。また、既存の評価スイート（evals/*.yaml）も探します。

2. プロファイルがあれば読み込む。 リポジトリのルート（またはユーザーのプロジェクトメモ）にある hex_context.profile.md を確認します。存在する場合はそれを使い、セットアップに関する質問はすべて省略します。

3. それでも判断できないことだけを、ウィザード形式ではなく、簡潔に一度だけ尋ねます。対象の用途／求める精度と、（曖昧な場合は）希望する公開方法を確認します。その後、二度と尋ねなくて済むよう、一度だけ記録します。

# hex_context.profile.md  — tell-it-once setup
- Workspace / connection: <name> (<connection_id>)
- Semantic project(s): <name> (<id>) — repo-synced | Hex-authored
- Guides + workspace context: <repo url, synced via Action> | Hex UI | mix
- Publish path: GitHub PR (versioned assets) | hex context publish | Hex UI
- Focus use case(s): <e.g. ecommerce orders & returns>
- Eval suite: <evals/…​.yaml>

6 行程度にまとめます。毎回再検出するコストは低く、情報も新鮮に保てます。プロファイルには、検出できない情報（好み、Hex 専用アセットの場所、重点を置く用途）だけを記録します。

コンテキストを配置できる場所 — アセットごとに振り分け、固定しない： ガイド、ワークスペースコンテキスト（hex.md）、セマンティックモデルは、それぞれ Git リポジトリ（Action で同期）、Hex UI での作成、またはその組み合わせで管理できます。エンドースメントとウェアハウスの説明は、常に Hex で操作します。この振り分けによって、各アセットの編集方法と公開方法が決まります（ワークフローを参照）。公開方法は 2 つあります。GitHub（バージョン管理やレビューを行うものに推奨）と Hex CLI（hex context preview → hex context publish を実行。より高速で、リポジトリがなくても利用でき、PR レビューを介しません）です。詳しい仕組みについては references/github-sync.md を参照してください。

---

タスクを選ぶ

該当するファイルに進みます。他のファイルは読み込まないでください。

ユーザーの希望	参照先
コンテキストをゼロから構築する（0 → 1）	workflows/bootstrap.md
実運用中のコンテキストを改善する — 提案、失敗した評価、誤った回答	workflows/improve-loop.md
評価を作成、実行、保守する（テストケースと評価基準の作成、既存スイートの変換）	agents/eval-engineer.md
評価／プレビューの仕組み — 実行、結果の確認、プレビューのフォーク	references/evals-and-preview-loop.md
特定の誤回答を診断する／アセットを一つ適切に作成する	agents/context-architect.md
リポジトリから Hex への同期／公開を設定または理解する	references/github-sync.md
コードリポジトリや MCP ツールに対応範囲を広げる（Team／Enterprise）	references/advanced-context.md

すべてのワークフローで、以下の考え方と原則を共有しています。

---

メンタルモデル — 4つのコンテキスト資産

Hex のエージェントは、4種類のコンテキストを参照します。それぞれに役割があり、ゆるやかな ガイダンスから厳格なガバナンスまでの幅があります。それぞれの役割に集中させることが、コンテキストエンジニアリングです。

1. 承認済み・除外済みステータス — ウェアハウスのガードレールです。 テーブル／スキーマ／モデルに「承認済み」または 「AI から除外」とマークします。これは最も迅速で、最も効果の高いアクションです。承認済みの選択肢を設定します。セルフサービスには 承認モード（設定 → AI とエージェント）を組み合わせます。
2. ウェアハウスの説明 — 基礎となる情報です。 カラム／テーブルに何が含まれているかを示します。基本的な衛生管理です。
3. ワークスペースのコンテキストとガイド — ビジネスについて教えます。 hex.md は常に有効なファイルで、全体に共通する事実を記載します。 ガイドは検索して参照するライブラリで、ドメインごとに1つ作成します。どちらもデータの使用方法と使用タイミングを扱います。
4. セマンティックモデル — 厳格なルールです。 結合、指標、ディメンションを YAML で定義します。毎回正確でなければならない指標に使います。

振り分けルール（コンテキストの配置先）：

• テーブルを承認する → Hex で承認します。不適切なテーブルを禁止する → AI から除外します（hex.md にテキストで禁止事項を書かないでください）。
• カラムに何が含まれているか → ウェアハウスの説明。結合ロジック → セマンティックモデル（それ以外は説明）。
• あらゆる質問に適用される → hex.md。特定のドメイン／質問タイプに適用される → ガイド。
• 指標の計算式 → ガイドまたはセマンティックモデル（常時有効なコンテキストには記載しません）。

バージョン管理できるもの： hex.md、ガイド、セマンティックモデルです。リポジトリ経由、または Hex で作成できます（振り分けの関門）。承認と説明は常に Hex で行う操作であり、リポジトリとは同期されません。

上級者向け（Team／Enterprise、後期段階）： リファレンスリポジトリ（コード）と External Apps／MCP を使って4つの資産を拡張できます。同じ方法で、明確な説明によって管理します。references/advanced-context.md を参照してください。

優先順位付け（最初の30分）： 主要なテーブルを承認し、不要なテーブルを除外する → 最もよくクエリされるカラムを説明する → 5～10個のルールを含むワークスペースガイドを作る → 主要な指標をセマンティックモデルで定義する。実際のユースケースに範囲を絞り、すべてを一度に解決しようとしないでください。

---

あらゆる出力に適用する作業原則

• 禁止事項より、肯定的なガイダンスを優先します。 「必ず customer_id で結合する」＞「間違ったキーを使わない」。
• 1つのユースケースに範囲を絞ります＝具体的な質問が3～5個あるテーマです。作業の効果を測定しやすくなります。
• 説明するより、実際に示します。 ファイル／資産の説明ではなく、実物を作成します。
• 2つのエージェント、2つの担当領域です。 リポジトリ、設定、CLI、PR のフローといった配線は担当できますが、ウェアハウスは確認できません。実際のテーブル／カラムを参照するコンテンツは、Hex エージェント（Threads／Notebook）が確認できます。まず Hex エージェントにドラフトを作成させ、それをこちらに戻してください。確認できない名前を決して作り出さないでください。
• CLI は自分で実行します。 hex thread get ／ hex eval get を自分でポーリングし、ユーザーにコマンドを渡さないでください。
• 変更の前後を測定します。 評価（または最低限プレビューのスレッド）で改善とデグレードがないことを確認するまで、変更は完了ではありません。
• 質問ごとに精度の基準を定めます。 「十分に良い」回答でよいものもあれば、完全に正確でなければならないものもあります。

参照ファイル

• workflows/bootstrap.md — 0 から 1 へ。 ユースケースの範囲を定め、承認または除外し、コンテキストを整え、最初のガイドとワークスペースコンテキストを作成して、プレビュー、公開し、ベースライン評価を確立します。
• workflows/improve-loop.md — 継続的な改善ループ。 シグナル（提案と評価）→ 下書き → プレビュー → 評価ゲート → 公開 → 完了処理。各変更は、アセットの保存場所に応じて振り分けます。
• agents/eval-engineer.md — 測定エンジン。 評価ケースとルーブリックの作成（ベースラインと段階的改善のライフサイクル、ルーブリック作成の技法、実際の利用状況からの情報源、既存スイートの変換）、スイートの実行、表ではなく判定結果の返却を行います。
• references/evals-and-preview-loop.md — 評価／プレビューの仕組み：実行、結果を誠実に読み取る（エラー発生 ≠ エージェントの失敗）、hex context preview をフォークする（hex eval run --preview-id）、公開する。注意：古い hex guide preview ではなく、hex context preview を使用します。
• agents/context-architect.md — 作成と診断のエンジン：4 つのアセットを作成／編集し、特定の誤回答を修正します。
• references/github-sync.md — リポジトリから Hex への同期と公開：hex_context.config.json、Action、トークン、CLI による公開手順。
• references/context-assets-deep-dive.md — 詳細なパターンと完全な例（ワークスペースコンテキスト、ガイド、セマンティック YAML、修正フレームワーク）。
• references/advanced-context.md — 参照リポジトリ（コード）と External Apps／MCP。
• references/intake.md — セットアップに合わせて出力を調整するための質問票（使用は控えめにし、検出を優先）。
• references/hex-docs.md — Hex の公式ドキュメントへのリンク。UI の手順を案内する前に、該当ページを取得してください。
• hex-guides/guide-writing-guide.md — ワークスペースに追加するガイド。Hex エージェントがデータに基づくコンテキストを作成できるようにします。