# プログレッシブディスクロージャー: エージェントシステムを覗き込むCLIという窓

Canonical source: https://maguyva.ai/ja/blog/progressive-disclosure-cli-into-agents

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-01-20 · Author: Maguyva Team

> エージェントシステムは、デフォルトでは不透明です。プログレッシブディスクロージャーは、素早いステータス確認からエージェント内部の全容や意思決定のトレースまで、オペレーターに階層化されたCLIビューを提供します。

> *この記事の数値は公開時点(2026年1月)のシステムを反映しています。最新の数値は[チームページ](/ja/team)をご覧ください。*

エージェントシステムは、設計上不透明です。意思決定を行い、ツールを呼び出し、数十体の専門エージェントにまたがる作業を調整します。しかし何かがうまくいかないとき、あるいは単に今何が起きているのかを理解したいとき、どこを見ればよいのでしょうか?

その答えがプログレッシブディスクロージャーです。必要なときに、必要な分だけ複雑さを見せる、階層化されたインターフェースです。

## 不透明性という問題

現代的なエージェントオーケストレーションシステムには、次のようなものが存在するかもしれません:

- それぞれ異なる能力を持つ、40体以上の専門エージェント
- 内部の自動化からベンダー連携までにまたがる、700個以上のスキル
- 振る舞いを形作る、470件以上のアーキテクチャ上の意思決定
- 外部機能を提供する、数十のMCPツールサーバー

この複雑さは意図的なものです。エージェントは、良い意思決定を下すために、ドメイン知識、コードインテリジェンス、データベーススキーマといった豊富なコンテキストへのアクセスを必要とします。しかしその同じ豊かさが、可視性の問題を生み出します。

どのエージェントがデータベースマイグレーションを担当しているかを、どうやって知ればいいのでしょうか? どんな意思決定が検索システムのランキングの挙動を形作ったのでしょうか? アーキテクチャアドバイザーはどんなツールにアクセスできるのでしょうか?

構造化されたアクセス手段がなければ、ソースコードを読むか、ドキュメントが最新であることを祈るしかありません。

## アーキテクチャとしてのプログレッシブディスクロージャー

プログレッシブディスクロージャーは、単なるUIパターンではありません。アーキテクチャ上の原則です。情報を、それぞれ前の層より深い階層に整理することで、ユーザーは自分の疑問に答えてくれる階層で立ち止まることができます。

エージェントシステムにおいて、これは深さを増していくCLIコマンド群として実現されます:

| レベル | コマンド | 答えてくれる問い |
|-------|---------|-------------------|
| 1 | `orkestra system status` | すべて健全か? |
| 2 | `orkestra agents list` | どんなエージェントが存在するか? |
| 3 | `orkestra agents info <name>` | このエージェントは何をするか? |
| 4 | `orkestra decisions search` | なぜこのように動くのか? |
| 5 | Maguyva MCPツール | コードを見せて。 |

各レベルは、自然な追加の疑問に答えてくれます。いきなりレベル5まで飛ぶ必要はめったにありません。

## レベル1: システムの健全性

最初の問いはいつも同じです。すべて正常に動いているか?

```bash
$ orkestra system status
```
```json
{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}
```

コマンド1つ。数字4つ。システムが正しく設定され、レジストリにデータが入っていることを知るには、それで十分です。

エージェント数が予期せず減ったり、スキルの読み込みに失敗したりすれば、まずここで気づきます。ログに潜る必要はありません。

## レベル2: エージェントの棚卸し

システムが健全だとわかったら、次の問いは「何が使えるか?」です。

```bash
$ orkestra agents list
```

これは構造化データ(エージェント名、説明、モデルの優先設定、ドメインのカバー範囲)を返します。出力はデフォルトでJSONなので、`jq`へパイプしてフィルタリングするのも簡単です:

```bash
$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'
```

データベース関連の作業を扱うエージェントが欲しいですか? searchコマンドで絞り込めます:

```bash
$ orkestra agents search "database"
```

これは名前、説明、能力をスキャンします。40体分のエージェント定義を読まなくても、適切な専門家を見つけられます。

## レベル3: エージェントの深掘り

関係がありそうなエージェントを見つけましたか? `info`コマンドがすべてを明らかにします:

```bash
$ orkestra agents info architecture-advisor
```

出力には次が含まれます:

- **メタデータ**: 名前、カテゴリー、モデルの優先設定、説明
- **ドメイン**: このエージェントがカバーする知識領域
- **アイデンティティ**: キャラクター特性(アーキテクト、ストラテジスト、ナレッジアーキテクトなど)
- **ツールガイド**: コンテキストに注入されるツールドキュメント
- **ツール**: このエージェントが利用できるMCPツールの完全な一覧

実際に表示される内容の一部です:

```jsonc
{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}
```

これにより、そのエージェントが何をできるのかが正確にわかります。ソースコードを読む必要はありません。

## レベル4: 意思決定の考古学

エージェントは、文書化された意思決定に従って振る舞います。何かが特定の形で動く*理由*を理解する必要があるとき、意思決定レジストリが信頼できる情報源になります。

```bash
$ orkestra decisions search "agent"
```

これにより、一致するアーキテクチャ上の意思決定が返されます:

```json
{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}
```

それぞれの意思決定には完全な来歴があります。いつ下されたのか、なぜか、どんなトレードオフが検討されたのか、どのコミットで実装されたのか:

```bash
$ orkestra decisions info DEC-SR-049
```

```json
{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}
```

これは、手作業で維持されるのではなくコミットからマイニングされているため、常に最新であり続けるアーキテクチャドキュメントです。

## レベル5: 直接的なコードインテリジェンス

実装に関するメタデータではなく、実際の実装そのものを見る必要があるとき、MaguyvaのMCPツールが直接的なアクセスを提供します。

エージェントセッションの内部からは:

```
mcp__maguyva__intelligent_search
  query: "agent context loading"
```

これは、関連コードを見つけるためにセマンティック検索、テキスト検索、AST検索を自動的に振り分けます。特定のシンボルについては:

```
mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"
```

依存関係分析については:

```
mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"
```

これらは単なるgrepの代替品ではありません。グラフを意識し、意味的にインデックス化され、エージェント自身を動かしているのと同じコードインテリジェンスと統合されています。

## レジストリを横断した統合検索

どのレジストリに答えがあるのか、わからないこともあります。統合検索はすべてを横断します:

```bash
$ orkestra search "database" --summary
```

```json
{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}
```

5つのレジストリにまたがる254件の一致。サマリーが、どこを深掘りすべきかを教えてくれます。詳細な結果が欲しければ`--summary`を外し、出力を扱いやすく保ちたければ`--limit 5`を加えましょう。

## これが重要な理由

プログレッシブディスクロージャーは、単なる利便性の話ではありません。複雑なシステムとの向き合い方そのものを変えます。

**デバッグが手に負えるものになる。** エージェントが予期しない意思決定をしたとき、ログをgrepする必要はありません。そのエージェントがどんなツールにアクセスできるか(`agents info`)、どんな意思決定がその振る舞いを形作っているか(`decisions search`)を確認し、必要なら実装をたどります(`intelligent_search`)。

**オンボーディングが加速する。** 新しいチームメンバーは、コードベース全体を読む必要はありません。`system status`から始め、`agents list`で探索し、理解できない何かにぶつかったときだけ、より深く掘り下げます。

**ドキュメントが常に最新であり続ける。** CLIはエージェントを構成しているのと同じレジストリから読み込むため、出力は常に正確です。ドキュメントの記述とシステムの実際の挙動の間にズレは生まれません。

## インターフェースとしてのCLI

Webダッシュボードを構築することもできました。膨大なドキュメントを書くこともできました。その代わりに私たちは、信頼できる情報源から直接読み込むCLIを構築しました。

CLIには次のような利点があります:

- **合成可能**: 出力を`jq`へパイプし、スクリプトと統合できる
- **スクリプト化可能**: チェックを自動化し、レポートを生成できる
- **高速**: ページ読み込みも認証フローも不要
- **正確**: キャッシュされた表現ではなく、実際の設定を読み込む

見た目より正しさが重要なシステムにおいては、CLIに軍配が上がります。

## 自分たちのプログレッシブディスクロージャーを構築する

エージェントシステムを構築しているなら、ユーザーがそれをどう検査するかを考えてみましょう:

1. **ヘルスチェックから始める。** すべてが動いているかを教えてくれる1つのコマンド。
2. **棚卸しビューを提供する。** 何をするかを説明する前に、何が存在するかを一覧化する。
3. **狙い撃ちのクエリを可能にする。** 大規模になれば、検索は閲覧に勝る。
4. **来歴を公開する。** ユーザーが意思決定をその起源までたどれるようにする。
5. **コードインテリジェンスへつなぐ。** 最終的に、ユーザーは実装そのものを見る必要がある。

それぞれの層が、追加の疑問に答えます。頻度順に構築しましょう。ほとんどのユーザーは層2か3で止まります。層5に到達するのはパワーユーザーだけです。

目標はすべてを公開することではありません。必要なときに、必要なものだけを、正確に公開することです。それこそが、エージェントアーキテクチャに適用されたプログレッシブディスクロージャーです。