Azit CTOの十亀（<a href="https://x.com/Pocket7878" target="_blank" rel="noopener noreferrer">@Pocket7878</a>）です。 DeliveryXでは、バックエンドのRuby on Railsでの開発をモジュラーモノリス構成で行っており、 本記事では、弊社のモジュラーモノリス構成へのRBSの導入にあたってどのような観点から判断を行ったか、 今後行いたい技術的な改善項目などをご紹介いたします。

弊社のDeliveryXでは、物流業界のDXという事業ドメインに向き合うソフトウェアの開発をおこなっており、 WoltやUber Directといった3PLとのAPI連携や、自社の配送網をすでに保有しているクライアント企業内の配送オペレーションの改善のための機能群など 一つのプロダクトのなかでも、ユースケースや利用タイミングが異なっていたり、同じ単語であっても業務フローが異なっている場面が存在するなど、 ソフトウェアとしてもロジックをいかに疎結合でわかりやすい形に保ち続けるかが開発効率の要の一つであり、顧客への迅速なアウトカムの提供のために重要です。 テストのカバレッジを高く保つことを意識したり、ドメイン駆動設計の概念などを取り入れてビジネス観点とソフトウェア内部の距離を近くするなどの活動も行っておりますが 本記事では、　RBSを利用して型チェックの観点から保守性を高めるための活動をご紹介いたします。

<h2 id="h35a3140377">モジュラーモノリスの分割方針とdry-structの活用</h2>DeliveryXでは、ルートディレクトリに <code>packages</code> というディレクトリを切り、 その下に <code>marketplace</code> (3PLネットワークとの接続） であったり、<code>delivery</code> （配達員アサイン後の配送進捗管理）などといった独立したディレクトリを作成し、 各ディレクトリの間はできるかぎり疎結合にできるように努めて構成をしています。 そのなかでの方針の一つとして、パッケージからは <code>usecase</code> という外部公開の用の限定されたインタフェースを腐敗防止層として定義し、 またUseCaseへの引数としては <code>types</code> というネームスペース以下に定義したイミュータブルなオブジェクトおよびIntegerやStringなどに限るようにしています。 そのようなイミュータブルなオブジェクトは例えば、以下のように<a href="https://dry-rb.org/gems/dry-struct/1.6/" target="_blank" rel="noopener noreferrer">dry-struct</a>と<a href="https://dry-rb.org/gems/dry-types/1.7/" target="_blank" rel="noopener noreferrer">dry-types</a>を利用して定義しています: <pre><code>module Marketplace
&nbsp; module Types
&nbsp; &nbsp; class FooBarConfiguration &lt; StructBase
&nbsp; &nbsp; &nbsp; attribute :foo_bar_id, Types::Integer
&nbsp; &nbsp; &nbsp; attribute :maximum_amount, Types::Integer
&nbsp; &nbsp; &nbsp; attribute :maximum_delivery_minutes_limit, Types::Integer
&nbsp; &nbsp; &nbsp; attribute :foo_prioritize_criteria, Types::Symbol.enum(:price_priority, :time_priority)
&nbsp; &nbsp; &nbsp; attribute :bars, Types::Array.of(Bar)
&nbsp; &nbsp; end
&nbsp; end
end</code></pre>(実際には、StrictやParamsやCoercibleなども適宜使い分けます） このように定義しておくことで、このパラメータとして受け取ったあとの処理は、このオブジェクトから取り出したフィールドはIntegerやStringなどであることは実行時に保証されているとして実装をすることができます。 また、ユースケースの返値についても同様にイミュータブルで明確なオブジェクトにしておくことで、ユースケースの返値を受け取る側の処理に対しても安定したインタフェースとして依存することができるようになります。

<h2 id="hc76d192b89">RBS導入の狙いと課題</h2>上記のように進めているdry-structやdry-typesでは主に実行時の型の保証と、インタフェースの明確化によるコードのドキュメントとしての効果を狙って行っています。 そこに加えてRBSを導入することで、静的にチェックできる領域を増やすことでテストのカバレッジの維持と同様にシステム全体の安全性を向上させるとともに、追加の機能開発の際に静的な型検査による影響範囲の検知なども狙いたいと思い、RBS CollectionやSteep、RubyMineでのRBSサポートがより成長してきたことなどを踏まえて正式に積極的に導入をすすようと判断をしました。 また、AzitではGithub CopilotやChatGPT Team、ChatGPT Proの試験導入や、Devinの試験導入などAIによる開発生産性の向上にも会社全体で取り組んでいます。 そのような観点からもAIにとって扱いやすい形として、主要なデータ型やinterfaceを明確な形で与えておきたい・設計したいという意図もあります。

<h2 id="h544f04ea88">dry-structとRBSの併用</h2>当然のことながら、すでに各パッケージのインタフェースとして定義しているdry-structはそのまま活用でき、引き続き実行時の保証という面では非常に役に立っています。 RBSによる静的型検査では、以下のようにuntypedを経由することで、実際には間違った型の値を外部から渡されてしまう可能性が存在するため、 引き続きdry-struct等による実行時の型検査は必要となります。 たとえば、以下のようなコードが書かれてしまっているとします。 <pre><code>class Foo
 def greeting_message
 return "Hello, World!"
 end
end


class Bar
 def add_two(number)
 return number + 2
 end
end


if __FILE__ == $0
 foo = Foo.new
 puts foo.greeting_message


 bar = Bar.new
 puts bar.add_two(foo.greeting_message)
end</code></pre> このとき、Bar側の型シグネチャとして <pre><code>class Bar
 def add_two: (Integer number) -&gt; Integer
end</code></pre> と、Integerを期待していることを明確にしていたとします。 このとき、Fooの型シグネチャが <pre><code>class Foo
 def greeting_message: () -&gt; String
end</code></pre> と定義されていれば、 steepによる検査時に <pre><code>app/sample.rb:18:19: [error] Cannot pass a value of type `::String` as an argument of type `::Integer`
│&nbsp; &nbsp;::String &lt;: ::Integer
│&nbsp; &nbsp; &nbsp;::Object &lt;: ::Integer
│&nbsp; &nbsp; &nbsp; &nbsp;::BasicObject &lt;: ::Integer
│
│ Diagnostic ID: Ruby::ArgumentTypeMismatch
│
└&nbsp; &nbsp;puts bar.add_two(foo.greeting_message)
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;~~~~~~~~~~~~~~~~~~~~</code></pre> と、正しくミスが指摘されますが、 <code>greeting_message</code> の返値が <code>untyped</code> と宣言されてしまっている場合は 実行時までこのミスに気がつくことはできません、プログラムが段々と大きくなっていくにつれてどのコードがどこで呼び出されているかを 記憶しておいて人間がミスに気がつくというのは段々と難しくなります、またテストのカバレッジを十分に高く保っていたとしても テストケースに万一の漏れが発生してしまう可能性はありますので、異なるタイプの検査で検知できるのであればそれに超したことはありません。 また今回の場合は、すぐにパラメータがbarメソッド内で利用されているので実行時にも値を渡しているところのすぐ近くでエラーが発生しますが、 もし、barメソッドがもらった引数をまた別の関数に渡して、その関数が..と呼び出しの連鎖が長くなってくると、 実行時のエラーを検知した際に、どこからそのような値が侵入してきてしまったかを把握することは困難になってしまいます。 このような場合にもdry-structで適切にインタフェースを宣言してあれば、想定外の値を渡してしまっていることはユースケースを呼び出すための パラメータを作成した段階で実行エラーとして検出されるようになり、パッケージ内部ではその心配をする必要性が減ります。 このように実行時の動的な型検査によって入り口の段階で型を一定保証することによって、パッケージ内部の型シグネチャではユースケースから連鎖的に呼び出される処理の間で渡される型について静的に型検査を行っておけば内部の呼び出し関係の型にある程度自信を持てるようになります。 このように実際の運用では、実行時の動的な型検査と、静的な型検査の役割の違いはきちんと意識して使い分ける必要があります。

<h2 id="ha3f037a130">RBS-Inlineへの段階的移行とそのメリット</h2>上記のようなメリットもあり、RBSの導入を進めていますが、さらにRBSでの普段の開発をスムーズにするために rbs-inlineについても導入をすすめています。 もともと、チームでRBSを導入をすすめるなかで<ul><li>コードレビューの際に、RBSとRubyコードの一致を確認することが難しい</li><li>手作業による型シグネチャの記述の場合に、RBS側にだけ残ってしまっている場合に検査で発見できない</li></ul>など型シグネチャとRubyコードの両方を同時に編集するなかでのミスも発生していました。 前者についてはRubyMineでの型シグネチャへのジャンプ機能なども進歩してきたためスムーズに行えるようになりました 後者については、リファクタリングの過程でのミスなどによって削除したはずのメソッドを引き続き呼び出してしまっている 処理が存在するものの、型シグネチャの方からの記述の削除漏れも同時に発生してしまうことによって型検査でも検出されなかったりする場面もありました。最終的にはCIでのテストによって発見されるものの、もっと開発者がコードでの機能開発に集中しながら型での恩恵も受けやすくしたいと思っていました。 そんななかで、rbs-inlineを導入することでRubyコード側のコメントと完全に同期した形でRBSが生成することが可能になり 開発者も開発中にわかりやすく、またコードレビューでも無意味に浮いたコメントであれば気がつきやすいのでより導入がしやすくなりました。

<h2 id="h0b42f6d9af">dry-structにも型をつけておく</h2>上記でも触れましたがdry-structで定義してあるオブジェクトにも静的型検査用の型シグネチャをrbs-inlineのコメントとしてつけておく必要があります。 以下では、いくつかのパターンに触れて、紹介しておきます。 まずは、メインであるattribute関連の型付けです<pre><code># frozen_string_literal: true
# rbs_inline: enabled
module Optimization
 module Types
 class FooConfiguration &lt; StructBase
 # @rbs! attr_reader optimization_duration_in_seconds: Integer
 attribute :optimization_duration_in_seconds, Types::Coercible::Integer
 # @rbs! attr_reader vehicle_speed_km_per_hour: Float
 attribute :vehicle_speed_km_per_hour, Types::Coercible::Float
 # @rbs! attr_reader clustering_equal_coordinates_service_jobs: bool
 attribute :clustering_equal_coordinates_service_jobs, Types::Bool
 # @rbs! attr_reader ttl: Time | nil
 attribute? :ttl, Types::Params::Time
 end
 end
end</code></pre> たとえば、このようにdry-structが独自で提供している <code>attribute</code> は当然のことながらrbs-inlineでは認識されないので、 <code>@rbs!</code> という埋め込み構文をコメントとしてつけておくことで、このオブジェクトからInteger型などでアットリビュートを取り出すことができることを表現しています。 また、すこしトリッキーな例としては、 <pre><code># frozen_string_literal: true
# rbs_inline: enabled
module Optimization
 module Types
 # @rbs!
 # type batchAssignmentServiceJobsStatus = "IN_PROGRESS" | "COMPLETED"


 # @rbs skip
 BatchAssignmentServiceJobsStatus = Types::String.enum('IN_PROGRESS', 'COMPLETED')
 end
end</code></pre> このように、dry-struct側では、独自の型を表現として大文字から始まる形で宣言ができるのにたいして、同等の型宣言はRBSでは小文字からしか開始できないことなどの制限もあるため 適宜、もとの記述を　<code>@rbs skip</code> でスキップしてもらい、先程と同様　<code>@rbs!</code> による埋め込みで同様のリテラル型による等価な型シグネチャを出力するなどの工夫も必要になります。

<h2 id="h5c913b2688">rbs_railsを併用した運用方針</h2>また、本記事では紹介しませんでしたが、<code>rbs_rails</code> も併せて導入済みのためRailsの自動生成してくれるアソシエーション系のメソッドなども 適切に型がつくため、より一層開発中にIDEでメソッドの自動補完が適切に行われたり、カラムが空の場合を考慮してメソッドの命名や設計意図をどのように設定するかなど 静的な型検査によってより意識的に設計を考える良い機会になっています。 rbs-inline, rbs_railsを併用して、以下のような配置でRBSファイルを管理しています。

<table border="1">
 <thead>
 <tr>
 <th>対象</th>
 <th>対応方針</th>
 <th>配置先</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td>ActiveRecordのメソッド</td>
 <td>rbs_rails に一本化</td>
 <td>sig/rbs_rails/ 以下</td>
 </tr>
 <tr>
 <td>ActiveRecordのカラムへのアクセサ</td>
 <td>rbs_rails に一本化</td>
 <td>sig/rbs_rails/ 以下</td>
 </tr>
 <tr>
 <td>rbs_inline をつけたファイルの sig</td>
 <td>rbs_inline に一本化し、適宜 @rbs! を使う</td>
 <td>各パッケージの sig 以下、 および app/sig 以下</td>
 </tr>
 <tr>
 <td>その他</td>
 <td>可能であれば rbs_inline に段階的に移行していく</td>
 <td>各パッケージの sig 以下、 および app/sig 以下</td>
 </tr>
 </tbody>
</table>

<h2 id="h28b62bc2c0">今後の課題</h2>本記事では、現在DeliveryXの開発で進めているRBSの導入を紹介いたしました。 テストによる試験などと同様に、静的な型チェックを進めることによってよりプロダクトの開発を自信をもって進めることが可能になり、 また、型という目線からプログラムやメソッドの設計を考える機会にもなり、よい設計の指針にもなっています。 今後は <code>steep stats</code> を定期的に報告する仕組みなどを作成し、プロジェクト全体へのRBSの導入率などをチェックできるようにしたいと思っております。

Azitではサーバーサイドエンジニアを募集中です。ご興味をお持ちいただけましたら以下の採用サイトからご応募下さい！

サーバーサイドエンジニア (Tech Lead)

RBSの導入をすすめて、モジュラモノリスバックエンドの保守性を高める

Sogame Masato

Azit CTOの十亀（<a href="https://x.com/Pocket7878" target="_blank" rel="noopener noreferrer">@Pocket7878</a>）です。 DeliveryXでは、2023年中盤からWebフロントエンドへの新しいアーキテクチャの導入を進めており、 本記事では、新しいアーキテクチャの導入にあたってどのような観点から判断を行ったか、 DeliveryXのWebフロントエンドで今後行いたいと思っている技術的な改善項目などをご紹介いたします。

<h2 id="he3a56227a9">2024年現在のDeliveryXのWebフロントエンド技術スタック</h2> 2024年11月現在、DeliveryXのWebフロントエンドの技術スタックは以下のようになっています。<ul><li>Next.js 14</li><li>React 18</li><li>TypeScript</li></ul>そして、プロジェクトの構成はモノレポ構成になっており<ul><li>クライアント企業が利用する管理画面</li><li>弊社オペレーターが利用する管理画面</li><li>共通化されたUIコンポーネント</li><li>UIコンポーネントではない共通化されたロジック</li></ul>という構造になっています。 また、クライアント向け管理画面は画面数27画面、社内管理画面は26画面となっており、それぞれの画面にいくつか機能が存在しますので機能数としてみるともう少し多くなっております。

<h2 id="h18d06fe205">2023年中盤ごろのアーキテクチャと課題</h2> 2023年中盤、DeliveryXではNext.js 13を使用し、Page Routerを採用していました。この時期、次期バージョンであるNext.js 14やApp Routerへの移行を検討していました。 当時のプロジェクト構成では、以下の特徴がありました： 	•	各ページを*.page.tsxファイルとして定義。 	•	ページ内で使用するコンポーネントを同じディレクトリに配置する形式。 <h3 id="h472bd8c72c">当時の課題</h3> この構成で初期段階の開発は順調に進んでいましたが、ページ数や機能数が増えるにつれ、以下の課題が明らかになりました。 コード管理の煩雑化 ページ内機能が複雑化するにつれて、データ取得用のReact hooks、UIコンポーネント、API通信（POSTやDELETEなど）が混在し、管理が難しくなりました。 プロジェクト構造の視認性の低下 ページとその関連コンポーネント、ロジックが一箇所にまとめられているため、どのページが存在しているか一目で把握しにくい状況に。 新規メンバーへの負担 プロジェクト内に明確な規律や設計パターンが存在せず、新しいメンバーが加入した際に開発に慣れるまで時間がかかる状態でした。 これらの課題は、アプリケーション規模の拡大に伴う問題を浮き彫りにし、設計や構成の見直しを検討するきっかけとなりました。

<h2 id="h0fc17a5a23">新しいアーキテクチャの導入検討</h2> そのため、これらの課題の解決のためにプロジェクトのアーキテクチャの見直しを検討しはじめました。 いくつかのアーキテクチャ設計のパターンを見ていく中で、たとえば以下のような事を検討しました。 <h3 id="h0a1de854d8">Atomic Design</h3> UIデザインの観点から整理するという方向で Atomic Designの思想にもとづいて整理することも検討を進め 実験用のブランチを作り試験的に既存の機能をリファクタしてみたりしました。 またAtomic Designを先に導入をすすめた企業の知見なども取り入れたいと思い、記事を探す中では以下の食べログさんの記事が非常に参考になりました。

食べログさんの記事では、<blockquote>「Atoms」と「Molecules」を分けることで得られたメリットが特にありませんでした。</blockquote>と触れられており、<ul><li>Atomsは他のコンポーネントに依存していない最小粒度のコンポーネント</li><li>MoleculesはAtomsや同じ階層のMoleculesなどを組み合わせたコンポーネント</li></ul>としてAtomic Designでは定義されていますが、 我々のチームの開発のなかでも<ul><li>ボタン</li><li>入力フィールド</li><li>入力フィールドとボタンが一列にならんだインラインフォーム</li></ul>などAtomsとMoleculesにそれぞれ分類できそうな単位のコンポーネントは存在しますが、 一方でそれらを区別して管理することで特に開発上まだメリットを感じられる状況では無いように思えました。 事業フェーズやチーム編成を考えると、場当たり的に開発を進めるのは当然避けるべきだと考えています。 一方で、設計思想に準拠しているかを検討することに過度な時間を割いてしまうリスクも、同様に避けるべきだと判断しました。

<h3 id="h66d711161f">bulletproof-react</h3>そのなかで、以下の記事と出会い、bulletproof-reactというアーキテクチャの存在を知りました。

bulletproof-reactではfeaturesというディレクト以下に機能のグループごとにディレクトリを作り<ul><li>hooks</li><li>api</li><li>components</li><li>types</li></ul>という構成で分類し、index.tsを通して外部に必要な部分だけを公開するという方針をとっています。 このような機能 (feature) ごとにディレクトリを分割して管理する方式はfeature moduleパターンとしてモバイルアプリなどでも採用事例が多く

実際にfeature moduleパターンを利用したプロジェクトの開発体験が良いことは弊社モバイルアプリに機能追加をした際に触れてみた場面でも感じていました。 ある機能がReact hooksであるか、componentsであるかなどは開発者の間で意見が分かれることは考えづらいと思い、 また、新しいアーキテクチャの導入目的であるプロジェクトへの規律という意味では十分であると判断しました。 そこで、実際に既存機能のいくつかを実験ブランチのなかで再整理し、迷いなく移行できることを確認したうえで導入を決定しました。 featuresディレクトリからはindex.tsを通して必要最小限の部分だけを外部公開しているため、内部のコンポーネントやロジックを再整理する際にも影響範囲が明確になるため、中長期でもメリットがあると感じています。

<h2 id="h59012fef17">featureアーキテクチャとAppRouter移行</h2>Next.js 13を長く使用してきたため、Next.js 14への早期移行を目指し、併せてApp Routerへの移行も進めることを検討していました。 しかし、まずは既存のコードベースの見通しが良くないと、新しい技術の導入は難しいため まずは新機能開発時にはfeatureアーキテクチャで開発することとし、開発の合間で既存機能についても移行をすすめて全ページの移行を完了しました。 そこで、今度はPageRouterからAppRouterへの段階的な移行プロジェクトを開始することとしました。 AppRouterを利用するにあたっては、ページをRSCに対応する必要がありますし、速度の観点などからも当然メリットがあるため導入したいと思っていました。 一方で、DeliveryXでは物流のデータを扱っているため、ページは必要な情報鮮度の観点から以下のように区別できます: <ul><li>クライアントの操作を伴わずに情報が更新され、鮮度の高い情報が随時反映される必要があるページ（業務の進捗確認ページや、車両の動態管理画面等）</li><li>一般的なCRUD型の管理機能であり、クライアント側の能動的な操作によって情報が変更されるページ</li><li>クライアントの操作を伴わずに情報が更新されるが、鮮度の高さは求められていないページ</li></ul> 後者の2つについてはブラウザのリロードをされたタイミングで最新の情報が反映されればよく、データのフェッチはレンダリングごとで問題ありません。 （※ログインを伴ってユーザーごとの情報を表示する部分が多く、完全に静的に配信できるページは今現在はほとんど存在しません） 一方で前者についてはタブレットや作業場所でブラウザを開いたままにしていても勝手に画面内容が更新されてほしく、 そのようなページについてはすでに<a href="https://swr.vercel.app/ja" target="_blank" rel="noopener noreferrer">SWR</a>を利用して実装されていたため、このようなページについてはほとんど丸々クライアントコンポーネントのままのほうが適切であると判断しました。 また、<a href="https://github.com/react-hook-form/react-hook-form" target="_blank" rel="noopener noreferrer">react-hook-form</a>を利用してデータの入稿や更新系のフォームや実現していたため、Server Actionsには対応しておらず 将来的にServer Actionへの移行は別プロジェクトとして行いたいものの、今回の移行プロジェクトにおいてはこのような通信についても引き続きクライアントサイドから実施する方針としました。

このようにApp Router移行にともなって引き続きクライアントから利用される部分と、RSCでサーバーサイドから利用されるようになる部分が生まれるため features内のAPI通信については、従来のapiディレクトリに一括してまとめるのは難しいと判断しました。 そこで、<ul><li>server_api</li><li>client_api</li></ul>という2つのディレクトリに分離し、それぞれに適切なAPIコールは配置することとしました。 また、featureディレクトリから外部に公開するのはserver_apiディレクトリのみに制限することでApp Router側のページからはRSCからの呼び出しを想定しているAPIのみとなるようにしました。

<h2 id="h7891b8d0ac">今後の課題とやりたいこと</h2> <h3 id="h7ad20108e9">ContainerとPresentationパターン化を検討しコンポーネントを整理する</h3> RSC化をすすめるなかで、今回はserver apiとclient apiを分離する形で分離をしていました。 現在はデータのフェッチはapiを直接呼び出すか、hooksで取得する形を利用していますが、<a href="https://zenn.dev/akfm/books/nextjs-basic-principle/viewer/part_2_container_1st_design" target="_blank" rel="noopener noreferrer">RSCにともなってそのような構成を見直す動き</a>もあります。 もしそのような設計のメリットが大きい場合は、featureディレクトリからserver_apiの公開を不要にできる可能性があり、その点も含めてリファクタリングを検討していきたいと思っています。 <h3 id="hb22db67169"> styled-componentsからRSCに適したCSSへ移行する</h3> RSC化を進めていく中でいくつかのコンポーネントでは、単に情報を表示しているのみなので本来はサーバー側でレンダリング可能であるものの styled-componentsしてスタイリングを行っているためクライアントコンポーネントのままになってしまっているパーツも存在します。 こちらについては、Tailwind CSSへの移行を進めており、そちらについても今後記事化したいと思っております。 <h3 id="h9603ac7f08">Sever Actionへの段階的な移行</h3> DeliveryXでは通信量を削減したりプログレッシブエンハンスメントを進めることで、 中長期的にプロダクトとして倉庫内など電波状況があまり良くない可能性がある環境など様々な方たちに導入していただきやすくなります。 そのような観点からRSCやServer Actionなどの仕組みを導入していくメリットがあると考えております。

AzitではWebフロントエンドエンジニアを募集中です。ご興味をお持ちいただけましたら以下の採用サイトからご応募下さい

Webフロントエンドエンジニア (Tech Lead)

DeliveryXのWebフロントエンドでのFeatureアーキテクチャ導入の背景と実践

株式会社AzitでRailsを使用したバックエンド開発をしている鈴木です。

今回は、Azitでのチーム開発に少しでも興味を持ってもらえるように去年(2022年)チームのコミュニケーション面で改善したことを紹介します。

# 改善した項目

- DesignDocのアップデート
- 定期的に話し合うために週次でのディスカッション・振り返りをするようにした
- チームで共通の認識をもつために社内読書会をおこなうようにした

## DesignDocのアップデート

私達のブログの記事でDesignDocを導入したことを書きましたが、DesignDocを運営をしていく中で以下の問題にあたりました。

- Draw.ioにログインをしている状態じゃないとNotion上で図が見られない
- SUDOモデルだと実装に入るために必要な情報が不足している

## **Notion上でDraw.ioを見れないときがあるのをMermaidを使用して改善した**

以前のDesignDocではDraw.ioに図を書いたものを貼り付けていたのですが、Draw.ioにログインをしている状態じゃないとNotion上で図が見られなかったり、Notion上では変更することができないという問題がありました。

それを改善するために、[Mermaid](https://mermaid.js.org/#/)というNotion上からでも編集できるテキストで図形を描画するツールを使用しました。

Mermaidを使用すると下のような図を作成することができます。


下のようなNotionでコードを入力するところでMermaidを使用して以下のような記述をすると上のような図を書くことができます。

これにより、最初の設計時に間違った内容だったとしてもドキュメント内(Notion)で簡単に編集をすることができ設計図を修正していくことができるようになりました。

## チームで実装をするために必要な設計をして共通認識をもったまま実装を開始できるようにした

DesignDocは以下のことを書くようにしています。

- 要件定義書のへのリンク
    - PdMとBizで話し合ったことの開発チームへの共有を簡単にしています
- コンテキストマップのアップデート
    - ドメインの変更について話し合ってドメインを適切にアップデートをしていくことができるようにしています
- ドメインモデリング
    - 今後の設計に必要な概念や用語を洗い出します
- ユースケース
    - ドメインモデリングをした概念や用語をもとにユースケースを定義します
    - ここからは、[ICONIX(ユースケース駆動)](https://ja.wikipedia.org/wiki/ICONIX)を参考にしています
- ユースケース記述
    - ユースケースを実装するために必要な項目を記述します
- ロバストネス図
    - プロジェクトを網羅的に理解できるようにするために作成します
- ドメインオブジェクト図
    - 集約などについて考えるために作成します
- ER図
    - ドメインオブジェクト図で考えた内容をRDBで作成できるようにします
    - ドキュメントの抽象度を高くしたいためテーブル名のみを記述します
        - カラムも記述するとソースコード内のマイグレーションファイルに記述している内容と乖離が発生しやすくなってしまいます
- UseCaseクラスの模擬コード
    - 実装のイメージを共有するため擬似コードを書く

このように、細かく設計を作成していくことですぐに実装に入ることができるようになります。

設計するときは必ずモブプロをすることで設計に関する議論をリアルタイムでするのと認識の共有をしていくことができます。

また、1回ではすぐに実装をするドキュメントを作成することはできないので、後工程で修正する必要があったら前工程の図を更新するようにしています。

# 定期的に話し合うために週次でのディスカッション・KPTをするようにした

私達のチームはフルリモート・コアタイム無しのフレックスです。また、Gatherなどのようなコミュニケーションツールも使用していないです。

そのため、なにもしなかったらただモクモクとタスクをこなして、チームで適切なコミュニケーションをしながら仕事をすることやチームを通しての成長をするという機会があまりとれないです。

その問題を解決するために、週次で各メンバーが今考えていることを話すためのディスカッションと簡単なKPTをするようにしました。

## ディスカッション

ディスカッションでは、チームに関することとリファクタリングに関することを相談できるようにしています。

### チームに関すること

チームに関することはこれができると良くなるのではないかという提案や相談したいこと、認識を揃えたいことなどチームに関することならなんでも良いです。

話し合うこと自体が目的な部分もあるのでここに書いたことは必ずしもおこなわなくてもいいです。

一度話したことに実際に着手するときは、チームではすでに話し合っているので実施しやすいです。

実際に話し合ったこと

- DDD Learningの次の社内勉強会で扱う本について
- RBSさわっています
- Rspecの記法を統一するために,RubocopのRspecを導入したい

### リファクタリングについて

リファクタリングは、現在は定例MTGに参加しているメンバーが全員バックエンドなのでRailsのリポジトリのコードでリファクタリングしたいことについて話しています。

今実装していたコードに関してはPRでレビューをすることができますが、以前実装した部分やモジュールレベルでのレビューはPRではできないです。

そのため、特定のタイミング(週次MTG)で話し合っています。

ここで話したことでおこなうことは、話し合ったことを忘れないようにするためにJIRAでチケットにしています。

実際に話し合ったこと

- UseCaseのクラス名について
- テストコードの粒度について
- RspecやOpenAPIで `.json` 等のURL末尾によるAcceptの指定をやめる

## KPT

フルリモートなため基本的に一人で仕事をすることになりますので、チームがどういうことをおもって仕事をしているかがわからないです。

わからなかったとしても直近の仕事をする上では問題はないですが、チームメンバーがどういうことをおもっているかが

わかるとお互いのことを知ることができチームビルディングの一つとして機能すると思いますので長期的には有効だと思います。

お互いのことを知るための手軽な方法はKPTだと思いますので、KPTをしたときにチームとして改善したほうがいいということを話すこともできると思います。

# 読書会の実施

チームの共通認識を作っていったほうが、コードレビューやコードの共同所有が効率的におこなえるという考えから勉強会の実施をすることにしました。

最初は、テスト駆動開発入門や実践ドメイン駆動設計などを扱っていましたが、チームとしてDDDに本格的に取り組むにあたりLearning Domain-Driven Design(以下Learning DDD)を読んでいくことにしました。

**Learning DDDの読書会について**

この本は最近発売したばかりなので、イベントソーシングドメインモデルやイベントストーミングなどの最新のトピックについても扱っています。

また、本の説明がわかりやすかったり、章末にある問題をチームで話し合いながら答えを探していくことにより1人で読むよりも理解度がたかくなります。

この本を読書会で扱ったことにより、チーム全体でDDDの共通認識をもつことができるようになっているのでこの本を読書会で扱ってよかったです。


# 求人

この記事に書いたように去年だけでも多くの改善をしていますが、今年はエンタープライズ規模のお客様などを含んだより多くのお客様にCREW Expressを使用してもらえるように、様々なお客様のニーズに答えられるようにしていく必要があります。

一緒に機能を開発したり、開発効率の改善を一緒にしてくれる方を大募集しています。

株式会社AzitでRailsを使用したバックエンド開発をしている鈴木です。今回は、Azitでのチーム開発に少しでも興味を持ってもらえるように去年(2022年)チームのコミュニケーション面で改善したことを紹介します。

サーバーサイドエンジニア (IC)

2022年に開発チームのコミュニケーションを改善するためにおこなったこと

鈴木

株式会社 Azit CTOの <a href="https://twitter.com/Pocket7878" target="_blank" rel="noopener noreferrer">@Pocket7878</a> です. 今回は、CREW Expressプロダクトの各領域で採用している技術スタックをご紹介します。 <h2 id="hebc0f8471a">APIサーバー</h2><ul><li>Rails 6.1.x</li><li>Ruby 3.1.x</li></ul>を利用しています。 サービスの開発当初は、WebフロントエンドもReactのコンポーネントをERBに乗せる形で提供していましたがフロントエンドの開発の生産性等を鑑みて、フロントエンドを切り話してAPIサーバーとしての機能提供に集中しています。 APIのスキーマはOpenAPIで定義しており、<a href="https://github.com/interagent/committee" target="_blank" rel="noopener noreferrer">commitee</a>で実装と定義の一致の検証をすると共に、Webフロントエンド側でAPIクライアントの自動生成に利用しています。 開発のプラクティスとしてTDDとDDDを採用しており、<a href="https://love-from.azit.co.jp/article/ddd" target="_blank" rel="noopener noreferrer">事業ドメインの整理の段階から戦略DDDに取りくんでいます</a> また、Rails上でドメイン構造を整理しつつ、静的型付けのある言語でより開発の信頼性や安定性を向上させるためにコアドメインを段階的にGoに移行することを計画しています。<h2 id="h3d909c6d1f">Webフロントエンド</h2>クライアントさんから利用していただく管理画面、弊社内のオペレータがカスタマーサポートの業務として利用する社内管理画面の開発では、ビジネスの変化に追従しつつ柔軟なUXを提供しやすいように<ul><li>Next.js</li><li>TypeScript</li></ul>を採用しています。 状態管理等にはRecoilとContextを利用しており、APIとの通信はOpenAPIからクライアントを自動生成し、SWRでラップしています。 CSSは、CSS ModuleとCSS in JSを併用していましたが、CSS in JSに寄せていく方針に決定して、新規コンポーネントはCSS in JSで書くと共に既存のコンポーネントの移行も進めています。<h2 id="h054fab72d6">モバイル</h2>配達パートナーから利用されるモバイルアプリケーションはAndroid, iOS両プラットフォームともにネイティブアプリで、Kotlin, Swift 100%でそれぞれ開発しています。 Android向けアプリはマルチモジュールのMVVMになっており、新規機能開発の際には既存の画面等もJetpack Composeでリライトを進めています。 iOS向けアプリはクリーンアーキテクチャ型のマルチバンドル構成で、UIのレイヤーではVIPERアーキテクチャを採用しており、新規機能開発の際には既存の画面をSwiftUIにリライトして開発しています。 VIPERアーキテクチャの採用判断はSwiftUIの登場する以前に判断したため、SwiftUIを前提に考えるとMVVMの方が適合しやすいため移行も検討しています。 Flutter等のクロスプラットフォームフレームワークの導入も開発初期に検討しましたが、サービス開発の時点でネイティブの専門性の高いメンバーが揃っていたこと、当時のフレームワークの知見の量や安定性とアプリケーションに求められる非機能要件などをふまえてネイティブで開発をする判断をしました。<h2 id="hb3c83ebaaa">最適化エンジン</h2>

CREW Expressでは、クライアントさんの配達リクエストをより少ない人数や稼動時間で効率よく配送するための各種最適化を提供する事で、クライアントさんのオペレーションや金銭的なコストを低下させる事を価値として提供しています。 そのような最適化を実施するエンジンはRustで記述しており、インフラはAWS Lambdaに乗せて最適化したい配送の問題定義をPOSTしてやると、最適化をした結果を返すようなプライベートAPIを公開しています。 APIのスキーマはOpenAPIで定義し、仕様の変更があると自動生成したクライアントコードがAPIサーバー側のリポジトリにPRとして発行されるようにしています。<h2 id="h1fc02ea273">インフラ</h2>インフラは全てAWS上に構築しており、スケールしやすい技術選定をすることで運用コストを下げるために、ECS Fargate, ElastiCache, Amazon Aurora, Amazon Lambda等を積極的に利用しています。<h3 id="hdc2da36b1a">位置情報管理</h3>AWS Automotive@Loft 第一回 モビリティサービスで登壇させていただいた時の資料:

配達パートナーの位置情報を記録する事でディスパッチの最適化に利用していますが、位置情報を稼動中の多くの配達パートナーの端末から受信して記録していくことが必要になります。 このシステムは、多くのトラフィックを受ける事になるためWriteに対してスケールする必要があり、またクライアントからの配達リクエストの量が増えた時にReadに対してもスケールが求められます。 そのような要件の位置情報の管理基盤を構築するにあたって、なるべく金銭的にも運用コスト的にも低コストで実現できる事を期待し、 Writeのスケールのために配達パートナーアプリからの書き込みの窓口にAmazon Kinesis Data Streamsを使用し、 位置情報の保存にはAmazon Location Serviceを利用しUberの<a href="https://h3geo.org/" target="_blank" rel="noopener noreferrer">H3</a>を利用してハッシュキーをつくってDynamoDBに索引をつくる事で高速な絞り込みを実現しています。<h3 id="hda9ca5f26d">構成管理</h3>構成管理にはTerraformを利用しています。 CI/CDにはGitHub Actionsを利用しており、PRを送るとfmtのチェックやvalidate、tflintの実行等の各チェックと共に、<a href="https://github.com/suzuki-shunsuke/tfcmt" target="_blank" rel="noopener noreferrer">tfcmt</a>でplanの結果がコメントされたり、マージされたら自動的にapplyされ結果がそのPRに投稿されるようにしており、GitHub上で構成の管理やレビューが完了するようにしています。<h2 id="h5e24d1c553">ログ分析・サーバー監視</h2>アプリケーションでエラーが発生してしまっている時の予兆にすばやく気がつき、その要因特定や解決をすばやく実施する事ができるよう、ログの集積・分析やAPMにはDataDogを利用しており、エラー発生時の要因分析、5xx系エラーの量の監視や外形監視等を実施しています。 また、アプリケーションレベルでのエラーの管理にはSentryを利用していて、新規のエラーが発生した場合にSlackに流れるようにして開発中やリリース後に即座に気がついて対応が可能なようにしています。<h2 id="ha214098e44">まとめ</h2>今回はCREW Expressプロダクトの各領域で採用している技術を紹介いたしました。 CREW Expressでは各領域毎に独立して最適な技術選定が可能となるように分離しながら日々改善を進めており、CREW Expressの技術的な改善を推進してくださる方を募集しています。 少しでも御興味をもってくださったら、是非お気軽に話を聞きにきてください!

CREW Expressプロダクトの各領域で採用している技術スタックをご紹介します。

CREW Expressを支える技術スタック

<h2 id="h5b7f0cf02b">当初はオフィスで口頭ベースで情報共有していた</h2>フルリモートになる前はコアタイムは設けていないにせよ、皆でオフィスに来て作業をして家に帰るというサイクルで日々の業務をしていました。 その頃は物理カンバンを用意して夕方デイリースタンドアップをチーム全体で実施して進捗やヘルプしてほしい事などを共有しながら進めていました。 また、PMとエンジニアの間の連携は、月曜日に前後半にわかれたスプリント計画の定例を開催し、 前半でPMからユーザーストーリーやバックログについて共有を受け、 後半でエンジニアがサブタスクに分解しながら見積を実施して、スプリントのスコープを決めてPMに共有して、物理カンバンに個別のタスクを付箋として貼っていく というサイクルで実施し、それ以外のプロジェクトの背景等は別途別のMTGや定例等で口頭で伝える形をとっていました。 この頃は、メンバーが日々オフィスで同期的に顔をあわせる頻度がたかく、またチームメンバーもあまり変動がないチームでした。<h2 id="he83ce89f4b">新規事業の立ちあげにチームのミッションが変化して発生した課題</h2>上述の口頭ベースで運用がされていたプロジェクトは、プロジェクトも開発されてから長く、チームも一定期間キープされつづけていたチームでした。 しかし、チームのプロジェクトが既存事業への改善や機能追加から新規事業のMVPファーストリリースを目ざす事に変化したために、不確実性やスコープ、仕様の変更等のリズムが従来チームが慣れていた頻度から大きく変化したために、様々な混乱が発生しました。 そのため、しっかりとプロジェクト自体への期待を周囲のステークホルダーと改めて揃え、プロジェクト全体を俯瞰で把握するための土台をつくらなければならないと感じ、インセプションデッキやユーザーストーリマッピングと共に要求仕様書として開発物のターゲットを体系的にまとめました。 その時の詳細は以下の記事にまとめてあります:

その際に、要求をどのようにして体系的にまとめるべきかを学び、要求仕様書をどう書くべきかについて以下の本をつかって勉強しました。 <a href="https://www.amazon.co.jp/%E6%94%B9%E8%A8%82%E7%AC%AC2%E7%89%88-%E5%85%A5%E9%96%80-%E5%AE%9F%E8%B7%B5-%E8%A6%81%E6%B1%82%E3%82%92%E4%BB%95%E6%A7%98%E5%8C%96%E3%81%99%E3%82%8B%E6%8A%80%E8%A1%93%E3%83%BB%E8%A1%A8%E7%8F%BE%E3%81%99%E3%82%8B%E6%8A%80%E8%A1%93-%E4%BB%95%E6%A7%98%E3%81%8C%E6%9B%B8%E3%81%91%E3%81%A6%E3%81%84%E3%81%BE%E3%81%99%E3%81%8B/dp/4774142573/?_encoding=UTF8&amp;pd_rd_w=1volA&amp;content-id=amzn1.sym.79ec8dbb-a6ed-4b2c-b8a2-e2dc98848cba&amp;pf_rd_p=79ec8dbb-a6ed-4b2c-b8a2-e2dc98848cba&amp;pf_rd_r=1ZJ8EXNEVHP7WDDF1BZK&amp;pd_rd_wg=Cnrb1&amp;pd_rd_r=e131dc0e-a1a9-4051-bf15-1e60dd278279&amp;ref_=pd_gw_ci_mcx_mr_hp_atf_m" target="_blank" rel="noopener noreferrer"><img src="https://images.microcms-assets.io/assets/d4e25007543940f0849c6e5f6c46811d/d2c53fa005a44bc0ab322dc82ee67488/91rlese4pOL.jpg?w=211&amp;h=300" alt="[改訂第2版] [入門+実践]要求を仕様化する技術・表現する技術 -仕様が書けていますか?"></a>

そして、以下のような構造でユーザーストーリー単位でビジネスの背景と実現したい細かい挙動の仕様についてまとめはじめました。

# 要求カテゴリ1 ## 要求サブカテゴリ ### 要求: ○○が△△の時□□の時XXできるようにしたい - 理由: 要求が存在するビジネス的背景・届けたい価値 仕様 - [ ] ○○の時XXボタンを表示する - [ ] △△ページに、○○のxxx情報を表示する

<h2 id="hb462e80b8e">業務委託中心のフルリモートチームになって</h2>その後、さらに別の事業にチームのミッションが変化すると共に、チームメンバーも既存のメンバーから業務委託として時間帯や稼動時間がそれぞれ違うメンバー達を中心としたチームになりました。 また、社会情勢の影響もありオフィス勤務という形からフルリモートで働く形のチームへとも変化しました。 このように、既存の関係性や暗黙知が共有されていて同期的に働くメンバーというチームから、新たに会ったメンバーたちと非同期的に働くというチームへとチームの構造が大きな変化を迎えました。 そのため、チームの中での情報の共有のあり方も<ul><li>オンラインでの共有や読みあわせがしやすいよう文書を中心とし</li><li>各メンバーの稼動時間の違いの影響が低くなるようローコンテキストに</li><li>メンバーのいれかわりや新規追加等による在籍期間の差があっても、情報の差が発生しづらいように後から読み返しても記録性や理解がしやすいように</li></ul>という事を重視して、プロダクトチームだけでなく会社全体のナレッジを文章を中心として透明性高く管理するようになりました。<h3 id="h0dcf4373d8">プロジェクトの目的や背景の文書化・明確化</h3>要求仕様書のレベルでも、個別の機能のWhy, Whatだけではなくプロジェクト単位での事業上の意義やユーザーへの価値提供を伝えられるように明記するようにしました。 また、よりオーナーシップをもって開発を進められるようにするためには、決定した形だけでなく「なぜ他の形ではないのか」についても情報に簡単にアクセスできるようにする事が重要であると考え 要求分析の元となった議事録等についてもセクションとして追加し文書から参照しやすいように改善しました。 その後、現時点で開発中や分析中・検討中のものもふくめて、45個ほどプロジェクト要求仕様書を積みかさねてきて段階的に改善をしてきました。

<h2 id="h07b508bda2">実装方針の議論や認識擦りあわせ</h2><h3 id="h3aeba0e563">実装方法についての認識を揃える</h3>上述のように段階的に「要求」という観点から明確化してきた文書ですが、 実際にそれを実体化してユーザーに価値を届けるためには、それをソフトウェア上に実装する必要があります。 そして、ソフトウェア上に実装するという事自体もメンバー間での情報共有や認識の共有等も必要で複雑で難しい事です。 当初は要求仕様書の目的で共有していましたが、しだいに開発メンバーが要求仕様書の色々なところに開発中に検討している事や検討すべき事などについて「開発メモ」のような物を自主的に追加しはじめてくれていました。 そのように実装についても情報が共有されるようになった事で、開発メンバー間での開発に関する情報共有が成されるようになった一方で、 文書としてのパターンや構造がなくなってしまい、長期的な文書としての記録性については下ってしまったと感じました。 そのため、そのような情報を正式に構造として文書に組み込みたいと考え、実装設計というセクションを設けました。 また、このタイミングで要求仕様だけでなく実装設計等も含めて体系的に記載する文書であるという観点で名称をDesign Docに変更しました。 また、開発の実装方針等の「議論の過程」については議事録の一種であると考え、文書中に都度走り書きする形式ではなく、別の文書に書いておきリンクしておくようにしました。 そして、実装設計のセクションに議論を経てのAPIエンドポイントの設計やモデルに対する変化を記載するようになりました。 この記載が、JIRAのカンバンで管理するようになった開発のタスクの元となりチームでの作業の分担の土台となるようにしました。<h3 id="h1f65feefd4">課題: 実装と対応する要求仕様の関連を時間が立つと見失うよう事が発生した</h3>最初はPMが主に責任を持つ要求仕様のセクションと開発チームが責任を持つ実装設計は別のセクションにしていました

1 要求仕様 1-a ○○としてXXしたい 1-a-1 理由 1-a-2 仕様 2 実装設計 2-1 モデル 2-1-a [ActiveRecord, 新規] FooBar 2-2 API 2-2-a GET /foo/bar/baz

しかし、こうした事によってプロジェクト開始から時間がたつと「この実装設計はどの要求の実現のためにつかうやつなのか」という認識の齟齬が発生発生し、実装方針のミスや、レビュー時の負担が増えました。 責任を持って内容を管理するセクションを分けるという事と、実際に正しい実装を通してユーザーに価値が早く届くという事では、当然後者の事が大切です。 そのため、セクション設計を変更し

<ol><li>背景</li><li>モデリング<ol><li>システム関連図</li><li>ユースケース図</li><li>ドメインモデル図&amp;オブジェクト図</li><li>オブジェクト図</li><li>ドメインモデル図</li></ol></li><li>要求仕様書<ol><li>○○としてXXしたい</li><li>理由</li><li>仕様</li><li>実装設計</li></ol></li><li>4. 議事録・開発メモ</li></ol>

と、実装設計を各ユーザーストーリーのセクションの中に配置する事とし、実装社もレビュワーもどの要件がどのように実現されようとしているのか(いたのか)という把握がしやすいように改善しました。<h2 id="hd4d28df497">事業ドメインが複雑になって要求も複雑になった</h2>その後、様々なクライアントからのニーズを把握し重要な価値提供をするために機能を追加していくにつれて、プロダクトであつかう事業ドメインが段々と複雑になってきました

そのため、プロダクトに新たに追加しようとしている(もしくは既存の機能を変化させようとしている)部分がどのような立ち位置やユースケースを事業ドメイン上持つのかという事を要求分析の段階から意識する必要があると共に、チームメンバーとも意識を共有する必要があります。 そのため、sudoモデリングの図についてもDesign Docに乗せ、現在は以下のようなセクション構造になっています。<h2 id="h6650e53384">一つ一つのセクションや構造について追加する意義を考えながら段階的に改善する</h2>このように、Azitのプロダクトチームでプロジェクトの情報共有をするための文書は、直面した課題に対してアプローチするために段階的に育ててきました。 他社で同様にDesignDocと呼ばれている文書の中にはまだ、今現在の弊社のDesignDocには設置されていないセクションもあります。 もちろん、他社のテンプレートをそのまま持ってくるという方法もあるとおもいますが、チームの中でただ盲目的に「セクションに内容を書くという事になっているからとりあず書く」というような文書化する事自体が目的化してしまう事は避けたいと考えているため、文書の構造をすばやく改善していく事を重視し、一つ一つのセクションや構造について「なぜここにそのセクションがあるのか」をきちんと理解した状態で文書を育てていきたいと考えています。

フルリモートになる前はコアタイムは設けていないにせよ、皆でオフィスに来て作業をして家に帰るというサイクルで日々の業務をしていました。    その頃は物理カンバンを用意して夕方デイリースタンドアップをチーム全体で実施して進捗やヘルプしてほしい事などを共有しながら進めていました。