レガシーソフトウェア vs 私たち with AI 〜仕様化テスト自動生成AIエージェント開発譚〜【AI駆動開発エンジニア勉強会/イベントレポート】

※この記事は、2025年10月に開催されたイベントでの発表内容をレポートしたものです。

冒険の舞台
- toC：Knowns App
- toB：Knowns 消費者リサーチ
あなたの隣にもいる"怪物"
皆さんの現場にも、こんな"怪物"、いませんか？
- 課題分析
- 戦略課題
攻略の鍵：振る舞いを"固定"する「魔法陣」
- アプローチ：仕様化テスト
パーティの掟
最初の呪文、そして"暴走"
- シンプルなプロンプトでの課題分析
魔法の精度を上げる①：「詠唱術」の習得
- 精度向上策①：実装ガイド(char-test.guide.md)の作成
- 「詠唱術」の習得 - 実装ガイドの中身
魔法の精度を上げる②：「真実の天秤」の創造
仲間の召喚：専門家パーティの結成
- アーキテクチャ：専門家AIチームによる「分業」
- 仲間の召喚 - サブエージェントの指示書
必殺魔法陣、完成
- 人間の開発フローを模倣した、自律型AIワークフロー
- 必殺魔法陣、完成 - 統括コマンド
レベルアップの日々
- 試行錯誤のリアル
冒険の書〜皆さんの現場で使える6つの攻略法〜
- なかまになってほしそうにこちらをみている！

登壇者はこの方

Akity

ノウンズ株式会社
VPoE

SIerにてOSS業務アプリのプリセールスとしてキャリアをスタート後、Web事業会社で複数サービスのEM、北米向けブランディングSaaSの技術責任者を歴任。BtoB SaaSのデータテクノロジー領域での組織づくりを経て、2025年3月に現職へ入社し、同年7月よりVPoEとしてエンジニア組織を率いる。

Akity：ノウンズ株式会社に所属しているAkityと申します。ノウンズでの役割としては、VPoEという形でエンジニアの組織づくりを担当しています。
これからお話しすることに関して、開発をリードしてくださった方は、実は私ではなく、弊社の仲間が開発をリードしてくださったものになります。なので、彼の奮闘記やチームのアウトプットを代表して私がお話しできればと思っています。

冒険の舞台

ノウンズでは、サービスを2つ展開しています。toC向けのAndroidやiOSのアプリとtoB向けのSaaSアプリになります。

toC：Knowns App

ユーザーがアンケートに答えると、アンケートの内容に応じてポイントが貯まっていく、いわゆるポイ活アプリです
月間5000万件、累計億単位の様々な領域のアンケートデータを収集

toB：Knowns 消費者リサーチ

toC向けアプリで答えていただいたアンケートデータをいつでもダッシュボードで分析できるようなSaaSです
toB向けのユーザーが、例えば企画書などを作る際に、データを持っていなくても、弊社が集めたデータで瞬時にデータ分析して、エビデンスを作って企画書を作れるサービスです
消費者意識データを簡単な操作で多彩な分析ができるサービスを企業に提供

Knowns Appは「解くよろこびを、スキなときにスキなだけ。」をコンセプトに、毎日アンケートが配信され、各ブランドの回答数が日々アップデートされる仕組みとなっています。

2025年3月31日時点で、累計インストール数は12万件、月間アクティブユーザーは25,000人に達しています。

本日の舞台はtoC向けのサービスの方になります。こちらReact Nativeでできているサービスになるので、本日お話しする内容に関してはReact Nativeのお話だと思ってください。

あなたの隣にもいる"怪物"

多くの現場に存在する"怪物"について話を始めます。

仕様書がない...真の姿を知る人は誰もいません
テストがない...下手に触れると何が起きるかわかりません
変更するのが怖い...いつも誰かが勇者になるのを待っています

皆さんの現場にも、こんな"怪物"、いませんか？

今日は私たちがそんな怪物にAIという武器でどのように立ち向かったかをお話しできればと思っています。今回話すAIに関してはClaude Codeのことになりますので、Claude Code前提だと思ってください。

課題分析

テストなき巨大レガシーに対して、経験則ではなく、まずデータ駆動で本質的な課題を特定していこうと考えました。

具体的には、例えばSonarJSやMadgeやgit log などを使ってリスクと難度と価値を定量分析した結果、複雑なだけではなく、複雑かつ頻繁に変更されるコードこそ生産性を蝕む真の課題と弊社では定義しました。

リスク・難度・価値を分析した結果、真の課題は「複雑」かつ「頻繁に変更される」コードだと定義しました。
循環的複雑度が200も超えているようなファイルが2つあるのですが、一方はそれほど変更が大きくない、一方は変更がすごく多いというものがありました。

戦略課題

フルリプレイスということも考えたりはしていたのですが、こちらに関してもリスクがあるという判断をしました。

フルリプレイス：そもそも挙動を保証するテストがなく、高頻度で変更される重要機能のため開発を止めることが難しいと判断しました
人手でのテスト作成：手動でのテスト作成には膨大な工数が見込まれ、現実的ではないという判断です

結論：データが示したROI最大のホットスポットに対して、まずその振る舞いを仕様化テストで固定化する戦略、攻略を選びました。

攻略の鍵：振る舞いを"固定"する「魔法陣」

アプローチ：仕様化テスト

仕様化テストとは何なのかというところですが、振る舞いを固定する魔法陣です。

仕様化テストとは、既存のコードの現在の振る舞いをそのまま記録して、仕様として固定化するテストのことです。どうあるべきかではなく、現在どう動いているかをコードで表現するものになります。

なぜこのテストが攻略の鍵だったのかというと、この安全網があることで、振る舞いの意図しない変更を即座に検知して、誰もが恐れずリファクタリングに挑めるようになるからです。

この安全網をまずAIで構築することこそが、レガシー攻略の最短の経路だと、弊社チームは判断した形になります。

パーティの掟

AI開発の原則として、チームで定めた3つのルールを紹介させてください。実際はルールが3つだけではないのですが、今日は抜粋したものを紹介できればと思っています。

1. 目的を明確にする

仕様化テストはリファクタリングの安全網であり、生きたドキュメントであるという目的にしました

2. モック方針を厳守する

プロジェクトの外部APIやSDKのみモックはOKで、他は内部ロジックはすべて実物を使いましょうというルールです

3. 品質目標を定義する

分岐カバレッジ、いわゆるC1を70%以上は必須として、テストの網羅性を担保するというのを掟としました

強力なツール、Claude Codeを導入するからこそ、まずチーム、これは人間も含めたチームの規約を定めることが、後の手戻りを防いでスケールさせる鍵に後々なっていたなと感じています。

最初の呪文、そして"暴走"

では早速Claude Codeにプロンプトを打っていこうかというところで、まずはメラのような呪文から、小さい呪文から始めていければと思います。

シンプルなプロンプトでの課題分析

AIコーディングエージェントの活用の課題を特定するために、まずソースコードを渡して、とりあえず「仕様化テストを作って」というごくシンプルなプロンプトから始めました。

その結果、予想通りAIの典型的な罠が明確になりました。

罠①：過剰なモック

AIが何でもモック化する傾向にあり、フックまでモック化されたテストが生成されました。これだともう結合された振る舞いを保証できないという状態になっていました

罠②：見せかけのカバレッジ

分岐カバレッジ99%達成していたのですが、中身を見ると全く意味のないテストが多数存在したような形です

罠③：不十分なアサーション

ほとんどのテストがアサーション不足でテストになっていませんでした。AIはテストの形を作れるけど、何を検証すべきかの意図を汲むのが非常に苦手だなと感じました

この実験で明らかになった気づきに基づいて、AIの出力を制御し、品質を担保するための本格アプローチをしていこうという形になっています。

魔法の精度を上げる①：「詠唱術」の習得

精度向上策①：実装ガイド(char-test.guide.md)の作成

AIに安定して高品質なコードを生成させるために、我々の開発ルールをまとめた教科書となるドキュメント作成を進めました。このドキュメント作成をchar-test.guide.mdでMarkdownにまとめていた形です。

なぜ外部ドキュメントにしたかというと、一つ目が一貫性の担保になります。

なぜ？

一貫性の担保：複数のAIエージェントが同じルールブックを参照することで生成されたコードのスタイルや品質を統一していこうという狙いがあります
保守性の向上：振る舞いと基準を分離することで、ガイド自体の改善を容易にして、将来のルール変更にも柔軟に対応できるようにしていこうという形で考えました

役割

テスト実装の具体的な「型」をAIに与えます
例えば、テスト対象の判定ロジックや、共通のセットアップ方法を書いていたり、対象別の実装パターンなどを書いています

AIを教育するために、まず人間が開発の正解を定義して、教科書として与えるアプローチを取った形になります。

「詠唱術」の習得 - 実装ガイドの中身

では、具体的な中身はどういった中身なのかというのを抜粋してお見せできればと思っています。

こちらは実際にAIが読み込むガイドの一部を抜粋して持ってきました。

このように具体的なコードパターンをAIに与えることで生成されるテストコードの品質と一貫性を劇的に向上させることが実際にできた形になります。

魔法の精度を上げる②：「真実の天秤」の創造

精度向上策②：品質基準(char-test.criteria.md)の定義

生成されたコードが良いものかをAI自身が判断するためのルールブックとして、char-test.criteria.mdとMarkdownに作っていきました。

このドキュメントは、良い仕様化テストを満たすべき4つの観点を細かく定義しました。

良い仕様化テストの4観点

網羅性：すべての振る舞いをカバーしているか
正確性：実際の振る舞いを正しく記述ができているか
明確性：何をテストしているかが一読してわかるか
保守性：将来のリファクタリングに役立つか

AIのレビュアーが修正担当AIに実行可能な形式で指示を出すために、厳格なルールを設けました。これによって、レビュープロセスも自動化の対象とすることができるようになりました。

「真実の天秤」の創造 - 品質基準の中身

具体的な内容がこちらになっていて、これは実際にAIレビューが読み込むルールの一部です。

すべてのルールにクリティカルなのかマイナーなのかなどの重要度が設定されています。今日はクリティカルだけ抜粋しました。

このように厳格なルールを定義して、AIがAIをレビューする仕組みを構築したことが、最終的な品質を担保する鍵となっていったなと思っております。

仲間の召喚：専門家パーティの結成

アーキテクチャ：専門家AIチームによる「分業」

いよいよ仲間集めに行ければなと思っています。仲間の召喚、専門家パーティーの結成というところで、巨大なプロンプトに複雑なタスクを一度に任せるアプローチは、出力が不安定になり破綻したという結果がありましたので、そこで人間と同じように各工程専門のサブエージェントに分業させる構成を採用しました。

生成担当 (Generator)：実装コードからテストの骨格を作成する専門家です
実行時修正担当 (Runtime-fixer)：テストを実行して、実行時に出たエラーを修正して全てパスさせる専門家です
レビュー担当 (Reviewer)：先ほどのルールブックの品質基準を照らしてコードレビューをする専門家です
ルール違反修正担当 (Rule-fixer)：コードレビューの指摘に基づいてコードを修正する専門家です

このような形で、各AIの責務を単機能に絞ることで、AIへのコンテキストを明確にして出力の安定性を高めることができました。

仲間の召喚 - サブエージェントの指示書

これが実際の各サブエージェントのMarkdownになるのですが、このような形でMarkdown形式でプロンプトが与えられています。これがClaude Codeのサブエージェントのmarkdownになります。

このような形で、このエージェントには品質基準とは何かというのは書かないようにしました。ただ、criteria.mdを読んでレビューしてくださいというように振る舞いを定義するようにしました。

このような責務の分離がAIの能力を最大に引き出す鍵になったなと思っています。

必殺魔法陣、完成

人間の開発フローを模倣した、自律型AIワークフロー

この一連のAIエージェント連携をClaude Codeのカスタムコマンドとして実装しました。

この流れは、まず対象のソースコードがインプットとして入ってきて、Generatorで仕様化テストが生成され、次にRuntime-fixerでテストをして、テスト失敗したら修正され、次にReviewerでコードレビュー、品質レビューされ、レビュー違反だったらレビューを直すためのRule-fixerの方に渡って修正される、またテストが実行されるというループが回るような形です。

このような形でコード作成、テスト実行、レビュー、修正という人間の開発プロセスをAIが自律的にループ実行する仕組みを構築した形になります。
この開発プロセスを、品質基準を満たすまでAIが自律的にループ実行する仕組みです。