artifact-pyramids

エージェント型 AI 研究のためのアーティファクト・ピラミッド

段階的開示は、エージェントにコンテキストを与える方法を定めます。起動時にはメタデータ、アクティブ化時には指示、必要に応じてリソースを提供します。アーティファクト・ピラミッドは、エージェントが生成する成果物にも同じ原則を適用します。 深さが増す3つのレイヤーは、それぞれ単独で利用でき、次のレイヤーへリンクしています。

読み込みガイド

アーティファクト・ピラミッドを作成する際は、次のリファレンスを必須セットとして（個別ではなく）読み込んでください。

リファレンス	ファイル
パイプラインの段階 — レイヤーの定義、ナビゲーション形式、制作フロー	references/pipeline-stages.md
出力分類フレームワーク — 役割に依存しないコンテンツ契約、00-index/L1 の境界	references/output-classification-framework.md
品質ゲート — レイヤーごとの検証チェックリスト	references/quality-gates.md
委任コンテキストのテンプレート — サブエージェントへの出力要件を示す正確なテキスト	references/delegation-context-template.md

この4つは、互いに補完し合う仕様の側面を定義しており、他のリファレンスもこれらを前提としています。一部だけを読み込むと、コンテンツ契約に違反したり（例：00-index に調査結果を記載する）、必要なナビゲーション機能を省いたりするおそれがあります。ピラミッドのファイルを作成する前に、必ず全セットを読み込んでください。

以下のリファレンステーブルでは、各ファイルを「いつ」読み込むべきかを説明しています。上記の4つは、ピラミッドの作成時に常に必須です。残りのリファレンス（フレームワーク、作成例、標準的な記事、思想的系譜、出典情報、複合的な統合）は補足資料であり、概念を深く掘り下げる場合や、具体的なパターン例が必要な場合に読み込みます。

ピラミッド

      ┌──────────────┐
      │  L1 SUMMARY  │  One file: research question, key findings,
      │    🎯        │  most important implications. Links to L2 files.
      └──────┬───────┘
      ┌──────┴───────┐
      │  L2 ANALYSIS │  Per-dimension files: market, competitive,
      │  COLLECTION  │  technical feasibility, risk. Self-contained,
      │   🧩        │  each links to L3 dossiers.
      └──────┬───────┘
      ┌──────┴───────┐
      │  L3 DOSSIERS │  Source excerpts, raw data tables, interview
      │    📦        │  transcripts, methodology notes. Reference
      └──────────────┘  library, pulled on demand.

ピラミッドは上から下へ読み進めますが、作成時には再帰的なギャップ分析を行います。まず要約を作成し、分析ファイルへのリンクを埋め込み、分析ファイルを作成して資料ファイルへリンクします。そして各ラウンドの後に、まだギャップが残っているかを評価します。

レイヤー番号は上から順に付けます。L1 は最も要約されたレイヤー（入口）で、L3 は最も詳細なレイヤー（必要に応じて参照するもの）です。これは、Agent Skills の入力モデルであるメタデータ（L1）→ 指示（L2）→ リソース（L3）に対応しています。

ナビゲーションの仕組み

すべてのレイヤーのすべてのファイルには、末尾に、絶対パスの参照と説明を含む明示的な SOURCES セクションを設けます。

SOURCES (LAYER 2 NAVIGATION)
research/analysis/market-position.md
 -> Competitor mapping and market share analysis supporting Section 2
research/analysis/technical-feasibility.md
 -> Architecture evaluation supporting Section 3
research/dossiers/competitor-profiles.md
 -> Raw competitor data dossiers

これらは脚注ではありません。エージェントが利用するためのナビゲーション機能です。それぞれの説明は、読み込む前に利用側のエージェントが抱く「さらに掘り下げると、何が見つかるか」という問いに答えます。

参照ファイル

参照	読み込むタイミング	ファイル
フレームワークと対称性	概念的な基盤全体（非対称性の問題、マルチエージェントルーティング、DIKW との関係）が必要な場合	references/artifact-pyramid-framework.md
パイプラインの段階	ピラミッドを構築または監査する場合 — 各レイヤーの詳細な定義、ナビゲーション形式、生成フロー	references/pipeline-stages.md
品質ゲート	アーティファクトがそのレイヤーの基準を満たしているか確認する場合	references/quality-gates.md
実例	3 つすべてのレイヤーを通した、完全な合成ウォークスルーを確認する場合	references/synthetic-example.md
知的系譜	ソフトウェアアーキテクチャのドキュメント（4+1 Views、C4、arc42、ADR）が、異なる名称のもとで段階的開示を独自に見出した経緯と、Artifact Pyramid がそれらを超えて一般化する内容	references/intellectual-lineage.md
方法論からピラミッドへのマッピング	専門家プロファイルが、ドメイン固有の方法論を汎用的なピラミッド構造に対応づける方法と、次元の境界ルール	references/methodology-to-pyramid-mapping.md
出力分類フレームワーク	役割に依存しません — 専門家が出力を適切なレイヤーに対応づけるために使える 3 つの質問（誰が利用するか、どのくらいの頻度か、どのような問いに答えるか）。00-index と L1 ファイル間の重複をなくす、レイヤーごとのコンテンツ契約も含まれます。	references/output-classification-framework.md
複合ピラミッドの統合	複数のサブエージェントのピラミッドをルートレベルの複合ピラミッドに統合する方法 — オーケストレーターのフロー、SOURCES 規約、jobs-finder パイプラインの実例	references/composite-pyramid-synthesis.md
委任コンテキストテンプレート	サブエージェントに調査を委任する際、artifact-pyramid 形式の出力を確実に得るためにコンテキスト文字列に含める正確なテキストが必要な場合	references/delegation-context-template.md
フラット形式からピラミッドへの移行	既存のフラットな JSON 出力を artifact-pyramid 形式に変換する場合 — L1/L2/L3 構造、00-index ルール、後続の利用側でのフォールバック読み込みのパターン	references/flat-to-pyramid-migration.md
入れ子型ピラミッドパターン	1 つのシステムで、時間の経過とともに複数のアーティファクトストリーム（複数フェーズ、複数エポック）を生成する設計を行う場合 — 散在を避け、エポックを 1 つのルートピラミッドの下にネストします	references/nested-pyramid-pattern.md

スクリプト

スクリプト	読み込むタイミング	ファイル
pyramid-status	既存の調査ディレクトリについて、構造的な網羅性を監査する場合	scripts/pyramid-status.sh
extract-atoms	生のソーステキストから、候補となる原子的な主張を抽出する場合	scripts/extract-atoms.py

テンプレート

テンプレート	読み込むタイミング	ファイル
プロジェクトのひな形	新しい調査プロジェクトを開始し、インデックスの骨組みが必要な場合	assets/pyramid-template.md
アーティファクト一覧	プロジェクト内の各レイヤーに存在するものを追跡する場合	assets/artifact-inventory.md

クイックスタート

# Scaffold a new research project with all three layer directories
mkdir -p my-project/{01-summary,02-analysis,03-dossiers}
cp assets/pyramid-template.md ./my-project/00-index.md

# Check structural coverage of an existing project
scripts/pyramid-status.sh ./my-project

# Extract candidate atoms from source text
scripts/extract-atoms.py ./my-project/03-dossiers/source-1.txt

プロジェクト構造

my-project/
├── 00-index.md              # Project scaffold (from template)
├── 01-summary/              # L1: one file — key findings, implications, links to L2
├── 02-analysis/             # L2: per-dimension files (market, competitive, technical)
├── 03-dossiers/             # L3: source excerpts, transcripts, raw data, methodology
└── artifact-inventory.md    # Cross-layer tracking (from template)

番号付きの接頭辞は、ピラミッドの上から下への向きを反映しています。01 が最も頻繁に利用され、03 は必要に応じて参照されます。

主要原則

1. 段階的な開示は対称的です。 エージェントが取り込む情報（メタデータ → 指示 → リソース）と、エージェントが生成する情報（要約 → 分析 → ドシエ）の両方に、同じ3層モデルが適用されます。
2. 各層は個別に利用できます。 プロダクトマネージャーエージェントはL1の要約のみを読みます。データサイエンティストエージェントはL2の分析ファイルを1つ読みます。検証者はL3のドシエを読みます。
3. ナビゲーションは明示的にします。 すべてのファイルに、絶対パスと説明を記載したSOURCESセクションを含めます。これは脚注ではなく、「さらに深く調べると何が見つかるか」に答える、エージェント向けのナビゲーション手段です。
4. 深さはミッションの複雑さに応じて変わります。 単純な概要では、L1と分析ファイル2つだけで済む場合があります。競合状況の調査では、3層すべてに複数のファイルが必要になることがあります。
5. 品質ゲートには方向性があります。 マテリアルは、対象層のゲートを通過した場合に限り、L3（ソース）からL1（要約）へ移動します。
6. 03-dossiers/はフラットで、サブディレクトリを作成しません。 ドシエ層はフラットな参照ライブラリです。ネストしたディレクトリではなく、エポックの接頭辞またはカテゴリの接頭辞を付けたファイル名（epoch-1-validation-edit-3.jsonなど）で整理します。03-dossiers/内のサブディレクトリはフラットファイルの契約に反し、SOURCESによるナビゲーション経路を壊します。
7. ルート階層のファイルは更新し、下位層のファイルは固定します。 複数エポックまたは複数フェーズのシステムでは、新しいデータが届くたびに00-index.md、01-summary/findings.md、02-analysis/の軌跡ファイルを拡張します。これらは現在の状態を反映するように書き換えます。03-dossiers/内のファイルと、02-analysis/以下のカテゴリ別分析ファイルは一度作成したら変更しません。これらは特定時点の状態を表します。

検証スクリプトの落とし穴

scripts/pyramid-status.shは現在、正規のディレクトリ名ではなく、ファイル名との照合によって層を検出します。そのため、01-summary/findings.md、02-analysis/topic.md、03-dossiers/source.mdのような要件に準拠したツリーでも、ネストしたファイル名自体がスクリプトの層パターンに一致しない場合、L1／L2が欠落していると誤って報告されることがあります。また、上記の層の契約ではYAMLフロントマターは必須ではないにもかかわらず、品質上の問題として報告します。このスクリプトはあくまでヒューリスティックとして扱い、正規のディレクトリ、L1ファイルを1つ、次元ごとのL2ファイル、フラットなL3ファイル、最後にある## SOURCESセクション、およびリンクの解決を個別に確認してください。

使用しない場合

• 保存すべき調査成果物がない、1ターンで完結するQ&A
• 一時的な出力のみを生成するタスク（一度限りの計算、簡単な検索）
• ソース資料そのものが最終成果物となるワークフロー（統合が不要な場合）

移植性

このスキルは、特定のホストに依存しないよう意図的に設計されています。ここに記載されている参照資料、テンプレート、スクリプトは、エージェントに備わっている通常の仕組みを使って読み込んでください。特定のプロファイルシステム、タスクオーケストレーター、メモリーサービス、または応答引き継ぎ形式を前提にしないでください。