🧑‍🔧
Claude Code に不具合調査の立ち上がりをフォローしてもらう（Notion × Google Cloud）

2025/12/14に公開
 はじめにClaude Code のリリース以降、そのコーディング能力の高さに助けられている方は多いのではないでしょうか。

この記事では、単にコードを書くだけでなく、サブエージェント（Sub-agents） や スキル（Skills） を活用して開発現場の不具合調査の立ち上がりも助けてもらったフローを紹介します。

 前提この記事では、以下の環境を前提にしています
不具合管理は Notion でおこなう
インフラは Google Cloud

 TL;DR
課題: 不具合調査の際、Notion のチケットを読み込んでからログ検索クエリを組み立てるまでの「コンテキストスイッチ」と「手作業」が地味に辛い

解決策: 「情報の抽出（トリアージ）」と「クエリ生成（分析）」を別々のサブエージェントに担当させ、ログ検索の記法はスキルとして定義する仕組みを構築

成果: コマンド一発で Notion の URL から「整理された JSON」と「即実行可能な Cloud Logging クエリ」が生成され、調査開始に着手しやすい状態に

 本題
 地味に辛い不具合調査不具合報告の Notion チケットには、再現手順、スクリーンショット、顧客 ID、発生日時など、調査に必要な情報が散在しています。エンジニアが調査を開始するとき、これまでは以下の手順を毎回踏む必要がありました。
Notion のページを開き、散らばった情報を頭に入れる
「どの環境で」「誰が」「いつ」発生したかを特定する
Cloud Logging を開き、タイムスタンプやアカウント ID でフィルタを作る
データベースを確認するためのクエリを考える
この「情報を頭に入れてから調査ツールに移る」までの時間は、短いようでいて集中力を削ぐ大きな要因となっていました。

 解決アプローチ：なぜサブエージェントとスキルなのかこの課題に対し、Claude Code のサブエージェントとスキル用いて解決を図りました。

 コンテキストの圧縮と分離（サブエージェント）すべての情報を 1 つのエージェントに詰め込むと、トークン消費が増えるうえに指示が複雑になり、精度が落ちがちです。

今回は「情報の抽出（トリアージ）」と「調査クエリの生成（分析）」を別々のエージェントに分けることで、各エージェントの役割を単純化しました。
サブエージェントに関する詳しい説明は公式ドキュメントに譲ります。

https://code.claude.com/docs/ja/sub-agents

 挙動の制御と専門化（スキル）「Cloud Logging のクエリ記法」のような厳密なルールは、プロンプトで指示するよりもスキルとして定義する方が確実です。

ツールとして定義することでハルシネーションを抑制し、正しい構文での出力を保証できます。
スキルに関しても、知らない人・まだ使ったことない人は公式ドキュメントをご覧ください。

https://code.claude.com/docs/ja/skills

 実装例以下の構成で実装しました。

bug-triage (Agent): Notion から情報を抽出し、JSON に整理する

gcp-log-query-creator (Skill): 正しいログクエリを書くための専用スキル

bug-investigation-support (Agent): JSON とスキルを使って、調査用クエリを生成する
これらを統括するカスタムコマンド bug-full-analysis で一括実行します。

図解すると以下のようになります。

 Phase 1: トリアージ担当 (bug-triage)まずは、自然言語で書かれた Notion の不具合報告を、構造化データ（JSON）に変換するエージェントです。

Notion の MCP サーバーを利用してページ内容を取得します。
---
name: bug-triage
description: Notionのバグチケットから情報を抽出し、構造化データ(context.json)を作成するトリアージエージェント。
model: sonnet
color: amber
---

You are a **Bug Information Triage Agent** specialized in extracting structured information from Notion bug tickets.

## Workflow
1. Accept Notion Page ID or URL
2. Use MCP `notion-fetch` to retrieve the Notion page
3. Extract required fields (Title, Reproduction steps, Environment, Customer account, etc.)
4. Create `bugs/{notion_page_id}/context.json`

(以下、詳細な抽出ルールなど)
このエージェントが生成する context.json のイメージは下記の通りです。
{
  "bug_id": "NOTION-123",
  "title": "ログイン画面でエラーが発生する",
  "environment": {
    "platform": "ios",
    "version": "1.2.0"
  },
  "customer_account": "user@example.com",
  "timestamp": "2025-12-05T10:00:00Z"
}
このコンテキストファイルは以降のステップで活用されますが、

他にもソースコードの調査をコーディングエージェントに依頼する際に、コンテキストの受け渡しが楽になります。

 Phase 2: ログクエリ作成スキル (gcp-log-query-creator)次に、Google Cloud Logging のクエリ生成に特化したスキルです。

再現性を担保したいので、プロンプト内で書き方を教えるのではなく、ツールとして定義してしまいます。
---
name: gcp-log-query-creator
description: Google Cloud Logging のクエリを生成するスキル。
---

# GCP Log Query Creator

(中略)

## クエリ生成ルール
Cloud Functions: resource.type="cloud_function"
...(中略)

## 出力形式
必ず以下の2形式を出力する：
1. Cloud Logging フィルタ
2. gcloud コマンド

 Phase 3: 調査支援担当 (bug-investigation-support)トリアージされた context.json を読み込み、上記のスキルを使って具体的な調査用クエリを生成します。
また、 Firestore などデータベースに関する具体の要素が context.json に含まれている場合、それらも整理してもらいます。

（この記事では実践していませんが、こういったデータベースクエリの生成も Skills に任せてそれらを参照させた方が良いです）
---
name: bug-investigation-support
description: Use this agent when investigating bugs...
model: sonnet
color: yellow
---

あなたは「不具合調査のサポートエージェント」です。

## タスク実行手順
1. context.json を読み込み、customer_account や timestamp を抽出
2. `gcp-log-query-creator` スキルを実行して、適切な Cloud Logging クエリを生成
3. Firestore のコレクションパスを特定
4. `query_and_fs_collection.md` というマークダウンファイルを作成

 実行用コマンド (bug-full-analysis)最後に、これらを連携させるカスタムコマンドを定義します。
カスタムコマンドについては下記参照。

https://code.claude.com/docs/ja/slash-commands#カスタムスラッシュコマンド
ポイント：

最初はサブエージェントを管理するオーケストレーション的なサブエージェントを作成しようと思ったのですが、

上手く動かず（bug-triage サブエージェントなどを起動してくれずエラーになる、起動できていないのに使ったと嘘をつかれる、など）、コマンドでコントロールすることにしました。
# Bug Full Analysis

## 実行指示

### Phase 1: bug-triage の実行
Task ツールを使用して `bug-triage` エージェントを起動してください。

### Phase 2: bug-investigation-support の実行
Phase 1 で作成された context.json のパスを使用して `bug-investigation-support` エージェントを起動してください。

 実際の動作例架空の不具合報告に対してコマンドを実行してみます。
入力（コマンド）
/bug-full-analysis https://notion.so/my-workspace/bug-report-123
Notion の内容（例）
タイトル: 商品詳細ページが開けない

発生日時: 2025/12/04 15:30 頃

ユーザー: test-user-001

現象: iOS アプリで商品一覧から詳細をタップすると、読み込み中のまま進まない。
実行結果

しばらく待つと、以下の 2 つのファイルが生成されます。
bugs/bug-report-123/context.json
抽出されたユーザー ID、発生日時、プラットフォーム情報などが格納されます。
bugs/bug-report-123/query_and_fs_collection.md
以下のように、コピペで使えるクエリが出力されます。
# 商品詳細ページが開けないの調査サポート

## Cloud Logging の検索クエリ
```
resource.type="cloud_function" OR resource.type="cloud_run_revision"
severity=(ERROR OR WARNING)
textPayload=~"test-user-001" OR jsonPayload.account_id="test-user-001"
timestamp>="2025-12-04T15:00:00+09:00"
timestamp<="2025-12-04T16:00:00+09:00"
```
これにより、コマンド一つで「誰の」「いつの」ログを見ればよいかが提示され、即座に調査を開始できる状態になりました。

 まとめClaude Code のサブエージェントとスキルを組み合わせることで、コンテキストを適切に分離しながら、不具合調査の立ち上がりに必要なステップを自動化 できました。
しかし、この記事で紹介した方法だけでは満足していないので、 今後は、生成された context.json をさらに別のエージェントに渡し、ログの自動分析や修正案の提示まで繋げていきたいと考えています。
この記事が皆さんの開発フロー改善のヒントになれば幸いです。
はじめに

前提

TL;DR

本題

地味に辛い不具合調査

解決アプローチ：なぜサブエージェントとスキルなのか

コンテキストの圧縮と分離（サブエージェント）

挙動の制御と専門化（スキル）

実装例

Phase 1: トリアージ担当 (bug-triage)

Phase 2: ログクエリ作成スキル (gcp-log-query-creator)

Phase 3: 調査支援担当 (bug-investigation-support)

実行用コマンド (bug-full-analysis)

実際の動作例

まとめ

Discussion
