クライアントとエージェンシーのためのソースコード引き渡しチェックリスト

ソースコード引き渡しで達成すべきこと

ソースコードの引き渡しは、プロジェクトが「エージェンシーだけが動かせるもの」から「クライアントが所有できるもの」へ変わる瞬間です。明確な引き渡しがないと、アプリが特定の開発者の環境でしかビルドできなかったり、本番が見つからない秘密鍵に依存していたり、小さな更新が数日間の推測作業になったりします。

このチェックリストの目的はシンプルです。引き渡し後、クライアントがエージェンシーを呼ばずにプロダクトをビルド、実行、デプロイできること。ただし「永久にサポート不要」を意味するわけではありません。基本的な作業が繰り返し可能で文書化されていれば、次の担当者が自信を持って引き継げます。

何が成果物に含まれるべきかは明示しましょう。最低限、完全な引き渡しには通常以下が含まれます:

• フルリポジトリ（デプロイ用ファイルとマイグレーションスクリプトを含む）
• クリーンなマシンで動くセットアップ手順書
• アクセスの引き継ぎ（アカウント、権限、システムの所在）
• 日常作業のランブック（デプロイ、ロールバック、バックアップ、ログ）
• クライアントが参照できる最終の「動作確認済み」バージョンタグやスナップショット

スコープは内容と同じくらい重要です。ある引き渡しは本番環境のみを対象とすることもあれば、開発／ステージング／本番を個別に含めることもあります。どの環境が含まれるかを明記しなければ、相手側が勝手に想定してしまい、そこで障害が起きます。

実務的には検証テストで成功条件を定義するとよいでしょう：そのアプリをビルドしていない人が、コードをエクスポート（例：Koder.aiのようなプラットフォームから）、ドキュメントに従い、環境変数を設定し、マイグレーションを実行し、ビルドして合意した環境にデプロイできることを確認します。

このチェックリストは技術的な準備に焦点を当てています：環境変数、シークレットのローテーション、データベースマイグレーション、デプロイスクリプト、ビルド検証。法的条件、契約、知的財産、支払いトラブルは別の合意に含めるべき事項であり、本稿では扱いません。

エクスポート前：所有権とタイミングを合意する

クリーンな引き渡しは、エクスポートの前に始まります。誰が何をいつ所有するか合意しておけば、デプロイが壊れる、ホスティングの未払いでサービスが止まる、アクセスが見つからないといった直前のトラブルを避けられます。

引き渡し日と短いフリーズ期間を決める

引き渡し日を決め、24〜72時間程度のフリーズ期間を定義して、その間は緊急修正のみを許可するのが一般的です。これによりエクスポートされるコードと稼働中のシステムの整合性が保たれます。フリーズ中にホットフィックスが入る場合は、何が変更されたかを正確に記録し、最終エクスポートに含まれることを確認してください。

アカウントと請求の所有権を明確にする

DNS、クラウドホスティング、その他有料サービスの所有権を誰が持つかを決めてください。これは単なる書類作業ではありません。請求がエージェンシーのカードのままだと、後でサービスが予告なく停止される可能性があります。

具体的なチェック項目:

• DNS、ホスティング、メールのアカウント所有者を明記する
• 引き渡し日以降の支払い担当を確認する
• アカウントを移管するのか、クライアント名義で再作成するのかを決める
• 各プロバイダーのサポート連絡先を記録する

これらは両者が従える平易な言葉で文書化してください。

環境とその実行場所を一覧化する

どの環境が存在するか（ローカル、ステージング、本番）と、それぞれがどこで動いているかを合意します。ステージングが別サーバーか別データベースか単なるフラグかを明記してください。Koder.aiのようなプラットフォームを使っていた場合、何がそこでホストされているか、エクスポート後にクライアントのインフラで動かすことが期待されているかも確認します。

早めにアクセスを収集する

最終日までアクセスを待たないでください。リポジトリ、CI、ホスティング、データベース、メールプロバイダーなど、適切な人が必要なものに到達できるようにしておきます。

また最終受け入れテストとサインオフのプロセスも合意してください。例：「クライアントがクリーンなマシンからビルドし、マイグレーションを実行し、ステージングにデプロイしてスモークテストに合格したら、両者が書面でサインオフする。」

リポジトリとドキュメントの基本事項

良い引き渡しは、新しいチームが数分で開けて理解できるリポジトリから始まります。何が含まれているか（アプリコード、設定テンプレート、スクリプト）と、意図的に含まれていないもの（実際のシークレット、プライベートキー、大きな生成ファイル）は何かを明確にしてください。除外したものがある場合は、その所在と所有者を示します。

構成は予測可能に保ちましょう。トップレベルのフォルダは frontend/、backend/、mobile/、infra/、scripts/、docs/ のように分かれていると分かりやすいです。モノレポの場合は各パーツの関係とそれぞれの実行方法を説明してください。

READMEは、そのプロジェクトを作った人以外でも使えるものであるべきです。前提条件と、動作する開発環境に到達する最短手順を推奨して、推測の余地をなくします。

最低限ドキュメントすべきこと

短い人間向けのREADMEセクションで以下に答えましょう:

• このリポジトリが何を含み、何をするのか（1段落）
• 正確なバージョンを含む前提条件（ランタイム、パッケージマネージャ、必要ならDocker）
• ローカル開発を一発で立ち上げる手順（成功の定義も）
• テストの実行方法とプロダクションアーティファクトの作成方法
• 主要ドキュメントの所在：アーキテクチャノート、マイグレーション、デプロイ手順

簡潔なアーキテクチャ説明も入れてください：何が何とやり取りしているのか、なぜそうしているのか。小さな図は任意ですが、数文で十分なことが多いです。例：「ReactフロントエンドがGoのAPIを呼ぶ。APIはPostgreSQLを読み書きする。バックグラウンドジョブは別のワーカープロセスで動く。」

最後に、引き渡しビルドのバージョン管理された変更履歴やリリースノートを含めてください。CHANGELOG.mdや短い「handoff release notes」ファイルに、正確なコミット/タグ、出荷内容、既知の問題を記載します。

Koder.aiなどのプラットフォームからコードをエクスポートした場合、生成されたプロジェクトタイプ（web、server、mobile）、想定ツールチェイン（例：React、Go、PostgreSQL、Flutter）、クライアントがビルドを再現するためにサポートするOS/ツールのバージョンも記載してください。

環境変数：一覧とドキュメント化

環境変数は、引き渡し直後にアプリが動かなくなる主な理由です。良いチェックリストでは、環境変数を製品の一部として扱います。

まず、新しいチームが推測せずに従える在庫（インベントリ）を作成してください。平易な言葉で、例となる値（本物のシークレットではない）を含めます。変数が任意の場合は、欠けているとどうなるか、使われるデフォルト値も示してください。

提示の簡単な方法:

• 変数名、何を制御するか、例の形式
• 必須か任意かと、存在しない場合の動作
• どこに設定するか（CI、ホスティングダッシュボード、ローカルの .env）
• 環境ごとに異なる値が必要か（dev、staging、production）
• 変更の所有者（クライアント、エージェンシー、共有）

環境固有の違いを明確に示してください。たとえば、ステージングはテスト用データベースやサンドボックス決済プロバイダーを使い、本番はライブサービスを使う、といった具合です。コールバックURLや許可オリジン、モバイルアプリのバンドル識別子など、システム間で一致させる必要がある値も明記します。

現在各値がどこにあるかを文書化します。多くのチームは値を分散させます：開発はローカルの .env、ビルドはCI変数、実行時はホスティング設定、などです。Koder.aiからプロジェクトをエクスポートした場合は、.env.example を含め、最初のビルド前に埋めるべき変数を短く示してください。

最後に、リポジトリにシークレットが隠れていないことを証明します。現在のファイルを見るだけでなく、コミット履歴もレビューして、誤って含まれたキー、古い .env、サンプル設定にコピーされた認証情報がないか確認してください。

具体例：ReactフロントエンドとGo APIなら、フロントは API_BASE_URL、バックエンドは DATABASE_URL と JWT_SIGNING_KEY が必要かもしれません。ステージングが別ドメインを使うなら両方の値を書き、どこで変更するかを記載しておけば、誤ってステージング設定を本番へ流すことを防げます。

シークレットのローテーション：安全に移譲して動作を確認する

引き渡しが完了するのは、クライアントが必要なすべての資格情報を制御するようになったときです。つまり、シークレットを共有するだけでなく、回転（ローテーション）させる必要があります。エージェンシーや前の請負業者がまだ有効なキーを持っていると、監査できない抜け穴が残ります。

まずは全シークレットのインベントリを作成してください。データベースのパスワードだけでなく、サードパーティAPIキー、OAuthクライアントシークレット、Webhook署名シークレット、JWT署名キー、SMTP認証、ストレージアクセスキー、CIに残った一時トークンなどを含めます。

ローテーション日の簡単な手順例:

• すべてのシークレットを列挙し、それが何をロックしているか、現在どこに設定されているか（ローカルenv、CI、ホスティング、Vault）を記載する
• クライアントのアカウントで新しい資格情報を作成し、各資格情報の所有者（個人とチーム共用のメール箱）を設定する
• アプリ設定を新しい値に更新し、まずステージングやテスト環境でデプロイして確認する
• 新しいものが動作確認できたら古い資格情報を即時取り消す
• 次回のローテーションが簡単になるように、正確な手順を記録する

ローテーション後は何も壊れていないことを証明してください。ログだけでなく「実際のユーザー」フローを短く実行します。

重点的に確認するフロー:

• ログイン、サインアップ、パスワードリセット、トークン更新
• 決済、メール送信、ファイルアップロード
• Webhook（署名検証と再試行処理）
• 外部APIを呼ぶバックグラウンドジョブやスケジュールタスク
• 特権エンドポイントに対する管理アクション

例：Koder.aiからエクスポートしたプロジェクトで決済プロバイダーとメール配信を利用しているなら、両方のキーをローテーションして再デプロイし、小額のテストトランザクションを行いテストメールを送信してからエージェンシー所有のキーを取り消します。

最後に、シークレットが今後どこに保管されるか（Vault、CI変数、ホスティング設定）、誰が変更できるか、ローテーションで問題が出たときの安全なロールバック手順を文書化してください。

データベースのマイグレーションとデータ取り扱い

引き渡しが「完了」に見えても、最初に壊れるのはデータベースのことが多いです。マイグレーションとデータは独立した製品として扱い、バージョン化、再現可能、テスト済みにしてください。

まず現在のデータベースバージョンと、マイグレーションがリポジトリのどこにあるかを記載します。フォルダパス、命名規則、最新のマイグレーションID（またはタイムスタンプ）を具体的に示してください。PostgreSQLを使っているなら、必要な拡張なども記載します。

他の人が実行できるようにドキュメントすべきこと

短いランブックで以下の疑問に答えましょう:

• どのコマンドでマイグレーションを実行するか、順序（データベース作成、マイグレーション適用、シード）
• 環境による違い（ローカル、ステージング、本番）、安全モードフラグなど
• マイグレーションがデプロイ時に自動で走るか手動で実行するか、実行権限を持つ人
• シードデータ戦略：なし、デモのみ、最低限の必須レコード（管理者ユーザー、初期設定）
• ロールバック計画：何が元に戻せて、何が戻せないか（例：破壊的なカラム削除）

ロールバックは正直に書いてください。復元可能なのはバックアップからのリストアだけかもしれません。そのことを明記し、デプロイ前のスナップショット取得や復元手順の検証を組み合わせてください。

可能なら引き渡し完了前に本番データのコピーでマイグレーションを実行してください。これで遅いクエリ、欠けているインデックス、「空のデータでは動くが実データでは動かない」問題を発見できます。現実的なテストは、コードをエクスポートし、環境変数を設定し、匿名化したダンプを復元して、マイグレーションを一から適用することです。

Koder.aiのようなプラットフォームからエクスポートした場合は、マイグレーションファイルやシードスクリプトがエクスポートに含まれ、バックエンド起動プロセスで正しく参照されるかも二重に確認してください。

ビルドとCI：再現性を持たせる

引き渡しが完了するのは、別の人がクリーンなマシンからアプリを再ビルドできるときです。チェックリストには正確なビルドコマンド、必要なバージョン、期待される出力（例：「/dist に Web バンドル」、「API バイナリの名前」、「Flutter の APK の場所」）を含めてください。

実際に使っているツールとパッケージマネージャを書き出してください。典型的なスタックでは、React の Web は Node.js（npm や pnpm）、サーバは Go ツールチェイン、ローカルセットアップに PostgreSQL クライアントツール、モバイルは Flutter SDK、などが想定されます。

依存関係のインストールを予測可能にします。ロックファイル（package-lock.json、pnpm-lock.yaml、go.sum、pubspec.lock）がコミットされていることを確認し、新しいコンピュータやクリーンコンテナで再インストールして動作を証明してください。

CIで何をしているかをステップごとに記録して、別のCIプロバイダーに移行できるようにします:

• 依存関係のインストール（ロックファイル付き）
• テストとリンタの実行
• ビルド出力（Webバンドル、サーババイナリ、モバイルビルド）
• アーティファクトの生成（zip、Dockerイメージ、リリースバンドル）
• ログとビルドメタデータ（バージョン、コミット、日付）の保存

ビルド時設定と実行時設定を分けてください。ビルド時設定は何がコンパイルされるかを変え（例：Webバンドルに埋め込まれるAPIベースURL）、実行時設定はアプリ起動時に注入される（データベースURL、APIキー、フラグ）。混同すると「CIでは動くがデプロイ後に動かない」という問題が起きます。

簡単なローカル検証レシピを提供してください。短いコマンド群でも十分です:

# Web
pnpm install
pnpm test
pnpm build

# API
go test ./...
go build ./cmd/server

# Mobile
flutter pub get
flutter test
flutter build apk

Koder.aiなどからエクスポートする場合、デプロイ時に使った生成済みのCIファイルやビルドプリセットを含めて、クライアントがプラットフォーム外でも同じビルドを再現できるようにしてください。

デプロイスクリプトとリリースプロセス

良いチェックリストは「ここにリポジトリがあります」で終わりません。ソースコードから稼働サービスまでどうやって移るか、誰がボタンを押すかを説明します。

まず、現在のデプロイ方法を書き出してください：完全手動（誰かがサーバー上でコマンド実行）、CI主導（パイプラインがビルドしてデプロイ）、ホステッドプラットフォーム経由、など。設定がどこにあるか、どの環境が存在するかも含めます。

リリース手順を再現可能にしてください。手順が人の記憶に依存しているなら、それをスクリプト化し、必要な権限も明記します。

デプロイ用パッケージに含めるもの

クライアントが初日からデプロイできるように、最低限以下を渡します:

• ビルドと実行コマンド（Node、Go、Flutterなどの正確なバージョン）
• デプロイスクリプト（シェルスクリプト、Makefileターゲット、パイプライン設定）
• 必要なアクセス権：クラウドアカウントロール、コンテナレジストリ、DNS、DB管理者
• 環境設定ノート：どこにenv変数が設定されるか、環境ごとの違い
• リリース名付けルール：タグ／リリースの把握方法

ダウンタイムの期待値について合意してください。「ゼロダウンタイム」を求めるなら、ブルーグリーンやローリングなど実務上何を意味するかを書き、ダウンタイムが許容されるなら明確なウィンドウを定義します。

静的アセットやキャッシュが失敗の原因になることが多いので、アセットの構築と配信方法、キャッシュの破棄タイミング、CDNの関与の有無も記載してください。

実行できるロールバック

ロールバックは短く、テスト済みの手順で、タグやリリースIDに紐づいているべきです。例：前のタグをデプロイし、必要なら前のデータベーススナップショットを復元し、キャッシュを無効化する。

Koder.aiで作成してエクスポートしたアプリなら、最後の動作確認済みスナップショットとエクスポートバージョンを示して、クライアントが作業中に素早く動作するリリースへ戻せるようにしておきます。

ステップバイステップ：エクスポート後にビルドを検証する

検証は引き渡しが本物かどうかを学ぶ瞬間です。目標はシンプル：新しい担当者がエクスポートされたコードを持ち、セットアップして、推測なしに同じアプリを動かせること。

始める前に「正しい状態」を記録します：稼働中のアプリのバージョン、現在のコミット／タグ（あれば）、比較用のキーとなる画面やAPIレスポンス。Koder.aiからのエクスポートならスナップショットやエクスポートのタイムスタンプも記録して、テストした状態が最新であることを証明します。

1. エクスポートが本番と一致しているか確認する：コミット履歴、リリースノート、ビルドメタデータをチェックし、表示されるバージョン文字列や特定の挙動で稼働中のアプリと比較する。
2. 環境変数とシークレットを設定する：ターゲット環境の設定（ローカルとステージング）を作成し、インベントリに従ってハードコーディングがないか確認する。
3. 依存関係をインストールしてテストを実行する：クリーンなインストール（キャッシュされた node_modules や vendor フォルダなし）。ドキュメント通りにユニットテストとリンタを実行。
4. マイグレーションを実行してローカルで起動する：データベースを立ち上げ、順序どおりにマイグレーションを適用し、アプリを起動。基本的な読み書きが機能し、保留中のマイグレーションがないことを確認。
5. ステージングにデプロイしてスモークテスト、その後プロモート：本番と同じスクリプト／パイプラインを使ってデプロイし、ステージングが期待どおりならプロモートする。

スモークテストは短く、リスクに直結するものに絞ります:

• ログイン／ログアウト（またはテストユーザー作成）
• 主要なワークフローのエンドツーエンド（作成→編集→保存）
• メール／Webhook／決済コールバック（該当する場合）
• 基本的なエラーハンドリング（不正入力、レコードなし）
• ログに繰り返すクラッシュやシークレット関連のエラーがないこと

もし失敗があれば、実行した正確なコマンド、エラー出力、使った環境変数を記録してください。これが所有権を移す際に数時間を節約します。

よくある引き渡しミスと回避方法

「コードがあれば十分だ」と仮定するのが、引き渡しをトラブルに変える最短ルートです。良いチェックリストは、クライアントがあなたなしで実行・変更できるかを決める小さな退屈な詳細に注目します。

引き渡しで最も問題を起こすミス

多くの問題は次のパターンに当てはまります:

• シークレットが回転されず、エージェンシーの古いパスワードやAPIキー、クラウドトークンがそのまま有効になっている。
• 環境変数が不完全で、一部の値がCIやホスティングのダッシュボードにのみ存在し、リポジトリにない。
• 本番で行った一時的な変更（ホットフィックス、手動のDB編集、サーバ上の直接トグル）が忘れられている。
• マイグレーションはローカルで動くが、本番では権限不足や拡張の不足、スキーマ所有権の違いで失敗する。
• ロールバック計画がなく、戻すべきタグやリリースノートがない。

それらを防ぐ方法（時間をかけすぎずに）

ローテーションやアクセスのクリーンアップを「時間があればやる」項目にしないでください。日付を決め、エージェンシーアカウントが削除される日、サービスキーが再生成される日、クライアントが自分の資格情報だけでデプロイできることを確認する日をスケジュールします。

環境変数はリポジトリ、CIシステム、ホスティングUIの3箇所から簡単なインベントリを取り、クリーンなマシンやコンテナで実際にビルドして検証してください。

マイグレーションは、本番デプロイが使うのと同じデータベースロールでテストしてください。本番で追加の操作（拡張の有効化など）が必要なら、それを手順に書き、所有権を明確にします。

現実的な例：Koder.aiからエクスポートしたプロジェクトをクライアントがデプロイすると、背景ジョブが失敗した。原因はキューのURLがホスティングダッシュボードにだけ設定されていたため。短い環境変数監査で発見でき、タグ付けされたリリースとドキュメント化されたロールバック（例：「タグ v1.8.2 を再デプロイし、最後のスナップショットを復元する」）があればダウンタイムを避けられます。

最終チェックリスト、簡単な例、次のステップ

このソースコード引き渡しチェックリストから1ページだけ残すとしたら、これを残してください。目標は単純：クリーンにクローンしたリポジトリが新しいマシンで動き、新しいシークレットで動作し、データベースを安全に前進させられることです。

クイックチェック（クリーンなクローンで行う）

これらのチェックは一度もそのプロジェクトを見たことのないラップトップ（またはクリーンなコンテナ／VM）で行ってください。欠けているファイル、想定外の前提、古い資格情報を素早く発見できます。

• スクラッチからビルド：依存関係をインストールし、テストを実行して、手動編集なしでリリースビルドを生成する。
• 設定が機能すること：文書化された環境変数を設定して、アプリが新しい設定で起動することを確認する。
• シークレットが回転されていること：新しいキーでアプリが動くことを確認し、古いキーを取り消して何も壊れないことを検証する。
• マイグレーションがクリーンに動くこと：空のデータベースからマイグレーションを実行し、アプリの基本フローを確認する。
• デプロイ経路が実在すること：デプロイスクリプトやCIワークフローを一度実行して、同じ出力が得られることを確認する。

簡単な引き渡し例

エージェンシーがReactフロントエンド、Go API、PostgreSQLを引き渡すとします。クライアントチームはリポジトリをクローンし、提供された .env.example を実際の環境変数にコピーし、データベース、メールプロバイダー、サードパーティAPI用に新しい資格情報を作成します。go test（または合意したテストコマンド）を実行し、Reactアプリをビルドし、マイグレーションを新しいPostgresインスタンスに適用して両サービスを起動します。最後にドキュメント化されたスクリプトでデプロイし、同じコミットが後で再ビルドできることを確認します。

次のステップ

引き渡しは短く、誰かが所有する形にしてください。30〜60分のウォークスルーは長い文書よりも有効なことが多いです。

• ウォークスルーをスケジュールし、決定事項（誰がデプロイとシークレット、DB変更を所有するか）を記録する。
• 本番アクセスのオーナーを1名、バックアップを1名割り当てる。
• 最終受け入れビルドのコミットハッシュを決めてタグ付けする。
• Koder.aiで作成したならソースをエクスポートし、クライアントが最初に自分でデプロイするときにスナップショットとロールバックを使ってリスクを下げる。