vignette-catalog-scaffold

ビネットカタログを作成する

カタログは、パッケージやパイプラインではなく、マニフェストと役立つノートブックから始まります。 カタログ名、対象パス、データの接続先（rest、duckdb、pooch、files）を推測できない場合に限り、ユーザーに確認してください。

ワークフロー

1. 対象を調べます。 新しいカタログの場合は、ディレクトリが存在しないか、空であることを必須とします。 既存のリポジトリの場合は、そのファイルを保持し、--adopt を使用します。 ユーザーまたは既存のリポジトリのポリシーですでに選択が指定されていない限り、任意の規約として何を採用するかを一度だけ尋ねます。選択肢は、標準的なデータ配置と作業規約、インデックスノートブック付きの出力サマリー、コミットするセッションスナップショットです。 手順 5 で選択肢を説明します。組み合わせ、いずれか一つ、または何も選ばないことを認め、回答を待ってから適用してください。

2. 最小限の構成を生成します。

   <skill-dir>/scripts/scaffold.py <target> --name <name> --surface <surface>
   # Existing repository:
   <skill-dir>/scripts/scaffold.py <target> --name <name> --surface <surface> --adopt
   

   スクリプトは、モデルに説明文からテンプレートを再現させるのではなく、実際のアセットをコピーします。

3. notebooks/nb01_orientation.py にある意図的な NotImplementedError を、実際のデータセットにアクセスする1回の範囲を限定した呼び出しに置き換えます。 再利用可能なアクセスロジックはトップレベルの @app.function に配置し、依存関係とバージョンをノートブックの PEP 723 ブロックで宣言します。

4. catalog.toml のデータセット固有の項目を埋めます。具体的には、説明、上流バージョン、キャッシュ、注意事項、認証、ヘルパー名、オリエンテーションノートブックで実演する内容です。 データセット識別子、API の動作、ハッシュ、運用上の注意事項は、共有スキルではなく、このカタログに記録してください。

5. 既存のリポジトリを採用する場合、既存の README.md、AGENTS.md、.gitignore、pyproject.toml を上書きせず、内容を調整します。 生成される AGENTS.md には、クローン後に実行するスキルのインストールコマンドが正確に記載されています。 選択した規約と選択しなかった規約を、パスとスナップショットのポリシーを含めてデータセットの契約に記録し、それに合わせて .gitignore を調整します。

   • 選択した場合は、標準のデータ配置と作業ルールを使用します。保護対象の入力データは data/raw/ と data/external/ に、再現可能な共有準備出力は data/interim/ に、各分析の作業領域は data/processed/<analysis>/ に置きます。 データは raw/external から interim、processed へと流れます。分析では入力を直接読み込むこともできます。 入力データや共有中間データを手作業で編集しないでください。準備用ノートブックまたはヘルパーを変更し、中間データを再生成してください。 ディレクトリは必要になった場合にのみ作成します。 カタログの AGENTS.md に作業ルールを記録し、既存のマニフェスト項目やドキュメントを重複させずにリンクします。 入力ソース、そのバージョンまたはハッシュ（入手可能な場合）、取得用ヘルパーまたはコマンドを明記します。 各共有中間データを再構築するノートブックまたはコマンドを明記するか、再構築が不要であることを示します。また、各分析の入力パスと出力パスを特定します。 共同作業者が出力を取得して共有する方法、またはローカルで再現する方法を説明し、該当する場合は共有入力データや準備作業の変更を調整する担当者を明記します。 不明な事実だけをユーザーに確認し、セットアップを完了する前に、範囲を限定した例で記載済みの取得・再構築手順を検証します。 共有時には、他の共同作業者の出力やローカルのみの作業を保持する必要があります。セットアップ自体は、アップロードや共有データの置き換えを許可するものではありません。
   • 選択した場合は、出力の概要とインデックスを追加します。保存済みの出力がある各分析では、description、numbers（名前と値のオブジェクト）、files（リポジトリ相対の path と caption を持つオブジェクト）を含む summary.json を書き出します。 標準のデータ配置を使用する場合は data/processed/<analysis>/summary.json を使用します。それ以外の場合は、選択した出力パスを記録します。 これらのエンベロープを検出して表示する notebooks/index.py を作成し、対象が空でも処理できるようにします。 出力が無視される場合は、エンベロープとその親ディレクトリを許可リストに追加し、新しいチェックアウトから検出できるようにします。出力ファイルが利用できない場合でも失敗しないようにします。
   • 選択した場合は、セッションスナップショットをコミットします。出力のレビューや閲覧のために notebooks/__marimo__/ 内の marimo スナップショットを追跡し、検証時に --write で更新します。 それ以外の場合は、スナップショットを無視したままにします。

6. 記載されているコマンドを使用してプロジェクトスキルをインストールし、vignette-catalog-compose-notebook を通じてオリエンテーションノートブックを開き、実際の出力を確認して、その scripts/validate-notebook.sh を実行します。

取得と準備には、既存のカタログヘルパーとノートブックを使用します。 プロジェクトの要件で必要な場合にのみ、src/、共有環境、ワークフローエンジン、またはクラウド同期を追加します。