こんにちは、関根です。
この記事は、Claude Desktopの「Code」モード（Claude Code相当の機能）を使って、実際に手を動かしながらGUIツールを1本作ってみるハンズオン記事です。使用モデルはSonnet 5、所要時間の目安は20〜30分程度です。ぜひ手元のPCでこの記事の通りに進めてみてください。
プロンプトを1回投げて終わり、ではなく、プラン→UI生成→ロジック生成→マニュアル作成の4ステップに分け、1ステップ終わるたびに手を止めて内容を確認しながら進めるのがこのハンズオンのポイントです。一気に全部作らせてしまうと、次のような問題が起きがちです。
- たくさんの機能を同時に作らせると、1つの指示に詰め込む内容が増え、それだけ手戻りも大きくなる
- ロジックを実装した後にUIを直そうとすると、依存関係が絡み合っていてものすごく時間がかかる
- 途中の設計判断のズレに気づくのが最後になり、どこまで戻ってやり直すべきか切り分けづらい
ステップごとに区切ることで、こうした問題を1つずつ早い段階でつぶしながら進められます。
さらには、チームの誰かにそのまま渡して使ってもらえるレベルのものをリリースするところまでを見据えて進めていきます。
前提・事前準備事項
- Claude Desktop
- ライセンス：Proプラン以上（Claude Codeは有料プランのみで利用可能。フリープランでは利用できません。Claude ConsoleでのAPI従量課金でも利用可能です）
- Python 3.13以上
- 本ハンズオンはWindows環境でテストしています
ハンズオンで作るもの
- Claude Codeのセッションログ（
.jsonl）を読み込んで、トークン使用量と概算金額を集計・表示するGUIツール - 技術構成：Python 3 + tkinter（標準ライブラリのみ）
- 追加インストールが発生しない構成なので、Pythonさえ入っていればすぐに試せます
制約事項
- 料金計算の前提はSonnet 5のみ
- 通常価格で算定（割引等は考慮しません）
- 料金はAPI・Amazon Bedrockなどを従量課金で利用した場合の価格です。Pro/Maxプランなど定額プランで使っている場合の実際の請求額とは関係ありません
- ツール上の概算金額はあくまで目安です
- ハンズオン効率化のため、テストは必要最低限にしています
事前準備：2つのファイルを用意する
まず、空の作業フォルダを1つ作り、そこに以下の2つのMarkdownファイルを置いてください。この2ファイルだけを用意した状態からハンズオンをスタートします。
① CLAUDE.md（進め方のルール）
Claude Codeは、作業フォルダにCLAUDE.mdがあると自動的に読み込んで指示として扱います。ここに「段階的に進めること」「1ステップごとに確認を取ること」を明記しておくのがこのハンズオンの肝です。以下をそのままコピーしてCLAUDE.mdとして保存してください。
# CLAUDE.md
このプロジェクトは、Claude Codeのセッションログからトークン使用量を集計・表示するGUIツールを開発するハンズオン用プロジェクトです。
技術仕様・データ仕様の詳細は `トークン量ツール.md` を参照してください。
## 進め方（このハンズオンの進行手順）
**重要: 全自動で作らないこと。** プランが承認されても、以下のステップをまとめて一気に実装しないでください。1ステップ実装が終わるたびに必ず手を止め、「次は〇〇（次のステップ名）を実施していいですか？」とユーザー（学習者本人）に質問し、明示的な許可を得てから次のステップの実装を開始すること。
以下の順序で、Claude Codeに段階的に指示を出して進めてください。1ステップずつ結果を確認しながら次に進みます。
1. **プラン**
まずプランモードに明示的に切り替えてから（「プランモードで進めて」と明示的に指示する）、`トークン量ツール.md` を読み込ませ、実装方針を計画してもらう。
仕様書には意図的に空欄（配色など）を残してあるため、Claudeから質問（QA）が出ることを想定している。質問には進行役がその場で回答して仕様を確定させる。プランの内容に合意できたらプランモードを終了し、実装に進む。
プラン計画後、確定した実装方針をプロジェクトルートに `プラン.md` として保存すること。
2. **UI生成**
ロジックは後回しにし、画面レイアウト（ウィジェット配置）だけを先に実装してもらう。ダミーデータで見た目を確認する。
3. **ロジック生成**
ファイル読み込み・トークン集計・CSV出力・日付範囲フィルタなどの実際の処理を実装してもらう。
4. **マニュアル作成**
完成後、使い方をまとめた簡単なマニュアルを作成してもらう。
## テストについて
自動テストは必要最低限でよい。トークン集計ロジックが正しく動くことを簡単に確認できれば十分（サンプルのjsonlを1つ読ませて合計値が合っているか目視確認する程度）。網羅的なテストコードは不要。
## 時間の目安
このハンズオン全体を30分以内で終えることを目標にする。過度に作り込まず、上記の進め方に沿ってテンポよく進める。
② トークン量ツール.md（仕様書）
もう1つ、要件をまとめた仕様書も用意します。ポイントは、あえて一部を空欄のままにしておくことです。配色やデフォルトパスなど、決め切らずに残しておくと、Claudeが実装前に質問してくるようになります。仕様を対話的に確定させていく体験そのものが、このハンズオンの見どころの1つです。
# トークン量ツール 仕様書
Claude Codeのセッションログ（jsonl）を読み込み、トークン使用量を表示するGUIツールの仕様。
## 技術仕様
・言語: Python 3
・GUI: tkinter（標準ライブラリのみで完結させる。追加インストールが発生する構成は避ける）
・外部ライブラリの追加は最小限にする（標準ライブラリで足りるならそれを優先。CSV出力も標準の`csv`モジュールでよい）
## 画面仕様
・ファイルパスを指定する入力欄（後述）
・読み込みボタン
・集計結果を表示するテーブルまたはリスト
・プロジェクトごと / セッションごとにトークン量を表示
・表示するトークン種別: input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens, 合計
・上記トークン量から算出した概算金額（USD）も表示する
・全体合計（トークン量・金額）を表示するエリア
・配色・フォント・全体的な見た目: （未定）
## ファイルパス仕様
・対象パス: `＜プロジェクトルート＞` 以下の各プロジェクトフォルダにある `*.jsonl`（Claude Codeのセッションログが保存されているフォルダ）
・デフォルトのパス（未定）: 実装前にユーザーに質問して確定すること
・画面上で任意のパスに変更できるようにする（テキスト入力 or フォルダ選択ダイアログ）
## ログデータ仕様
・1行1JSONのセッションログ
・assistantメッセージの `message.usage` にトークン情報が入っている
・`input_tokens`
・`output_tokens`
・`cache_creation_input_tokens`
・`cache_read_input_tokens`
・`timestamp`（ISO8601, UTC）、`sessionId`、`cwd` も同じ行に含まれる
## 金額計算仕様
・対象モデルは Sonnet 5 のみでよい（他モデルの料金は考慮しない）
・単価（1Mトークンあたり、USD）
・input_tokens: $3.00
・output_tokens: $15.00
・cache_creation_input_tokens: $3.75（5分キャッシュ想定。入力単価の1.25倍）
・cache_read_input_tokens: $0.30（入力単価の0.1倍）
・各トークン種別 × 単価 ÷ 1,000,000 を合算して金額を算出する
・単価は将来的に変わりうるため、コード中に定数として分かりやすく定義しておく
## 機能
### 必須機能
・指定フォルダ配下の `*.jsonl` を再帰的に読み込み、トークン量を集計して表示する
・集計したトークン量から概算金額（USD）を算出して表示する
### 選択機能（トグルやチェックボックスなどで有効/無効を選べるようにする）
・CSV出力: 集計結果をCSVファイルに書き出す
・日付範囲での絞り込み: `timestamp` を基準に期間を指定して集計対象を絞る
## マニュアル作成
・原則Markdown形式で作成する
・作成するタイミングで「Markdown」または「画像付きHTML」を選択する（作業者に選んでもらう）
・マニュアル作成はハンズオンの最後の工程のため、残り時間を踏まえて作業者に選択してもらうこと
## 補足
・上記以外の細かい仕様は決めていません。実装を進める中で不明点があれば質問してください。
・30分程度で完成させたいため、必要以上に機能を増やさないでください。
ファイルを2つ用意できたら、Claude Desktopでその作業フォルダをプロジェクトとして開いてください。
作業フォルダの中身はこの2ファイルだけでOKです。
STEP 1：プランを作ってもらう
まずモード切り替えでプランモードにします。プランモードでは、Claudeがファイルの編集を行わず「計画を立てる」ことに専念してくれるので、いきなりコードが書き始まってしまう事故を防げます。
Claude Desktopは次の設定にしてください。
- 左上：Codeモード
- 下中央：プランモード
- 下右：Sonnet 5・高
- 作業フォルダ：先ほど2ファイルを置いたフォルダを指定
この状態からスタートします。まだ何も入力していない初期画面です。
準備ができたら、チャット欄に以下のように入力してみましょう。半角@を打つとファイル選択のポップアップが出るので、そこから仕様書を指定します。
@トークン量ツール.mdを作成してください
送信すると、Claudeはまずセッションログの実際の保存場所を自分で確認しにいきます。そのうえで、仕様書に書かれていない項目について質問が届きます。
「対象パスのデフォルト値はどうしますか？」「配色・見た目のテイストはどうしますか？」といった質問が選択肢付きで届きます。
配色もこの時点で選択肢から決められます。今回は「シンプルな配色を指定」を選びました。
回答すると、数十秒でプランが右側パネルに表示されます。Context（背景）・確定した仕様・技術構成・画面構成方針・実装ステップまで、この後の作業内容が整理されて出てきます。中身に問題がなければ「承認」ボタンを押してください。
プランは、プラン.mdに保存されます。内容に問題がなければ、「はい」と返信して次のステップに進みます。
STEP 2：UIを作ってもらう
ここからはステップバイステップで実装していきます。まずはUIです。
ステップ2では、あえてロジックを実装せず、画面レイアウトだけをダミーデータ付きで作ってもらいます。Claudeが自動でPythonファイルを作成し、実際に起動して見た目を確認できる状態にしてくれます。
UIの構成内容を説明しつつ、目視確認を依頼してきます。
しばらく待つと、tkinter製のウィンドウが立ち上がります。プロジェクト・セッションごとにツリー表示でトークン量が並び、下部に全体合計が表示されるレイアウトです（中身はまだダミーデータです）。実際に手元で操作して、レイアウトに問題がないか確認してみてください。
ダミーデータ付きのUIが起動します。レイアウトの確認はこの時点で済ませておきましょう。
TIPS
もし画面が閉じてしまった場合は、「画面をもう一度開いて」とお願いしてみてください。
見た目に問題がなければ、「はい」と返信して次のステップに進みます。
STEP 3：ロジックを作ってもらう
ステップ3では、ファイル読み込み・トークン集計・CSV出力・日付範囲フィルタなど、実際の処理を実装してもらいます。金額計算の単価は、仕様書に書いた以下の値がそのままコードの定数として埋め込まれます。
トークン金額はSonnet 5の通常価格です（https://platform.claude.com/docs/ja/about-claude/pricing）。
| トークン種別 | 単価（1Mトークンあたり） |
|---|---|
| input_tokens | $3.00 |
| output_tokens | $15.00 |
| cache_creation_input_tokens | $3.75 |
| cache_read_input_tokens | $0.30 |
ステップ3が始まると、Claudeはサンプルのsession1.jsonlを自分で作成し、手計算した期待値と突き合わせてロジックを検証してくれます。ここでバグが見つかることも珍しくありませんが、見つかった場合はそのままClaudeが自動で修正してくれます。
ここで、サンプルデータだけでなく自分の実際のセッションログ（C:\Users\＜ユーザー名＞\.claude\projects配下）を対象に、GUIの「読み込み」ボタンから動作確認をしてみましょう。ふだん自分がどれくらいトークンを使っているか、実感を持って確認できるはずです（料金は目安です）。
実際の作業フォルダを読み込んだ結果の例。日付範囲での絞り込みも確認できます。
TIPS
もし画面が閉じてしまった場合は、「画面をもう一度開いて」とお願いしてみてください。
実装した機能は次のとおりです。
- 指定フォルダ配下の
*.jsonlを再帰的に読み込み、プロジェクト/セッションごとにトークン量を集計 - 日付範囲フィルタ（timestampの日付部分で絞り込み）
- 概算金額の算出（仕様書の単価定数どおり）
- CSV出力（utf-8-sigでExcelでも文字化けしないように保存）
- フォルダが存在しない場合などのエラーメッセージ表示
ロジック生成が完了すると、実装内容のサマリーとともに次のステップへの確認が届きます。
ロジックに問題なければ、「はい」と返信して次のステップに進みます。
STEP 4：マニュアルを作ってもらう
最後にマニュアルを作ってもらいます。ここでは形式をどちらにするか選択肢が出てくるので、残り時間に応じて選んでください。
- Markdown：テキストのみで手早く完成する
- 画像付きHTML：実際の画面スクリーンショットを挿入した見やすいマニュアルになるが、作成に時間がかかる
「マニュアルの形式はどちらにしますか？」と聞かれるので、好きな方を選びましょう。
TIPS
HTML版の場合はスクリーンショットを取得していますので、生成中は画面の操作を控えてください。
画像付きHTMLを選んだ場合の完成例。手順ごとに実際のスクリーンショットが自動挿入されます。
ここまでで、実際に動くGUIツールと使い方マニュアルが完成しているはずです。お疲れさまでした。
今後の拡張ポイント
今回はハンズオンの時間内に収めるため、あえて手を付けなかった部分もあります。慣れてきたら、こうした拡張もClaude Codeに追加で頼んでみてください。
- 起動バッチ（
起動.bat）の作成：ダブルクリックで起動できるようにする - 金額表示を円建てに対応：為替レートを定数または取得APIで扱う
- 他モデル（Opus・Haiku等）の単価にも対応：モデルごとの単価テーブル化
- 集計結果のグラフ表示：日別・プロジェクト別の推移をグラフ化
- 数値表示のスケール調整：桁数が大きいトークン数をK・M単位で見やすく表示
まとめ
今回は、Claude Codeに「プラン→UI生成→ロジック生成→マニュアル作成」の4ステップで段階的に指示を出しながら、トークン集計ツールを1本作ってみました。一気に全部を任せてしまう方が早そうに見えますが、実際にはたくさんの機能を同時に作らせるほど手戻りが大きくなりますし、ロジックを実装した後にUIを直そうとすると余計な時間がかかりがちです。ステップごとに立ち止まって確認する分、多少遠回りに感じるかもしれませんが、その分だけ「自分のPCでとりあえず動けばいい検証ツール」ではなく「チームの誰かにそのまま渡して使ってもらえるもの」に近づいていきます。
やってみるときのコツは、次の3つです。
- 仕様書はあえて空欄を残す：最初からすべて決め切らず、配色やデフォルト値などを空欄にしておくと、Claudeが質問してくる流れが生まれます。選択肢から選ぶだけで仕様が対話的に確定していきます。
- 「次に進んでいいですか？」には必ず答えてから進める：CLAUDE.mdに「段階的に進めること」を明記しておくのが肝です。ステップの節目で必ず立ち止まる設計にすることで、手戻りを最小限に抑えられます。
- 動かないものは、動かないとそのまま伝える：画面が閉じてしまったといったトラブルは、AIも一発では気づけません。「画面を開いてください」の一言で、素直に再び開いてくれます。
今回作ったCLAUDE.mdと仕様書はそのままコピーして使えるので、ぜひ手元の環境で試してみてください。慣れてきたら、仕様書の内容を自分の作りたいツールに差し替えて、同じ流れで別のアプリを作ってみるのもおすすめです。