はじめに

この記事は、前回の転送設定・データマート定義のメモ生成を紹介した記事の続きです。

前回は、転送設定とデータマート定義のメモをAIに生成させる方法を紹介しました。

TROCCOの基本機能はあとひとつ、 「ワークフロー」 があります。今回はそのワークフローのメモ生成を、Claude CodeなどのAIコーディングエージェントとTROCCO APIを使って実現する方法を紹介します。

ワークフローのメモ生成は、前回とは違うアプローチが必要

TROCCOのワークフローは、作成した転送設定やデータマート定義を並べて、処理の流れ（データパイプライン）を組むことができる機能です。

この機能を使うことで「バラバラなデータをDWHなど1箇所に集約して、分析可能なデータに加工する」という一連の流れを、パイプラインとして一括管理できます。

ワークフロー定義もYAML形式で設定をコピーできますが、このYAMLはタスクの接続構造しか持っておらず、各タスクの実体（何を転送しているか・どう加工しているか）は含まれていません。
転送設定やデータマート定義はYAMLをそのままAIに渡せば中身を理解してもらえましたが、ワークフロー定義はそのYAMLだけでは「このパイプラインは何をやっているのか」をAIが詳細に把握することができないのです。

そこで今回は、TROCCO APIを使って各タスクの詳細まで取得し、ワークフロー全体としての処理内容をAIにまとめてもらうアプローチを取ります。
AIに難しいコードを生成させるわけではないので、環境さえ整えれば比較的簡単に実践できます。

前提：必要なもの

AIコーディングエージェント

AIにTROCCO APIを実行させるため、AIコーディングエージェントを使用します。
今回は、AIコーディングエージェントに Claude Code（Desktopアプリ版） を使いました。
Desktopアプリ版のClaude Codeは、PCにアプリをインストールすればすぐに使えるうえに、アプリ内でファイルの確認や編集もできるので導入がとても楽です。
※Claude CodeはClaudeの有料プランで利用できる機能です。

Claude デスクトップのダウンロードはこちら：https://claude.com/download

作成するファイル構成などは変わりますが、ChatGPT CodexやCursorなど、他のAIコーディングエージェントでも同様のことは可能です。

TROCCO API機能

TROCCO APIはTROCCOのAdvancedプランで提供されている機能です。
またTROCCO Freeプランでも、アカウント作成後30日間はTROCCO API機能をお試しいただけます。（2026/06現在）

TROCCO APIについてはこちら：TROCCO APIリファレンス

やってみた：ワークフロー定義のメモを自動生成

ということで今回も実際にAIを使ってワークフローのメモを作成してみました。

実践した手順はこの5ステップです。

プロジェクトの作成とCLAUDE.mdの設置
TROCCO APIキーの発行と設置
ワークフローのメモ生成プロンプトを実行
アウトプットを確認して、TROCCOのメモに登録
(+α) プロンプトをSKILL.mdに設定、AIへの指示を簡略化

なお、この手順はClaude CodeとTROCCOの画面を行き来しながら進めます。STEP 1、3はClaude Code側の作業が中心、STEP 2、4はTROCCO側での操作です。あらかじめ両方の画面を並べておくとスムーズです。

STEP 1：プロジェクトの作成とCLAUDE.mdの設置

まずは、Claude Codeの下準備です。
Claude Codeのセッションで利用する作業フォルダを作成し、「TROCCO API 利用ルール」をCLAUDE.mdを配置します。Claude Codeのチャット欄で、下記内容を添えて「この内容でCLAUDE.mdを作成して」と投げてもよいです。

## TROCCO API 利用ルール

- TROCCO API を呼ぶときは、プロジェクトルートの .env の TROCCO_API_KEY を使う
- 各呼び出し前に set -a; source ./.env; set +a で読み込み、ヘッダは Authorization: Token $TROCCO_API_KEY（Bearer ではない）
- ベースURLは [https://trocco.io/api](https://trocco.io/api) 
- 鍵の値は出力しない（echo / cat / 展開値の表示をしない）
- 使うのは GET のみ。PATCH / POST / DELETE は使わない

CLAUDE.md は、Claude Codeがプロジェクトを読み込む際に参照する指示ファイルです。
ここにデータを取得する GETメソッドしか使わない ことを明記しておきます。
TROCCO APIには更新系のエンドポイント（POST/PATCHなど）もあるので、この制約を明示することで意図しないデータ変更を防ぎます。

また、次のステップで発行するTROCCOのAPI KEYを格納する .env ファイルを作成します。これもClaude Codeに指示して作らせました。

この時点では、下記画面のような状態になっています。

STEP 2：APIキーの発行と設置

つぎに、TROCCOでAPIキーを発行します。

TROCCOにログインし、サイドメニューの「外部連携 > TROCCO API KEY」を選択します。
右上の「新規作成」ボタンから、API KEYの新規作成に進みます。

新規作成画面で任意の名前を付けて「保存」ボタンをクリックすると、API KEYが発行されます。
このAPI KEYは画面を閉じると確認できなくなるので、安全な場所に控えておきましょう。

発行したAPI KEYを .env ファイルに保存します。
Claude Codeデスクトップ版では、画面右上メニューの「ファイル」からプロジェクト配下のファイル操作ができるようになっています。便利ですね！

.env ファイルを開き、API KEYを入力して保存します。

.env

TROCCO_API_KEY=(ここに発行したAPI KEYを貼り付け)

注意点

API KEYを発行したユーザーにワークフローの各タスクへの参照権限がない場合は、TROCCO APIでも設定情報を取得できません。

STEP 3：ワークフローのメモ生成プロンプトを実行

ここまでできたら前回と同様に、Claude Codeに対してプロンプトを投げます。
今回はワークフロー定義自体のYAMLもAPIで取得するので、TROCCOからはYAMLではなくワークフロー定義のIDを使います。
プロンプトテンプレートとワークフロー定義のIDをチャット欄に貼り付けて、Claude Codeに投げましょう！

今回作成したプロンプトテンプレートのサンプルも添付します。

ワークフロー定義メモ生成のプロンプトテンプレートはこちら

# 役割
あなたはデータエンジニアリングおよびデータ分析の専門家です。
TROCCOのワークフロー定義（ワークフロー定義IDを指定し、API経由で取得）を読み解き、指定されたMarkdownテンプレートに従ってワークフロー定義の概要を作成してください。

# 目的
ワークフロー名・各タスク名・参照する転送設定／データマート定義から「これがどのような業務データの流れ（ドメイン知識）なのか」を推測・分析し、非エンジニアでも理解できる日本語の説明を作成すること。

# 取得プロセス（API）※このプロセスは変更しないこと
- 入力はワークフロー定義ID（例: 12345）。

1. GET /api/pipeline_definitions/{id} でワークフロー全体を取得する。
   - 各タスクは key と type、種別ごとの *_config（中に name と definition_id）を持つ。
   - 処理順序は task_dependencies（source→destination、いずれもタスクの key）から組む。
   - スケジュールは schedules、通知は notifications、停止・リトライ方針は is_stopped_on_errors／max_retries／min_retry_interval から読む。
2. タスクを type で振り分けて深掘りする（IDは必ずレスポンスの該当 config から拾う。推測しない）：
   - trocco_transfer            → trocco_transfer_config.definition_id で GET /api/job_definitions/{id}
   - trocco_bigquery_datamart   ┐
   - trocco_redshift_datamart   │ それぞれの trocco_*_datamart_config.definition_id で
   - trocco_snowflake_datamart  │ GET /api/datamart_definitions/{id}
   - trocco_databricks_datamart ┘
   - trocco_pipeline            → trocco_pipeline_config.definition_id で GET /api/pipeline_definitions/{id}
                                  （ネスト。1階層だけ。循環に注意し、深い階層は未解決として注記）
   - trocco_dbt                 → GET /api/dbt_job_definitions/{dbt_job_definition_id}
   - trocco_transfer_bulk       → 取得エンドポイントが無いので trocco_transfer_bulk_config.name のみ使う
   - bigquery_data_check / redshift_data_check / snowflake_data_check / databricks_data_check /
     http_request / if_else / slack_notify / tableau_extract
                                → 追加取得しない。各 *_config 内の情報をそのまま使う。
                                  if_else は if_else_config.condition_groups の条件と
                                  destinations.if / destinations.else から分岐を読み取る。
3. 叩く前に「これから GET するエンドポイントとID」を一覧表示する。
4. 取得できなかったもの（403/404 等）は握りつぶさず「未解決」として明記する。
   ※ 軽い概要でよければ手順2の深掘りは省略し、各 *_config.name と依存関係だけで作ってよい。

# 思考プロセス（分析手順）
1. ワークフロー名・各タスク名から、どのシステムやサービスに関するデータパイプラインかを推測する。
2. 各タスクの種別と参照設定（転送元→転送先、データマートのクエリ目的、データチェックの条件など）から、「データがどこから来て、どう加工され、どこへ向かう処理なのか」を読み解く。
3. 読み解いた内容をベースに、説明文を「〇〇のデータを取り込み、△△に整形して□□へ格納する一連の処理」という流れの解説に昇華させる。

# 制約事項
- スケジュール・通知・停止/リトライ方針はAPIレスポンスから埋める。APIに含まれない情報（実行時間目安・設定の管理者など）は、テンプレートの項目名だけを残し、空欄にする。
- 推測が難しい場合は、名称から最低限読み取れる事実のみを記載する。
- 認証情報・パスワード等の値、APIキー本体は出力しない。
- 出力は必ず「``markdown」と「`」で囲んだコードブロック形式にする。概要本文の中では ``（三連バッククォート）を使わない。

# アウトプット
ワークフロー概要は、以下の出力テンプレートをもとに、コピー＆ペースト可能なMarkdown形式のコードブロックで出力してください。

# 出力テンプレート
以下のフォーマット（コードブロックごと）で出力してください。

# 概要
説明：

## 処理の流れ
（task_dependencies の順。例：転送A → データチェックB → データマートC）

## 各タスク
### （タスク名）（種別）
- 内容：
- 参照設定：（転送設定ID／データマート定義ID など）

# 運用
- スケジュール：
- 実行時間目安：
- エラー発生時：（タスク失敗時の停止有無・リトライ方針）
- 設定の管理者：

# 通知
- 通知先：（Slack／メール、通知タイミング）

# トラブルシューティング履歴
-- エラー発生時の対応や設定変更などの履歴

## 日付
-- エラーログ
-- 解消に向けてやったこと

# インプット（ワークフロー定義ID）
---
[ここにワークフロー定義のIDを入力]
---

実行中は、ファイルへのアクセスやAPIの実行などの許可を求められます。内容を確認したうえで許可しつつ進めましょう。

ざっくりとした解説ですが、Claude Codeは下記のような処理を実行するはずです。

TROCCO APIでワークフロー情報（タスク一覧・接続構造）を取得
各タスク（転送設定・データマート定義など）の詳細をTROCCO APIで個別に取得
取得した全情報をもとに、ワークフロー全体の処理概要を生成

ワークフロー定義のYAMLだけでは見えなかった「このパイプラインは何をやっているか」を、AIが各タスクの中身まで読み解いてまとめてくれます。

STEP 4：アウトプットを確認して、TROCCOのメモに登録

Claude Codeがワークフローの概要を生成しアウトプットしてくれたら、生成されたメモを確認し内容に問題がなければ、TROCCOのワークフロー定義の編集に入り、メモ欄に貼り付けます。
※AIが生成した内容をそのまま使うのではなく、必ず内容を確認してから登録するとをおすすめします。

これで、ワークフローの概要をメモから確認できるようになりました。

STEP 5：+α SKILL化でさらに効率化

ここまでで、ワークフローのメモを生成する一連の流れはできました。

ただ、毎回プロンプトをコピペするのは手間なので、Claude Codeの「SKILL」として登録しておくと便利です。
SKILL化することで、「ワークフロー12345のメモを作成して」 と投げるだけで動くようになります。

STEP 3が完了したセッションで、そのまま「SKILL化して」とClaude Codeに投げれば、SKILLを作ってくれます。
生成したSKILLにはプロンプトテンプレートの内容が記載されます。以後はここを修正することで、出力するメモのフォーマットも変更できます。

最終的に下記のような構造でファイルが作成されているはずです。

{プロジェクトルートフォルダ}/
├── .env              # TROCCO APIキー（チームで共有しないもの）
├── .env.example       # チーム共有用のテンプレート
├── CLAUDE.md         # AIへの共通指示ファイル（API実行時のルール）
└── .claude/
    └── skills/
        └── {SKILL化で生成されたフォルダ}/
            └── SKILL.md  # SKILLファイル（ワークフロー概要作成のプロンプト）

作成したプロジェクトごとチームで共有すれば、チーム内でのメモ生成品質を統一できます。
今回実践した内容は複雑なコードやプラグインなども使用していないので、Claude Codeが使えれば他のメンバーも同じ環境をすぐに構築し実行できます。
（.env は共有せず、.env.example のみを配布しましょう）

発展：更新まで全自動化することも可能

TROCCO APIには、各種設定を更新するエンドポイントも用意されているので、CLAUDE.mdのルールを変更してPOSTメソッドを許可すれば、メモの登録までAIに任せることも可能ではあります。
SKILLもカスタマイズすれば、各タスク（転送設定・データマート定義）のメモ生成から登録まで、ほぼ自動化することもできます。

ただし、全てをAIに丸投げすることはリスクでもあります。 AIが何をやっているかを理解し、アウトプットの品質まで適切にコントロールすることが重要です。処理過程を把握しつつ段階的に自動化の範囲を広げていくのがおすすめです。

おわりに

前回に引き続き、TROCCOのメモ自動生成を題材に、なるべく作り込むことなくAIで効率化する方法をご紹介しました。
今回はAIコーディングエージェントを使いましたが、生成したファイルはほぼMarkdownファイルになっており、基本的には自然言語で記載されています。
AIが登場するまではPythonなどのプログラミング言語を駆使して実装していた処理も、AIを活用することで非エンジニアでも理解しやすい形で実装でき、効率化のハードルもかなり低くなったと感じました。

また、こういった取り組みはデータエンジニアリングスキルをレベルアップするきっかけにもなると思いますので、AIを使ったTROCCO利活用促進のステップとして、ぜひ試してみてください！