- はじめに
- レガシー課題の整理から始まった、持続可能な設計への再定義
- 共通の設計言語をつくる
- 設計標準をAIが読める形に
- アーキテクチャ審議会の立ち上げ：個別移行から全体最適へ
- イベントストーミングによる共通理解の再構築
- AIツールと共存するレビュー文化
- まとめ
- 宣伝
はじめに
この記事は、DMMグループ Advent Calendar 2025 の11日目の記事です。
デジタル作品を販売するオンラインECサービスでバックエンドエンジニアをしているyachiyと申します。
私が担当しているサービスは、10年以上運用している大規模プロダクトです。 長い歴史の中で多くの改修や拡張を重ねてきましたが、一部にはPHP5系で構築されたままのレガシーなシステムが残っていました。
今回、その領域をPHP8.4とLaravel12へ移行する負債脱却プロジェクトに取り組みました。
本記事では、この移行を通じて見えた、時間を奪う小さな課題の解消や、将来の負債を生まない仕組みづくりについて紹介します。 単なる技術リプレイスではなく、レガシーを生まない設計文化をどう再構築したか。人とAIが協働し、設計を進化させていった過程もあわせてお伝えします。
似た課題を抱えるプロダクトの年末の設計大掃除に向けたヒントになれば幸いです。
レガシー課題の整理から始まった、持続可能な設計への再定義
移行前のシステムには、典型的なレガシー課題が積み重なっていました。
- コントローラの肥大化とビジネスロジックの散在
- レイヤー境界の曖昧さによる依存関係の複雑化
- テストしづらさに起因するリファクタリングの心理的ハードル
Laravelへの移行を、単なるフレームワーク置き換えに終わらせず、変化に耐えられるアーキテクチャへの再構築と位置づけました。 目標は移行完了そのものではなく、数年後もレガシー化しにくい土台づくりです。
現行構造を振り返る中で、同じ機能でもどの層に責務を置き、どう表現するかという設計判断がメンバーごとに微妙に異なる点が見えてきました。 小さな差異でも積み重なると保守性や可読性を損ね、やがて構造的なレガシーの芽になります。
まず、チーム全体の判断基準をそろえるために、アーキテクチャと設計の考え方を整理し、設計標準を策定する方針としました。 これが、移行作業を超えて設計文化を形づくる第一歩になりました。
共通の設計言語をつくる
最初に取り組んだのは、人間のための設計標準づくりです。 正しさを押し付けるのではなく、誰もが共通の基準で迷わず設計できる状態を目指しました。
判断が属人化すると、レビュー観点やコード構造がぶれ、開発速度や保守性に影響します。 共通言語を整えることで、チームとしての一貫性を確立しました。
設計標準の軸
策定では次の4点に重点を置きました。
レイヤー責務の明確化 DDDのドメイン層を中心に、アプリケーション層・インフラ層の役割を明示し、迷いを減らす。
ドメイン以外の層の標準化 実務ではアプリケーション層・プレゼンテーション層の設計判断にも一貫性が必要。
更新系と参照系の分離 CQRSの発想でフローを整理し、責務境界を明確化。テスト容易性と変更耐性を高める。
設計判断の記録 なぜその設計にしたのかをコードと同レベルでドキュメント化。背景やトレードオフも明示し、後から検証可能にする。
これにより、経験や勘に依存しない仕組みとして設計を整理し、共通基準でのレビューや議論が可能になりました。
迷わないルールが、設計を自由にする
ルールを定めると発散が減り、どこに書くか・どう分けるかで悩む時間が短縮されます。 その分、何を表現するか、どんなドメインモデルにするかといった本質的な議論に集中できました。
当初この設計標準はあくまで人のための基準でしたが、後述のAIレビュー導入を通じて、結果的にAIにも参照しやすい構造になっていると気づきました。
設計標準をAIが読める形に
設計標準の策定後、AIコードレビュー（CodeRabbit等）を導入しました。 当初は人間が迷わず判断するための基準でしたが、設計標準をリポジトリに同梱し、レビュー時にAIが参照できるようになると、そのまま有用な情報源として機能しました。 特別なチューニングがなくても、AIは設計標準に沿ったレビューを行えるようになります。
実施した工夫は以下です。
- 設計標準をリポジトリ内に配置し、AIが参照可能にする
- 各レイヤーの責務とフォルダ構成をルールとして明記
- ドメイン層のクラスに、意図や業務背景の簡潔なコメントを付与
その結果、AIが構造や責務の境界を把握できるようになりました。 AIはコードスタイルや構造的な不整合を検出し、人間はドメイン表現や意図、トレードオフといった本質的な議論に集中できます。 レビューは、指摘の場から、人とAIが協働して設計品質を高めるプロセスへと変わりました。
アーキテクチャ審議会の立ち上げ：個別移行から全体最適へ
PHP5からLaravel12への移行で得た知見は、特定プロジェクトにとどまらず、組織全体の設計文化にも活かせるものでした。
設計判断のばらつきやレビュー基準の不統一は、個々のチームに共通するテーマだったため、部としてアーキテクチャ審議会を立ち上げました。
目的は正解の強制ではなく、考え方の共有
審議会はルールの押し付けではなく、判断の背景や意図を透明化し、思考の方向性を揃える場です。 既存構造の是非から入るのではなく、理想像を起点に議論を進めました。 フレームワークやプロダクトに依存しない設計原則を意識し、他システムにも展開可能な共通の考え方を整理しています。
議論テーマと成果
- DDDにおけるレイヤー構造と責務の整理（Domain / Application / Infrastructure）
- 命名規約・依存方向・表明や例外のルール化
- 設計原則・技術選定方針の明文化
- 設計判断の議事録化とナレッジベース化
こうした取り組みにより、設計判断をチームで再現できる知見として共有できるようになりました。 原則はAIレビューにも適用しやすいよう構造を明確化しており、AIがコード構造や命名を適切に理解し、人間はドメインやトレードオフの議論に集中しやすくなっています。
イベントストーミングによる共通理解の再構築
設計標準を現場に根付かせる鍵は、チーム全体がドメインを同じ目線で理解することでした。
そのための手段として、イベントストーミングを導入しました。
開発メンバーを中心に、業務イベントを時系列で整理し、システムの振る舞いとデータの流れを可視化します。 ドメインエキスパートやプロダクト担当から得た情報を開発側で言語化・モデル化していきました。
このプロセスの主な効果は以下です。
- ドメイン境界と責務が明確になり、モジュール設計の方向性が自然に定まる
- 抽象的な議論から、業務事実に根ざした具体的な議論へ移行できる
- 共通モデルを前提に、審議会の議題が建設的に進む
イベントストーミングは、現実世界の出来事を軸に設計を捉え直す実践的なアプローチとして機能しました。 チーム全体への浸透には時間がかかりますが、理解の精度を高める一歩として有効でした。
AIツールと共存するレビュー文化
AIレビューの導入で、レビューの質と速度は大きく変化しました。 AIが形式的・構造的なチェックを担い、人間は設計意図やドメイン判断に集中できます。
一方で、AIの指摘を無批判に受け入れてしまう課題も見えました。そこで、次のような運用を続けています。
- 指摘はそのまま反映せず、背景と意図を確認する
- 審議会でAIの判断プロセスを題材にし、人とAIの認識差を明確化する
- AIの提案が妥当な場合でも、人間が理由を説明できる状態を保つ
まだ発展途上ではありますが、相互補完しながら設計を磨くレビュー文化が形になりつつあります。
まとめ
今回の移行で得た最大の成果は、設計をチームで語り、共に考えられるようになったことです。
審議会、設計標準、イベントストーミング、AIツール。いずれも、設計を個人の感覚からチームの共通言語へ引き上げる文化活動として機能しています。
レガシー移行は、積もった迷いと曖昧さを整理し、次の開発に備える大掃除でもあります。 コードを新しくするだけでなく、設計への向き合い方を整える。その過程で、AIがコードをレビューし、人が意図を磨く。 そんな協働の設計文化が生まれつつあります。
年末の大掃除を終えた部屋のように、新しいアーキテクチャの上で、気持ちよく次の一年を迎えられそうです。
宣伝
長期で運用されているデジタル作品を販売するオンラインECサービスを共に成長させていくエンジニアを募集しております。 ご興味があれば覗いてみていただければと思います。
