スパイダープラス Tech Blog

建設SaaS「スパイダープラス」のエンジニアとデザイナーのブログ

トップ > 生成AI > レガシーコードの仕様整理にAIをフル活用してみた ― Claude Codeとsubagentで生産性爆上げした話

レガシーコードの仕様整理にAIをフル活用してみた ― Claude Codeとsubagentで生産性爆上げした話

生成AI テクノロジー swift iOS

皆さんこんにちは〜スパイダープラスの舘です！！

もう年の暮れが近くなってきていますが、みなさんは年末の整理や掃除は進んでいますか？ 今回は、プライベートだとそこら辺は苦手で放置気味になってしまっている僕がSPIDER+の仕様・ドキュメント整備をやった際にAIを活用して 「これはよかった」「効果的だった」と思ったことを、備忘録として皆さんに共有できたらなと思っています。

きっかけ ― なぜAIに頼ることにしたのか

SPIDER+はSwift/Objective-Cが混在する、それなりに規模の大きいコードベースです。 機能ごとの仕様ドキュメントを整備したいと思っていたものの、コードを読み解きながらまとめていくのはなかなか骨の折れる作業…。

「これ、AIに手伝ってもらえないかな？」と思って試してみたのが Claude Code でした。

AIの特性を理解する ― 「魔法の箱」ではない

効果的なアプローチの話をする前に、まずAIの特性について触れておきます。

当たり前かもしれませんが、僕たちが普段活用している生成AIは、あるインプットに対していろいろなパラメータを加味して確率的に情報を出力しているだけです。 つまり、AIは「なんでも知っている魔法の箱」ではなく、与えられた情報をもとに最もそれらしい回答を生成するツールなんですね。

だからこそ、自分が求めている出力を得るためには、それに必要な情報を過不足なく揃えてAIに渡す必要があります。 これが普段「プロンプト」として渡しているものの正体です。

今回は、より効果的なプロンプトを作成するための考え方と、Claude Codeならではの便利機能を紹介していきます！

実践① ― CLAUDE.mdでプロジェクトの文脈を共有する

Claude Codeには CLAUDE.md というファイルを置くことで、プロジェクト固有の情報を常にClaudeに認識させる仕組みがあります。

僕の場合、以下のような情報を記載しました：

  • プロジェクトの概要（SPIDER+が何をするアプリなのか）
  • ディレクトリ構成の説明
  • 使用している技術スタック（Swift / Objective-C混在など）
  • 命名規則やコーディングルール
  • 今回のタスク（仕様整理）の目的とゴール

これを置いておくだけで、毎回「このプロジェクトは〜」と説明する手間が省け、Claudeが文脈を理解した上で回答してくれるようになります。

実践② ― Custom Slash Commandで繰り返し作業を効率化

仕様整理では、同じようなパターンの調査を何度も繰り返すことになります。たとえば：

  • 「この画面の機能一覧を洗い出して」
  • 「このクラスの責務を要約して」
  • 「この処理フローを図解して」

こういった定型的な指示は Custom Slash Command として登録しておくと便利です。

# /spec-summary
指定されたViewControllerの以下の情報を整理してください：
1. 画面の役割
2. 主要な機能一覧
3. 依存しているクラス/モジュール
4. 特記事項（レガシーコードや技術的負債があれば）

一度作っておけば、あとは /spec-summary HogeViewController と打つだけで統一フォーマットの調査結果が得られます。

実践③ ― Subagentで専門チームを編成する

ここが今回一番伝えたいポイントかもしれません。

Claude Codeには subagent という機能があり、特定の役割を持った「専門家」を定義して、タスクを委譲することができます。 僕は今回、社内に用意されていたiOS専門の調査チームとして「iOS機能調査班」というsubagentを用いました。

Subagentの設定ファイル

.claude/agents/ios-investigator.md として以下のような設定を作成します：

---
name: iOS機能調査班
description: iOS専門の機能調査班です。Swift/Objective-Cの調査には、必ず使用してください。
model: opus
color: blue
---

あなたは、iOSアプリケーションのソースコードを解析し、機能、実装、アーキテクチャパターンを理解することを専門とする、Swift/Objective-Cコード解析のエキスパートです。
あなたの第一言語は日本語であり、Swift/Objective-Cのコードベースに関する詳細な技術調査報告を提供します。

## 主な責務

1. よく考えて実行する
2. **Swift/Objective-Cソースコードを解析し**、機能がどのように実装されているかを理解する
3. クラス、プロトコル、モジュール間の**関係性を明らかにする**
4. コードベース内の**パターンとアーキテクチャ上の決定を特定する**
5. アプリケーションの各レイヤーを通過する**データフローを追跡する**
6. **調査結果を**、明確で構造化された日本語で**文書化**し、`.md`ファイルで書き出す

ポイント解説

  • 役割の明確化：「Swift/Objective-Cコード解析のエキスパート」と明示することで、AIがその専門家として振る舞う
  • 出力言語の指定：「第一言語は日本語」と書くことで、英語混じりの回答を防ぐ
  • 具体的な責務リスト：何をしてほしいかを箇条書きで明確に
  • 出力フォーマットの定義：調査結果のテンプレートを指定しておくと、統一された形式でドキュメントが出力される

実際の調査指示

このsubagentに対して、以下のような指示を出しました：

あなたは機能調査のスペシャリストです。
使うエージェントは iOS機能調査班 です。

あなたは、絶縁抵抗計の機能を調査をやっていただきます。

やって欲しいことは、
- 解体新書的なドキュメントの作成
- 欲しい情報をまとめる

こちらが欲しい情報は
- 使われているBLEの通信方式
- 使われているコマンドの種類
- 実装箇所
- レスポンスの形
- 通信で送っている情報

情報にはそれぞれリファレンスをつけるようにしてください

この指示のポイントは：

  • 「解体新書的な」という比喩：どんなレベルの詳細さを求めているかをイメージで伝える
  • 欲しい情報の明示：箇条書きで具体的に列挙することで、漏れなく調査してもらえる
  • リファレンスの要求：「この情報はどのファイルのどこにあったのか」を明記させることで、後から検証しやすくなる

Subagentが出力した実際の調査結果

「iOS機能調査班」に絶縁抵抗計（KEW3441BT/KEW3552BT）のBLE通信仕様を調査させた結果の一部がこちらです：

## コマンド仕様

### 共立電気 絶縁抵抗計(KEW3441BT/KEW3552BT)のコマンド

#### コマンド一覧表

| コマンド名 | バイト列 | ASCII表現 | 目的 |
|----------|---------|----------|------|
| 通信開始 | `[0x02, 0x30, 0x30, 0x37, 0x31, 0x30, 0x46, 0x38, 0x03]` | `[STX]00710F8[ETX]` | デバイスとの通信を初期化 |
| 連続通信開始 | `[0x02, 0x30, 0x30, 0x37, 0x42, 0x31, 0x30, 0x41, 0x03]` | `[STX]007B10A[ETX]` | 連続測定モードを開始 |
| 連続通信終了 | `[0x02, 0x30, 0x30, 0x37, 0x42, 0x32, 0x30, 0x42, 0x03]` | `[STX]007B20B[ETX]` | 連続測定モードを終了 |
| 通信終了 | `[0x02, 0x30, 0x30, 0x37, 0x31, 0x31, 0x46, 0x39, 0x03]` | `[STX]00711F9[ETX]` | 通信を終了 |

**リファレンス:** KewBLECommand.swift:27-66

注目してほしいのは以下のポイントです：

  1. 表形式で整理されている — バイト列、ASCII表現、目的が一目で分かる
  2. コードスニペット付き — 実際の実装がすぐ参照できる
  3. リファレンスが明記されている — 「どのファイルの何行目」まで追える

これを手動でやろうとすると、コードを読み解きながらExcelやNotionにまとめて…という作業が発生します。 subagentなら、指示を出して数分待つだけでこのクオリティのドキュメントが出てきます。

なぜSubagentが効果的なのか

通常のプロンプトでも同じことはできますが、subagentを使うメリットは以下の点です：

  1. 再利用性：一度設定すれば、別の機能調査でも同じ品質の調査ができる
  2. 一貫性：出力フォーマットが統一されるので、複数の機能を調査してもドキュメントの体裁が揃う
  3. 専門性の担保：毎回「あなたはiOSの専門家です」と書かなくても、subagentを呼ぶだけでOK
  4. 並列実行：メインの作業をしながら、バックグラウンドで調査を走らせられる

Subagent設計のコツ

実際に運用してみて気づいた設計のコツをいくつか共有します。

1. 「改善案は不要」と明記する

## 留意事項: 
- 改善案は不要なので、絶対に記載しないでください。

AIは親切心から「こうした方がいいですよ」と提案してきがちですが、仕様調査の段階では余計な情報になることも。 目的に応じて制限をかけておくと、欲しい情報だけが得られます。

2. エッジケースを想定しておく

## エッジケース
- Swift/Objective-Cの混合コードに遭遇した場合は、ブリッジの仕組みを記録する
- ジェネリクスやプロトコルを多用したコードについては、抽象化レイヤーを説明する

レガシーコードの調査では想定外のパターンに出会うことが多いので、「こういう場合はこうして」と事前に書いておくと、AIが適切に対応してくれます。

3. 品質チェックリストを入れる

## 品質チェック
調査結果を提示する前に:
1. すべてのファイルパスとクラス名が正確であることを確認する
2. 依存関係が正しくマッピングされていることを保証する

AIに「セルフレビューしてから出力して」と指示することで、ケアレスミスが減ります。

効果と学び

この方法で仕様整理を進めた結果：

  • 調査時間の大幅短縮：コードを読む時間が体感で半分以下に
  • ドキュメントの品質向上：統一フォーマットで整理されるので読みやすい
  • 属人化の解消：AIが整理したドキュメントは誰でも読める形になる

一方で学びもありました。AIは万能ではないので、出力結果は必ず自分の目で検証する必要があります。 特にレガシーコードは「書いてあるけど実際には動いていない」処理もあったりするので、AIの回答を鵜呑みにせず、実機確認と組み合わせることが大事です。

まとめ

AIを使った開発、めちゃくちゃいいです！！

ただし、AIの特性を理解して適切な情報を渡すこと、そして便利な機能（CLAUDE.md、Custom Command、Subagent）を活用することで、その効果は何倍にもなります。

年末の大掃除は苦手な僕ですが、コードの整理整頓はAIの力を借りてバッチリ進められました。 皆さんもぜひ試してみてください！

ところで、スパイダープラスでは仲間を募集しています。 少しでも興味が出てきたなという方はお気軽にご連絡ください！