コードベース

どのようなものか

コードベースは、チームが一つのまとまりとして編集、レビュー、出荷する
ソース全体です。英語ではcode
baseと二語で書くこともあります。エンジニアが「コードベース」と言うと
きは、アプリケーションのあらゆる変更が集まる場所を指します。コード本
体、テスト、ビルドや検査のスクリプト、データベースの変更、各部分の関
係を説明するドキュメントが含まれます。

ウェブサービスを構築するための方法論であるTwelve-Factor
Appは、実務に最も役立つ定義を示しています。境界を実際に検証できるか
らです。Subversionのような集中型バージョン管理システムでは、一つのリ
ポジトリが一つのコードベースです。Gitのような分散型システムでは、
ルートコミットを共有するリポジトリの集合を指します。ルートコミットと
は、履歴の最初にある、親を持たないコミットです。同じ最初のコミットか
ら発展した二つのリポジトリは、どれほど違いが大きくなっても一つのコー
ドベースです。別々に始まった二つは、ほぼ同じファイルを含んでいても、
二つのコードベースです。

同じ文書は、この定義にもう一つの規則を組み合わせています。一つのコー
ドベースから、複数のデプロイを行うという規則です。各デプロイは、アプ
リケーションの稼働する一つのインスタンスを指し、通常は複数が同時に存
在します。本番が一つ、ステージングがもう一つで、各開発者のローカルコ
ピーも含みます。すべて同じコードベースを実行しますが、コミットは異な
ることがよくあります。開発者の手元にはステージングにない変更があり、
ステージングには本番にない変更があります。

中に何を含めるかは、この定義から決まります。ソースと、それを動くプロ
グラムにするために必要なものはすべて含めます。各依存関係の名前とバー
ジョンを示すマニフェストも、その一つです。依存先そのものは通常は外に
置き、パッケージマネージャーで取得します。デプロイごとに変わる値も外
に置きます。特に認証情報はそうです。一度コミットしたパスワードは、そ
の後、履歴のすべてのコピーに付いて回ります。

一つのコードベースに複数のプログラムを含めることもできます。モノレポ
はフロントエンド、API、データベースのコードを一つのリポジトリに並
べ、一つのコミットで三つすべてを変更できるようにします。ルートコミッ
トによる規則では、これも一つのコードベースです。逆に、別々の履歴を持
つリポジトリにアプリケーションを分けると、各リポジトリが独立したコー
ドベースになります。Twelve-Factorは、その帰結を明言しています。コー
ドベースが複数なら、それは分散システムであり、各構成要素がそれぞれ一
つのアプリケーションです。

なぜ重要なのか

境界は、何を一緒に変更できるかを決めます。一つのコードベース内なら、
APIとそれを呼ぶ画面の変更を、ひとまとまりとして書き、レビューし、
マージできます。二つのコードベースにまたがると、同じ変更に二つのプル
リクエストと二回のリリースが必要になり、一方だけが先に進んでいる期間
が生まれます。どちらも運用できますが、その負担は境界の引き方で決まり
ます。

コードベースは、基準を適用する単位でもあります。テストスイート、リン
ター、フォーマッター、コミットメッセージの規則、タスクランナーは、い
ずれも「コードベース」を対象範囲とし、その外にあるものはどれにも検査
されません。

初期の判断は、コードベースでは特に早く定着します。判断の後に書かれる
すべての行が、その判断を前提とします。そのため、最初の数週間で決めた
層分けの規則や品質基準が、その後に続くすべての形を決めます。後から覆
すには、その前提に沿って増えたコードを書き直すことになります。

人にとって、コードベースは新しく加わった人が受け取るものです。ビル
ド、テスト、実行に必要なものがすべて入っていれば、一度クローンし、一
つのコマンドを実行すれば始められます。必要な知識の一部がコードにあ
り、一部が誰かの記憶にあるなら、最初の一週間は、何がどちらにあるかを
探すことに費やされます。

実際の活用例

あるプラットフォームのリポジトリでは、Go、TypeScript、SQL、Python、
シェルが同居し、複数言語のモノレポを構成しています。言語ごとにビル
ド、テスト、リントの方法が異なります。その対策は、入口を一つにするこ
とでした。go-taskの層は、名前付きターゲット578件に拡大し、ルートファ
イルに50件、その下の名前空間別ファイルに528件を置きました。ネイティ
ブ、Docker、HTTPSの開発モード、コード品質、データベース管理、デプロ
イを扱います。誰でも`task
i--list`を実行すれば、ツール一式を見渡せます。ただし、この数は注意す		engineer.company	70
iべき点も示します。578件は誰か一人が覚えられる範囲を超えており、使い		engineer.company	70
iやすさを保っているのは命名と名前空間による整理です。		engineer.company	70

別のプロジェクトは2025年11月25日に空のリポジトリから始まり、最初の数
週間に決めた三つの方針は、九か月と数千回のコミットを経ても維持されて
いました。層分けした技術構成、ストアド関数を介したデータアクセス、そ
して守らせるコードがまだ少ないうちに設けた警告ゼロの基準です。最後の
判断の理由こそ、この記事の核心です。コミット5,000件目で導入する基準
は整理・改善のプロジェクトになりますが、同じ基準を50件目で導入すれ
ば、それがリポジトリの通常の運用になります。

コードベース内の境界自体が、設計になることもあります。当社の創業者が
NextMarinerでアーキテクチャーの一部に貢献した海事プラットフォーム
は、三層で構成されています。Next.jsのフロントエンドは表示だけを扱い
ます。Fiber上のHumaを使った、意図的に薄いGoのAPIが、ルーティング、検
証、処理の取りまとめを行います。業務ロジックはPostgreSQLの関数に置か
れます。規則を変えるときは、一つの層、つまりSQLだけを変えます。境界
を文書化し、レビューで守らせていました。誰も確認しない慣習は、やがて
慣習として機能しなくなるためです。

このサイトのコードベースには、別の種類の境界があります。プロジェクト
のページは別のリポジトリで執筆し、スクリプトでこのリポジトリへ書き出
してコミットするため、サイトは単独でビルドできます。このコードベース
内では、それらのページは生成ファイルです。ここで作業するための指示
は、手で編集してはならないと定めています。

問題が起きるところ

コピーしたコードが別々に変化します

二つのアプリケーションで同じ補助処理が必要になり、最も手早い方法とし
てコピーします。一年後には、異なる修正を加えた二つの版が存在し、一方
で直した不具合が、もう一方では残っています。Twelve-Factorは、複数の
アプリケーションで同じコードを共有することを規則違反とし、対処方法も
示しています。共通部分をライブラリーに移し、依存関係マネージャーを介
して取り込み、各コードベースで使用するバージョンを明示します。

秘密情報が履歴に入ります

接続文字列やAPIキーを設定ファイルに入れたままコミットすると、その後
はすべてのクローンが持つ履歴に残ります。後のコミットでその行を削除し
ても変わりません。Twelve-Factorの判定を、コミット前に毎回行う価値が
あります。このコードベースを今オープンソースとして公開しても、認証情
報を一つも漏らさずに済むでしょうか。この判定を通らないものは、それぞ
れのデプロイ先の環境に置きます。

生成ファイルを手で編集します

スクリプトが書いたファイルも普通のソースファイルに見えるため、誰かが
誤字を直接直します。次にスクリプトを実行すると古い文章が書き戻され、
修正は何の知らせもなく消えます。生成先のパスを明示し、書き込むのは生
成プログラムだけに限定します。修正はすべて、その入力に加えます。

内部の境界が曖昧になります

締め切りに追われ、最短で済むという理由からリクエストハンドラーにクエ
リを直接書くと、当初の層分けは実際のコードに合わなくなります。一つひ
とつの近道は小さくても、積み重なると二行の変更がすべての層に及ぶよう
になります。規則の文書化は役立ち、レビューはさらに役立ちます。ある層
から別の層へ踏み込むとビルドが失敗する検査は、最も役立ちます。

基準がコードの半分にしか適用されません

フロントエンド用のリンターだけを用意すると、シェルスクリプトとSQLは
検査されず、リンターで防ぐはずだった問題が、そのまま蓄積します。コー
ドベース全体の品質基準には、そこで使うすべての言語を明示する必要があ
ります。これが複数言語を使うリポジトリの、見えにくい負担です。

フォークから別の製品が始まります

チームが関連製品を始めるためにリポジトリをコピーします。両方に同じ
ルートコミットが残るため、Twelve-Factorの規則では、依然として二つの
アプリケーションに使われる一つのコードベースです。そして、先に説明し
た分岐が、リポジトリ全体の規模で始まります。ルートコミットを比較すれ
ば、どちらの状態かが分かります。

```sh
git -C app-a rev-list --max-parents=0 HEAD
git -C app-b rev-list --max-parents=0 HEAD
```

出力が同じなら、ルートとコードベースを共有しています。異なるなら、
別々の二つの履歴です。

参考資料

  * I. コードベース —
一つのコードベースから複数のデプロイを行う規則と、その根拠となるルー
トコミットの共有による判定を説明します。

  * II. 依存関係 —
すべての依存関係をマニフェストで宣言して分離し、何を取り込むのかを
コードベースで厳密に示す方法を説明します。

  * III. 設定 — コードベースの外に置くべきものを判断する、オープン
ソースとして公開できるかという判定を説明します。

  * gitsubmodules — それぞれの履歴を保ちながら、あるリポジトリを別の
リポジトリに埋め込むGitの仕組みを説明します。

  * git-rev-list — 履歴のルートコミットを含め、コミットを列挙するた
めのリファレンスです。

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/codebase/	engineer.company	70
