Content last updated 2026-06-15

モジュラーコードの指針

Growth Engineers が AI ネイティブなコラボレーションと長期的なメンテナンス性を最適化し、デフォルトでモジュラーコードを書く理由と方法

モジュール性をデフォルトにする理由

Growth Engineers は デフォルトで モジュラーコードを書きます。これは私たちの働き方についての指針であり、「時間があれば」行う任意のリファクタリング作業ではありません。

デリバリーのプレッシャーが高いとき、その瞬間に最も速いもの、つまり今日追加するのは速いが、後で変更、テスト、推論するには高くつく密結合なコードに手を伸ばしたくなります。私たちは意図的にそこから離れようとしています。モジュール性は、最終的に全員を遅くする負債を積み上げることなく、速く進み続けるための方法です。

スコープと他のドキュメントとの関係

このページは意図的に Growth にスコープを限定した、薄い期待値レイヤー です。Growth Engineers に期待することを述べ、どのように 行うかは、ここでガイダンスを再記述するのではなく、ガイドと参考資料にリンクした GitLab の標準的な情報源に委ねます。目的は、「これが Growth での期待値である」と言う場所を 1 つに保つことであり、競合する情報源を作ることではありません。

私たちは意図的に Growth から始めています。これらの期待値は、素早くイテレーションする Fullstack Engineers として私たちがどのように運営するかに適用されます。ここにスコープを限定することで、より広い採用を提案する前にその振る舞いをモデル化できます。有用であることがわかれば、次の自然なステップは、耐久性のある部分を全社的なエンジニアリングドキュメントへ昇格させることです。

AI ネイティブなコラボレーション（主な理由）

私たちは、エンジニアが開発ライフサイクル全体で AI エージェントとコラボレーションする未来に向けて構築しています。AI が正しく安全な変更を提案できるのは、コードが 明確で十分に境界付けられたインターフェイス を公開している場合だけです:

明示的な入力と出力を持つ小さなモジュールは、システム全体を作業メモリに読み込まずに変更を推論するために必要なコンテキストを AI に与えます。
明確な継ぎ目により、AI が提案する変更は、コードベース全体に予測不能に波及するのではなく、局所化されレビュー可能になります。
適切に名付けられた単一責任の単位は、人間とエージェントの両方に意図を読み取りやすくします。

つまり、モジュラーインターフェイスは、AI が私たちを正しく支援するための前提条件です。 密結合なコードは、新しいエンジニアにとって安全に変更しにくいのと同じくらい、エージェントにとっても安全に変更しにくいものです。

メンテナンス性（耐久性のある理由）

コードを AI が扱いやすくする特性は、常に良いコードを作ってきた特性と同じです:

変更の分離 — 1 つのモジュールの変更が、無関係な領域全体に変更を強制しません。
テストしやすさ — 明確な境界を持つ小さな単位は、直接テストしやすいものです。
読みやすさとオンボーディング — 新しいエンジニア（そして将来の私たち自身）は、すべてを理解しなくても 1 つの部分を理解できます。
明確な所有権 — 境界付けられたモジュールは、責任とレビューにきれいに対応します。

AI が扱いやすいこととメンテナンス性は対立しません。それらは同じ規律であり、そこへ投資することはツールがどのように進化しても効果を生みます。

Growth Engineers に期待されること

これを適用するためにソフトウェアアーキテクトである必要はありません。期待されるのは、モジュラーな選択を デフォルトの反射 にし、レビューやリファインメントで なぜそうするのか を説明できることです。具体的には:

小さく単一責任の単位を優先する。 メソッド、クラス、コンポーネントが複数のことを始めたら、分割します。
境界を明示する。 他のモジュールの内部ではなく、明確なインターフェイスに依存します。システムを横断して手を伸ばすのではなく、必要なものを渡します。
新しい作業を明確に定義された継ぎ目に接続する。 新しい機能や変更は、無関係なコードをほどかなくても追加、変更、削除できるよう、明確な拡張ポイントを通じて接続されるべきです。
見つけたときよりもモジュラーにして残す。 もつれた領域に触れるときは、速さのためにもつれを増やすのではなく、作業している継ぎ目に対して小さくスコープ内の改善を行います（ボーイスカウトルール）。
継ぎ目を説明できるようにする。 MR やリファインメントで、モジュールの責任、インターフェイス、境界がそこにある理由を説明できるべきです。

これは学習されるスキルです。問題ありません

モジュラーコードをうまく書くことは、時間をかけて伸びるスキルであり、最初は既存コードに追加するだけより遅く感じることがあります。そのトレードオフは想定内であり、受け入れられます。もつれたコードに対する複利的な利息を後で払うよりも、今そのスキルに投資したいと考えています。境界をどこに置くべきか不確かな場合は、リファインメント、#sd_growth_engineering、または Engineering DRI と早めに相談し、それをブロッカーではなく設計上の会話として扱ってください。

ワークフローでどのように現れるか

これは判断に基づく原則であり、linter が完全にチェックできるものではありません。これは私たちがすでに行っている働き方を通じて強化され、特定の 1 人のレビュアーに取り締まられるものではなく、エンジニアリングチーム全体が所有します。

リファインメント。 継ぎ目がどこにあるかを知ることは、リファインメントの成果物です。これは、すべての変更をより多くの Issue に分割するという意味では ありません。エンジニアが境界を十分に理解し、変更にいくつのマージリクエストが必要か、どのように切り分けるかを判断できるという意味です。
コードレビュー。 私たちのコードレビューは、この原則が強化される主な場所です。レビュアーは結合と境界に関する懸念を提起することが期待され、エンジニアは継ぎ目、つまりモジュールの責任、インターフェイス、境界がそこにある理由を説明できるべきです。
ツール。 すでに正式な境界が存在する場所、例えばバックエンドのバウンデッドコンテキストやフロントエンドのカプセル化作業では、CI がそれらを強制します。それ以外はすべて、レビューで適用される人間の判断です。

水平方向の変更より垂直方向の変更を優先する

継ぎ目がどこにあるかを知っていると、変更を 垂直方向 に、つまり触れるレイヤーを end-to-end に通って価値を届ける薄いスライスとして切り分けられます。これは、すべてのデータベース作業を行い、次にすべてのバックエンド作業を行い、次にすべてのフロントエンド作業を別々の変更として行う 水平方向 の切り分けとは異なります。垂直スライスは、明確な継ぎ目を 必要とし、同時に 強化します。レイヤー間の境界が明示的な場合にのみ、薄い end-to-end のスライスを切り出せます。

Growth ではチームに Fullstack Engineers が配置されているため、これはより重要です。1 人のエンジニアが通常、データベースから UI までスライス全体を所有するため、レビュアーが全体像を見られる 1 つのマージリクエストで一貫した垂直スライスを出荷できる独自の立場にあります。同じ変更を水平方向に分割すると、同じ人が書いているレイヤー間に人工的な引き継ぎが発生し、レビューが難しくなり（各レイヤーが他のレイヤーのコンテキストを欠くため）、変更全体を見ないままコードをマージするリスクが増えます。小規模な Fullstack チームにとって、垂直スライスはオーバーヘッドが低く、フィードバックが速いデフォルトです。

これは判断であり、ルールではありません。正しい答えが 1 つの垂直マージリクエストの場合もあれば、いくつかの場合もあります。レイヤーが本当に独立している場合、水平方向の切り分けがより良い選択であることもあります。詳しくは、水平方向と垂直方向の切り分けのトレードオフと私たちのイテレーションのバリューを参照してください。

ガイドと参考資料

この原則は、GitLab の既存のエンジニアリング標準に基づいています。境界を どのように 引くかの実践的な参考資料として、これらを使用してください:

Software design guides — バウンデッドコンテキスト、深いモジュール、疎結合 / 高凝集に関する GitLab の標準的なガイダンス。
GitLab Modular Monolith design document — この原則がつながる全社的なアーキテクチャ方針。
バックエンド (Ruby): Reusing abstractions と Ruby style guide。
フロントエンド (JavaScript/Vue): Frontend design patterns と JavaScript style guide。
外部: 深いモジュールと複雑さの最小化に関する A Philosophy of Software Design (Ousterhout)。上記のガイダンスの多くの基礎です。