AIエージェントのセットアップ

Cursor / Claude Code / Codex / Gemini CLI などのAIエージェントから cdm コマンドを使い、ノートブックファイル(*.cnb.md)の編集や、カタログの整備（アノテーション *.cann.yaml / タグ *.ctag.yaml）を効率的に行うためのセットアップ手順です。

前提

• クイックスタートのインストールと認証を完了していること
• （Skill を利用する場合）利用するAIエージェントが Skills（SKILL.md）に対応していること

連携の方法

AIエージェントに cdm が扱うファイル（*.cnb.md / *.cann.yaml / *.ctag.yaml）の編集ルールを伝える方法には、起動タイミングの異なる2種類があります。

• Skill: AIエージェントが「これらのファイルを読む・編集する」と判断したときに起動します。必要なときだけ読み込まれるためコンテキストを節約できますが、起動はエージェントの判断に依存します
• 常時適用の連携（任意）: プロジェクト全体の方針として常時読み込まれます。Skill の判断起動に頼らず確実に方針を効かせたい場合に指定します

通常は Skill の配置だけで十分ですが、うまくAIエージェントが cdm を使わない場合や、特定用途で必ず cdm を使わせたい場合は、併用することでより確実になります。

Skill を配置する

cdm skill install で、エージェントに cdm の使い方を伝える SKILL.md を配置します。

# 対話でエージェント・スコープを選んで配置
cdm skill install

# エージェントを指定して配置
cdm skill install --agent claude-code

配置される SKILL.md は、エージェントが cdm の対象ファイル（*.cnb.md / *.cann.yaml / *.ctag.yaml）を読み書きする際に、 cdm コマンドと PAT の確認や AIエージェント向けガイド の取得を促すものです。対応エージェントや配置先の詳細は cdm skill を参照してください。

配置後は、エージェントに認識させるため、エディタのウィンドウ再読み込みや新しいセッションの開始が必要な場合があります。

常時適用の連携（任意）

各エージェントには、プロジェクト全体に常時適用される指示ファイルがあります。cdm の対象ファイルを確実に正しく扱わせたい場合は、これらに cdm の Skill を使うよう促す内容を記載します。cdm skill の対象外のため、手動で設定します。

エージェント	ファイル	主な配置先
Claude Code	CLAUDE.md	リポジトリルート
Cursor	.cursor/rules/*.mdc (Rules ファイル)	.cursor/rules/cdm.mdc
Codex	AGENTS.md	リポジトリルート（または ~/.codex/AGENTS.md）
Gemini CLI	GEMINI.md	リポジトリルート（または ~/.gemini/GEMINI.md）

記載する内容

常時適用ファイルには cdm の対象ファイルを扱うときに cdm の Skill を使うよう促す内容を記載しておけば、詳細な手順は Skill 側に委ねられます。

記載例は以下の通りです。実際の文面は、お使いのプロジェクトの方針に合わせて調整してください。

## Codatum

For any task involving Codatum notebooks or catalog curation — `*.cnb.md`, `*.cann.yaml` (annotations), or `*.ctag.yaml` (tags) — use the installed `cdm` skill and follow its instructions. These files are not plain Markdown/YAML; do not read, edit, create, or format them outside the `cdm` workflow.

Cursor の Rules（.cursor/rules/cdm.mdc）のみ、適用範囲を制御するための frontmatter が必要です。globs で対象ファイル（*.cnb.md / *.cann.yaml / *.ctag.yaml）を開いた時に適用されるように以下のように書きます。

Cursor の Rules の例:

---
description: Use the cdm skill for Codatum files (*.cnb.md, *.cann.yaml, *.ctag.yaml)
globs:
  - "**/*.cnb.md"
  - "**/*.cann.yaml"
  - "**/*.ctag.yaml"
alwaysApply: false
---

For any task involving Codatum notebooks or catalog curation — `*.cnb.md`, `*.cann.yaml` (annotations), or `*.ctag.yaml` (tags) — use the installed `cdm` skill and follow its instructions. These files are not plain Markdown/YAML; do not read, edit, create, or format them outside the `cdm` workflow.

AGENTS.md について

AGENTS.md は、特定のエージェントに依存しないクロスツールの指示ファイルの標準として広がりつつあり、Codex 以外の多くのエージェント（Cursor、Gemini CLI など）も AGENTS.md を読み込む場合があります。

そのため、複数のエージェントを併用する場合は、エージェントごとに別々のファイルを用意する代わりに、AGENTS.md に一本化することも検討できます。各エージェントが AGENTS.md を読み込むかどうかや、読み込みの優先順位は、利用するエージェントの仕様を確認してください。

トラブルシューティング

Skill / 指示ファイルが認識されない

• 配置先のパスが正しいか確認してください
• エディタのウィンドウ再読み込みや、エージェントの再起動・新しいセッションの開始を試してください
• Claude Code では /skills、Gemini CLI では /memory show など、読み込み状況を確認するコマンドが利用できる場合があります