AIエージェント向けガイド

このページについて

• このページは、Cursor / Claude Code 等のAIエージェントが *.cnb.md ノートブックファイルを編集する際に従うべき作業ガイドです
• cdm は Codatum の機能を CLI から操作するツールです。本ページでは、マークダウン版ノートブック（*.cnb.md）の編集に使うコマンドに焦点を当てます
• エージェントは cdm コマンドをシェルから実行して、ドキュメントやメタデータを取得してください
• このページに書かれていないフォーマット等の仕様の詳細は、cdm doc index で目次を取得し、該当ページを cdm doc show <path> で取得してください

作業を始める前に

1. cdm コマンドと PAT の動作確認

エージェントは作業を開始する前に、シェルで cdm が利用可能か、登録済みの PAT が有効かを確認してください。

cdm --version
cdm auth whoami

• cdm --version でバージョンが返ること（CLI がインストールされ PATH が通っていること）を確認します
• cdm auth whoami で Status: OK が返ること（profile が登録され、PAT が有効であること）を確認します
• whoami が Status: INVALID や exit 1 になる場合、PAT の再登録が必要です。cdm auth login の手順をユーザに案内してください（PAT は Codatum Web の アカウント設定 → パーソナルアクセストークン から発行）

2. cdm が使えない場合

cdm: command not found 等のエラーが出る場合、ユーザの環境にインストールされていないか、PATH が通っていません。エージェントは勝手にインストールを試みず、以下をユーザに案内してください。

• インストールが必要な可能性があること
• インストール手順ははじめにを参照すること

cdm が使えない、または PAT が無効なまま *.cnb.md の編集を進めると、format / validate や API 連携コマンドが正しく動かず、不正なファイルを残してしまう可能性があります。cdm --version と cdm auth whoami の両方で確認が取れるまで編集作業に入らないでください。

cdm コマンドで取得できるもの

cdm コマンドでは、大きく分けて以下の機能が利用できます。詳細な入出力仕様は cdm コマンド を参照してください。

ドキュメント取得

• cdm doc index: ドキュメントの目次（このサイト全体）
• cdm doc show <path>: 各ドキュメントページの内容
  • <path> は cdm doc index の出力に記載された形式で、先頭の / と末尾の .md 拡張子が必須（例: cdm doc show /md/sql-block.md）

*.cnb.md の編集対象に応じて、必要なドキュメントを取得してから編集してください。特にチャート設定は template_type ごとに構造が大きく異なるため、該当する /md/chart-types/<TEMPLATE_TYPE>.md を確認してください。

コネクション・テーブル

• cdm connection list: 認証済みワークスペースで利用可能なコネクション一覧を取得
• cdm catalog search-tables <query>: 指定したコネクション内のテーブルをキーワード検索（カラム情報含む）
  • 複数キーワードを指定する場合は cdm catalog search-tables "users summary" のようにクオートで囲む

SQL 実行（アドホックな検証用）

• cdm sql dry-run: SQL を実行せず、構文や処理予定バイト数を確認
• cdm sql run: SQL を同期実行し、結果が出るまで待機して取得（単発確認向け）
• cdm sql get-job-metadata / cdm sql get-job-result: 既存ジョブのステータス・結果を取得（*.cnb.md 内の jobId を再利用したい場合など）
• cdm sql create-job: ジョブを作るだけで結果待機しない非同期実行（CI で長時間ジョブを投入したい等の特殊用途）

これらのコマンドの位置づけは後述のSQL 実行コマンドの使いどころを参照してください。

動作の前提

• データ系のコマンド（connection list / catalog search-tables / SQL 実行系）は、cdm auth login で登録した PAT を用いて Codatum API に直接アクセスします
• *.cnb.md ファイルは CLI では編集できません。次節の通り、ファイルシステム経由で直接編集してください

ファイルの編集方法

• *.cnb.md ファイルは、エディタやファイルシステム経由で直接編集してください
• cdm はドキュメントやメタデータの取得、ファイルの検証・フォーマット用であり、ファイル内容の直接書き込みには対応していません

編集の基本ワークフロー

1. 編集前

関連情報を cdm コマンドで取得します。推測で書かないことが最優先です。

• 関連ドキュメントを cdm doc show <path> で取得する（特にチャート設定）
• コネクションIDが必要なら cdm connection list で取得する
• テーブルやカラムを参照するなら cdm catalog search-tables <query> で実在とカラム情報を確認する
  • SQL ブロックの TABLE_REF.tableResourceId、SQL 内のテーブル参照、チャート設定で参照するカラム名などは、ここで得た情報を元に書く

2. 編集中

• フロントマターの id・workspace_id は省略しない（cdm notebook clone の出力を起点にする）
• ページ属性や SQL ブロック属性の id など、自動補完されるフィールドは省略してよい（format に任せる）
• SQL ブロックの connId は必ず指定する（デフォルトコネクションはない）
• 自動付与フィールド（jobId, state, chartJobId 等）は触らない、生成しない
• SQL の妥当性に不安があれば cdm sql dry-run で事前検証する（後述）

3. 編集後

cdm コマンドで検証・整形し、問題がなければサーバに反映します。

cdm notebook validate <target>    # 検証のみ（ファイル/ディレクトリ）
cdm notebook format <target>      # 自動修復 + 検証 + 整形（ファイル/ディレクトリ）
cdm notebook diff <file>          # 任意: push 時のサーバ側の変更影響を確認（ファイルのみ）
cdm notebook push <target>        # サーバへ反映（ファイル/ディレクトリ・ユーザが依頼した場合）

• format で自動修復可能なエラー（一覧）はそのまま解消されます
• push は profile のワークスペースと、対象ファイルの workspace_id が一致している必要があります
• push 前に差分を確認したい場合は diff を別途実行してください
• 詳細はcdm コマンドを参照してください

SQL 実行コマンドの使いどころ

cdm sql 系のコマンドは、エージェントが編集中にアドホックな確認・検証を行うためのものです。

想定する使い方

• SQL の構文を検証したい: cdm sql dry-run で実行せずに構文と処理量を確認
• データの中身を確認したい（単発）: cdm sql run で同期実行して結果を取得
  • タイムアウトや Ctrl+C で中断した場合もジョブIDがエラーメッセージに含まれるので、後から get-job-metadata で状態確認可能
• 既にノートブック内で実行済みの SQL ブロックの結果を見たい: *.cnb.md 内の jobId を cdm sql get-job-metadata / cdm sql get-job-result に渡せば、再実行せずに結果を取得できる

やってはいけない使い方

• ノートブック内に書いた SQL ブロックを、cdm sql run や cdm sql create-job で個別に実行して回らない
  • SQL ブロックの実行は、ユーザがプレビュー画面で行うか、ノートブックの実行機能に任せるのが本来の流れです
  • エージェントが SQL ブロックごとに実行するのは、ノートブックの実行モデルから外れた使い方であり、*.cnb.md の jobId 等の管理とも整合しません
• 大量データを取得して中身を分析する用途
  • あくまで編集判断のための補助情報を取るためのものです
  • cdm sql run / get-job-result の取得上限は 1000 行ですが、これは制限であって目標値ではありません

迷ったら、「自分が書こうとしている SQL やデータ構造の確認のため」かどうかで判断してください。それ以外の目的（ノートブックそのものの実行）は、これらのコマンドの責任範囲外です。

やってはいけないこと

• コネクションIDの推測（cdm connection list で取得）
• テーブル名・カラム名・型の推測（cdm catalog search-tables で確認）
• チャート設定や SQLブロックをドキュメントを読まずに書く
• *.cnb.md の手動フォーマット整形（format に任せる）
• cdm が使えない、または cdm auth whoami で PAT が無効な状態での編集続行
• ノートブック内の SQL ブロックを cdm sql run / cdm sql create-job で個別に実行して回ること（前節参照）

プレビュー中の編集について

ユーザが cdm notebook preview を起動している間に編集する場合、書き込みの競合が起きることがあります。

• エディタの formatOnSave は無効にしてもらう
• 大量ファイル監視中のエディタでは更新反映が遅延することがある
• 詳細はプレビューの注意事項を参照

困ったとき

• フォーマット仕様で迷ったら → cdm doc index で目次を取得し、関連ページを cdm doc show /md/xxx.md で読む（先頭 / と .md を忘れない）
• スキーマエラーが出たら → まず cdm notebook format を実行する（自動修復可能なエラーはこれで解消する）
• 制限事項に引っかかったら → 制限事項を確認
• テーブルやカラムが分からない → cdm catalog search-tables で確認（推測しない）
• SQL の妥当性が不安 → cdm sql dry-run で検証

ユーザに代わって判断を急ぐより、ドキュメントを引いて根拠を持って書くことを優先してください。