エクスポートされたソースコードをガバナンスで同期させる

解決しようとしている問題（平易に）

プラットフォームがアプリを再生成すると、コードベースの大部分を書き換えることがあります。これはコードを整然と保つ利点がありますが、生成されたファイル内で手作業で行った変更は、次に再生成や新しいビルドを公開したときに消えてしまうこともあります。

本当の目標は「決してコードをエクスポートしないこと」ではありません。視覚的なモデルをソースオブトゥルースとして保ち、変更が一貫して再現可能である状態にすることです。AppMaster では、そのモデルにデータスキーマ、ビジネスプロセス、API エンドポイント、UI スクリーンが含まれます。モデルが正しければ、再生成はストレスのあるイベントではなく、安全で日常的な操作になります。

「エクスポートされたソースコード」とは通常、生成された Go バックエンド、Vue3 Web アプリ、Kotlin/SwiftUI のモバイルアプリを手元で管理下に置くことを指します。チームがエクスポートする理由は現実的です：セキュリティレビュー、自社ホスティング、カスタムなインフラ規則、特別な統合、あるいはプラットフォーム外での長期メンテナンスなどです。

問題は、エクスポートしたリポジトリが独自の人生を歩み始めるときに起きます。誰かが生成ファイルに直接バグ修正を入れたり、「ちょっとだけ」と機能をコードで追加したり、データベース層を手でいじったりします。後でモデルが変わると（フィールド名の変更、新しいエンドポイント、ビジネスプロセスの修正など）、アプリを再生成したときにドリフト、煩雑なマージ、あるいは作業の消失が発生します。

ガバナンスは主にプロセスであり、ツールではありません。いくつかの基本的な質問に答えます：

• 手作業の変更はどこで許可され、どこで禁止されるのか？
• 視覚モデルの変更とエクスポートされたリポジトリの変更を誰が承認できるのか？
• なぜその変更をコードで行ったのかをどう記録するか？
• 再生成がカスタム拡張と衝突したときにどうするか？

これらのルールが明確であれば、再生成はリスクではなくなります。更新を出荷する信頼できる方法となり、本当に必要な手作業部分を保護できます。

真のソースを選び、徹底する

エクスポートされたソースコードを再生成プラットフォームと同期させるには、どこをデフォルトの変更先にするかという明確な方針が必要です。

AppMaster のようなプラットフォームでは、最も安全なデフォルトは単純です：視覚モデルをソースオブトゥルースにすること。日々のプロダクトの振る舞いを定義するものは、エクスポートされたリポジトリではなくモデルに存在すべきです。通常、これにはデータモデル、ビジネスロジック、API エンドポイント、主要な UI フローが含まれます。

エクスポートしたコードは依然として有用ですが、ビルド成果物かつモデルでは表現しにくい作業用の小さく明示されたゾーンとして扱ってください。

多くのチームが従えるポリシーの例：

• 製品の振る舞いを変えるものはモデルに属する。
• 外部へのコネクタは薄いアダプタとしてモデル外に置ける。
• 共有ユーティリティ（ログ調整、小さなパーサヘルパー）はライブラリとしてモデル外に置ける。
• 顧客固有や環境固有の設定はモデル外に保ち、デプロイ時に注入する。
• パフォーマンスやセキュリティの修正は、まずモデルで表現できるか確認し、できなければ例外を文書化する。

許可されたゾーンは意図的に小さく保ってください。ゾーンが大きくなるほど、再生成が変更を上書きしたり、見えないドリフトを生んだりする可能性が高まります。

また、誰が例外を承認できるかを決めてください。例えば、認証、データ検証、コアワークフローに影響するコード変更はテックリードのみが承認するといった具合です。例外が有効である期間も定めましょう（例：「次の再生成サイクル後にレビュー」）—これにより一時的な修正が静かに恒久的なフォークになるのを防げます。

コードをエクスポートすべき場合とそうでない場合

ソースコードのエクスポートは正しい判断になることがありますが、その理由とエクスポート後に何が変わるかを明確にしておく必要があります。AppMaster のような再生成プラットフォームでは、視覚モデルをソースオブトゥルースとして扱い、エクスポートは検査、テスト、デプロイ可能な成果物とみなすのが最も安全なデフォルトです。

エクスポートが通常適している状況：監査性の強化（本番で何が動いているかを示せること）、自社ホスティング、組み込みモジュールで対応できない特別な統合、セキュリティチームによるコードスキャンの要請、またはベンダー非依存の出口戦略などです。

重要な質問は「コードにアクセスする必要があるのか、コードを編集する必要があるのか」です。

• コードアクセスのみ（読み取り専用エクスポート）：監査、セキュリティレビュー、災害復旧、ポータビリティ、ステークホルダーへの説明。\n- コード編集（編集可能なエクスポート）：低レベルの機能追加、サードパーティライブラリのパッチ、モデルで表現できない厳しいランタイム要件の対応。

読み取り専用のエクスポートのほうが楽です。生成物が上書きされることを心配せずに頻繁に再生成できます。

編集可能なエクスポートでチームが困ることが多いです。長期化した手作業の変更は開発者の個人的な好みではなくガバナンスの決定です。「1年後にこの変更はどこにあるか？」に答えられなければ、モデルはあることを示し、本番コードは別のことを示すドリフトが生じます。

良いルール：変更がビジネスロジック、データ形状、UI フロー、API 振る舞いであればモデルに残す。真のプラットフォームのギャップであれば、明示的な所有者、書面化された拡張パターン、そして再生成の扱い方を明確にしてコード編集を許可する。

再生成で壊れない安全な拡張ポイントの設計

生成されたファイルを「ちょっとだけここに追加しよう」と考えてはいけません。再生成が最終的に勝ちます。

まず、視覚モデルが所有するものとチームが所有するものの境界を明確に引きます。AppMaster ではモデルがバックエンド（Go）、Web（Vue3）、モバイル（Kotlin/SwiftUI）コードを再生成できるため、生成領域内のものはいつでも置き換えられる可能性があると想定してください。

越えにくい境界を作る

リポジトリと習慣の中で境界を分かりやすくしてください。正しいことが面倒だと、人は間違ったことをしがちです。

実務で有効なガードレールの例：

• 生成された出力は専用フォルダに置き、読み取り専用として扱う。
• カスタムコードは別フォルダに置き、独自のビルドエントリポイントを持たせる。
• カスタムコードは生成コードを内部ファイル経由ではなく公開インタフェース経由で呼ぶことを必須にする。
• "do not edit" ファイルが変更されたら CI が失敗するチェックを追加する。
• 生成ファイルに「DO NOT EDIT: regenerated from model」といったヘッダコメントを入れる。

最後の点は重要です。「編集しないでください：モデルから再生成されます」という明確なメッセージが、善意の修正が将来の破損につながるのを防ぎます。

編集よりラッパーを優先する

カスタム振る舞いが必要なときは、生成コードを直接変更するのではなくラップしてください。アダプタ層や薄いファサードを想定して、アプリと生成部分の間に置きます。

例えば、AppMaster のバックエンドをエクスポートして、サードパーティの在庫システムにカスタム統合が必要な場合、生成されたエンドポイントハンドラを編集するのではなく：

1. 生成されたエンドポイントはそのままにする。

2. カスタムサービス（custom エリア）を追加して在庫 API を呼ぶ。

3. 生成ロジックからは InventoryClient のような安定したインタフェース経由でそのサービスを呼ぶ。

再生成でエンドポイント実装は置き換えられても、統合コードはそのまま残ります。安定したインタフェース境界だけが維持されればよいのです。

可能な限り安定した統合ポイントを使う

カスタムコードを書く前に、API、Webhook、プラットフォームモジュールのような安定したフックで振る舞いを接続できないか確認してください。たとえば AppMaster には Stripe 決済や Telegram、メール/SMS の組み込みモジュールがあります。安定した統合ポイントを使えば、再生成で驚かされる回数を減らせます。

「編集禁止」ゾーンを一枚の短いページで文書化し、自動化で強制してください。ルールが人の頭の中だけにあると締め切りに負けて残りません。

再生成に耐えるリポジトリ構成

再生成に耐えるリポジトリは一目で何が生成物で何が人間の所有物か、そして何が設定かが分かります。誰かが 10 秒で判断できなければ、上書きや "謎の修正" が起きます。

AppMaster のような再生成プラットフォームからエクスポートする際は、エクスポートを一度きりの引き渡しではなく再現可能なビルド成果物として扱ってください。

実用的な構成は所有権とライフサイクルでコードを分けます：

• generated/（または appmaster_generated/）: 再生成可能なすべて。手動編集禁止。
• custom/: 手書き拡張、アダプタ、グルーコード。
• config/: 環境テンプレート、デプロイ設定、シークレットのプレースホルダ（実際のシークレットは置かない）。
• scripts/: "regen + patch + test" のような自動化スクリプト。
• docs/: リポジトリの簡単なルールページ。

名前付け規約は急いでいるときに助けになります。カスタム部分に一貫したプレフィックス（例：custom_ や ext_）を使い、生成レイアウトを写すのは本当に役立つ場合に限ります。生成ファイルを「今回だけ触ろう」と思ったら立ち止まり、その変更を custom/ に移すか合意された拡張ポイントに入れてください。

ブランチ運用も同じ分離を反映させましょう。多くのチームはモデル駆動の変更（視覚モデルの更新でコードが再生成されるもの）とカスタムコードの変更（拡張や統合）という 2 種類の作業を可視化します。単一リポジトリでも PR ラベルや model/* と custom/* のようなブランチ命名を義務付けるとレビューが明確になります。

リリースでは「新鮮な再生成」を非交渉にしてください。リリース候補はまず generated/ に再生成し、スクリプト化されたパッチを再適用し、テストを実行することで始まるべきです。再構築できないリポジトリはすでにドリフトしています。

モデルとコードを揃えるための手順付きワークフロー

すべてのエクスポートを小さなリリースとして扱ってください：再生成、検証、安全なものだけを再適用し、変更を明確に記録する。これにより視覚モデルをソースオブトゥルースとして保持しつつ、慎重に管理されたカスタム作業を許可できます。

有効なワークフローの例：

• 最新モデルから再生成する： 視覚モデルが最新であること（データスキーマ、ビジネスロジック、UI）を確認し、その正確なバージョンから再生成・エクスポートする。
• クリーンビルドと簡易スモークテストを行う： クリーンな状態からビルドして基本的な「起動するか」チェックを実行する。バックエンドのヘルスエンドポイントや Web の主要画面の読み込みを確認する。
• 承認された拡張ポイント経由でのみカスタムコードを再適用する： 生成ファイルに編集をコピペするのは避ける。カスタム挙動は再生成に耐えるモジュール、ラッパー、フックに入れる。
• 自動チェックを実行し、主要な出力を比較する： テストを実行し、重要な点（API 契約、データベース移行、主要画面の UI チェック）を比較する。
• リリースにタグ付けし、何が変わったかを記録する： モデルの変更（スキーマ、ロジック、UI）とカスタム変更（拡張、統合、設定）を分けて短いノートを書く。

再生成後に何か壊れたら、可能ならまずモデルで修正してください。モデルで表現できない場合のみカスタムコードを選び、そのコードを隔離して次の再生成で消えないようにします。

ガバナンスルール：役割、承認、チェンジコントロール

プラットフォームがコードを再生成できる場合（AppMaster のように）、ガバナンスは作業の喪失を防ぎます。明確な所有とシンプルな承認経路がなければ、チームは近くにあるものを直接編集し、再生成が定期的な驚きになります。

いくつかのオーナーを定めましょう。委員会は不要ですが、明確さは必要です。

• モデルメンテナ: データ、API、コアロジックの視覚モデルを所有する。
• カスタムコードメンテナ: 手書き拡張と安全な拡張境界を所有する。
• リリースオーナー: バージョン管理、再生成のタイミング、何を本番に出すかを調整する。

リスクの高い領域のレビューは必須にしてください。支払い、メッセージング、外部 API の統合やセキュリティ（認証、ロール、シークレット、データアクセス）に関わるカスタムコードは、カスタムコードメンテナともう一人のレビュアーによるレビューを必須にする、といったルールです。これはスタイルの問題ではなく、巻き戻しが難しいドリフトを防ぐためです。

チェンジコントロールには、誰でも記入できる小さな変更申請を使ってください。実際に使われる程度に簡潔に保つこと。

• 何が変わったか（モデル、生成設定、またはカスタム拡張）
• なぜ変わったか（ユーザーニーズやインシデント）
• リスク（何が壊れる可能性があるか、誰が影響を受けるか）
• ロールバック計画（安全に元に戻す方法）
• 検証方法（1〜2 個のチェック）

緊急修正のルールも設定してください。もしホットフィックスをエクスポートされたコードに直接適用する必要があるなら、その変更を視覚モデルに再現する（または拡張ポイントを再設計する）作業を 1〜3 営業日以内にスケジュールする、といった期限を設けることで、一時例外が永久的なドリフトになるのを防げます。

上書きやドリフトを招く一般的な誤り

ほとんどの上書き問題は「ちょっとした近道」から始まります：「このファイルだけ直そう」。AppMaster のような再生成プラットフォームでは、その近道はたいてい次の再生成時に差分が消えたり衝突を起こしたりします。

ドリフトを生むパターン

最も一般的なのは、生成コードを直接編集することが瞬間的には速く感じられるために起きます。それは次の再生成まではうまくいくかもしれませんが、再生成時にパッチが消えるか新しい出力と衝突します。

別の問題は、複数の人が明確な境界なしにカスタムコードを追加することです。あるチームが生成フォルダ内に「一時的」ヘルパーを置き、別のチームが同じ場所に別のヘルパーを置くと、もう再生成できなくなったり変更をクリーンにレビューできなくなったりします。

ドリフトはリリースで再生成を飛ばす場合にも発生します。再生成がリスクに感じられると再生成を行わず、モデルが変わっても本番は古いエクスポートを実行し続ける。数サイクル経つと誰もアプリが実際に何をしているか分からなくなります。

静かな誤りとしては、どのモデルバージョンがどのエクスポートを生んだかを記録しないことがあります。単純なタグやリリースノートがなければ、「この API の振る舞いはモデルから来ているのかカスタムパッチなのか？」に答えられません。

短い例

開発者がバリデーションルールの不足に気づき、生成された Go ハンドラを直接編集して空の値をブロックしました。テストを通り本番に出ました。2 週間後、チームが AppMaster の Business Process を更新して再エクスポートすると、ハンドラは再生成され、バリデーションは消えてバグが再発しました。

早期警告サイン：

• 生成ディレクトリ内にカスタムコミットが混入している
• 拡張はどこに置くかの書面ルールがない
• 「このリリースは再生成できない」が常態化している
• リリースで使用したモデルバージョンが記録されない
• 修正がコードにしか存在せずモデルに反映されていない

ドリフトを早期に検出する品質チェック

再生成を小さなリリースとして扱ってください。アプリがまだ動くかどうかだけでなく、視覚モデル（例：AppMaster の Data Designer と Business Process Editor）がリポジトリにデプロイされるものと一致しているかを確認します。

まずは実際のユーザ振る舞いを模した最小限のテストスイートから始めてください。小さく保って毎回実行できるようにしつつ、収益に関わるフローやサポートチケットに繋がるフローをカバーします。内部運用ツールであれば、「サインイン、レコード作成、承認、レポートで確認」のような流れが該当します。

繰り返し実行しやすい集中チェック例：

• 上位 3〜5 のユーザフローのスモークテスト（Web とモバイルがあれば両方）
• 主要 API の契約チェック（要求/応答の形）や Stripe/Telegram といった重要統合のチェック
• エクスポート後の差分レビュー（生成領域ではなくカスタムフォルダに焦点を当てる）
• ロールバックドリル：最後の既知の安定ビルドを素早く再デプロイできることを確認する
• バージョンログ：モデルバージョン、エクスポート日、デプロイしたコミットタグ

契約チェックは「UI 上は問題ないが実際には壊れている」問題を捕まえます。例：再生成でエンドポイントは残るが、フィールド型が整数から文字列に変わり下流の課金呼び出しが壊れる、など。

差分レビューでは簡単なルールを設けてください：生成ディレクトリ内のファイルは手で編集しない。レビュー担当はノイズの多い変更を無視し、自分たちが所有する部分（カスタムモジュール、アダプタ、統合ラッパー）に集中すること。

ロールバック計画を書いておき、必要になる前に準備してください。再生成が破壊的な変更を導入した場合、誰がロールバックを承認できるか、最後に安定していた成果物がどこにあるか、どのモデルバージョンがそれを生んだかを把握しておくべきです。

例：再生成で失われないようにカスタム統合を追加する

チームが AppMaster でカスタマーポータルを構築しており、組み込みモジュールでカバーされないニッチな SMS プロバイダとのカスタムメッセージ統合が必要になったとします。プロバイダ SDK を追加し、いくつかのエッジケースを処理するためにソースコードをエクスポートしました。

後で問題にならないようにするルールは単純です：データ、API エンドポイント、コアフローは視覚モデルをソースオブトゥルースとして保持する。カスタムプロバイダコードは生成コードから呼ばれるアダプタ層に置き、生成側が所有しないようにします。

きれいな分割の例：

• 視覚モデル（AppMaster）: データベースのフィールド、API エンドポイント、認証ルール、メッセージ送信を決めるビジネスプロセス
• アダプタ層（手書き）: プロバイダクライアント、リクエスト署名、リトライ、プロバイダエラーを小さな安定したアプリエラーに変換するロジック
• 薄い境界: ビジネスプロセスが呼ぶ SendMessage(to, text, metadata) のような一つのインタフェース

週次の運用では、再生成が退屈になることが目標です。月曜日にプロダクト変更で新しいメッセージタイプと PostgreSQL のフィールドが追加されたら、AppMaster モデルを更新して再生成します。生成されたバックエンドコードは変わりますが、アダプタ層はそのまま残ります。もしインタフェースに新しいパラメータが必要なら、そのインタフェースを一度だけ変更し、合意された境界の単一の呼び出し箇所だけを更新します。

レビューとテストは部族的知識に頼らないために役立ちます。最低限のチェックは：

• 誰も生成フォルダを直接編集していないことのチェック
• アダプタの単体テスト（正常系、プロバイダタイムアウト、無効な番号）
• 再生成後に実行される統合テストでメッセージ送信が確認できること

次の担当者のために短い統合カードを書いておきましょう：アダプタが何をするか、どこにあるか、資格情報のローテーション方法、テストの実行方法、視覚モデルが新しいフィールドを追加したときに何を変えるか。

次のステップ：実践的なロールアウト計画（軽いツール選択の注記付き）

小さく始めて書面化してください。リポジトリで何を変更して良いか、何を視覚モデルで変更すべきかの 2 つの問いに答えれば、1 ページのポリシーで十分です。生成とカスタムのどのフォルダがあなたのものかを示す境界図（スクリーンショットでも可）を README のそばに置きましょう。

次に 1 つの実際の機能でパイロットを行います。価値はあるが範囲が限定されたもの（Webhook の追加、小さな管理画面、新しい承認ステップなど）を選んでください。

実践的なロールアウト計画：

• ポリシーと境界図を作成し、リポジトリ README の近くに置く。
• 1 つのパイロット機能を選び、エンドツーエンドで実行する：モデル変更、エクスポート、レビュー、デプロイ。
• 定期的な再生成ドリルをスケジュールする（月次で十分）—意図的に再生成して重要なものが上書きされないことを確認する。
• 単純な変更ゲートを追加する：視覚モデルの変更が参照されていない（チケット、メモ、コミットメッセージ）場合はマージ禁止。
• 2 回の成功したドリルの後、同じルールを次のチームや次のアプリに適用する。

ツール選択の注記：AppMaster を使う場合、データ、API、ビジネスロジックは視覚モデルに置くことをデフォルトにしてください。エクスポートコードはデプロイ要件（自社クラウド、ポリシー）や明確に分離された領域に置かれた管理された拡張のために使います。

もし appmaster.io 上で AppMaster を使っているなら、小さなノーコードプロジェクトでまず練習する習慣をつけると良いでしょう：コアアプリロジックを視覚エディタで作り、エクスポートして再生成し、境界が維持されることを確認してから大きなシステムに拡張してください。