Claude Code の Agent Skills を活用してリポジトリのオンボーディングを効率化する

こんにちは。ウォンテッドリーでバックエンドエンジニアをしている小室 (@nekorush14) です。今回は、Claude Code の Agent Skills を活用してリポジトリのオンボーディングを効率化する取り組みについて紹介します。

先日、日々の業務改善や効率化につながる課題の解決がテーマの社内AIハッカソンが開催されました。私は自分自身が入社した時につまずいた「ドキュメントを読んでも全体像がつかめない」や「環境構築で謎のエラーが出る」などのオンボーディングに関する課題の解決に取り組みました。

その中で、Claude Code のコンテキストとしてリポジトリの「手がかり」と「地図」、そして「手順」を持たせ、リポジトリに慣れていないエンジニアが自走可能な仕組みの構築を目指しました。

はじめに

マイクロサービス開発において、初めて触るリポジトリの仕様把握や環境構築は多くの時間を要しがちです。ドキュメントが散在していたり、情報が古くなっていたりすることが主な要因で、特に New Joinner にとっては大きなハードルの一つです。

本稿では、リポジトリのナレッジやトラブルシューティングを Agent Skills として集約し、Claude Code と対話するだけでオンボーディングが完結する仕組みを紹介します。

Agent Skills を活用する

今回作成したのはオンボーディング用の2種類のAgent Skills を内包した Claude Code の Plugin です。/onboarding でリポジトリの全体像を対話的に学習し、/setup で環境構築を半自動で行えるようにしました。
ディレクトリ構成は以下のようになっています。

onboarding-kit/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── setup/                  # 開発環境をセットアップするSkill
    │   ├── SKILL.md
    │   ├── scripts/
    │   │   └── check_prerequisites.sh
    │   └── references/
    │       ├── environment-checklist.md
    │       └── troubleshooting.md
    └── onboarding/             # 対話によるリポジトリ理解を深めるSkill
        ├── SKILL.md
        └── references/
            ├── architecture-overview.md
            ├── directory-conventions.md
            ├── domain-model-relationships.md
            └── microservice-map.md

Claude Code Plugins や Claude Code Agent Skills そのものの仕組みについては以前公開した記事を参照いただくとして、ここではオンボーディングを円滑にするための勘所を3つ紹介します。

リポジトリの概要をナレッジとして埋め込む

初めて見るリポジトリで最も困るのは、「この処理はどこに書くのが正解か？」、「このディレクトリは何のためにあるのか？」など「リポジトリにおけるお作法」がわからないことです。README に概要はあっても、詳細な規約までは書かれていないことがよくあります。

そこで、ソースコードを読む際の手がかりとなる情報を references ディレクトリに配置し、作業をしている Agent のコンテキストに載せられるようにしました。

directory-conventions.md: 各ディレクトリの役割とステータス (Recommended / Deprecated)
domain-model-relationships.md: 主要なドメインモデルの関係性 (ER図など)
architecture-overview.md: アーキテクチャパターンの解説

例えば directory-conventions.md には以下のような表を含めています。
(*以下はサンプルで、実際の記載やディレクトリ構成とは異なります。)

| ディレクトリ | ステータス | 説明 |
|-----------|--------|-----|
| app/services/ | Recommended | ビジネスロジックの実装場所。Service Objectパターンを採用。 |
| app/jobs/ | Recommended | 非同期処理を行うジョブ。 |
| app/assets/ | Deprecated | 旧フロントエンド資産。新規追加は禁止。 |

これにより、ユーザーが「〜の機能を追加したい」と相談した際、Claude Code はこの手がかりを参照して「app/assets は非推奨なので、新しい構成に従って実装しましょう」といった「リポジトリにおけるお作法」に即したガイドができるようになります。

サービス・リポジトリ間のつながりを参照可能にする

マイクロサービス開発では、対象のリポジトリ単体だけでなく、「誰から呼ばれ、誰を呼んでいるのか」を理解することが重要です。しかし、単一リポジトリのソースコードだけから全体像を読み解くのは困難です。

この課題に対しては、microservice-map.md を用意し、通信の流れを可視化して Agent に与えるアプローチを取りました。
(*以下はサンプルで、実際の記載やサービス構成とは異なります。)

対象リポジトリ
    │
    ├─── gRPC ──→ サービス A (認証・ユーザー管理)
    ├─── gRPC ──→ サービス B (画像変換)
    └─── HTTP ──→ 外部決済サービス

また、例えば protbuf の定義ファイルが別リポジトリにある場合などは、「API 定義を変更する際どの順で変更するかのワークフロー」も明記しておきます。これにより、Agent は「このメソッドを変更するには、先に protbuf を管理しているリポジトリ側で PR を出してマージする必要があります」といった、リポジトリの外側まで考慮した回答をしてくれるようになります。

セットアップ手順を Skill 化して自走を支援する

オンボーディングで最も時間を使うのが環境構築のトラブルです。「手順通りにやったのに動かない」という事態を防ぐため、Setup Skill では以下の設計を取り入れました。

冪等性の担保: 何度実行しても壊れないスクリプトにする
構造化された出力: スクリプトの実行結果を PASS / FAIL で出力し、Agent が判定しやすくする
自動修復: エラー発生時、トラブルシューティングドキュメントを参照して自動で解決を試みる

自動修復をうまく稼働させるために特に効果的だったと考えられるのが、以下のようなAgent の挙動を制御する指示です。
(*以下はサンプルで、実際の記載とは異なります。)

## Core Behavior

**Autonomous progression**: 各ステップが成功したら確認なしで次へ進む

**Pause only when**:
- コマンドが失敗した、またはエラーが出力された
- ユーザーの判断が必要 (認証情報の入力など)
- ターミナル外での手動操作が必要

## Verification

**On Success**
両方のチェックに合格しました。セットアップの完了をユーザーに報告します。 

**On Failure**
エラー出力を解析し、解決を試みます。
自動的に解決できない場合は、AskUserQuestion を使用してエラーを提示し、ユーザーに対処方法を尋ねます。

Claude Code にはユーザーに選択肢付きで質問を投げかけるツール (AskUserQuestion) 組み込まれています。これを使用することで、Agent が作業中にユーザーに対応方針を確認できるため、意図しない挙動を可能な限り抑えることができます。

このツールをうまく活用し、順調なときはワークフロー定義に従って作業を進め、トラブルが起きたときや、不足している依存ツールのインストール操作などのときだけ立ち止まってユーザーに確認する、という理想的なアシスタントの動きを実現できました。

社内からのフィードバック

作成した Claude Code Plugin を組み込んだリポジトリを、普段触らない社内のエンジニアに使ってもらったところ、以下のようなポジティブな反応が得られました。

「リポジトリの概要や開発プロセスをざっくり理解できた」
「セットアップもほぼ自動でやってくれた」

一方で、「セットアップで全体でどれくらいのステップがあって、今どれくらい進捗しているのかがわかると、リポジトリの中身を知らない人でも安心感がある」、「より具体的にマイクロサービス間のつながりが示されると良い」と言った改善フィードバックもいただいているため、継続してブラッシュアップしていこうと考えています。