HRBrainでサーバサイドエンジニアをしている蔭山です。
この記事はアドベントカレンダー2日目の記事になります。

なぜやるのか

最近のAI駆動開発の流れに乗って、業務でもClaude Codeを使っています。ただ活用できているとは言えず、とりあえずClaude Codeに投げているだけの状態が続いていました。
簡単なタスクであれば良いのですが、大規模コードベースでのAPI改修には役立てていないという現状でした。

この記事はSub AgentとCommandsを実際に蔭山が開発に導入する流れを解説する記事になります。

実際にチームメンバーにヒアリングを行うと、下記の問題が見えてきました。

大規模なコードベースであり知見も少なく、エンドポイントの仕様調査に時間がかかる
変更による影響範囲が膨大で認知負荷がかかる
エビデンス取得とテストケース作成のためのデータセット作成に時間がかかる

このあたりの問題点をまるっと解決するために、実際にClaude CodeのSub AgentとCommands機能を用いてAPI開発を楽に行えるようにするためのPoCを回してみることにしました。

上記の問題点を解決するための打開策として、役割ごとのSub Agentを作る方向で考えました。

Sub Agent
- 仕様調査Sub Agent
- 影響範囲調査Sub Agent
- データセット整備Sub Agent
- レビュワーSub Agent
Commands
- 仕様調査と実装計画までを行うコマンド
- 実装計画に基づいて実装を行うexecコマンド

とはいえ全て解説すると膨大になるかつアドベントカレンダーに間に合わないため、この記事では仕様調査エージェント、実装計画エージェント、それを動かすコマンドの作成についてどのような手順で進めていったかを解説していきます。

実際にSub AgentとCommandsを作った流れ

1. まずはSub AgentをClaude Codeに作らせる

Claude Codeではdocsが非常に整っているので、まずは素直にDocsを渡して作成します。

エンドポイントを指定されたときにその仕様調査を行うSub Agentを作りたいです。
// docs paste

と投げるだけで下記のような構成を作ってくれます。
利用するtoolについてもコンテキスト消費を押さえられるserenaが指定できています。

---
name: api-spec-writer
description: API仕様書生成専門家。RestAPI、gRPC、GraphQLの3種類のエンドポイントに対応。ユーザーがAPIエンドポイントを指定したときに使用します。API仕様の調査、パラメータ分析、データフロー追跡、バリデーションルール抽出を提供します。エンドポイント分析タスクで積極的に使用してください。
tools: mcp__serena_backend__read_file, mcp__serena_backend__find_symbol, // snip
Read, Grep, Glob
model: sonnet
---

# API仕様書生成エージェント

ここでもし使いたいmcpなどのtoolsが指定されていない場合は/agentsコマンドでtoolsのみの編集も可能です。LLMにやらせるよりも確実に編集できます。

2. 実際にサンプルAPIで実行し、出力結果をレビューする

実際に作られたSub Agentで仕様書を作らせてみるとこの時点である程度のものが出力されています。とはいえ、出力結果をレビューすると下記のことが気になりました。

ポン出しそのままでは出力フォーマットの内容が多すぎるかつ、ドメインやプロダクト固有のフォーマットになっていない
人間がそれを読んで把握できるような形式になっていない
- 実装ファイルのコード行が記載されていたり文字情報が多めだった

上記を踏まえて再度Sub Agentのフォーマットを修正しました。

ドメインやチームによったフォーマットを指定
データフローのMermaid図の出力を追加
App内部実装でのバリデーション一覧を追加

ここで必ず人間のレビューを挟まないと情報量は多いけど使えないSub Agentになるのでしっかりレビューするのがキモです。

3. 実装計画書作成エージェント

仕様調査書を元にして、実装計画を立てるエージェントを作成していきます。ここでも仕様調査エージェントの時と同じくDocsを含めて与えました。

api-spec-writer というSub Agentによって出力されたエンドポイントの仕様調査書を元にして実装計画を行うSub Agentを作りたいです。
// docs paste

実際にここでも仕様調査Sub Agentと同じく、実行結果を見てレビューを行いました。

出力結果の実装の範囲が他のプロダクトまで幅広く記載されている
- -> 仕様調査の点ではありがたいが、実装計画では余分な実装になってしまうため一つのプロダクトに閉じるように修正

Sub Agentの責務と出力する範囲を明確に指定する必要があるなと感じました。

精度向上のためにやってよかったこと

すでに人間が対応済のAPIについて、仕様調査->実装計画->PRとの差分検証
比較結果を元に再度Sub Agentの出力フォーマットを修正

人間の対応結果を正として、LLMで簡易eval的な動きをさせると過不足ない出力が得られるなと感じます。

4. 仕様調査と実装計画Sub Agentを実行させるコマンドを作成する

ここまでで仕様調査と実装計画を行うSub Agentを作成しました。しかしこのままでは毎回Sub Agentを使って。などという指定をしないとClaude Codeは使用してくれません。
それだと面倒なので、一括で実行してくれるコマンドを作成することにしました。

commands/endpoint-migrate/exec.md　にてendpoint-migrateコマンド実行後に設計通りに実装するコマンドを作成しました。
このコマンドでは事前にSub Agentに実装を行う場合の設計書を作らせていることを前提として、その結果を元に実際に実装を行います。

下記のDocsを参考にしてください。
// https://code.claude.com/docs/en/slash-commands の内容コピペ

実際に実行する際はClaude CodeのコマンドのDocsがあるのでそちらも与えるようにしました。

実際に下記のようにコマンドが作成されました。

---
name: hoge-endpoint-migrate
description: 指定されたAPIエンドポイントの仕様書作成、移行影響分析、実装までを一貫して実行するコマンド。実装前にユーザー確認を行います。
argument-hint: <エンドポイント名> [phase2]
model: sonnet
color: purple
---

# Endpoint Migration Command

小ネタなのですが、argument-hintを記載しておくとコマンド入力時に補完は効かないのですが、意図を伝えやすいので便利です。

ここでも同様に下記の点が気になったので修正させました。

詳細を書きすぎてしまっておりSub Agentとの棲み分けができていない
- -> 必要最低限に観点を伝えてリファクタリングさせた
Sub Agent側でmdファイル出力先のpathを指定していたが、それとCommands側の想定がズレていた
- pathを確認して修正させた
実装までコマンドに含めようとしておりコマンド責務が冗長になっていた
- -> 実行はexecコマンドに切り出した

5. 実際に実装を行うコマンドを作成する

仕様駆動開発ではおなじみのtaskを順に実行するためのコマンドを作成しました。

commands/配下で仕様調査を行うコマンド名と同じ名称のフォルダを作成しその配下にexec.mdを置くことでClaude Code実行時にendpoint-migrate:execのように指定が可能になります。

実際に実行する際はこちらも同様にClaude CodeのコマンドのDocsを与えるようにしました。

commands/hoge-endpoint-migrate/exec.md　にてhoge-endpoint-migrateコマンド実行後に設計通りに実装するコマンドを作成しました。
このコマンドでは事前にSub Agentに実装を行う場合の設計書を作らせていることを前提として、その結果を元に実際に実装を行います。

下記のDocsを参考にしてください。
// https://code.claude.com/docs/en/slash-commands の内容コピペ

6. これにて完成

実際にコマンドを実行してみると下記のように仕様書と実装計画書が作成されました。
execコマンドも使えますね。

お疲れ様でした。あとは使い倒して少しずつ改善をしていってください！

取り組みの振り返り

実際にSub Agentを作成して感じたのがSub Agentの出力を安定させることが難しいという点です。

LLMであるがゆえ仕方ない部分もあるのですが、構造化できない情報や安定を求める動作はShell ScriptやCLI Commandsなどで失敗しにくい形に寄せていく必要があるなと感じました。

また、Claude CodeではSkillsという適時参照できる参考書のような機能が提供されているのですが、こちらを利用することでSub Agentのコンテキスト消費を押さえたり、出力精度を上げることができるのではと考えています。

プロダクトごとのコード規則
TerraformといったIaCの知識

こういった「必要なときだけ参照したい知識」を切り出せるのが有効になりそうです。

READMEやNotionに散らばっていた情報がSkillsに集まることで新規アサインのメンバーがClaude Codeに聞きながらキャッチアップできるという未来もありそうです。

最後に

この記事ではAPI開発の負担を軽減するためにClaude CodeのSub AgentとCommandsを使って、仕様調査と実装計画までを自動化した流れを紹介しました。
個人的にもSub AgentやCommands、Skillsを改めて学習する良い機会になりました。

この記事がどなたかのClaude Code活用に役立てば幸いです。

最後に株式会社HRBrainでは新しいメンバーを募集中です。

私自身も新卒で入社しているのですが、社内の雰囲気もよく、エンジニアとしても尊敬できる先輩がたくさんいます。
興味がありましたら、ぜひご応募ください！