AIのみで作られたシステムを引き継いだら、品質の現実に直面した話

はじめに

自分は普段、自社向けの新規業務システムを開発しています。そんな中、急な案件でAIエージェントだけで作られたシステムを引き継ぐ機会がありました。

結論から言うと、動きはするものの品質は低く、改修にかなり苦労しました。

普段は自分も実装のほぼすべてをAIエージェントに任せており、AIエージェントを使用することは肯定的です。なので「AIでは高品質なものは作れない」と言いたいわけではありません。むしろ、AIをきちんと制御できていないとどうなるか、という事例として見ています。

この記事では、単なる愚痴では終わらせず、何が起きていたのか、そこから何を学んだのかを以下にまとめました。

背景

引き継いだシステムは、業務で急に必要になり、AIエージェントを中心に作られたものです。その後、事情があって自分が改修を担当することになりました。

引継ぎのPowerPointの資料は整理され、進行も時間通りでした。正直、少しだけ期待していました。ただ、ドキュメントやコードを開くとその期待は外れました。

見つかった問題

確認して見つかったのは次の点です。

• ドキュメントの可読性が悪い
• プロダクトコードの設計原則が守られてない
• テストコードがそもそも書かれてない
• UIが不自然・AIっぽい
• 開発プロセスが整っていない

ドキュメントの可読性が悪い

ドキュメントは全ての機能が5000行ほどの1ファイルに詰め込まれていました。詳細仕様がないため、それぞれが何を表す機能なのか一目で理解できませんでした。

関数名や変数名もそのまま書かれていて、PM層やユーザーが読む文書として機能していませんでした。ある程度コードが読める自分でも解読に苦労した...

プロダクトコードの設計原則が守られてない

同じロジックの処理が繰り返されている等、設計原則が守られていない箇所が数多くありました。
モジュールの分割が不適切で、依存関係が絡み合っていました。また、改修箇所が想定より増えていました。

そのため、機能を追加する前に、まず全体的なリファクタリングが必要な状態でした。

テストコードがそもそも書かれてない

テストコードが1行もありませんでした。ユニットテストやE2EテストはAIに任せれば比較的短時間で用意できるので、ここは最初から整えておきたかった部分です。

テストがないため、直すと別の不具合が出る状態でした。少し操作しただけで不具合が出ることもありました。

自動テストがないので、当然完全手動の受け入れテストの割合が増えるのですが、バージョンを重ねるごとに確認項目が増え、検証の負担が大きくなっていました。

UIが不自然・AIっぽい

UIにAIっぽさが残っており、記号や見た目で済む案内も文章で書かれていました。たとえば編集できない入力欄は、入力こそ無効化されているものの背景は通常のままで、代わりに「ここでは編集ができません」といった長い案内文が表示されていました。

自分は説明書を読む前にとりあえず試してしまうタイプなので、入力できると勘違いするトラップに引っかかってしまいました。

開発プロセスが整っていない

PRレビューが存在せず、Pushして終了という運用でした。また、ライブラリが古いままで、更新や脆弱性診断をした形跡がありませんでした。サポート中の最新メジャーバージョンから10以上遅れているものもありました。

なぜこうなったのか

単に適当に作っていたのではなく、構造の問題だと感じています。

ただし、自分は開発の当事者として現場に居合わせたわけではありません。以下は、残されたコード・ドキュメント・履歴から読み取れる範囲での推測です。

AIは動くコードを高速に出します。しかし、テストがないリスクや密結合が生む保守コストは、下流工程を経験していないと見えません。出力の欠陥に気づけないため、動いた時点で完成に見えてしまいます。

加えて、AIエージェントは依頼されたタスクの実行に忠実です。実装がどんな仕組みになったかを開発者が理解していなくても、タスクを先へ進めてしまいます。こちらから問い返さない限り、AI側が立ち止まって理解を促してくれることもありません。そのため、自ら強く意識してコードを読みにいかなければ全体像はつかめず、気づけばブラックボックス化してしまいます。

さらに、「AIだから早くできるはず」「動けばOK」という空気があると、検証は実機の動作確認が通るかどうかで終わりがちです。品質の基準を示せる人がいなければ、「テストを書いてほしい」と頼んでもカバレッジや設計の基準までは指示できず、できあがったものを中身で評価することも難しくなります。

こうした要因が重なって、見た目は完成していて中身が空っぽのシステムができあがってしまったのだと思います。

良かった点

悪い面ばかりではありませんでした。

• 発生した不具合の再発を防ぐためのナレッジが蓄積されていた
• 可読性は悪いが、一応「仕様書、ユーザーマニュアル、リリースやタスクの履歴」がリポジトリ内に整備されていた
• 業務要件自体は満たせていた

特に可読性が悪くてもナレッジが蓄積されていたことで事前に不具合となりそうな箇所を回避した事例があり、そういった面ではとても勉強になりました。

品質を保つためにしていること

自分が意識しているのは、プロンプトの工夫だけに頼らず、開発環境側にガードレールを置くことです。AIエージェント基盤で取り入れている仕組みを、いくつか紹介します。

• ドキュメント校正スキルを使用する
  • 可読性を向上させる効果のあるドキュメント校正スキルを使用するようにしています
• 設計原則をインプットさせる
  • 設計・実装・レビュー時に機能単位の分割や疎結合などの設計原則を事前に渡し、適切な設計になるようにしています
• 実装・テストのルールをスキルに持たせて実装させる
  • コーディング規約とテストの書き方をスキルに組み込み、テストを先に書いてから実装する流れで進めさせています
• コードレビューのルールをスキルに持たせてレビューさせる
  • レビューの観点や基準をスキルに組み込み、実装したものとは別のエージェントにレビューさせています
• UIのルールをインプットさせる
  • 「文字より記号を優先する」といったUIの考え方を事前に渡し、AIっぽい画面になるのを防いでいます
• 開発フローのルールを定義する
  • PRフォーマットやコミットメッセージの形式を決めておき、変更の経緯を後から追えるようにしています
  • ブランチ戦略もルールとして記載しています

まとめ

AIによって、動くものは誰でも作れる時代になり、動くことそのものの価値は下がったと感じています。
しかし、品質を上げることの価値はまだ求められていると思います。保守性、セキュリティ、UI/UX、テスト、アーキテクチャは、AIに任せるだけでは担保されません。人が中身を理解して判断する必要があります。

AIを野放しにせず、知見のある人が自身のナレッジを蓄積したAIエージェント基盤を構築し、チームで使用できるようにする。これが品質を保つ秘訣だと感じています。