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

このページについて

このページは、Cursor / Claude Code 等のAIエージェントが cdm コマンドを使って作業する際の作業ガイドです。対象は、Codatum のノートブックファイル(*.cnb.md)の編集と、カタログの整備（アノテーション *.cann.yaml / タグ *.ctag.yaml）です。

作業を始める前に

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

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

cdm --version    # CLI がインストールされ PATH が通っていることを確認
cdm auth whoami  # profile が登録され、PAT が有効であることを確認

2. cdm が使えない場合

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

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

cdm --version と cdm auth whoami の両方が成功するまで編集作業に入らないでください。

cdm コマンドの使い方

• cdm コマンドを使ってノートブックを編集する流れについては、クイックスタートを参照してください
  • 利用可能なコマンドの一覧は cdm コマンドを参照してください
• ファイル本体（*.cnb.md / *.cann.yaml / *.ctag.yaml）は CLI では編集できません。エディタやファイルシステム経由で直接編集し、生成・同期・検証は cdm のコマンド経由で行ってください

ユーザの許可が必要なコマンド

以下のコマンドは、取り消し不可能な操作や、大量のリソース消費を伴う操作になる可能性があるため、ユーザからの明示的な指示がある場合のみ実行してください。指示がない場合は、実行前に必ずユーザに確認してください。

• サーバへ反映する push 系（notebook push / catalog annotation push / catalog tag push）は、実行前に対応する diff（notebook / annotation / tag）で反映内容を確認してください
  • サーバ側の変更を意図せず上書きする可能性があるため、削除される差分が大きい場合や、ローカルの編集とは別にサーバ側で編集が進んでいると思われる場合は、実行前にユーザへ再確認を取ってください
• サーバ上のリソースを削除する delete / prune 系（notebook delete / catalog tag prune）は取り消しできない操作のため、明示的な指示がある場合のみ、削除対象をユーザに確認してから実行してください
• なお、引数・オプションを確認する --help は副作用がないため、ユーザの許可なく実行して構いません

各コマンドの固有の注意点は次のとおりです。

• cdm notebook create: サーバ上に新規ノートブックを作成します
• cdm notebook delete: サーバ上のノートブックを削除します。取り消しできない操作のため、実行前にノートブック名をユーザに確認するなど、特に慎重に判断してください
• cdm notebook run: ノートブック内の SQL を一括実行します。大量のSQLブロックやチャートがある場合、リソース消費・実行時間が大きくなる可能性があります
• cdm catalog annotation push: カタログのアノテーションを更新します。ファイルに記載のないカラム（manages: all-tables では記載のないテーブルも）のアノテーションは削除されるため、 diff による事前確認を必ず行ってください
• cdm catalog tag push: タグ定義を更新します。タグはワークスペース全体で共有されるため、cdm catalog tag list で既存タグを確認し、再利用できる場合は新規作成をなるべく避けてください
• cdm catalog tag prune: 参照されていないタグを削除します。取り消しできない操作のため、明示的な指示がある場合のみ、削除対象の一覧をユーザに確認してから実行してください

SQL コマンドの使い方

cdm sql コマンドはノートブックの編集中にアドホックにデータの中身を確認・検証するために利用します。

• cdm sql run / cdm sql create-job では、シェルが標準入力をオープンパイプのまま接続している環境でも確実に動作するよう、SQL は位置引数 <sql> で渡してください。詳細は SQL の渡し方
• ノートブック内のSQLを実行する場合は、cdm notebook run を使ってください
  • cdm notebook run では過去の実行結果をキャッシュとして利用できるため、個別に cdm sql run を実行するよりも効率よく実行できます
• ノートブック内で実行済のSQLブロックの結果を取得したい場合は、cdm sql get-job-metadata や cdm sql get-job-result を使います。ノートブック内の jobId は ジョブリソース ID 形式なので、<job-id> 引数にそのまま渡してください
• cdm sql run でも cdm notebook run でも、クエリの実行結果は最大 1,000 行までしか取得できません。大量データを取得して分析する用途には使えません
  • 1,000 行の取得制限は、クエリの実行後のデータ取得のタイミングで適用され、自動で LIMIT 1000 を追加するものではありません。データのサンプルを取得する場合、必ず LIMIT 句を指定してください。

チャート・ページの仕上がり確認

チャートやページの見た目の仕上がりを確認したい場合は、cdm notebook render chart でチャートを、cdm notebook render page でページを画像（PNG）として書き出せます。

• エージェント自身が画像を確認し、ラベルの重なり・凡例・レイアウトの崩れなどを判断して、チャート設定を修正する用途に使えます
• render はSQLを実行せず、ノートブックファイルに記録済みの実行結果を参照して描画します。最新のデータで確認したい場合は、事前に cdm notebook run を実行してください
• cdm util image で PNG 画像のサイズ取得・縮小・切り取りが可能です。画像サイズが大きい場合は、縮小して全体のレイアウトを把握し、必要な箇所だけを原寸から切り取って詳細を確認する、という用途で利用できます
• ドキュメントページでダイアグラム(Mermaid)や数式(KaTeX)を利用している場合は、cdm notebook lint で文法をチェックできます

新規ノートブック作成時の作法

ユーザから特別な指示がない場合は、ゼロからノートブックを作成する前に、既存ノートブックを参考にしてください。.cnb.md は仕様通りに書けても、「どのコネクションのどのテーブルからデータを抽出するか」「SQLをどう書き、どう分割するか」「チャートをどう設定・組み合わせるか」といった部分は、既存の資産に倣うことで自然な成果物になりやすくなります。

1. 作りたいものに近い既存ノートブックを cdm notebook search で探す
2. 参考になりそうなノートブックを cdm notebook clone で取得し、中身を確認する
3. 掴んだ作法に沿って、新規ノートブックを作成・編集する

作成場所の決め方

新規ノートブックの作成場所（フォルダ）は、次の順で決めてください。

• ユーザから作成場所の明示的な指示（フォルダのURLやID、「○○フォルダに作って」等）がある場合は、それに従ってください
• 作成自体は指示されているが、作成場所が明示されていない場合は、cdm notebook folder list（引数なし）で探索の起点となるフォルダを確認し、必要に応じてサブフォルダを辿って、どこに作成するかユーザに確認してください

作成場所が決まったら、cdm notebook create を実行する前に、cdm notebook folder info でそのフォルダに編集権限（permissions に write が含まれるか）があるかを確認してください。write 権限がない場合は作成できないため、無理に作成を試みず、ユーザに権限の確認や別フォルダの指定を依頼してください。

カタログの整備

ユーザからカタログの整備を指示された場合は、次の点に考慮しつつ、分析コンテキストの整備を参考に作業を行ってください。何をどう書くかの設計の考え方は 分析コンテキストの設計 も参照してください。

• 既存のアノテーションやタグの作法や内容を参考にする
  • ユーザからの特別な指示がない場合は、既存のアノテーションやタグを検索し、表現や内容を参考に統一感を持たせてください
• 量より質を重視する
  • 同じようなアノテーション・タグを大量に作成すると、検索時のヒット数が増えすぎて、逆に検索性を損なう可能性があります
  • 説明はなるべく簡潔に保ち、無駄な重複を避けてください
    • 例えば、サンプルSQLなどの詳細な内容はノートブックにまとめて、ノートブックのURLを説明内に記載するなど

やってはいけないこと

• cdm が使えない、または cdm auth whoami で確認が取れない状態での編集を行うこと
• ユーザの許可が必要なコマンドをユーザの明示的な指示や許可なしで実行すること
  • 特に取り消し不可能な削除系（cdm notebook delete / cdm catalog tag prune）は、明示的な指示なしに実行しないこと
• ID類やテーブル名・カラム名・タグ名を根拠なしに推測して書くこと
  • コネクションIDは cdm connection list、テーブル名・カラム名・型は cdm catalog search-tables、アノテーションに書くタグ名は cdm catalog tag list で確認
  • ページ属性や SQL ブロック属性の id など、cdm notebook format で自動付与される ID は format に任せ、手動指定が必要な ObjectId は cdm util gen-id で生成
• cdm sql run / cdm sql create-job を大量、高頻度に実行すること
• cdm の format を使わず、対象ファイルを手動で整形すること（通常の .md / .yaml とはフォーマットの仕様が異なり、手動整形では正規化も行われません）
  • *.cnb.md は cdm notebook format、*.cann.yaml / *.ctag.yaml は cdm catalog annotation format / cdm catalog tag format を使ってください

困ったとき

• ファイルのフォーマットや検証でエラーが出る
  • エラーメッセージにドキュメントのパスが記載されている場合は、cdm doc show <path> でドキュメントを確認する
• ノートブックやカタログ、Codatum の仕様が分からない
  • cdm doc index で目次を取得し、関連ページを cdm doc show <path> で確認する
  • cdm doc full で全ドキュメントを取得し、ローカルで grep 等で検索する
  • Web版のCodatum Docsを参照する

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