既存のアーキテクチャの問題が見えると、アーキテクチャを変更して解決すると思います。

それ自体は素晴らしいことなのですが、変更が全体に浸透し切らず古いアーキテクチャと新しいアーキテクチャが混在したままになってしまうと、状況はさらに悪化します。そのため、アーキテクチャを変更する時には、「どうやって完遂するか」もセットで考えるべきでしょう。

10Xの現状は？

混在しています。

自然と移行を完遂できる日は来なかったので、完遂する努力をしています。

完遂するための取り組み

アーキテクチャの限界を漸進的に押し上げる取り組みで紹介した通り、10Xでは以下の4ステップのサイクルを回してアーキテクチャを改善しようとしています。

欲しい特性を狙ってアーキテクチャ決定を積み重ねる
ADRでアーキテクチャ決定の意図を明確にする
linterでADRに辿り着けるようにする
ADRへの違反状況を可視化して漸進的に適応度を上げる

完遂に向かう話は4番目で触れているのですが、実際に移行を完遂するには非適合箇所がわかるだけではなく、適合状況の俯瞰的な現在地がわかる必要があると感じました。

そこで、以下のようなイメージの可視化を行いました。

可視化にあたっては、以下の2点を把握できることを重視しました。

アーキテクチャ決定とコードの乖離は過去と比べて増えているのか。
コードとの乖離が多いアーキテクチャ決定はどれか。

アーキテクチャ決定とコードの乖離は過去と比べて増えているかどうかが把握できると、乖離を解消する動きに割く力が今くらいで十分なのか、それとも不足しているのか、理解できます。また、乖離の増減に加えて総量も把握できると、今が新しいアーキテクチャ決定を加えても良い時なのかどうかも判断できます。

コードとの乖離が多いアーキテクチャ決定を把握できると、何の乖離の解消に力を割けば状況が良くなるのか理解できます。乖離が生じている理由は様々で、単に移行の腕力不足の場合もあれば、アーキテクチャ決定の内容自体に移行を鈍らせる要因がある場合もあります。いずれにせよ、何を見るべきかのヒントにはなります。

可視化の仕組み

10Xではアーキテクチャ決定はADR化し、ADRへの非適合箇所はlintで検出できるようにしています。新しいADRの導入時には非適合箇所がたくさん出るので、当該箇所ではlintを無効にするのですが、この無効にするコード(Dartの場合は // ignore: <rule>)を可視化の材料にしています。

以下のようなスクリプトで日ごとの非適合箇所を抽出し、データを作成しています。

date=<YYYY-MM-DD>
sha=$(git log main --merges --until="${date}$ +0900" -1 --pretty=format:"%H")
git grep -rE "// (ignore|ignore_for_file): .+" "${sha}"

デイリーのデータ作成はGitHub Actionsで行い、BigQueryにロードし、Looker Studioでグラフ化しています。

やってみた手応え

実際にアーキテクチャ決定への適合状況を時系列で可視化してみて、今までよりも良い判断ができそうだと感じました。今自分が主に開発しているリポジトリでは「今はアーキテクチャ変更よりも既存のコードを適合させることに注力する」と判断していますが、今回の可視化は判断の拠り所となる事実であり、この判断を変える条件を考える材料にもなりました。

今後もより良い判断をするための仕組みづくりをしていきたいと思います。