クリーンな引き継ぎのための AI 作成コードベースエクスポートチェックリスト

引き継ぎ後にプロジェクトが失敗する理由

多くのエクスポートされたプロジェクトが失敗する理由は単純です：元のプラットフォーム内ではデフォルト、シークレット、データベースの状態、ビルド手順が既に整っていて動いていただけです。コードがそのバブルを出ると、次の開発者は何が前提だったのかを推測しなければなりません。

クリーンな引き継ぎとは、プロジェクトをクローンし、設定し、新しいマシンで長いやり取りなしに起動できる状態を意味します。完璧なコードを要求するわけではありません。必要なのは基本が明示され、繰り返し実行できることです。

エクスポートが壊れる原因はいつも同じです：隠れた設定、シークレットの扱いが不明瞭、あいまいなローカルセットアップ手順、データベースの驚き、そして特定の環境でしか動かない CI。

そのため、AI 作成のコードベースエクスポートチェックリストは主にドキュメント化と再現性に関するものです。ファイルを単にコピーすることではありません。もし Koder.ai のような vibe-coding プラットフォームでアプリを作り、ソースコードをエクスポートしたなら、次のチームは何を設定し、何を実行し、「動いている」とは何かを示す地図を必要とします。

このチェックリストは引き継ぎの必須項目に焦点を当てています：環境変数、シークレット、ローカル開発セットアップ、データベースのブートストラップ、CI 設定、そして実用的な「どうやって動かすか」README。プロダクトの意思決定、UX の磨き上げ、アーキテクチャの再設計は扱いません。

所有権も明確にするべきです。作成者は前提を可視化する（ドキュメント、スクリプト、安全なデフォルト）責任を持ち、受け取る側はプロジェクトを自分たちの環境に適応する（シークレットマネージャ、ホスティング、厳格な CI ルール）責任を持ちます。双方が自分の役割を知っていれば、引き継ぎは日常的な作業になります。

エクスポート前に：引き継ぎ契約を決める

クリーンな引き継ぎはシンプルな合意から始まります：コードがプラットフォームを離れるときに「完了」とは何を意味するか。これがないと、後でスクリプトの欠如、予期せぬ依存関係、あるいはどのバージョンが本物だったかで議論になります。

エクスポートのタイミングを選ぶ

単一の安定した時点を選び、それを真実のソースとして扱ってください。変更の途中でエクスポートすると、ほとんど動かないリポジトリが出来上がります。

良いエクスポートポイントは通常次のいずれかです：

• 簡単なリリースノート付きの安定コミット（何が変わり、何をテストするか）
• タグ付きリリース（たとえ v0.1.0 でも）
• プラットフォームのスナップショット（例：エクスポートを繰り返す必要がある場合にロールバックできる Koder.ai のスナップショット）

このポイントがなぜ適切かを一文で説明してください。例：「主要フローはすべて通っており、このマイルストーンではデータベーススキーマが確定している。」

引き継ぎに何を含めるか決める

受け取り側が何を期待すべきか、短いインベントリを書いてください。含まれるものと意図的に含めていないものを明示します。

基本を含めます：ソースコード（アプリ、サービス、共有パッケージ）、設定テンプレート（例 .env ファイル）、スクリプト（ビルド、dev、テスト、マイグレーション、シード）、デプロイの注意点。サンプルデータは scrub（個人情報等を除去）され安全である場合のみ含めます。

次にバージョンを固定して「私のマシンで動く」が新しい基準にならないようにします。ランタイムとツールチェーンのバージョン（Node、Go、Flutter、パッケージマネージャ）と、データベースのバージョン（PostgreSQL のメジャーバージョン）をキャプチャしてください。

最後に、実行前に必要な前提を列挙します。短く具体的に：必要なアカウント、インストール済みツール、開放が必要なポート、ワンタイムのセットアップ手順など。

環境変数：何も隠れないようにドキュメント化する

「プラットフォーム上では動いていた」エクスポートの多くが失敗するのは、重要な設定が記録されていなかったからです。環境変数が典型的な原因です：リポジトリ外に存在するため、新しいチームメンバーは何が期待されているか分かりません。

クリーンなエクスポートには必須の作業として、すべての変数を発見でき、説明され、推測なしで設定しやすくしてください。

ハンドオフ README に一元化した情報源を作成します：環境変数名、アプリ内で何を制御するか、値の出所を一覧にします。説明は平易な言葉で、セキュリティ上の注意点は明確に示してください。

各変数に対する簡単なフォーマット：

• Name: 正確なキー（コピー＆ペースト可能）
• Meaning: アプリ内で何を変えるか
• Required?: 必須か任意か（欠けたときの挙動）
• Example: 安全な例（実際のシークレットは絶対に入れない）
• Where it differs: dev と staging と production の違い

そのドキュメントと並行して、リポジトリに .env.example ファイルを添付してください。必要になり得るすべての変数を含め、安全なプレースホルダ値を入れておけば、アプリは最小限の編集で起動できます。

# Required
APP_ENV=development
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/app_dev

# Optional
LOG_LEVEL=info
CORS_ORIGINS=http://localhost:5173

# Environment specific
PUBLIC_BASE_URL=http://localhost:3000

いくつかの詳細がほとんどの混乱を防ぎます：

「必須か任意か」を明確にしてください。欠けるとクラッシュする変数は明記し、機能を有効にするだけの変数ならどの機能かを名前で示してください。

環境ごとに何が変わるかを明記します。DATABASE_URL や PUBLIC_BASE_URL は dev/staging/production でしばしば異なり、LOG_LEVEL はすべての環境で同じかもしれません。もし Koder.ai でエクスポートとデプロイを行っていた場合は、プラットフォームのデフォルト（ポート、ベース URL、許可されたオリジン）がドキュメントに反映されているかを二重に確認してください。

最後に、ローカルで環境変数がどう読み込まれるかを記載してください。プロジェクトが .env ファイルを期待しているのか、ファイルの場所、アプリが自動的に読み込むのかコマンド／ツールが必要かを明示します。

シークレット：リポジトリに置かず設定しやすくする

シークレットとは漏洩すると危険な値です：API キー、データベースパスワード、認証トークン、OAuth クライアントシークレット、プライベートキー、Webhook の署名シークレットなど。

エクスポートでは簡潔に：リポジトリにはプレースホルダのみを置き、実際のシークレットは絶対に入れないでください。起動にシークレットが必須なら、.env.example に明確なプレースホルダ名を入れ、本物をどう生成するか説明してください。

実用的なパターンは三つを分離すること：サンプルファイル、ローカルファイル、CI／デプロイ用のシークレットストア。エクスポートしたコードにはサンプルを含め、ローカルファイルは ignore し、CI／ホスティングにシークレットがどう渡るかをドキュメントに示します。

シークレットの置き場所

環境ごとに一つのアプローチを選び、それを守ってください。

• ローカル開発：アプリで読み込まれる .env（gitignore 対象）、またはチームのローカルシークレットマネージャ
• CI：CI プロバイダの暗号化されたシークレット変数
• デプロイ／ホスティング：ホスティング環境に格納され、実行時に注入される

例：リポジトリには PAYMENTS_API_KEY=replace_me を置きます。受け取り側はプロバイダダッシュボードで自分のキーを生成し、ローカルの .env と CI に設定します。コード自体は変わりません。

ローテーション手順を一つ追加する

ハンドオフはシークレットをローテーションする良い機会です。特に共有プラットフォームで使われていた場合はなおさらです。

• 外部サービスのキーを再発行し、古いものを取り消す
• データベースのパスワードや管理トークンをリセットする
• まず CI とホスティングのシークレットを更新し、その後ローカルの .env を更新する
• アプリが起動しテストが通り、古いキーが機能しなくなったことを確認する

Koder.ai からエクスポートした場合は、エクスポートを新しい環境とみなし、受け取るチーム用に新しいシークレットを生成してください。

ローカル開発セットアップ：初回起動を退屈にする

ハンドオフが成功したと言えるのは、新しい開発者がリポジトリをクローンし、数コマンド実行して推測なしにアプリを確認できるときです。予測可能な前提、明確な実行順、実際に動く短い「動かし方」ブロックを目指してください。

前提（明確に書く）

README の先頭にこれらを置き、誰もエラーメッセージから推測しなくて済むようにします：

• OS メモ：「macOS と Ubuntu でテスト済み」（Windows はテストした場合のみ記載）
• ランタイムのバージョン：Node.js（React 用）、Go（API）、PostgreSQL（DB）
• ツール：npm/pnpm/yarn、Make（使用している場合）、Docker（依存している場合のみ）

プロジェクトが Koder.ai 上で構築されたなら、ローカルセットアップはエクスポートしたものと整合させてください（同じフォルダ構成、同じ起動コマンド）。「Postgres は既に動いている」と仮定しないでください。

インストールと開発用コマンド（1 行に 1 コマンド）

新しいチームメンバーが実行すべき正確なコマンドを順番に置きます。コピペできるようにしてください：

# 1) Install dependencies
cd web
npm ci

cd ../server
go mod download

# 2) Create your env file
cp .env.example .env

# 3) Start dependencies (if needed)
# e.g., start Postgres locally or via docker compose

# 4) Run the app
cd server
go run ./cmd/api

cd ../web
npm run dev

そのすぐ下に最小限のテストとビルドの節を追加してください：

# Tests
cd server && go test ./...
cd web && npm test

# Build
cd web && npm run build
cd server && go build ./...

トラブルシューティング：よく起きる初回エラー

多くの「動かない」問題は次のカテゴリに当てはまります：

1. バージョン不一致（Node/Go）。症状：依存関係やコンパイルのエラー。対処：固定されたバージョンを入れて再インストール。

2. 環境変数の欠如。症状：「undefined」設定、認証失敗、500 エラー。対処：.env と .env.example を比較して必須値を埋める。

3. データベースに接続できない。症状：接続拒否、"database does not exist"。対処：Postgres を起動し、ホスト／ポート／ユーザを確認し、データベース初期化手順を正確に実行する。

データベースのブートストラップ：マイグレーション、シード、リセット

プラットフォームからエクスポートされたプロジェクトで最初に壊れやすいのはデータベースです。目標はシンプルです：チームメンバーが「リポジトリをクローンした」状態から「アプリが実データで動く」まで推測せずに行けるようにすること。

ドキュメント化すべきこと（かつリポジトリに置くもの）

新しい PostgreSQL セットアップの最小手順を書き、可能ならスクリプトにしておきます。ハンドオフで答えるべき四つの質問は次の通りです：

• データベースとロールはどう作成するか（名前、権限、パスワードの出所）？
• マイグレーションはゼロから最新までどう実行するか？
• アプリのデモに使えるシードデータはどうロードするか？
• 開発中に安全にリセットするにはどうするか？

すでにスクリプト（Makefile のターゲット、シェルスクリプト、タスクランナー）があれば、それを使い、手動手順の説明に頼らないでください。なければ簡単なスクリプトを追加しましょう。

再現性のある退屈なブートストラップフロー

ローカル、CI、ステージングでフローを一貫させます。基本の例は次の通りです：

# 1) Create role + database (example names)
createuser app_user --pwprompt
createdb app_db --owner=app_user

# 2) Apply migrations
# Replace with your repo's migration command
./scripts/migrate up

# 3) Seed minimal demo data
./scripts/seed

シードは本番相当のダンプより、最小限で動作するデータを好みます。シードは何度実行しても安全（冪等）であるか、あるいは「空の DB のときのみ実行」など明確なルールを持ちます。

リセットは安全性を明確にしてください。リセットコマンドはデフォルトでローカル開発のみを対象にするべきです。破壊的なスクリプトを提供する場合はガードレールを付けてください（例：CONFIRM_RESET=1 を要求、または APP_ENV=development をチェック）。「リセット」が何を意味するか（ドロップ＆再作成、テーブルのワイプ、既知のスナップショットの復元）も定義してください。

リポジトリの衛生：何をソースに入れ、何を入れないか

リポジトリが散らかった引き出しのようだとハンドオフは失敗します。新しい人が何が重要で何が生成物か、どこを変更すべきかをすぐに分かるべきです。

プロジェクトを再現可能にするものはコミットします：ロックファイル、マイグレーションファイル、小さな設定テンプレート（.env.example）、アプリのブートストラップスクリプトなど。

個人用、生成物、または機密のファイルはバージョン管理から除外します：ローカル環境ファイル、エディタ設定、ビルド出力、ログ、キャッシュ、アクセス権を与えるファイル（API キー、DB パスワード、サービスアカウントファイル）など。

簡単なルール：変更が全員に影響するならコミットする。マシンや環境ごとに変わるならドキュメントに書き、リポジトリには入れない。

短い「コミットすべきもの vs 無視すべきもの」メモを付けると良いです：

• コミット：README、ロックファイル、マイグレーション、シードスクリプト、.env.example
• 無視：.env、シークレットファイル、ビルドフォルダ、ログ、ローカルキャッシュ

ディレクトリマップを添えて構造を一目で分かるようにします。例：「/backend API サービス、/web フロントエンド、/mobile アプリ、/db マイグレーションとシード、/scripts セットアップ補助。」

Koder.ai からエクスポートした場合は、エクスポートを起点にクリーンアップ作業を行ってください：生成されたゴミを削除し、ignore ルールを確認し、ディレクトリマップを書きます。

CI 設定：パイプラインを再現可能にする

CI がほとんどローカルと同じであることが静かに失敗の原因になります。ローカルで動くコマンドを CI でも実行し、同じ結果が得られるべきです。

プルリクエストで CI が証明すべきことを決めます。多くのチームは最小限で十分です：

• Lint／フォーマットチェック
• ユニットテスト
• ビルド（web とサーバのコンパイルがクリーンであること）

統合テストやデプロイステップも良いですが、信頼でき明確に範囲が定義されている場合に限ります。

CI の手順はローカルのコマンドに近づけて、乖離を避けてください。ローカルで make test を使っているなら CI も make test を実行するべきです。Makefile（または同等のタスクランナー）を追加し、共通の入り口にすることを検討してください。

環境変数とシークレットを明示する

CI が壊れる最も多い原因は隠れた設定です。README に CI が期待する正確な名前の一覧を追加し、公開設定とシークレットを分けてください。

名前の例（スタックに合わせて調整してください）：APP_ENV、DATABASE_URL、PORT、JWT_SECRET、S3_BUCKET、STRIPE_API_KEY。CI ではシークレットはコミットされたファイルからではなく、CI のシークレットストアから供給されるべきです。Go + Postgres バックエンド（Koder.ai のエクスポートでよくある組み合わせ）の場合、マイグレーションが自動で実行されるか明記してください。

マージ保護はステータスチェックで

どのチェックをマージ前に必須にするかを書いておきます。「lint + unit tests + build」なら通常十分です。モバイルビルドのような任意のジョブは、真に必要でない限りブロッキングにしないでください。

また CI の出力がデバッグしやすいようにしましょう：ツールのバージョンを表示し、失敗時は明確なメッセージを出すこと。パイプラインが安定したらキャッシュを追加します。

例：クローンからアプリ起動までのハンドオフシナリオ

Maya は Koder.ai からエクスポートされたプロジェクトを受け取ります。典型的な構成：React の web、Go の API、PostgreSQL。クローンして推測せずに動作画面に到達できるべきです。

最初の 30 分は次のようになります：

1. リポジトリをクローンしてルート README を開く。
2. .env.example を .env にコピー（または同じ値をシェルに設定）して、web と api の両方で行う。
3. PostgreSQL を起動（ローカルまたは Docker）して空のデータベースを作成。
4. マイグレーションとシードを実行して既知の開始データセットを用意。
5. バックエンド、次にフロントエンドを起動し、ブラウザでアプリを読み込む。

散らかったハンドオフでは、通常三つの障害に当たります。

まず：アプリは起動するが、不明瞭な「missing config」で落ちる。実際の原因は AUTH_JWT_SECRET のような未記載の変数や DATABASE_URL の形式。README がすべての必須変数を列挙し、安全な例を示し、それがどこで使われるか説明していれば、すぐに直せます。

次に：API は起動するが、ページは「データなし」か 500 エラーになる。データベースは存在するがテーブルやシードがない。クリーンなハンドオフには一つか二つの確実なコマンドがあり：マイグレーションを実行、最小限のデータをシード、問題があればリセットを行う。

三つ目：すべて動いているがフロントエンドが間違ったポートを指している。Maya は localhost:3000 を開くが API は localhost:8080 を期待している、あるいは CORS でブロックされる。ここでは一貫したデフォルトが役立ちます：WEB_PORT、API_PORT、API_BASE_URL を一箇所で設定し、README に期待されるローカル URL を書いておきます。

最終チェックリスト、よくある落とし穴、次のステップ

ハンドオフは、別の人がクリーンなクローンからプロジェクトを質問なしに実行できるときにのみ完了です。プロジェクトがプラットフォーム外でも生き残ることを証明してください。

新しいマシンか使い捨てコンテナで最終的な「クリーンクローン」テストを行ってください。既存フォルダ、キャッシュ済み依存、ローカル DB を使い回さないでください。README に従ってそのまま実行し、もし即興が必要ならドキュメントかスクリプトを修正して繰り返します。

よく見るチェック項目：

• README にローカル開発用の単一のコピー＆ペースト可能な「how to run」パスと短い「how to test」がある。
• .env.example が存在し、すべての必須変数が安全な例値で説明されている。
• データベースのブートストラップが end-to-end で動く：DB 作成、マイグレーション実行、任意のシード、リセットコマンド。
• CI がクリーンランナーで動作し、ローカルコマンドと一致する。
• 新しい開発者が小さな変更を1つ行い、テストを実行し、それがアプリに反映される。

よくある落とし穴は地味なので見落とされがちです：

• ドキュメントに載らないワンタイム手順
• 古いフォルダ構成やコマンド名に合った README
• ハードコーディングされた値（API URL、機能フラグ、キー）がコードに埋め込まれている
• 非公式に共有されたシークレットで安全なセットアップパスがない
• キャッシュ済みのアーティファクトやローカルサービスに依存しているために通る CI

次のステップ：エクスポート後 24〜48 時間以内に検証するオーナーを割り当て、クリーンクローンテストを行ってギャップを報告させてください。

もしあなたが Koder.ai（koder.ai）上で構築しているなら、このチェックリストを通常のワークフローの一部として扱うと便利です：planning mode で実行手順を書き留め、重要な変更前にスナップショットを取り、スケジュールに従ってソースをエクスポートしてハンドオフパッケージを最新に保ちましょう。