vibe-coding プラットフォームからソースコードをクリーンにエクスポートして所有権を得る方法:ローカル実行、CI 設定、シークレット管理、引き渡し準備されたリポジトリの作り方を解説します。

package.json と src/ フォルダ(多くは main.tsx 等)\n- バックエンド: go.mod と cmd/ フォルダや main.go\n- モバイル: Flutter の pubspec.yaml と lib/main.dart\n- トップレベルの README や Makefile に全体の実行方法が書かれている\n- サービス群として動かすことを意図した docker-compose.yml\n\n### 依存関係、設定、データベース関連の要素\n\n依存関係はピン留めされているべきです。JavaScript ならロックファイル(package-lock.json、yarn.lock、pnpm-lock.yaml)、Go なら go.mod と go.sum。ピンがないと実行不可能ではないにせよ、再現可能なビルドが難しくなります。\n\n設定はコードから分離すべきです。.env.example や config.example.yaml のようなサンプルを探してください。本物のシークレット(API キーや本番用パスワード)がコミットされているべきではありません。もし見つけたら漏洩として扱い、即座にローテーションしてください。\n\nデータベース周りは migrations/ や db/migrations/ といったマイグレーションフォルダや、タイムスタンプ付きの SQL ファイルを探します。Go + PostgreSQL のアプリでは、小さなマイグレーションランナーやマイグレーションを適用するスクリプトが含まれていることもあります。\n\n簡単なサニティチェックとして、まずビルドと実行コマンドを探します(npm run dev、go run、make など)。スクリプトがプラットフォーム専用のコマンドに依存しているなら、リポジトリ独立させる前に標準的なツールに置き換えましょう。\n\n## 手順:エクスポート、コミット、ローカル実行\n\nエクスポートをリリースアーティファクトのように扱います。何かを実行する前に「すべて揃っているか?」の簡単チェックを行ってください。欠けている部分は、変更を始める前に見つけた方が簡単です。\n\n実務的な完全性チェックとして、各パートの“根”を探します:React ウェブアプリなら package.json、Go バックエンドなら go.mod、PostgreSQL 用のマイグレーション/シードファイルなど。\n\n### 最初のクリーンなコミット(履歴を読みやすくするため)\n\nエクスポートフォルダから新しい Git リポジトリを作り、何も直さず受け取ったものをそのままコミットしてください。これがクリーンなベースラインとなり、後の変更レビューが簡単になります。\n\nbash\ngit init\n# Optional: set default branch name\n# git branch -M main\n\ngit add -A\ngit commit -m "Initial export"\n\n\nその後、小さな検証可能なステップでローカル実行を進めます。依存関係をインストールし、ローカル設定を作成し、データベース→バックエンド→フロントエンドの順で起動します。実際に使ったコマンドをすべてメモし、そのメモを README に書き起こしましょう。\n\n以下はエクスポート構成に合わせて適用できるシンプルなコマンドの例です:\n\nbash\n# Frontend\ncd web\nnpm install\nnpm run dev\n\n# Backend\ncd ../server\ngo mod download\ngo run ./cmd/server\n\n\n### データベースが本当に動いていることを確認する("サーバが起動した"だけではない)\n\nサーバは起動してもアプリが壊れていることがあります。読み書きができるかを確認してください。\n\n製品に適した迅速な確認方法:\n\n- データ依存のページを開く(一覧、プロフィール、ダッシュボード)。\n- レコードを作成(サインアップ、アイテム作成、メモ追加)、リフレッシュして永続化を確認。\n- UI が対応していれば更新と削除も一度試す。\n- マイグレーションエラーや「relation does not exist」などのログを監視する。\n\nローカルで動作が確認できたら、メモを README.md にまとめて、コマンドをコピペできる形で順序や必要な環境変数を明示してください。\n\n## エクスポートを引き渡し準備されたリポジトリにする\n\nエクスポートは動くかもしれませんが、生成物っぽさが残ることがあります。引き渡し準備が整ったリポジトリは、どこに何があるか、どう実行するか、一貫性を保つ方法が明確です。\n\nまずトップレベルのレイアウトを分かりやすくします。名前そのものより一貫性が重要です。\n\n- apps/ : ユーザー向けフロントエンド(web、mobile)\n- services/ : バックエンド API、ワーカー、ジョブ\n- shared/ : 共有の型やユーティリティ\n- infra/ : デプロイテンプレート、スクリプト、環境サンプル\n- docs/ : アーキテクチャノートやランブック\n\n続いて推測を減らす小さなファイル群を追加します:\n\n- README.md(前提条件と正確なコマンドを掲載)\n- CONTRIBUTING.md(ブランチ、PR、シークレット取扱いの簡単なルール)\n- .gitignore(ローカル env ファイルやビルド出力を Git から除外)\n\nREADME は実務的に保ちます。リポジトリに複数のパーツ(React フロントエンド、Go API、PostgreSQL)があるなら、起動順や設定ファイルの場所(例:".env.example を .env にコピー")を明記してください。\n\n新しいマシンでのチェックを行いましょう:新しいフォルダにクローンして README に従って作業します。Koder.ai からエクスポートした場合は、そのエクスポートを新しい独立プロジェクトの最初のコミットとして扱い、他の人を招待するのはその後にします。\n\n## 新しい人が従えるローカル開発セットアップ\n\n良いローカルセットアップは一つの質問に素早く答えます:新しい人が推測せずにアプリを 15 分以内に動かせるか。\n\nデフォルトのアプローチを選び、明示してください。ネイティブインストールは既にツールが整っている人には速いです。コンテナはマシン間の一貫性が高いですが手間が増えます。両方サポートするなら、どちらをデフォルトにするかラベル付けしましょう。\n\nよく使われるシンプルなパターン:1 ページの README、1 つのサンプル env ファイル、1 つのブートストラップコマンド。\n\n### 最小限で安全な env 設定\n\n偽の値を入れたサンプルファイルをコミットして、実際のシークレットを漏らさずに何を設定すべきかを示します。\n\nenv\n# .env.example (example values only)\nAPP_ENV=local\nPORT=8080\nDATABASE_URL=postgres://app_user:app_pass@localhost:5432/app_db?sslmode=disable\nJWT_SECRET=change-me\nAPI_BASE_URL=http://localhost:8080\n\n\nREADME には実ファイルの置き場所(例:".env.example を .env にコピー")と、どの変数が必須か任意かを説明してください。\n\n### ブートストラップを一つのコマンドで\n\n退屈な手順を正しい順序で実行する小さなスクリプトを追加します。読みやすさを保ってください。\n\nbash\n#!/usr/bin/env bash\nset -euo pipefail\n\ncp -n .env.example .env || true\n\n# Backend deps\ncd backend\ngo mod download\n\n# Database: create, migrate, seed\n./scripts/db_create.sh\n./scripts/db_migrate.sh\n./scripts/db_seed.sh\n\n# Frontend deps\ncd ../web\nnpm install\n\n\nデータベース計画には次の三つを文書化してください:DB 作成方法、マイグレーションの実行方法、そして現実的な最初の実行のためのシードデータ取得方法。\n\n最後に、クリックする前にアプリが動作していることを確認できる簡単なヘルスチェックを追加しましょう。GET /health のような小さなエンドポイントが「ok」を返し、データベース接続を検証するだけでも十分です。\n\n## シークレットと設定を漏らさず扱う\n\nエクスポートしたプロジェクトのコードはあなたのものかもしれませんが、シークレットは機密のままにする必要があります。リポジトリが新しいチームメンバーと共有されることを想定してください。\n\nまずアプリが動くために何が必要かをリストアップします。推測しないでください。コードをスキャンして設定の読み取り箇所(環境変数、設定ファイル)を確認し、有効にした統合をチェックします。\n\n基本的なシークレット目録には通常、データベース資格情報、サードパーティ API キー、認証設定(OAuth や JWT)、ストレージ資格情報、暗号化キーや webhook 署名キーのようなアプリ固有のシークレットが含まれます。\n\n各環境でどこにシークレットを置くかを決めます。よいデフォルトルールは:\n\n- ローカル: 開発者が管理する .env(コミットしない)\n- CI: CI プロバイダのシークレットストア\n- 本番: 専用のシークレットマネージャーかホスティングの環境変数\n\nKoder.ai のような vibe-coding プラットフォームからエクスポートした場合、チャットやログ、設定パネルに表示されたものはどこかにコピーされている可能性があります。シークレットをリポジトリから直ちに移動してください。\n\n現実的なアプローチは、安全なテンプレート(.env.example)をコミットし、本物の値を Git に入れない(.env を .gitignore に追加)こと、そして本番のシークレットはデプロイ時に注入することです。\n\nもしエクスポート時にシークレットが露出した可能性があるなら、必ずローテーションしてください。優先度はデータベースパスワード、OAuth クライアントシークレット、Webhook 署名キーです。\n\n再発を防ぐためのガードレールをいくつか追加しましょう:明らかなシークレットパターンの pre-commit チェック、CI によるシークレットスキャン、必須変数がないと失敗する厳格な設定読み込み、環境ごとに分けた資格情報。\n\n短い SECRETS.md を用意して引き渡しを容易にします。必要な変数、各環境でどこに保管するか、誰がローテーションできるかを簡潔に記載してください。\n\n## リポジトリを健康に保つための CI 設定\n\n所有権を持ったら、CI は安全網になります。最初は小さく始めてください。すべてのプッシュでプロジェクトがビルドでき、基本チェックが通り、テスト(ある場合)が実行されることを素早く確認するだけで十分です。\n\nCI は次の問いに素早く答えるべきです:「この変更はマージして安全か?」多くのリポジトリでは、依存関係のインストール、ビルド、lint、ユニットテストの実行がこれに該当します。\n\nジョブはアプリのパートごとに分けて失敗箇所を明確にします:\n\n- Web: install、lint/typecheck、build、テスト実行\n- バックエンド: build、ユニットテスト、リンター/フォーマッタチェック\n- オプションのモバイル(Flutter): 分析、テスト、ビルド\n- オプションの DB チェック: 使い捨て環境でマイグレーションを適用\n\nキャッシュを使うのは良いですが、キャッシュが問題を隠さないようにします。キャッシュミスでも CI は遅くなるだけで失敗しないことが重要です。\n\n各ステップで単一コマンド(make test、npm run test など)を推奨します。これによりローカルと CI のコマンドが一致し、ログも短く保てます。\n\n形の例(リポジトリに合わせて調整):\n\nyaml\njobs:\n web:\n steps:\n - run: npm ci\n - run: npm run lint\n - run: npm run build\n api:\n steps:\n - run: go test ./...\n - run: go build ./...\n\n\n基礎が安定したらシンプルなリリースフローを追加します:リリースにタグを付け、アーティファクトをビルドして CI アーティファクトとして保存します。今日プラットフォームからデプロイしている場合でも、再現可能なアーティファクトがあれば後でホストを変えるのがずっと簡単になります。\n\n## よくあるミスと回避法\n\nコードをエクスポートするのは仕事の半分です。残り半分は、プラットフォームの外でもプロジェクトが同じように振る舞うようにすることです。\n\n### ミス 1: 何のセットアップもせずに動くと思い込む\n\nエクスポートには環境変数、マイグレーション、シードデータ、プラットフォームが勝手にやっていたビルド手順などが含まれていることが多いです。初回起動で真っ白な画面やデータベースエラーが出るのは普通です。\n\nまずベースラインで一度実行してから変更を加えましょう:依存関係をインストールし、env を設定し、マイグレーションを実行し、サービスを順に起動します。必要な修正だけを行って期待されるセットアップに合わせてください。\n\n### ミス 2: シークレットを Git に漏らす\n\n最も一般的な事故は、本物の API キーやパスワードを .env などでコミットしてしまうことです。\n\nテンプレートのみコミットし、本物の値はローカル環境かシークレットストアに置きましょう。\n\n### ミス 3: すぐに依存関係を変える\n\nパッケージをアップグレードしたりフォルダを再構成したりすると、問題の原因がエクスポート由来か自分の変更由来か判別しづらくなります。\n\nまずは動作確認をしてから、小さな別コミットで改善を行いましょう。\n\n### ミス 4: バージョンをピン留めしない\n\n"自分のマシンでは動く" の多くはアンピンのツールバージョン(Node、Go、Flutter、パッケージマネージャーなど)に起因します。\n\nランタイムバージョンはファイルや README に明確に示し、ロックファイル(package-lock、go.sum、pubspec.lock)を保持し、別のマシンやクリーンなコンテナでセットアップを検証してください。\n\n### ミス 5: ドキュメントを省いて後で困る\n\n引き渡しが失敗する理由は、誰もが覚えている "一つの変な手順" を誰も書き残していないことです。必要な環境変数、マイグレーションの実行方法、ログの場所、ローカル状態のリセット方法などを新鮮なうちに書き留めてください。\n\n## 現実的な例:プラットフォームプロジェクトから独立リポジトリへ\n\n3 人チームが Koder.ai 上でカスタマーポータル(React、Go、PostgreSQL)を作りました。外部の開発チームに引き渡すとき、彼らはエクスポートが普通のリポジトリのように初日から動くことを望みます。\n\nDay 1: エクスポートして新しい Git リポジトリを作り、ローカルで実行。フロントエンドは起動したが API は環境変数が欠けて失敗しました。彼らは推測せずコードを読んで必要なキーを特定し、プレースホルダ入りの .env.example を作成しました。本物の値はパスワードマネージャーとローカルの .env に置きます。\n\nまた、プラットフォームでは問題なかったポートや CORS 設定がローカルでは必要だったため、API を 8080、Web を 3000 のような予測可能なデフォルトに設定しました。\n\nDay 2: マイグレーションと小さなシードスクリプトを追加してデモ用ユーザーと数行のデータを作成しました。続いて prerequisites、実行コマンド、動作確認方法(API のヘルスエンドポイントと UI のサンプルログイン)をカバーする短い README を書きました。\n\nDay 3: プルリクエストごとに両サービスのテスト、lint、ビルドを実行する基本的な CI ワークフローを追加しました。ステージング向けにはコンテナをビルドして環境にシークレットを設定し、デプロイ時にマイグレーションを実行し、ロールバック手段を残すという簡単な計画を文書化しました。\n\n良い引き渡しには通常、クローン直後のローカル実行、.env.example とシークレット保存場所の説明、マイグレーションとシードデータ、失敗が早く分かる CI チェック、ステージングとロールバックの短いデプロイノートが含まれます。\n\n## 最終チェックと次のステップ\n\nエクスポートを完了と呼ぶ前に、プロジェクトがプラットフォームの外で生きられることを証明してください。別の開発者が推測せずに動かせるなら、良い状態です。\n\n最終チェックリスト:\n\n- リポジトリが読みやすい:明確な README、妥当なフォルダ名、アプリを起動する一つの方法。\n- 新規クローンからローカル実行が動く:クローン→インストール→設定→実行でアプリが確認できる。\n- テストが実行される(スモークテストやヘルスチェックでも可)。\n- プッシュごとに CI が走る:lint、テスト、ビルドが早く失敗する。\n- シークレットが分離されている:リポジトリに鍵がない、サンプル設定ファイルで必要変数が分かる。\n- ドキュメントが基本をカバー:実行方法、デプロイ方法、よく変える設定の場所。\n\n技術的チェックの後に、所有権を明確にします。依存関係の更新、インフラの変更(DB、キュー、DNS)、リリースの責任者を決めましょう。誰も責任を持たないと、今日アプリが動いていてもリポジトリは徐々に腐っていきます。\n\n主要な機能作業の前に短い安定化期間を計画してください。2〜5 営業日あれば、エクスポートの粗さを直し、README を強化し、「自分のマシンでは動く」問題を取り除けることが多いです。\n\nもし Koder.ai(Koder.ai)を使っているなら、スナップショットやロールバックのような機能があるため、エクスポートを整えながらイテレーションしやすくなります。リポジトリが安定したら Git を信頼できる単一の情報源にし、将来のプラットフォームからのエクスポートは主な履歴ではなくチェックポイントとして扱ってください。\n\n次の引き渡しマイルストーンを分かりやすく定義しましょう:「どんな開発者でも 30 分で動かせる」。その後、新しい人にクリーンなマシンで README に従ってもらい、彼らの質問を最終的な TODO リストにします。所有権は自律性として扱ってください:通常のリポジトリから、元のプラットフォームプロジェクト、特別な UI 設定、あるいは隠れたビルド手順を必要とせずにビルド、実行、変更、デプロイできることです。\n\n良いテストは次の問いです:新しいチームメンバーが README だけでリポジトリをクローンして動かせますか?
まずは簡単な完全性チェックを行いましょう:\n\n- 各アプリの“ルート”を探す(package.json、go.mod、pubspec.yaml)。\n- ロックファイルがあるか確認する(package-lock.json、yarn.lock、pnpm-lock.yaml、go.sum)。\n- データベースマイグレーションの有無を確認(migrations/ 等)。\n- 実行可能なワークフローがあるか(README、Makefile、スクリプト、docker-compose.yml)。\n\n実行に必要なものが UI やチャットでしか説明されている場合は、それをドキュメント化してリポジトリに移しましょう。
小さく、検証可能なステップで進めます:\n\n1. Git を初期化して生のエクスポートをコミット(ベースライン)。\n2. .env.example を参考にローカル設定を作る(.env へ)。\n3. データベースを起動。\n4. マイグレーションを実行。\n5. バックエンドを起動。\n6. フロントエンドを起動。\n\nすぐにリファクタせず、まずはそのまま動くことを証明してから改善を別コミットで行いましょう。
ホスティング環境にはローカルで明示していない設定があるためです:\n\n- 環境変数(API ベース URL、JWT シークレット、ストレージキーなど)が欠けている。\n- データベースが作成されていない、マイグレーションやシードデータが未実行。\n- プラットフォーム上で事前に設定されていたポートや CORS 設定。\n- “どこかで”行われていた暗黙のビルド手順。\n\nこれらは .env.example、マイグレーションスクリプト、README に明示することで修正できます。
サーバが起動するだけでは不十分です—実際のデータの読み書きができるか確認してください:\n\n- データ依存のページを開く(リスト、プロフィール、ダッシュボードなど)。\n- レコードを作成し、リフレッシュして永続化されたか確認。\n- 可能なら更新と削除も一度試す。\n- ログに「relation does not exist」などのマイグレーションエラーがないか見る。\n\nローカルでデータ変更を再現できないなら、セットアップやマイグレーションが不完全です。
基本的なやり方:\n\n- .env.example を偽の値でコミットして必要項目を示す。\n- 実際の .env は .gitignore に追加して Git にコミットしない。\n- 実際のシークレットはパスワードマネージャーやシークレットストアで管理する。\n\nもしリポジトリに本物のキーがあれば、漏洩したと考えて直ちにローテーションしてください。優先順位はデータベース資格情報、OAuth クライアントシークレット、Webhook の署名キーなどです。
最初はシンプルにしてローカルと一貫させましょう:\n\n- Web アプリのビルドと lint/typecheck。\n- バックエンドで go test ./... を実行しビルド。\n- 必要ならエフェメラルな DB でマイグレーションを適用して確認。\n\nCI はローカルで実行するのと同じスクリプト(make test、npm run build など)を呼ぶようにして、ローカルで動くものが CI でも動くようにします。
はい。予測可能な引き渡しに必要です。推奨は:\n\n- トップレベルの README.md にコピペできるコマンドを記載。\n- 必要項目と任意項目を整理した .env.example。\n- 依存関係のインストールや DB 準備を行うブートストラップスクリプト。\n\n目標は新しい開発者が 15~30 分でアプリを推測なしで動かせることです。
一般的な構成例:\n\n- フロントエンド(web、mobile)を apps/ に置く。\n- API やワーカーを services/ に置く。\n- 共通の型やユーティリティを shared/ に入れる。\n- デプロイテンプレートや環境例を infra/ に置く。\n\n名前そのものよりも、何がどこで動くか、パーツ同士がどう繋がるかが一目で分かることが重要です。
実務的な手順:\n\n1. エクスポートしてベースラインをコミット。\n2. 明示的な設定、マイグレーション、README を整備してローカルで動かす。\n3. CI を追加してビルドやテストが壊れないようにする。\n4. シークレットの設定方法、マイグレーション実行、ロールバック方法を含むデプロイノートを作る。\n\n安定したら Git を信頼できるソースオブトゥルースにして、将来のプラットフォームからのエクスポートはチェックポイントとして扱いましょう。