vibe-coding プラットフォームからソースコードをクリーンにエクスポートする

エクスポート後に所有権を持つとはどういう意味か

コードを所有することは、プラットフォームから ZIP を受け取るだけ以上の意味があります。元のワークスペース、特別なボタン、隠れた設定を必要とせずにアプリをビルド、実行、変更、出荷できることを意味します。真に所有されたプロジェクトは普通のリポジトリと同じように振る舞います：新しいチームメンバーがクローンしてラップトップで起動し、標準的なパイプラインでデプロイできるはずです。

多くのロックイン不安は同じ少数のギャップから来ます：

• プラットフォームの UI にのみ存在する設定
• 「どこか別で」行われるビルド手順
• 想定されているが書かれていない依存関係

もう一つよくある驚きは、ホストされたバージョンでは動くのにローカルで失敗するケースです。環境変数、データベースのセットアップ、シークレットが明示されていなかったことが原因です。

vibe-coding プラットフォームからのクリーンなエクスポートは、次の四つの結果につながるべきです：

• エクスポートされたアプリを予測可能な手順でローカルで実行できる。
• 手動クリックではなく、自分のリポジトリから CI を使ってデプロイできる。
• シークレットは安全に扱われる（Git に鍵がない、推測しない）。
• リポジトリは引き渡し準備が整っており、新しい人が素早くオンボードして内容を信頼できる。

これはプラットフォームを離れるつもりがなくても重要です。堅牢な所有姿勢は保険のようなもので、リスクを減らし、監査を容易にし、エージェンシーを雇ったり資金調達をしたりチームを変えたりするときの交渉を単純にします。

もし Koder.ai を使っていたなら、エクスポートには React ウェブアプリ、Go バックエンド、PostgreSQL、Flutter モバイルアプリのような一般的なスタックが含まれることがあります。スタック自体よりも原則が重要です：動作に必要なすべてがリポジトリで見えること、ホストされた環境に閉じ込められていないことです。

創業者がコントラクターにアプリを渡す場面を想像してください。"リポジトリをどうぞ"と渡せばそれで十分であるべきです。コントラクターが API ベース URL を探したり、データベーススキーマを作成したり、フロントエンドのビルド方法を学ぶために元のプラットフォームプロジェクトにアクセスする必要があってはなりません。

エクスポートされたプロジェクトに期待すべきこと

エクスポート後は、エディタで開けてラップトップで実行でき、元のプラットフォームなしで別のチームに渡せる普通のリポジトリがあるはずです。

Koder.ai のプロジェクトでは、エクスポートが次のような馴染みのある構成に対応することがよくあります：React ウェブアプリ、Go バックエンド、（存在するなら）Flutter モバイルアプリ。フォルダ名は異なることがありますが、どの部分がどこにあり、どう繋がるかがリポジトリから明白であるべきです。

プロジェクトの形状：フォルダ、エントリポイント、何が何を動かすか

まずエントリポイントと想定されるワークフローを見つけます。各アプリを起動する最初のファイルと、開発・実行方法を示すスクリプトが欲しいところです。

典型的な目印：

• Web: package.json と src/ フォルダ（多くは main.tsx 等）
• バックエンド: go.mod と cmd/ フォルダや main.go
• モバイル: Flutter の pubspec.yaml と lib/main.dart
• トップレベルの README や Makefile に全体の実行方法が書かれている
• サービス群として動かすことを意図した docker-compose.yml

依存関係、設定、データベース関連の要素

依存関係はピン留めされているべきです。JavaScript ならロックファイル（package-lock.json、yarn.lock、pnpm-lock.yaml）、Go なら go.mod と go.sum。ピンがないと実行不可能ではないにせよ、再現可能なビルドが難しくなります。

設定はコードから分離すべきです。.env.example や config.example.yaml のようなサンプルを探してください。本物のシークレット（API キーや本番用パスワード）がコミットされているべきではありません。もし見つけたら漏洩として扱い、即座にローテーションしてください。

データベース周りは migrations/ や db/migrations/ といったマイグレーションフォルダや、タイムスタンプ付きの SQL ファイルを探します。Go + PostgreSQL のアプリでは、小さなマイグレーションランナーやマイグレーションを適用するスクリプトが含まれていることもあります。

簡単なサニティチェックとして、まずビルドと実行コマンドを探します（npm run dev、go run、make など）。スクリプトがプラットフォーム専用のコマンドに依存しているなら、リポジトリ独立させる前に標準的なツールに置き換えましょう。

手順：エクスポート、コミット、ローカル実行

エクスポートをリリースアーティファクトのように扱います。何かを実行する前に「すべて揃っているか？」の簡単チェックを行ってください。欠けている部分は、変更を始める前に見つけた方が簡単です。

実務的な完全性チェックとして、各パートの“根”を探します：React ウェブアプリなら package.json、Go バックエンドなら go.mod、PostgreSQL 用のマイグレーション／シードファイルなど。

最初のクリーンなコミット（履歴を読みやすくするため）

エクスポートフォルダから新しい Git リポジトリを作り、何も直さず受け取ったものをそのままコミットしてください。これがクリーンなベースラインとなり、後の変更レビューが簡単になります。

git init
# Optional: set default branch name
# git branch -M main

git add -A
git commit -m "Initial export"

その後、小さな検証可能なステップでローカル実行を進めます。依存関係をインストールし、ローカル設定を作成し、データベース→バックエンド→フロントエンドの順で起動します。実際に使ったコマンドをすべてメモし、そのメモを README に書き起こしましょう。

以下はエクスポート構成に合わせて適用できるシンプルなコマンドの例です：

# Frontend
cd web
npm install
npm run dev

# Backend
cd ../server
go mod download
go run ./cmd/server

データベースが本当に動いていることを確認する（"サーバが起動した"だけではない）

サーバは起動してもアプリが壊れていることがあります。読み書きができるかを確認してください。

製品に適した迅速な確認方法：

• データ依存のページを開く（一覧、プロフィール、ダッシュボード）。
• レコードを作成（サインアップ、アイテム作成、メモ追加）、リフレッシュして永続化を確認。
• UI が対応していれば更新と削除も一度試す。
• マイグレーションエラーや「relation does not exist」などのログを監視する。

ローカルで動作が確認できたら、メモを README.md にまとめて、コマンドをコピペできる形で順序や必要な環境変数を明示してください。

エクスポートを引き渡し準備されたリポジトリにする

エクスポートは動くかもしれませんが、生成物っぽさが残ることがあります。引き渡し準備が整ったリポジトリは、どこに何があるか、どう実行するか、一貫性を保つ方法が明確です。

まずトップレベルのレイアウトを分かりやすくします。名前そのものより一貫性が重要です。

• apps/ : ユーザー向けフロントエンド（web、mobile）
• services/ : バックエンド API、ワーカー、ジョブ
• shared/ : 共有の型やユーティリティ
• infra/ : デプロイテンプレート、スクリプト、環境サンプル
• docs/ : アーキテクチャノートやランブック

続いて推測を減らす小さなファイル群を追加します：

• README.md（前提条件と正確なコマンドを掲載）
• CONTRIBUTING.md（ブランチ、PR、シークレット取扱いの簡単なルール）
• .gitignore（ローカル env ファイルやビルド出力を Git から除外）

README は実務的に保ちます。リポジトリに複数のパーツ（React フロントエンド、Go API、PostgreSQL）があるなら、起動順や設定ファイルの場所（例：".env.example を .env にコピー"）を明記してください。

新しいマシンでのチェックを行いましょう：新しいフォルダにクローンして README に従って作業します。Koder.ai からエクスポートした場合は、そのエクスポートを新しい独立プロジェクトの最初のコミットとして扱い、他の人を招待するのはその後にします。

新しい人が従えるローカル開発セットアップ

良いローカルセットアップは一つの質問に素早く答えます：新しい人が推測せずにアプリを 15 分以内に動かせるか。

デフォルトのアプローチを選び、明示してください。ネイティブインストールは既にツールが整っている人には速いです。コンテナはマシン間の一貫性が高いですが手間が増えます。両方サポートするなら、どちらをデフォルトにするかラベル付けしましょう。

よく使われるシンプルなパターン：1 ページの README、1 つのサンプル env ファイル、1 つのブートストラップコマンド。

最小限で安全な env 設定

偽の値を入れたサンプルファイルをコミットして、実際のシークレットを漏らさずに何を設定すべきかを示します。

# .env.example (example values only)
APP_ENV=local
PORT=8080
DATABASE_URL=postgres://app_user:app_pass@localhost:5432/app_db?sslmode=disable
JWT_SECRET=change-me
API_BASE_URL=http://localhost:8080

README には実ファイルの置き場所（例：".env.example を .env にコピー"）と、どの変数が必須か任意かを説明してください。

ブートストラップを一つのコマンドで

退屈な手順を正しい順序で実行する小さなスクリプトを追加します。読みやすさを保ってください。

#!/usr/bin/env bash
set -euo pipefail

cp -n .env.example .env || true

# Backend deps
cd backend
go mod download

# Database: create, migrate, seed
./scripts/db_create.sh
./scripts/db_migrate.sh
./scripts/db_seed.sh

# Frontend deps
cd ../web
npm install

データベース計画には次の三つを文書化してください：DB 作成方法、マイグレーションの実行方法、そして現実的な最初の実行のためのシードデータ取得方法。

最後に、クリックする前にアプリが動作していることを確認できる簡単なヘルスチェックを追加しましょう。GET /health のような小さなエンドポイントが「ok」を返し、データベース接続を検証するだけでも十分です。

シークレットと設定を漏らさず扱う

エクスポートしたプロジェクトのコードはあなたのものかもしれませんが、シークレットは機密のままにする必要があります。リポジトリが新しいチームメンバーと共有されることを想定してください。

まずアプリが動くために何が必要かをリストアップします。推測しないでください。コードをスキャンして設定の読み取り箇所（環境変数、設定ファイル）を確認し、有効にした統合をチェックします。

基本的なシークレット目録には通常、データベース資格情報、サードパーティ API キー、認証設定（OAuth や JWT）、ストレージ資格情報、暗号化キーや webhook 署名キーのようなアプリ固有のシークレットが含まれます。

各環境でどこにシークレットを置くかを決めます。よいデフォルトルールは：

• ローカル: 開発者が管理する .env（コミットしない）
• CI: CI プロバイダのシークレットストア
• 本番: 専用のシークレットマネージャーかホスティングの環境変数

Koder.ai のような vibe-coding プラットフォームからエクスポートした場合、チャットやログ、設定パネルに表示されたものはどこかにコピーされている可能性があります。シークレットをリポジトリから直ちに移動してください。

現実的なアプローチは、安全なテンプレート（.env.example）をコミットし、本物の値を Git に入れない（.env を .gitignore に追加）こと、そして本番のシークレットはデプロイ時に注入することです。

もしエクスポート時にシークレットが露出した可能性があるなら、必ずローテーションしてください。優先度はデータベースパスワード、OAuth クライアントシークレット、Webhook 署名キーです。

再発を防ぐためのガードレールをいくつか追加しましょう：明らかなシークレットパターンの pre-commit チェック、CI によるシークレットスキャン、必須変数がないと失敗する厳格な設定読み込み、環境ごとに分けた資格情報。

短い SECRETS.md を用意して引き渡しを容易にします。必要な変数、各環境でどこに保管するか、誰がローテーションできるかを簡潔に記載してください。

リポジトリを健康に保つための CI 設定

所有権を持ったら、CI は安全網になります。最初は小さく始めてください。すべてのプッシュでプロジェクトがビルドでき、基本チェックが通り、テスト（ある場合）が実行されることを素早く確認するだけで十分です。

CI は次の問いに素早く答えるべきです：「この変更はマージして安全か？」多くのリポジトリでは、依存関係のインストール、ビルド、lint、ユニットテストの実行がこれに該当します。

ジョブはアプリのパートごとに分けて失敗箇所を明確にします：

• Web: install、lint/typecheck、build、テスト実行
• バックエンド: build、ユニットテスト、リンター／フォーマッタチェック
• オプションのモバイル（Flutter）: 分析、テスト、ビルド
• オプションの DB チェック: 使い捨て環境でマイグレーションを適用

キャッシュを使うのは良いですが、キャッシュが問題を隠さないようにします。キャッシュミスでも CI は遅くなるだけで失敗しないことが重要です。

各ステップで単一コマンド（make test、npm run test など）を推奨します。これによりローカルと CI のコマンドが一致し、ログも短く保てます。

形の例（リポジトリに合わせて調整）：

jobs:
  web:
    steps:
      - run: npm ci
      - run: npm run lint
      - run: npm run build
  api:
    steps:
      - run: go test ./...
      - run: go build ./...

基礎が安定したらシンプルなリリースフローを追加します：リリースにタグを付け、アーティファクトをビルドして CI アーティファクトとして保存します。今日プラットフォームからデプロイしている場合でも、再現可能なアーティファクトがあれば後でホストを変えるのがずっと簡単になります。

よくあるミスと回避法

コードをエクスポートするのは仕事の半分です。残り半分は、プラットフォームの外でもプロジェクトが同じように振る舞うようにすることです。

ミス 1: 何のセットアップもせずに動くと思い込む

エクスポートには環境変数、マイグレーション、シードデータ、プラットフォームが勝手にやっていたビルド手順などが含まれていることが多いです。初回起動で真っ白な画面やデータベースエラーが出るのは普通です。

まずベースラインで一度実行してから変更を加えましょう：依存関係をインストールし、env を設定し、マイグレーションを実行し、サービスを順に起動します。必要な修正だけを行って期待されるセットアップに合わせてください。

ミス 2: シークレットを Git に漏らす

最も一般的な事故は、本物の API キーやパスワードを .env などでコミットしてしまうことです。

テンプレートのみコミットし、本物の値はローカル環境かシークレットストアに置きましょう。

ミス 3: すぐに依存関係を変える

パッケージをアップグレードしたりフォルダを再構成したりすると、問題の原因がエクスポート由来か自分の変更由来か判別しづらくなります。

まずは動作確認をしてから、小さな別コミットで改善を行いましょう。

ミス 4: バージョンをピン留めしない

"自分のマシンでは動く" の多くはアンピンのツールバージョン（Node、Go、Flutter、パッケージマネージャーなど）に起因します。

ランタイムバージョンはファイルや README に明確に示し、ロックファイル（package-lock、go.sum、pubspec.lock）を保持し、別のマシンやクリーンなコンテナでセットアップを検証してください。

ミス 5: ドキュメントを省いて後で困る

引き渡しが失敗する理由は、誰もが覚えている "一つの変な手順" を誰も書き残していないことです。必要な環境変数、マイグレーションの実行方法、ログの場所、ローカル状態のリセット方法などを新鮮なうちに書き留めてください。

現実的な例：プラットフォームプロジェクトから独立リポジトリへ

3 人チームが Koder.ai 上でカスタマーポータル（React、Go、PostgreSQL）を作りました。外部の開発チームに引き渡すとき、彼らはエクスポートが普通のリポジトリのように初日から動くことを望みます。

Day 1: エクスポートして新しい Git リポジトリを作り、ローカルで実行。フロントエンドは起動したが API は環境変数が欠けて失敗しました。彼らは推測せずコードを読んで必要なキーを特定し、プレースホルダ入りの .env.example を作成しました。本物の値はパスワードマネージャーとローカルの .env に置きます。

また、プラットフォームでは問題なかったポートや CORS 設定がローカルでは必要だったため、API を 8080、Web を 3000 のような予測可能なデフォルトに設定しました。

Day 2: マイグレーションと小さなシードスクリプトを追加してデモ用ユーザーと数行のデータを作成しました。続いて prerequisites、実行コマンド、動作確認方法（API のヘルスエンドポイントと UI のサンプルログイン）をカバーする短い README を書きました。

Day 3: プルリクエストごとに両サービスのテスト、lint、ビルドを実行する基本的な CI ワークフローを追加しました。ステージング向けにはコンテナをビルドして環境にシークレットを設定し、デプロイ時にマイグレーションを実行し、ロールバック手段を残すという簡単な計画を文書化しました。

良い引き渡しには通常、クローン直後のローカル実行、.env.example とシークレット保存場所の説明、マイグレーションとシードデータ、失敗が早く分かる CI チェック、ステージングとロールバックの短いデプロイノートが含まれます。

最終チェックと次のステップ

エクスポートを完了と呼ぶ前に、プロジェクトがプラットフォームの外で生きられることを証明してください。別の開発者が推測せずに動かせるなら、良い状態です。

最終チェックリスト：

• リポジトリが読みやすい：明確な README、妥当なフォルダ名、アプリを起動する一つの方法。
• 新規クローンからローカル実行が動く：クローン→インストール→設定→実行でアプリが確認できる。
• テストが実行される（スモークテストやヘルスチェックでも可）。
• プッシュごとに CI が走る：lint、テスト、ビルドが早く失敗する。
• シークレットが分離されている：リポジトリに鍵がない、サンプル設定ファイルで必要変数が分かる。
• ドキュメントが基本をカバー：実行方法、デプロイ方法、よく変える設定の場所。

技術的チェックの後に、所有権を明確にします。依存関係の更新、インフラの変更（DB、キュー、DNS）、リリースの責任者を決めましょう。誰も責任を持たないと、今日アプリが動いていてもリポジトリは徐々に腐っていきます。

主要な機能作業の前に短い安定化期間を計画してください。2〜5 営業日あれば、エクスポートの粗さを直し、README を強化し、「自分のマシンでは動く」問題を取り除けることが多いです。

もし Koder.ai（Koder.ai）を使っているなら、スナップショットやロールバックのような機能があるため、エクスポートを整えながらイテレーションしやすくなります。リポジトリが安定したら Git を信頼できる単一の情報源にし、将来のプラットフォームからのエクスポートは主な履歴ではなくチェックポイントとして扱ってください。

次の引き渡しマイルストーンを分かりやすく定義しましょう：「どんな開発者でも 30 分で動かせる」。その後、新しい人にクリーンなマシンで README に従ってもらい、彼らの質問を最終的な TODO リストにします。