トランクベース開発導入ガイド

開発チームに共有したものを再編したもの。

1. トランクベース開発とは

トランクベース開発（Trunk-Based Development, TBD）は、単一のメインブランチ（trunk/main）に全員が頻繁に統合する開発スタイルです。長寿命のフィーチャーブランチを避け、小さな変更を1日に複数回マージすることで、統合の痛みを最小化します。

DORAリサーチによると、トランクベース開発は継続的インテグレーションの必須条件であり、ソフトウェアデリバリーのパフォーマンスと組織のパフォーマンスに強い相関があるとされています。

核となる原則

短寿命ブランチ: ブランチは数時間〜最大1日で完結
頻繁な統合: 1日に複数回のマージ
常にデプロイ可能: mainブランチは常にリリース可能な状態を維持
小さな変更: PRサイズを小さく保つ（推奨200行以下）

PRの位置づけ：短命な検証の箱

トランクベース開発において、**PRは「作品」ではなく「検証ゲート」**です。

┌─────────────────────────────────────────────────────────┐
│  従来の認識（❌ アンチパターン）                          │
│                                                         │
│  PR = 完成した機能を披露する場                           │
│       → 大きくなりがち、レビューが重い、マージが遅い      │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  トランクベースでの認識（✅ 推奨）                        │
│                                                         │
│  PR = CIと最低限の品質保証を行うための短命な箱            │
│       → 小さく、素早く通過、trunk に統合                 │
└─────────────────────────────────────────────────────────┘

PRの役割を再定義する

観点	従来の考え方	トランクベースでの考え方
目的	機能の完成を確認	CIパス + 最低限の品質チェック
寿命	数日〜数週間	数時間〜最大1日
サイズ	機能単位（大きい）	変更単位（小さい）
レビュー	詳細な設計レビュー	壊れていないかの確認
心理的位置づけ	「見せる場」	「通過点」

なぜ「短命な箱」なのか

統合の遅延はリスク: PRが長く開いているほど、コンフリクトと統合コストが増大
フィードバックループの短縮: 早くマージすれば、早く本番で検証できる
レビュー負荷の軽減: 小さなPRは認知負荷が低く、素早くレビューできる
心理的安全性: 「完璧でなくても出せる」という文化が継続的改善を促進

チームで共有すべきマインドセット

「PRは完成品の発表会ではない。trunkに安全に統合するための一時的なチェックポイントである。」

PRをオープンしたまま数日放置しない
「まだ完璧じゃないから」とマージを躊躇しない（Feature Flagsで制御）
レビューは「承認するか否か」ではなく「壊れていないか」を確認
大きな機能は複数の小さなPRに分割する設計力を磨く

2. Git Flow との比較

観点	Git Flow	トランクベース開発
ブランチ寿命	長い（数日〜数週間）	短い（数時間〜1日）
ブランチ構成	develop, feature/, release/, hotfix/*	main + 短命ブランチ
マージ頻度	低い（機能完成時）	高い（1日複数回）
コンフリクト	大きくなりがち	小さく済む
リリース	計画的・バッチ型	継続的デプロイ向き
コードドリフト	発生しやすい	最小限
統合の痛み	大きい（Big Bang Integration）	小さい（頻繁な統合）

選択の基準

Git Flow が向くケース:

明確なリリースサイクルがある製品
複数バージョンの並行保守が必要
リリース承認プロセスが重い組織

トランクベース開発が向くケース:

CI/CDを活かした継続的デリバリー
SaaS・Webサービス
高頻度リリースを目指すチーム
AI Agentとの協業ワークフロー

3. 導入の前提条件

トランクベース開発を機能させるには、いくつかの技術的・文化的な土台が必要です。

必須に近いもの

高速で信頼性の高いCIパイプライン
- コミットごとに自動テスト実行
- 目標: 10分以内でフィードバック
十分なテストカバレッジ
- 壊れたコードの早期検知
- ユニットテスト + インテグレーションテスト
迅速なコードレビュー
- 同期的レビュー（ペアプロ含む）の推奨
- レビュー待ちの最小化

あると良いもの

Feature Flags: 未完成機能を本番に入れつつ非表示に
Branch by Abstraction: 大きなリファクタリングを段階的に
自動デプロイ: マージ→デプロイの自動化

4. 技術的な導入プロセス

Phase 1: CI/CD の整備（2-4週間）

GitHub Actions の基本設定

# .github/workflows/ci.yml
name: CI Pipeline
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

目標メトリクス

CI実行時間: 10分以内
テストカバレッジ: 可視化・目標設定
ビルド成功率: 95%以上

Phase 2: PR Size Labeler の導入

CodelyTV/pr-size-labeler を使って、PRサイズを自動でラベル付けし、大きすぎるPRを可視化します。

# .github/workflows/labeler.yml
name: PR Size Labeler
 
on: [pull_request]
 
jobs:
  labeler:
    permissions:
      pull-requests: write
      contents: read
      issues: write
    runs-on: ubuntu-latest
    steps:
      - uses: codelytv/pr-size-labeler@v1
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          xs_label: 'size/xs'
          xs_max_size: '10'
          s_label: 'size/s'
          s_max_size: '100'
          m_label: 'size/m'
          m_max_size: '200'
          l_label: 'size/l'
          l_max_size: '500'
          xl_label: 'size/xl'
          fail_if_xl: 'false'
          message_if_xl: >
            ⚠️ このPRは推奨サイズ（500行）を超えています。
            複数のIssueを1つのPRで対応していないか確認してください。
          files_to_ignore: |
            package-lock.json
            pnpm-lock.yaml
            *.generated.ts

推奨PRサイズ基準

ラベル	行数	推奨度
XS	〜10行	✅ 理想的
S	〜100行	✅ 推奨
M	〜200行	⚠️ 許容
L	〜500行	⚠️ 要注意
XL	500行超	❌ 分割推奨

Phase 3: ブランチ保護ルールの設定

リポジトリ設定 → Branches → Branch protection rules

✅ Require a pull request before merging
✅ Require approvals (1人以上)
✅ Require status checks to pass before merging
   - CI Pipeline
✅ Require branches to be up to date before merging
✅ Do not allow bypassing the above settings

Phase 4: Feature Flags の導入

未完成機能を安全にデプロイするための仕組み。

// lib/feature-flags.ts
type FeatureFlag = 'new-checkout-flow' | 'ai-recommendations' | 'v2-api';
 
interface FeatureFlagContext {
  userId?: string;
  environment: 'development' | 'staging' | 'production';
}
 
export function isEnabled(flag: FeatureFlag, context: FeatureFlagContext): boolean {
  // 環境変数ベースの簡易実装
  // 本格運用ではLaunchDarkly, Unleash等を検討
  const envKey = `FEATURE_${flag.toUpperCase().replace(/-/g, '_')}`;
  return process.env[envKey] === 'true';
}
 
// 使用例
if (isEnabled('new-checkout-flow', { userId, environment: 'production' })) {
  return <NewCheckoutFlow />;
}
return <LegacyCheckoutFlow />;

Feature Flag ツール比較

トランクベース開発を支えるFeature Flagツールは、内製からマネージドサービスまで選択肢があります。

OpenFeature について

OpenFeature は CNCF（Cloud Native Computing Foundation）のインキュベーティングプロジェクトとして開発された、フィーチャーフラグ用のオープン仕様APIです。

ベンダー非依存: 統一インターフェースで、ツール間の切り替えが容易
ベンダーロックイン回避: コードレベルでの依存を排除
幅広いSDK: Go, Java, JavaScript, Python, .NET, PHP, Ruby など対応
主要ツールがサポート: LaunchDarkly, Unleash, Flagsmith, Split など

OpenFeature に準拠したツールを選ぶか、内製する場合も OpenFeature 準拠で実装すると、将来のツール移行が容易になります。

ツール比較表

ツール	種別	デプロイ	OpenFeature	特徴	価格
LaunchDarkly	SaaS	クラウドのみ	✅	業界標準、豊富な機能、エンタープライズ向け	$12~/月〜
Unleash	OSS/SaaS	セルフホスト/クラウド	✅	Apache 2.0、段階的ロールアウト	無料〜
Flagsmith	OSS/SaaS	セルフホスト/クラウド/オンプレ	✅	Apache 2.0、柔軟なデプロイ	$45~/月〜
GrowthBook	OSS/SaaS	セルフホスト/クラウド	✅	A/Bテスト特化、データウェアハウス連携	無料〜
ConfigCat	SaaS	クラウド	✅	シンプル、クロスプラットフォーム	無料〜
Flipt	OSS	セルフホスト	✅	Git連携、DB不要	無料
PostHog	OSS/SaaS	セルフホスト/クラウド	✅	分析・セッションリプレイ統合	無料〜
DevCycle	SaaS	クラウド	✅	開発者ワークフロー最適化	無料〜
Statsig	SaaS	クラウド	-	実験機能が強力、無料枠が大きい	無料〜
内製（環境変数）	自社	任意	実装次第	シンプル、コスト最小	インフラ費のみ

選定の観点

1. デプロイ要件

クラウドのみで良い: LaunchDarkly, ConfigCat, DevCycle
セルフホスト必須（規制・データ主権）: Unleash, Flagsmith, Flipt, GrowthBook

2. 機能要件

シンプルなオン/オフのみ: 内製、ConfigCat, Flipt
段階的ロールアウト: Unleash, LaunchDarkly, Flagsmith
A/Bテスト統合: GrowthBook, Statsig, LaunchDarkly
分析統合: PostHog, Statsig

3. コスト

無料で始めたい: Unleash（OSS）, Flipt, GrowthBook（OSS）, 内製
予算がある: LaunchDarkly, Split

4. OpenFeature 対応

将来のツール移行を考慮するなら、OpenFeature 対応ツールを選ぶか、内製時も OpenFeature 準拠で実装

内製する場合のアプローチ

CyberAgentの事例（参考記事）のように、シンプルな要件であれば内製も有効です。

内製のメリット:

コスト最小（インフラ費のみ）
シンプルな要件に最適化
外部依存なし（可用性リスク低減）

内製のデメリット:

運用・保守コスト
高度な機能（段階的ロールアウト、A/Bテスト）は追加開発が必要
UI がない場合、非エンジニアが状態を把握しにくい

内製時の推奨:

OpenFeature 準拠で実装: 将来 FFaaS に移行する際のコード変更を最小化
フラグの肥大化対策: 有効期限（expire）をメタデータとして管理
定期的な棚卸し: Slack通知などで放置フラグを検知
ドキュメント化: 各フラグの目的・状態・期限をコメントで明記

// OpenFeature 準拠の Provider インターフェース実装例
type FeatureProvider interface {
    Metadata() Metadata
    BooleanEvaluation(ctx context.Context, flag string, defaultValue bool, evalCtx FlattenedContext) BoolResolutionDetail
    StringEvaluation(ctx context.Context, flag string, defaultValue string, evalCtx FlattenedContext) StringResolutionDetail
    // ...
}

フラグ管理のベストプラクティス

どのツールを使っても共通して重要なのは、フラグのライフサイクル管理です。

const (
    EnableNewCheckout FeatureFlag = "ENABLE_NEW_CHECKOUT"
    // where: api-gateway
    // status: Active
    // expire: 2026-03-01
    // note: 新決済フローの段階的ロールアウト用
    // ----------------------------------------
)

where: どのサービスで使用するか
status: Active / Development / Disabled
expire: 無効化予定日（技術的負債化防止）
note: フラグの目的・背景

5. Code Climate Velocity によるメトリクス計測

DORA メトリクスの活用

Code Climate Velocity は、DORA（DevOps Research and Assessment）が定義した4つのキーメトリクスを計測できます。

メトリクス	説明	Elite基準
Deployment Frequency	本番デプロイの頻度	オンデマンド（1日複数回）
Lead Time for Changes	コミット→本番までの時間	1時間未満
Mean Time to Recovery	障害からの復旧時間	1時間未満
Change Failure Rate	デプロイ失敗率	0-15%

Velocity で追跡すべき追加メトリクス

トランクベース開発の健全性を測るために、DORA以外にも以下を追跡します:

Cycle Time: PRオープン → マージまでの時間
PR Size: 変更行数の分布
Unreviewed PRs: レビュー待ちPRの数
Time to First Review: PRオープン → 最初のレビューまでの時間

導入ステップ

Code Climate Velocity にリポジトリを接続
Jira/GitHub Issues との連携設定
デプロイ・インシデントデータのAPI連携
ダッシュボードでチーム別メトリクスを可視化

6. AI Agents によるタスク分解

トランクベース開発の成功には「大きな機能を小さなPRに分解する力」が不可欠です。AI Agent の Planning 機能を活用することで、この分解作業を効率化できます。

なぜタスク分解が重要か

トランクベース開発では、1つのPRは数時間〜1日で完結する必要があります。しかし、実際の機能開発は数日〜数週間かかることも多い。このギャップを埋めるのが**タスク分解（Task Decomposition）**です。

┌─────────────────────────────────────────────────────────┐
│  従来の開発                                              │
│                                                         │
│  「ユーザー認証機能を作る」                               │
│       ↓                                                 │
│  1つの大きなPR（2週間後にマージ）                         │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  トランクベース開発 + タスク分解                          │
│                                                         │
│  「ユーザー認証機能を作る」                               │
│       ↓ AI Agent による分解                             │
│  PR1: User モデルとマイグレーション追加                   │
│  PR2: パスワードハッシュ化ユーティリティ                   │
│  PR3: 認証サービスの骨格（Feature Flag で非表示）          │
│  PR4: ログインエンドポイント                              │
│  PR5: セッション管理                                     │
│  PR6: Feature Flag を有効化してリリース                   │
└─────────────────────────────────────────────────────────┘

AI Agent を使ったタスク分解のワークフロー

Step 1: ゴールを明確にする

まず、実現したい機能の全体像を AI Agent に伝えます。

ゴール: ユーザーがメールアドレスとパスワードでログインできるようにする

受け入れ基準:
- メールアドレスとパスワードでログインできる
- ログイン状態が24時間維持される
- 5回連続で失敗するとアカウントがロックされる

Step 2: 依存関係を考慮した分解

AI Agent は、以下の観点でタスクを分解します:

依存関係の特定: どのタスクが先行して完了する必要があるか
独立性の確保: 並行して進められるタスクはどれか
PRサイズの最適化: 各タスクが200行以下に収まるか
テスト可能性: 各タスク単体でテストできるか

依存関係グラフの例:

[DB スキーマ] ─────┬──→ [認証サービス] ──→ [エンドポイント]
                  │
[ハッシュ関数] ────┘

[Feature Flag 設定] ──→ [UI 統合]

Step 3: 各タスクを Issue/PR 単位に落とし込む

分解されたタスクを、それぞれ独立した Issue として作成します。

#	タスク	依存	推定サイズ	Feature Flag
1	users テーブルのマイグレーション追加	なし	XS	不要
2	User モデルとバリデーション	#1	S	不要
3	bcrypt によるパスワードハッシュ関数	なし	XS	不要
4	AuthService の骨格（空実装）	#2, #3	S	必要
5	login() メソッドの実装	#4	S	必要
6	アカウントロック機能	#5	S	必要
7	POST /auth/login エンドポイント	#5	S	必要
8	Feature Flag 有効化 + E2Eテスト	#7	S	-

タスク分解のパターン

AI Agent が使う典型的な分解パターン:

1. レイヤー分解

データ層 → ビジネスロジック層 → API層 → UI層

各レイヤーを独立したPRとして切り出す。

2. 垂直スライス

機能A の全レイヤー → 機能B の全レイヤー → ...

1つの小さな機能を端から端まで実装してリリース。

3. Branch by Abstraction

1. 抽象インターフェース定義
2. 新実装を追加（Feature Flag で切り替え）
3. 旧実装を削除

大規模なリファクタリングを安全に進める。

チームでの活用方法

計画フェーズで使う

スプリント計画やタスク見積もりの際に、AI Agent にタスク分解を依頼:

入力: 「決済システムに PayPay を追加する」

出力:
- 必要なタスクのリスト
- 依存関係
- 各タスクの推定サイズ
- Feature Flag が必要な箇所
- リスクが高いタスクの特定

レビューで使う

PRが大きすぎる場合、AI Agent に分割案を相談:

入力: 「このPR（500行）を分割したい」

出力:
- 論理的な分割ポイント
- 分割後の各PRの概要
- 分割の順序（どれを先にマージすべきか）

注意点

AI の出力は出発点: 分解案はチームでレビュー・調整する
ドメイン知識は人間が補完: AI はコードベースの文脈を完全には理解できない
過度な分解を避ける: タスクが細かすぎるとオーバーヘッドが増える
依存関係の検証: AI が見落とす依存関係がないか確認する

7. よくある懸念と対処法

「大きな機能開発はどうする？」

対処法: Feature Flags + 段階的な内部リファクタリング

機能を小さなPRに分解する設計力が重要
内部APIの変更 → UIの変更 → Feature Flag有効化
Branch by Abstraction パターンの活用

「レビューが追いつかない」

対処法:

小さなPRは実際にレビューしやすい（認知負荷が低い）
ペアプログラミングでリアルタイムレビュー
レビュー待ち時間のメトリクス化・改善

「CIが遅い」

対処法:

テストの並列化
差分テスト（変更されたファイルに関連するテストのみ）
キャッシュの活用（依存関係、ビルド成果物）
テストピラミッドの見直し（E2Eの削減）

「コードフリーズはどうする？」

対処法:

理想的にはコードフリーズ不要
Feature Flagsで本番リリースをコントロール
どうしても必要な場合は短期間に限定

8. 導入チェックリスト

準備フェーズ

CI/CDパイプラインが10分以内で完了する
テストカバレッジが可視化されている
ブランチ保護ルールが設定されている

運用フェーズ

PR Size Labeler が動作している
PRサイズの目安がチームで合意されている
レビュー待ち時間が計測されている
Feature Flagsの仕組みがある（必要な場合）

計測フェーズ

DORA メトリクスが計測されている
Cycle Time が可視化されている
定期的な振り返りでメトリクスを確認している

AI Agent 活用フェーズ

タスク分解に AI Agent を活用するフローが確立されている
分解されたタスクの依存関係が可視化されている
AI の分解案をチームでレビューするプロセスがある

Notes

エクスプローラー

トランクベース開発 導入ガイド

1. トランクベース開発とは

核となる原則

PRの位置づけ：短命な検証の箱

PRの役割を再定義する

なぜ「短命な箱」なのか

チームで共有すべきマインドセット

2. Git Flow との比較

選択の基準

3. 導入の前提条件

必須に近いもの

あると良いもの

4. 技術的な導入プロセス

Phase 1: CI/CD の整備（2-4週間）

GitHub Actions の基本設定

目標メトリクス

Phase 2: PR Size Labeler の導入

推奨PRサイズ基準

Phase 3: ブランチ保護ルールの設定

Phase 4: Feature Flags の導入

Feature Flag ツール比較

OpenFeature について

ツール比較表

選定の観点

内製する場合のアプローチ

フラグ管理のベストプラクティス

5. Code Climate Velocity によるメトリクス計測

DORA メトリクスの活用

Velocity で追跡すべき追加メトリクス

導入ステップ

6. AI Agents によるタスク分解

なぜタスク分解が重要か

AI Agent を使ったタスク分解のワークフロー

Step 1: ゴールを明確にする

Step 2: 依存関係を考慮した分解

Step 3: 各タスクを Issue/PR 単位に落とし込む

タスク分解のパターン

1. レイヤー分解

2. 垂直スライス

3. Branch by Abstraction

チームでの活用方法

計画フェーズで使う

レビューで使う

注意点

7. よくある懸念と対処法

「大きな機能開発はどうする？」

「レビューが追いつかない」

「CIが遅い」

「コードフリーズはどうする？」

8. 導入チェックリスト

準備フェーズ

運用フェーズ

計測フェーズ

AI Agent 活用フェーズ

9. 参考リソース

グラフビュー

目次

トランクベース開発導入ガイド