Tsumiki の Kairo コマンドを使ってBigQueryテーブルのdescription自動生成ツールを作らせてみる
2025.08.28データ事業本部のsutoです。
クラスメソッドから AI 支援型テスト駆動開発フレームワークの「Tsumiki」が公開されています。
私も試しに使ってみたいなと思い、
Tsumiki は Claude Code での利用を前提としています。よって私はVSCodeの拡張機能として「Claude Code for VSCode」を入れてVisual Studio Code環境のなかでClaude Code(Tsumiki)を実行していこうと思います。
AI 支援型テスト駆動開発フレームワーク『Tsumiki』について
Tsumiki は Claude Code を使用して効率的な開発プロセスを要件定義から設計、タスク分割、実装まで体系化して提供します。主に使用できるコマンドは以下となります。
Kairoコマンド（包括的開発フロー）
- kairo-requirements - 要件定義
- kairo-design - 設計文書生成
- kairo-tasks - タスク分割
- kairo-task-verify - タスク内容確認
- kairo-implement - 実装実行
TDDコマンド（個別実行）
- tdd-requirements - TDD要件定義
- tdd-testcases - テストケース作成
- tdd-red - テスト実装（Red）
- tdd-green - 最小実装（Green）
- tdd-refactor - リファクタリング
- tdd-verify-complete - TDD完了確認
リバースエンジニアリングコマンド
- rev-tasks - 既存コードからタスク一覧を逆生成
- rev-design - 既存コードから設計文書を逆生成
- rev-specs - 既存コードからテスト仕様書を逆生成
- rev-requirements - 既存コードから要件定義書を逆生成
DIRECTコマンド（TASK 作成時に DIRECT と判定している場合に使用）
- direct-setup - DIRECTタスクの設定作業の実行
- direct-verify - DIRECTタスクで実行した設定作業の動作確認とテスト
今回は初めての実践なので凝ったことはせず、要件定義（kairo-requirements）からリソースの実装（kairo-implement）まで、人間による途中の加筆修正をほとんど加えずにどこまでのリソースが生成されるかを見ていこうと思います。
やってみた
Claude Codeのインストールが完了していることを前提に、以下のURLのReadMeを参考にTsumikiのインストールを行います。
今回はタイトルにあるとおり、「BigQueryテーブルのdescription自動生成するCLIツール」を構築できるか試してみます。
要件定義書作成(/kairo-requirements)
さっそくClaude Code で /kairo-requirements コマンドを実行すると、要件の概要を入力するよう求められます。
他の方の生成AI系の記事だと、「〇〇なことができるアプリを作って」、「〇〇できるツールを作って」などの一言や一行の文章でどれだけのものが作れるかを見せているのがほとんどだと思いますので、私はもう少し詳しく要件を箇条書きにまとめたものを伝えて、どれだけのものが作られるか見てみようと思います。以下の文章を入力して実行してみました。
Bigqueryの既存テーブルに、Descriptionを自動で付与できるCLIツールの構築をしたいです。要件は以下です。
・自然言語による入力で、Bigqueryの既存テーブル名とテーブルに関する情報が記載してあるGoogleスプレッドシートを指定する
・指定したテーブルのDDLを取得後、Gemini APIを使用して、DDLの内容とスプレッドシートの情報を参考にテーブルとカラムのdescriptionを自動生成する
・自動生成したdescriptionを反映したDDLのSQLを生成する
・生成したDDLについて、GitHubにプルリクエストを作成する
コマンドが終了すると、次のように docs/spec フォルダ内に要件定義書が作成されました。
要件定義書.md
# BigQuery テーブルDescription自動付与CLIツール 要件定義書
## 概要
BigQueryの既存テーブルに対して、自然言語入力とGoogleスプレッドシート情報を基に、Gemini APIを活用してテーブルおよびカラムのDescriptionを自動生成し、DDLの更新からGitHubプルリクエストの作成まで一連の流れを自動化するCLIツール。
## ユーザーストーリー
### ストーリー1: テーブルDescription自動付与
- **である** データエンジニア **として**
- **私は** 既存BigQueryテーブルにDescription情報を効率的に付与 **をしたい**
- **そうすることで** テーブルの理解性と保守性を向上させ、チーム内でのデータ資産の活用を促進できる
### ストーリー2: 自然言語による簡単操作
- **である** データアナリスト **として**
- **私は** 複雑な設定なしに自然言語でテーブル情報を指定 **をしたい**
- **そうすることで** 技術的な詳細を知らなくてもテーブルのドキュメント化を実行できる
### ストーリー3: 自動PR作成によるワークフロー統合
- **である** プロジェクトマネージャー **として**
- **私は** Description更新作業をコードレビューワークフローに統合 **をしたい**
- **そうすることで** 変更の透明性と品質管理を確保できる
## 機能要件（EARS記法）
### 通常要件
- REQ-001: システムは自然言語による入力でBigQueryテーブル名を受け付けなければならない
- REQ-002: システムはGoogleスプレッドシートのURLまたはIDを受け付けなければならない
- REQ-003: システムは指定されたテーブルのDDLを BigQuery API経由で取得しなければならない
- REQ-004: システムはGemini APIを使用してDescription文を自動生成しなければならない
- REQ-005: システムはDescriptionを日本語で生成しなければならない
- REQ-006: システムは生成されたDescriptionを含むDDL SQLを出力しなければならない
- REQ-007: システムはGitHubにプルリクエストを自動作成しなければならない
### 条件付き要件
- REQ-101: テーブルが存在しない場合、システムはエラーメッセージを表示して処理を終了しなければならない
- REQ-102: スプレッドシートにアクセスできない場合、システムは代替手段またはエラー処理を実行しなければならない
- REQ-103: Gemini API呼び出しが失敗した場合、システムはリトライ機構を実行しなければならない
- REQ-104: GitHub APIへのアクセスが失敗した場合、システムは生成されたDDLをローカルファイルとして保存しなければならない
### 状態要件
- REQ-201: 認証情報が設定されていない状態の場合、システムは認証設定のガイダンスを表示しなければならない
- REQ-202: DDL生成済みの状態の場合、システムはプレビュー表示と確認プロンプトを提供しなければならない
### オプション要件
- REQ-301: システムは生成されたDescriptionの編集機能を提供してもよい
- REQ-302: システムは複数テーブルの一括処理機能を提供してもよい
- REQ-303: システムはDescription生成ルールのカスタマイズ機能を提供してもよい
### 制約要件
- REQ-401: システムはGoogle Cloud認証を適切に処理しなければならない
- REQ-402: システムはGemini API使用量制限を考慮しなければならない
- REQ-403: システムはGitHub APIレート制限を考慮しなければならない
## 非機能要件
### パフォーマンス
- NFR-001: DDL取得は30秒以内に完了しなければならない
- NFR-002: Description生成は1テーブルあたり2分以内に完了しなければならない
- NFR-003: GitHub PR作成は1分以内に完了しなければならない
### セキュリティ
- NFR-101: システムは認証情報を安全に管理しなければならない
- NFR-102: システムはAPIキーをログに出力してはならない
- NFR-103: システムは最小権限の原則に従ってアクセス権を設定しなければならない
### ユーザビリティ
- NFR-201: システムは直感的なコマンドラインインターフェースを提供しなければならない
- NFR-202: システムは処理状況を分かりやすくユーザーに表示しなければならない
- NFR-203: システムはエラー発生時に有用なエラーメッセージを表示しなければならない
### 可用性
- NFR-301: システムはネットワーク一時的障害に対する耐性を持たなければならない
- NFR-302: システムはAPI呼び出し失敗時の適切な復旧機能を提供しなければならない
### 互換性
- NFR-401: システムはmacOS、Linux、Windows環境で動作しなければならない
- NFR-402: システムはPython 3.8以上で動作しなければならない
## Edgeケース
### エラー処理
- EDGE-001: BigQueryテーブルに権限がない場合の処理
- EDGE-002: スプレッドシートが空または形式が不正な場合の処理
- EDGE-003: Gemini APIからレスポンスが異常な場合の処理
- EDGE-004: GitHubリポジトリに書き込み権限がない場合の処理
- EDGE-005: ネットワーク接続が不安定な場合の処理
### 境界値
- EDGE-101: 非常に大きなテーブル（1000カラム以上）の処理
- EDGE-102: 特殊文字を含むテーブル名・カラム名の処理
- EDGE-103: Gemini APIの1リクエスト当たりの文字数制限への対応
- EDGE-104: 日本語・英語混在環境での処理
### データ整合性
- EDGE-201: 既存Descriptionが設定されているテーブルの処理方針
- EDGE-202: DDL実行中にテーブル構造が変更された場合の処理
- EDGE-203: 複数ユーザーが同時に同一テーブルを処理する場合の競合回避
## 受け入れ基準
### 機能テスト
- [ ] 自然言語入力でテーブル名とスプレッドシートを正しく指定できる
- [ ] BigQuery APIを使用してDDLを正常に取得できる
- [ ] Gemini APIを使用してDescription文を生成できる
- [ ] 生成されたDescriptionを含むDDLが正しい構文で出力される
- [ ] GitHub APIを使用してプルリクエストが作成される
- [ ] 存在しないテーブルを指定した場合に適切なエラーが表示される
- [ ] 認証エラー時に分かりやすいガイダンスが表示される
### 非機能テスト
- [ ] 典型的なテーブル（50カラム程度）で2分以内に処理が完了する
- [ ] APIキーがログファイルやコンソール出力に表示されない
- [ ] ネットワーク障害時に適切にリトライされる
- [ ] 複数プラットフォーム（macOS、Linux、Windows）で動作する
- [ ] 日本語を含むテーブル名・カラム名が正しく処理される
### ユーザビリティテスト
- [ ] 初回ユーザーが認証設定を10分以内に完了できる
- [ ] コマンドライン引数の指定方法が直感的である
- [ ] エラー発生時にユーザーが次にとるべき行動が明確である
- [ ] 処理進行状況がリアルタイムで確認できる
## 技術的制約
### 依存関係
- Google Cloud SDK
- GitHub CLI または GitHub API アクセストークン
- Gemini API アクセス権限
- Python環境（3.8以上）
### API制限
- BigQuery API: 1日あたり100,000リクエスト（デフォルト）
- Gemini API: 1分あたり60リクエスト（利用プランに依存）
- GitHub API: 認証済みユーザー 1時間あたり5,000リクエスト
### 設定要件
- `~/.config/gcloud/` にGoogle Cloud認証情報
- GitHub認証情報（トークンまたはCLI認証）
- Gemini API キー（環境変数または設定ファイル）
---
**作成日:** 2025-08-20
**バージョン:** 1.0
**ファイルパス:** `docs/spec/bigquery-description-cli-requirements.md`
メインの機能要件から日機能要件、テスト要件までしっかり考慮されていました。
要件定義書を元に設計(/kairo-design)
要件定義書がある程度出来たので、それを元に設計を行います。
/kairo-design コマンドを実行し、完了後に以下のようにdesignフォルダの配下に設計書が作成されました。
しっかりとコンポーネント構成が出力されていました。API設計に関する部分のほか、ツールの実行履歴やログ保存のためのデータベーススキーマ設計まで考慮されていました。（今回は外部APIをリクエストするので永続化が必要なDBテーブルは必要ないと思ったのですが、ログやキャッシュのことまで考慮してしっかり作り込んでくれるものができて驚きました。）
設計書をもとにタスク整理(/kairo-tasks)
設計書をもとに実装の準備を行なってくれます。
/kairo-tasks を実行してリソース実装のためタスクリストを作成・整理します。
完了後、以下のようなタスクリストが作成されました。
依存環境のインストールからリソースの実装、テストまでしっかり網羅されていました。（今回はフェーズ1〜6までありました）
推定作業時間やクリティカルパスが表示されているのがすごいですね。
タスクの実装(/kairo-implement)
最後にタスクの実装を行いましょう。
/kairo-implements コマンド実行で、タスクリストの内容に従ってリソースの実装が始まります。
依存関係のインストールからやってくれるので、開発環境準備などの面倒ごともすべてやってくれるみたいです。
たとえ実行コマンドでエラーが起きても、エラー修正をしながら実装を進めてくれています。
また、要所で必要かつ可能なテストケースの消化をしながら実装を進めて行ってるように見えたので、ユーザーで考える開発プロセスよりも効率的に遂行していってくれているのではないかと思いました！
また、完了したタスクにはチェックがついて進捗管理もできていました。
今回は「フェーズ1: 基盤構築」のタスクが完了した時点で、一旦実装がストップしてClaude CodeのCLIに戻ってきました。
なのでタスクの続きを行うよう指示する or 再度 /kairo-implement を実行すると「フェーズ2: 認証・外部API基盤」の実装を開始してくれました。
途中経過までのClaude Codeで発生した料金は以下となります。
- 8/20：
/kairo-requirements、/kairo-designの実行 - 8/22：
/kairo-tasksの実行（入力ミス等で１度やり直しています） - 8/25：
/kairo-implementの実行（フェーズ1〜フェーズ2の途中まで） - 8/26：
/kairo-implementの実行（〜フェーズ3の途中まで） - 8/27：
/kairo-implementの実行（〜フェーズ3まで） - 8/28：
/kairo-implementの実行（〜フェーズ4の途中まで）
当たり前ですが、構築するリソースが予想より多かったため実装に多くのコストがかかっています。
さいごに
Tsumikiを使ってBigQueryに関連するツールの作成の様子を紹介しました。
メイン機能といくつかのエラーハンドリングがしっかり構築できれば十分と思っていたところ、セキュリティ、パフォーマンス、可用性など、本番環境の導入をしっかり見据えたコンポーネント群が生成されたことに驚きました。
次は、実装完了まで進めてみて、リソースがちゃんと動作するのか検証していこうと思います。
また、Kiroも似たようなことができるはずなので、いずれKiroも触ってみようと思います。
【追記】
公式からdescription自動生成の機能出ましたね。。。
どうやら日本語出力には対応していなさそうです。
どんな情報から生成してくれるのか、内部仕様も気になるところです。
