環境変数、シークレット、ローカルセットアップ、データベース初期化、CI、実行 README を含む、プロジェクトを安全に引き渡すための AI 作成コードベースエクスポートチェックリスト。
多くのエクスポートされたプロジェクトが失敗する理由は単純です：元のプラットフォーム内ではデフォルト、シークレット、データベースの状態、ビルド手順が既に整っていて動いていただけです。コードがそのバブルを出ると、次の開発者は何が前提だったのかを推測しなければなりません。
クリーンな引き継ぎとは、プロジェクトをクローンし、設定し、新しいマシンで長いやり取りなしに起動できる状態を意味します。完璧なコードを要求するわけではありません。必要なのは基本が明示され、繰り返し実行できることです。
エクスポートが壊れる原因はいつも同じです：隠れた設定、シークレットの扱いが不明瞭、あいまいなローカルセットアップ手順、データベースの驚き、そして特定の環境でしか動かない CI。
そのため、AI 作成のコードベースエクスポートチェックリストは主にドキュメント化と再現性に関するものです。ファイルを単にコピーすることではありません。もし Koder.ai のような vibe-coding プラットフォームでアプリを作り、ソースコードをエクスポートしたなら、次のチームは何を設定し、何を実行し、「動いている」とは何かを示す地図を必要とします。
このチェックリストは引き継ぎの必須項目に焦点を当てています：環境変数、シークレット、ローカル開発セットアップ、データベースのブートストラップ、CI 設定、そして実用的な「どうやって動かすか」README。プロダクトの意思決定、UX の磨き上げ、アーキテクチャの再設計は扱いません。
所有権も明確にするべきです。作成者は前提を可視化する（ドキュメント、スクリプト、安全なデフォルト）責任を持ち、受け取る側はプロジェクトを自分たちの環境に適応する（シークレットマネージャ、ホスティング、厳格な CI ルール）責任を持ちます。双方が自分の役割を知っていれば、引き継ぎは日常的な作業になります。
クリーンな引き継ぎはシンプルな合意から始まります：コードがプラットフォームを離れるときに「完了」とは何を意味するか。これがないと、後でスクリプトの欠如、予期せぬ依存関係、あるいはどのバージョンが本物だったかで議論になります。
単一の安定した時点を選び、それを真実のソースとして扱ってください。変更の途中でエクスポートすると、ほとんど動かないリポジトリが出来上がります。
良いエクスポートポイントは通常次のいずれかです：
このポイントがなぜ適切かを一文で説明してください。例：「主要フローはすべて通っており、このマイルストーンではデータベーススキーマが確定している。」
受け取り側が何を期待すべきか、短いインベントリを書いてください。含まれるものと意図的に含めていないものを明示します。
基本を含めます：ソースコード（アプリ、サービス、共有パッケージ）、設定テンプレート（例 .env ファイル）、スクリプト（ビルド、dev、テスト、マイグレーション、シード）、デプロイの注意点。サンプルデータは scrub（個人情報等を除去）され安全である場合のみ含めます。
次にバージョンを固定して「私のマシンで動く」が新しい基準にならないようにします。ランタイムとツールチェーンのバージョン（Node、Go、Flutter、パッケージマネージャ）と、データベースのバージョン（PostgreSQL のメジャーバージョン）をキャプチャしてください。
最後に、実行前に必要な前提を列挙します。短く具体的に：必要なアカウント、インストール済みツール、開放が必要なポート、ワンタイムのセットアップ手順など。
「プラットフォーム上では動いていた」エクスポートの多くが失敗するのは、重要な設定が記録されていなかったからです。環境変数が典型的な原因です：リポジトリ外に存在するため、新しいチームメンバーは何が期待されているか分かりません。
クリーンなエクスポートには必須の作業として、すべての変数を発見でき、説明され、推測なしで設定しやすくしてください。
ハンドオフ README に一元化した情報源を作成します：環境変数名、アプリ内で何を制御するか、値の出所を一覧にします。説明は平易な言葉で、セキュリティ上の注意点は明確に示してください。
各変数に対する簡単なフォーマット：
そのドキュメントと並行して、リポジトリに .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 対象）、またはチームのローカルシークレットマネージャ例：リポジトリには PAYMENTS_API_KEY=replace_me を置きます。受け取り側はプロバイダダッシュボードで自分のキーを生成し、ローカルの .env と CI に設定します。コード自体は変わりません。
ハンドオフはシークレットをローテーションする良い機会です。特に共有プラットフォームで使われていた場合はなおさらです。
.env を更新するKoder.ai からエクスポートした場合は、エクスポートを新しい環境とみなし、受け取るチーム用に新しいシークレットを生成してください。
ハンドオフが成功したと言えるのは、新しい開発者がリポジトリをクローンし、数コマンド実行して推測なしにアプリを確認できるときです。予測可能な前提、明確な実行順、実際に動く短い「動かし方」ブロックを目指してください。
README の先頭にこれらを置き、誰もエラーメッセージから推測しなくて済むようにします：
プロジェクトが Koder.ai 上で構築されたなら、ローカルセットアップはエクスポートしたものと整合させてください（同じフォルダ構成、同じ起動コマンド）。「Postgres は既に動いている」と仮定しないでください。
新しいチームメンバーが実行すべき正確なコマンドを順番に置きます。コピペできるようにしてください：
# 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 ./...
多くの「動かない」問題は次のカテゴリに当てはまります：
バージョン不一致（Node/Go）。症状：依存関係やコンパイルのエラー。対処：固定されたバージョンを入れて再インストール。
環境変数の欠如。症状：「undefined」設定、認証失敗、500 エラー。対処：.env と .env.example を比較して必須値を埋める。
データベースに接続できない。症状：接続拒否、"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 の手順はローカルのコマンドに近づけて、乖離を避けてください。ローカルで 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 分は次のようになります：
.env.example を .env にコピー（または同じ値をシェルに設定）して、web と api の両方で行う。散らかったハンドオフでは、通常三つの障害に当たります。
まず：アプリは起動するが、不明瞭な「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 に従ってそのまま実行し、もし即興が必要ならドキュメントかスクリプトを修正して繰り返します。
よく見るチェック項目：
.env.example が存在し、すべての必須変数が安全な例値で説明されている。よくある落とし穴は地味なので見落とされがちです：
次のステップ：エクスポート後 24〜48 時間以内に検証するオーナーを割り当て、クリーンクローンテストを行ってギャップを報告させてください。
もしあなたが Koder.ai（koder.ai）上で構築しているなら、このチェックリストを通常のワークフローの一部として扱うと便利です：planning mode で実行手順を書き留め、重要な変更前にスナップショットを取り、スケジュールに従ってソースをエクスポートしてハンドオフパッケージを最新に保ちましょう。
安定した一点を選び、そこを真実のソースとして扱いましょう。
最低限、次を含めます：
.env.example と明確な環境変数ドキュメント機密情報や実際の認証情報は含めないでください。
環境変数は一箇所にまとめてドキュメント化し、.env.example を添付してください。
各変数について次を記載します：
シークレットをコミットしないこと。プレースホルダだけをコミットします。
単純なセットアップ例：
replace_me プレースホルダを置いた .env.example.env（gitignore 対象）また、各必須シークレットをどう生成するかを記載してください（例：「JWT_SECRET はランダムな 32 文字以上の文字列を作成する」）。
共有されていた可能性のあるものはローテーションしましょう。
実用的なローテーション順序：
.env を更新エクスポートを新しい環境として扱い、クリーンに始めてください。
初回起動が「コピー → 貼り付け → 実行」になるようにします：
Docker や Make が必要なら明記し、エラーで気づかせないようにします。
はい。PostgreSQL のメジャーバージョンやツールのバージョンは挙動が変わることがあります。
少なくとも記録するもの：
可能ならバージョンを固定し、CI でツールのバージョンを出力しておくとデバッグが楽になります。
ゼロから再現できる手順を提供します：
破壊的な操作にはガードレールを追加してください（例：APP_ENV=development のチェックや確認フラグ）。
CI はローカルコマンドに近づけ、設定を明確にします。
テストにマイグレーションが必要なら、CI が自動で実行するのか明記してください。
「クリーンクローン」テストを実行します：
一度でも即興で対処する必要があれば、ドキュメントやスクリプトを直して再テストしてください。これが元のビルド環境に隠れた前提を見つける最速の方法です（Koder.ai のような vibe-coding プラットフォームからのエクスポートを含む）。