このソースコード引き渡しチェックリストを使って、コードのエクスポート、ドキュメント作成、シークレットのローテーション、マイグレーション実行、ビルド検証、およびクライアントとのデプロイ所有権の確認を行いましょう。

ソースコードの引き渡しは、プロジェクトが「エージェンシーだけが動かせるもの」から「クライアントが所有できるもの」へ変わる瞬間です。明確な引き渡しがないと、アプリが特定の開発者の環境でしかビルドできなかったり、本番が見つからない秘密鍵に依存していたり、小さな更新が数日間の推測作業になったりします。
このチェックリストの目的はシンプルです。引き渡し後、クライアントがエージェンシーを呼ばずにプロダクトをビルド、実行、デプロイできること。ただし「永久にサポート不要」を意味するわけではありません。基本的な作業が繰り返し可能で文書化されていれば、次の担当者が自信を持って引き継げます。
何が成果物に含まれるべきかは明示しましょう。最低限、完全な引き渡しには通常以下が含まれます:
スコープは内容と同じくらい重要です。ある引き渡しは本番環境のみを対象とすることもあれば、開発/ステージング/本番を個別に含めることもあります。どの環境が含まれるかを明記しなければ、相手側が勝手に想定してしまい、そこで障害が起きます。
実務的には検証テストで成功条件を定義するとよいでしょう:そのアプリをビルドしていない人が、コードをエクスポート(例:Koder.aiのようなプラットフォームから)、ドキュメントに従い、環境変数を設定し、マイグレーションを実行し、ビルドして合意した環境にデプロイできることを確認します。
このチェックリストは技術的な準備に焦点を当てています:環境変数、シークレットのローテーション、データベースマイグレーション、デプロイスクリプト、ビルド検証。法的条件、契約、知的財産、支払いトラブルは別の合意に含めるべき事項であり、本稿では扱いません。
クリーンな引き渡しは、エクスポートの前に始まります。誰が何をいつ所有するか合意しておけば、デプロイが壊れる、ホスティングの未払いでサービスが止まる、アクセスが見つからないといった直前のトラブルを避けられます。
引き渡し日を決め、24〜72時間程度のフリーズ期間を定義して、その間は緊急修正のみを許可するのが一般的です。これによりエクスポートされるコードと稼働中のシステムの整合性が保たれます。フリーズ中にホットフィックスが入る場合は、何が変更されたかを正確に記録し、最終エクスポートに含まれることを確認してください。
DNS、クラウドホスティング、その他有料サービスの所有権を誰が持つかを決めてください。これは単なる書類作業ではありません。請求がエージェンシーのカードのままだと、後でサービスが予告なく停止される可能性があります。
具体的なチェック項目:
これらは両者が従える平易な言葉で文書化してください。
どの環境が存在するか(ローカル、ステージング、本番)と、それぞれがどこで動いているかを合意します。ステージングが別サーバーか別データベースか単なるフラグかを明記してください。Koder.aiのようなプラットフォームを使っていた場合、何がそこでホストされているか、エクスポート後にクライアントのインフラで動かすことが期待されているかも確認します。
最終日までアクセスを待たないでください。リポジトリ、CI、ホスティング、データベース、メールプロバイダーなど、適切な人が必要なものに到達できるようにしておきます。
また最終受け入れテストとサインオフのプロセスも合意してください。例:「クライアントがクリーンなマシンからビルドし、マイグレーションを実行し、ステージングにデプロイしてスモークテストに合格したら、両者が書面でサインオフする。」
良い引き渡しは、新しいチームが数分で開けて理解できるリポジトリから始まります。何が含まれているか(アプリコード、設定テンプレート、スクリプト)と、意図的に含まれていないもの(実際のシークレット、プライベートキー、大きな生成ファイル)は何かを明確にしてください。除外したものがある場合は、その所在と所有者を示します。
構成は予測可能に保ちましょう。トップレベルのフォルダは frontend/、backend/、mobile/、infra/、scripts/、docs/ のように分かれていると分かりやすいです。モノレポの場合は各パーツの関係とそれぞれの実行方法を説明してください。
READMEは、そのプロジェクトを作った人以外でも使えるものであるべきです。前提条件と、動作する開発環境に到達する最短手順を推奨して、推測の余地をなくします。
短い人間向けのREADMEセクションで以下に答えましょう:
簡潔なアーキテクチャ説明も入れてください:何が何とやり取りしているのか、なぜそうしているのか。小さな図は任意ですが、数文で十分なことが多いです。例:「ReactフロントエンドがGoのAPIを呼ぶ。APIはPostgreSQLを読み書きする。バックグラウンドジョブは別のワーカープロセスで動く。」
最後に、引き渡しビルドのバージョン管理された変更履歴やリリースノートを含めてください。CHANGELOG.mdや短い「handoff release notes」ファイルに、正確なコミット/タグ、出荷内容、既知の問題を記載します。
Koder.aiなどのプラットフォームからコードをエクスポートした場合、生成されたプロジェクトタイプ(web、server、mobile)、想定ツールチェイン(例:React、Go、PostgreSQL、Flutter)、クライアントがビルドを再現するためにサポートするOS/ツールのバージョンも記載してください。
環境変数は、引き渡し直後にアプリが動かなくなる主な理由です。良いチェックリストでは、環境変数を製品の一部として扱います。
まず、新しいチームが推測せずに従える在庫(インベントリ)を作成してください。平易な言葉で、例となる値(本物のシークレットではない)を含めます。変数が任意の場合は、欠けているとどうなるか、使われるデフォルト値も示してください。
提示の簡単な方法:
.env)環境固有の違いを明確に示してください。たとえば、ステージングはテスト用データベースやサンドボックス決済プロバイダーを使い、本番はライブサービスを使う、といった具合です。コールバック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に残った一時トークンなどを含めます。
ローテーション日の簡単な手順例:
ローテーション後は何も壊れていないことを証明してください。ログだけでなく「実際のユーザー」フローを短く実行します。
重点的に確認するフロー:
例:Koder.aiからエクスポートしたプロジェクトで決済プロバイダーとメール配信を利用しているなら、両方のキーをローテーションして再デプロイし、小額のテストトランザクションを行いテストメールを送信してからエージェンシー所有のキーを取り消します。
最後に、シークレットが今後どこに保管されるか(Vault、CI変数、ホスティング設定)、誰が変更できるか、ローテーションで問題が出たときの安全なロールバック手順を文書化してください。
引き渡しが「完了」に見えても、最初に壊れるのはデータベースのことが多いです。マイグレーションとデータは独立した製品として扱い、バージョン化、再現可能、テスト済みにしてください。
まず現在のデータベースバージョンと、マイグレーションがリポジトリのどこにあるかを記載します。フォルダパス、命名規則、最新のマイグレーションID(またはタイムスタンプ)を具体的に示してください。PostgreSQLを使っているなら、必要な拡張なども記載します。
短いランブックで以下の疑問に答えましょう:
ロールバックは正直に書いてください。復元可能なのはバックアップからのリストアだけかもしれません。そのことを明記し、デプロイ前のスナップショット取得や復元手順の検証を組み合わせてください。
可能なら引き渡し完了前に本番データのコピーでマイグレーションを実行してください。これで遅いクエリ、欠けているインデックス、「空のデータでは動くが実データでは動かない」問題を発見できます。現実的なテストは、コードをエクスポートし、環境変数を設定し、匿名化したダンプを復元して、マイグレーションを一から適用することです。
Koder.aiのようなプラットフォームからエクスポートした場合は、マイグレーションファイルやシードスクリプトがエクスポートに含まれ、バックエンド起動プロセスで正しく参照されるかも二重に確認してください。
引き渡しが完了するのは、別の人がクリーンなマシンからアプリを再ビルドできるときです。チェックリストには正確なビルドコマンド、必要なバージョン、期待される出力(例:「/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バンドルに埋め込まれる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主導(パイプラインがビルドしてデプロイ)、ホステッドプラットフォーム経由、など。設定がどこにあるか、どの環境が存在するかも含めます。
リリース手順を再現可能にしてください。手順が人の記憶に依存しているなら、それをスクリプト化し、必要な権限も明記します。
クライアントが初日からデプロイできるように、最低限以下を渡します:
ダウンタイムの期待値について合意してください。「ゼロダウンタイム」を求めるなら、ブルーグリーンやローリングなど実務上何を意味するかを書き、ダウンタイムが許容されるなら明確なウィンドウを定義します。
静的アセットやキャッシュが失敗の原因になることが多いので、アセットの構築と配信方法、キャッシュの破棄タイミング、CDNの関与の有無も記載してください。
ロールバックは短く、テスト済みの手順で、タグやリリースIDに紐づいているべきです。例:前のタグをデプロイし、必要なら前のデータベーススナップショットを復元し、キャッシュを無効化する。
Koder.aiで作成してエクスポートしたアプリなら、最後の動作確認済みスナップショットとエクスポートバージョンを示して、クライアントが作業中に素早く動作するリリースへ戻せるようにしておきます。
検証は引き渡しが本物かどうかを学ぶ瞬間です。目標はシンプル:新しい担当者がエクスポートされたコードを持ち、セットアップして、推測なしに同じアプリを動かせること。
始める前に「正しい状態」を記録します:稼働中のアプリのバージョン、現在のコミット/タグ(あれば)、比較用のキーとなる画面やAPIレスポンス。Koder.aiからのエクスポートならスナップショットやエクスポートのタイムスタンプも記録して、テストした状態が最新であることを証明します。
スモークテストは短く、リスクに直結するものに絞ります:
もし失敗があれば、実行した正確なコマンド、エラー出力、使った環境変数を記録してください。これが所有権を移す際に数時間を節約します。
「コードがあれば十分だ」と仮定するのが、引き渡しをトラブルに変える最短ルートです。良いチェックリストは、クライアントがあなたなしで実行・変更できるかを決める小さな退屈な詳細に注目します。
多くの問題は次のパターンに当てはまります:
ローテーションやアクセスのクリーンアップを「時間があればやる」項目にしないでください。日付を決め、エージェンシーアカウントが削除される日、サービスキーが再生成される日、クライアントが自分の資格情報だけでデプロイできることを確認する日をスケジュールします。
環境変数はリポジトリ、CIシステム、ホスティングUIの3箇所から簡単なインベントリを取り、クリーンなマシンやコンテナで実際にビルドして検証してください。
マイグレーションは、本番デプロイが使うのと同じデータベースロールでテストしてください。本番で追加の操作(拡張の有効化など)が必要なら、それを手順に書き、所有権を明確にします。
現実的な例:Koder.aiからエクスポートしたプロジェクトをクライアントがデプロイすると、背景ジョブが失敗した。原因はキューのURLがホスティングダッシュボードにだけ設定されていたため。短い環境変数監査で発見でき、タグ付けされたリリースとドキュメント化されたロールバック(例:「タグ v1.8.2 を再デプロイし、最後のスナップショットを復元する」)があればダウンタイムを避けられます。
このソースコード引き渡しチェックリストから1ページだけ残すとしたら、これを残してください。目標は単純:クリーンにクローンしたリポジトリが新しいマシンで動き、新しいシークレットで動作し、データベースを安全に前進させられることです。
これらのチェックは一度もそのプロジェクトを見たことのないラップトップ(またはクリーンなコンテナ/VM)で行ってください。欠けているファイル、想定外の前提、古い資格情報を素早く発見できます。
エージェンシーがReactフロントエンド、Go API、PostgreSQLを引き渡すとします。クライアントチームはリポジトリをクローンし、提供された .env.example を実際の環境変数にコピーし、データベース、メールプロバイダー、サードパーティAPI用に新しい資格情報を作成します。go test(または合意したテストコマンド)を実行し、Reactアプリをビルドし、マイグレーションを新しいPostgresインスタンスに適用して両サービスを起動します。最後にドキュメント化されたスクリプトでデプロイし、同じコミットが後で再ビルドできることを確認します。
引き渡しは短く、誰かが所有する形にしてください。30〜60分のウォークスルーは長い文書よりも有効なことが多いです。