はじめに（TL;DR）
モバイルアプリやWebフロントエンドから複数のマイクロサービスにまたがるプロダクトで、調査作業（不具合調査、挙動確認、影響範囲の特定など）をClaude Code Skillsで自動化しました。
Claude Codeは強力ですが、デフォルトではリポジトリの構成やサービス間の依存関係を知りません。Skillsでアーキテクチャ知識と調査手順を注入することで、「自然言語で質問するだけでクライアントからバックエンドまで一気通貫で調査が完了する」仕組みを作った話です。
背景：マイクロサービス横断調査の辛さ
私が開発に携わるプロダクトにはアプリ版とWeb版があり、それぞれ以下のような構成になっています。
【アプリ版】
モバイルアプリ ---> BFF ---> 多数のマイクロサービス群
【Web版】
ブラウザ ---> 複数のWebフロントエンド ---> 各種バックエンド
どのサービスがどこから呼ばれているのかを把握していないと、そもそも調査の起点すら見つかりません。さらにサービスごとに技術スタックもバラバラです。
こうしたアーキテクチャで不具合調査や影響範囲の特定を手作業で行うと、以下のような辛さがあります。
- サービス間の呼び出し関係を頭に入れておく必要がある — 全体のトポロジを把握していないと、関連するリポジトリを見落とす
- リポジトリを1つずつ開いて追っていくしかない — サービスごとにリポジトリが分かれているため、IDEやターミナルを何画面も開き、サービス境界をまたぐたびに手動で次のリポジトリに移る
- 言語・フレームワークごとにコードの追い方が違う — サービスによって技術スタックが異なるので、エントリポイントの探し方やレイヤー構成の知識がそれぞれ必要になる
これらは結局、調査する人にアーキテクチャの知識、ドメイン知識、そしてサービスごとの調査手順が求められるということです。長く携わっているエンジニアなら経験で対処できますが、属人的で時間もかかります。
「ならClaude Codeにやらせればいいのでは？」と思うかもしれませんが、素のClaude Codeはリポジトリの構成やサービス間の依存関係を知りません。的外れなリポジトリを延々と探したり、1つのリポジトリ内で完結してしまったりと、人間と同じ知識不足の問題にぶつかります。
解決アプローチ：Skillsでアーキテクチャ知識を注入する
そこでClaude Codeの「Skills」という仕組みを使い、これらの知識——アーキテクチャ構成、ドメイン知識、調査ワークフロー——をファイルとして永続化するアプローチを取りました。
具体的には、アプリ版とWeb版でSkillを2つに分け、それぞれに「サービスマップ」「調査手順」「参照ドキュメント」を持たせています。ユーザーが自然言語で調査を依頼すると、Skillが自動的にトリガーされ、リポジトリの検出からコード追跡、レポート出力までを一貫して実行します。
Claude Code Skills とは
Claude CodeのSkillsは、SKILL.mdファイルとreferences/ディレクトリで構成され、特定のタスクに必要な知識と手順をClaude Codeに注入できる仕組みです。
skills/
├── investigate-app/
│ ├── SKILL.md # 調査手順
│ └── references/
│ └── service-map.md # サービス構成・リポジトリ対応表
└── investigate-web/
├── SKILL.md # 調査手順
└── references/
└── service-map.md # サービス構成・リポジトリ対応表
重要なのがdescriptionフィールドです。ここに書いた内容がSkillの自動トリガーに使われます。
---
name: investigate-app
description: "ネイティブアプリに関する実装を調査する。アプリからBFF経由で
バックエンドマイクロサービスまで全レイヤーを体系的に追跡する。
不具合調査、挙動確認、コードトレースが必要な時に使用。"
---
ユーザーが「○○の機能がおかしいんだけど調査して」と話しかけると、descriptionの内容とマッチして自動的にSkillが発動します。/skill-nameでコマンド的に呼ぶこともできます。
Skill自体の作り方
このSkill自体もClaude Codeに書かせました。Skill作成用の「Skill-Creator」というSkillを導入した上で、以下の流れで進めました。
- Claude Codeに対象リポジトリ群を読ませる — 追加ワーキングディレクトリに関連リポジトリを設定し、CLAUDE.mdやAPI定義、ディレクトリ構成などを読み込ませる
- 「これらのリポジトリを横断調査するSkillを書いて」と依頼する — サービス間の呼び出し関係やレイヤー構成をClaude Code自身に分析させ、SKILL.mdとreferences/を生成させる
- 実際に使ってみて修正する — 生成されたSkillで調査を実行し、うまくいかなかった部分（調査の順序、見落とすリポジトリ、レポートのフォーマットなど）をフィードバックして改善する
Skillの中身は自然言語のMarkdownなので、プログラミングの知識がなくても読み書きできます。「ここの手順が足りない」「このサービスも調査対象に含めて」といった修正も、Claude Codeに指示するだけで反映されます。
以下、実際に作ったSkillの設計を紹介します。
アプリ調査Skillの設計
アプリ側の調査Skillは以下のステップで構成しました。
調査の前提として、Skillはまずローカル環境にある関連リポジトリを自動検出します。追加ワーキングディレクトリや候補ディレクトリを走査し、git remote -v でリポジトリを特定する仕組みです。ローカルに見つからないリポジトリがあれば、GitHubからのcloneを案内します。
Step 1: キーワード抽出 → BFF起点のクロスサーチ
ユーザーの質問文から機能名・API名・エラーメッセージなどを抽出し、BFFのAPI定義を起点に横断検索を行います。BFFはすべてのクライアントリクエストの入口なので、ここのAPI定義からサービス間の呼び出し関係を一覧できます。
Step 2: ユーザー確認チェックポイント
調査計画を提示してユーザーの確認を得ます。これがないと、Claude Codeが見当違いの方向に突き進むリスクがあります。
Step 3: BFF → クライアント＋バックエンド並列トレース
BFFのハンドラからコールチェーンを辿った後、Taskエージェントをリポジトリごとに並列起動して各レイヤーを同時に追跡します。これがSkills導入で最も効いた部分です。
Step 4: 構造化レポート
最終的に構造化されたレポートを出力します。以下はその一例です。
## コールチェーン図
[Client] ViewModel
→ Repository.getData()
→ DataSource.fetch()
→ BFF.GetSomething()
[BFF] GetSomethingHandler
→ UseCase.Execute()
→ BackendService.Query()
[Backend] QueryHandler
→ UseCase.Execute()
→ Repository.FindByID()
→ [DB]
## 関連ファイル一覧
- client/app/.../ViewModel.kt:42
- bff/internal/handler/something.go:128
- backend/internal/usecase/query.go:35
## 問題箇所の指摘
- backend/internal/usecase/query.go:72 — nilチェック漏れ（確信度: 高）
クライアントからDB層まで、どのファイルの何行目を通っているかが一目で分かるレポートが生成されます。
Web調査Skillの設計
Web側はアプリとは別Skillにしています。エントリポイントがBFFではなくURLパスになること、ドメインごとに技術スタックやディレクトリ構成が異なることが理由です。
基本的な調査の流れはアプリ版と同じ（キーワード抽出 → 調査計画提示 → 並列トレース → レポート出力）ですが、URLパスから対象ドメインを自動判定するステップが加わります。ドメインごとにトレースパターンが異なるため、それぞれのルーティング構成やレイヤー構造を参照ドキュメントに記載しています。
参照ドキュメント：組織知識のエンコード
Skill本体のSKILL.mdに加えて、references/ディレクトリに組織知識をエンコードした参照ドキュメントを配置しています。
service-map.md
サービス名とリポジトリの対応表です。調査時に「この呼び出し先はどのリポジトリを見ればいいか」をすぐ判断できます。
| サービス名 | リポジトリ | 役割 |
|-----------|----------|------|
| service-a | repo-a | ○○処理 |
| service-b | repo-b | △△管理 |
| ... | ... | ... |
マイクロサービスの構成やリポジトリの依存関係は常に変化していきます。参照ドキュメントにすべてをハードコードすると陳腐化しやすいため、基本的な構成は事前知識として与えつつ、実際のコード構造は調査時に動的に探索する方針にしています。参照ドキュメントはあくまで「どこを探しに行けばいいか」の手がかりであり、SSOTは常にコードそのものです。
DevinWikiとの違い
コードベースの理解を助けるツールとしては、Devinの「DevinWiki（DeepWiki）」が知られています。DevinWikiはリポジトリを自動的にインデックスし、アーキテクチャ図やコードの説明を含むドキュメントを自動生成してくれる便利な機能です。
Skillsはアプローチが異なります。
| DevinWiki | Skills | |
|---|---|---|
| 生成方法 | リポジトリを定期的にインデックスして自動生成 | Claude Codeと協力して調査手順・アーキテクチャ知識を設計 |
| 出力 | 静的なドキュメント（読むもの） | 動的な調査の実行（行動するもの） |
| スコープ | 単一リポジトリのドキュメント化 | 複数サービスを横断した調査の実行 |
| カスタマイズ | 自動生成のため限定的 | 組織固有のワークフローを自由に設計可能 |
DevinWikiが「コードベースの地図を自動で作ってくれるもの」だとすれば、Skillsは「地図の読み方と目的地への行き方を教えて、実際にそこまで連れて行ってくれるもの」です。知識の提供にとどまらず、調査の実行そのものを自動化できる点が大きな違いです。
もちろん両者は排他的ではなく、DevinWikiで全体像を把握しつつ、具体的な調査はSkillsで実行する、という使い分けも考えられます。
Before / After
| Before | After | |
|---|---|---|
| 調査開始 | 「この機能どこのサービスだっけ…」とリポジトリを探す | 自然言語で質問するだけ |
| リポジトリ検出 | 手動で複数ウィンドウを開く | 自動でローカルクローンを検出 |
| コード追跡 | 関数名を個別にgrep、サービス間の呼び出しを見失う | エントリポイントから自動で全レイヤーを追跡 |
| 並列調査 | 不可能（人間は1つずつ見る） | Task Agentがリポジトリごとに並列起動 |
| 結果共有 | Slackに断片的にコピペ | コールチェーン図＋ファイルパス一覧の構造化レポート |
| 所要時間 | 調査対象が多いほど膨らむ | 規模によらずほぼ一定 |
導入して見えた副次的な効果
当初は調査の効率化が目的でしたが、使っていくうちに想定以上の効果がありました。
- ドキュメント作成の質が上がった — 調査結果にデータフローやコールチェーンが明示されるため、そのままドキュメントのベースとして使えます。調査結果をまとめ直す手間が大幅に減りました
- 横断的なボトルネック分析がしやすくなった — パフォーマンス改善などに取り組む際、クライアントからバックエンドまでの全レイヤーが可視化されているので、どこがボトルネックかを特定しやすくなりました
- 非エンジニアでも調査に使えるようになった — Skillにアーキテクチャ知識と調査手順が組み込まれているため、コードベースに詳しくないメンバーでも自然言語で質問するだけで調査を実行できます。エンジニアに都度聞かなくても、自分で状況を把握できるようになりました
おわりに
Claude Code Skillsは、言ってみれば 「組織のアーキテクチャ知識をAIに注入する仕組み」 です。
マイクロサービスの横断調査に限らず、組織固有の知識と手順が必要な作業であれば同じアプローチが応用できるはずです。興味のある方はぜひ試してみてください。