Claude Code

Claude Code から cdm コマンドを使い、*.cnb.md ファイルを効率的に編集するための手順です。

前提

• Claude Code v2.x 以降（Skills 対応バージョン）
• cdm コマンドがインストール済み（はじめにを参照）
• cdm auth login で PAT が登録済み

セットアップ方針

エージェントに *.cnb.md の編集ルールを伝える方法として、Claude Code では Skills と CLAUDE.md の2つが利用できます。

• Skills: エージェントが「読む・編集する」と判断したタイミングで起動する。*.cnb.md 編集時にだけ必要な情報を読み込ませたい場合に向く
• CLAUDE.md: プロジェクト全体の方針として常時読み込まれる。プロジェクトに既に CLAUDE.md がある場合や、cdm 以外の方針と一緒に管理したい場合に向く

どちらか一方でも動作しますが、Skill の配置を推奨します。Skill は必要な時だけ起動するため、コンテキストを節約できます。両方設定しても問題ありません。

Skill の配置

*.cnb.md ファイルの編集時に起動し、cdm CLI と PAT の確認、エージェント向けガイドの取得を行う Skill を配置します。

プロジェクトルートに .claude/skills/cdm/SKILL.md を作成し、以下の内容を保存してください。

---
name: cdm
description: Use this skill when reading or editing any *.cnb.md notebook file. Loads the cdm agent workflow guide and verifies the cdm CLI / PAT are available before making changes.
---

# Editing cdm notebook files

This skill applies whenever you are about to read or edit a `*.cnb.md` notebook file.

## Steps

1. Verify that the `cdm` command is available and the PAT is valid:

```sh
   cdm --version
   cdm auth whoami
```

   - If `cdm --version` fails with "command not found", stop and ask the user to install `cdm`. Do not attempt to install it yourself. Point them to the "Getting Started" page in the cdm docs.
   - If `cdm auth whoami` returns `Status: INVALID` or exits with code 1, stop and ask the user to re-register the PAT via `cdm auth login`.

2. Fetch the agent workflow guide via the cdm CLI:

```sh
   cdm doc show /guide/for-agents.md
```

3. Follow the workflow defined in that guide. The guide will direct you to fetch additional documentation pages as needed for the specific edit you are making (chart settings, grid layouts, SQL blocks, parameters, etc.).

4. After editing, run `cdm notebook format` to verify and auto-repair the file.

Claude Code はセッション開始時に skills を読み込むため、ファイル作成後は新しいセッションを開始してください。

CLAUDE.md の設定（代替手段）

Skill の代わりに、または併用する形で、プロジェクトの CLAUDE.md に編集方針を記載することもできます。

# プロジェクトの方針

（既存のプロジェクトの記述...）

## cdm の `*.cnb.md` ファイルを編集する場合

`*.cnb.md` ファイルを編集する際は、以下を必ず実行してください。

1. シェルで `cdm --version` と `cdm auth whoami` が両方とも成功することを確認する
   - `cdm` が未インストールの場合は、ユーザにインストールを依頼する（はじめにのページを参照）
   - PAT が無効な場合は、`cdm auth login` での再登録をユーザに依頼する
2. `cdm doc show /guide/for-agents.md` でエージェント向けガイドを取得する
3. そこに記載されたワークフローに従う

すでに CLAUDE.md がある場合は、上記のセクションを追記してください。

CLAUDE.md はプロジェクト全体に常時適用されるため、*.cnb.md を編集しないセッションでもコンテキストに含まれる点に注意してください。*.cnb.md 編集時のみ起動させたい場合は、Skill の利用を検討してください。

トラブルシューティング

Skill が認識されない

• .claude/skills/cdm/SKILL.md のパス構造になっているか確認してください
• Claude Code を再起動してください
• セッション中に skills を追加した場合、/skills コマンドで認識状況を確認できます

cdm コマンドが見つからない

エージェントが「cdm: command not found」と報告した場合、グローバルインストールが必要です。詳細ははじめにを参照してください。

API コマンドが失敗する

• cdm auth whoami で PAT が有効か確認してください
• ノートブックファイルのフロントマター workspace_id と、利用中の profile のワークスペースが一致しているか確認してください