複数の AI セッションが同じ Apps Script に clasp push しても互いの反映を消さない

これは何か

1 つの Google Apps Script プロジェクトに、複数の AI コーディングセッション（または複数人）が並行して clasp push する運用での事故防止手順。 clasp push は差分ではなく「ローカルにある全ファイル = 本番の全ファイル」に揃える。そのため、古いスナップショットから push すると、その後に別の誰かが追加したファイルは本番から削除される。エラーも警告も出ない。

よくある構成と、なぜ壊れるか

作業ツリーを複数セッションで共有していると、作業ツリーから直接 push すると他人の書きかけが本番に乗る。そこで次の「ステージング方式」がよく使われる。

1. 一時ディレクトリで clasp pull（本番のスナップショット）
2. 自分が変えたファイルだけ上書き
3. clasp push -f

この方式は「他人の書きかけを乗せない」点では正しい。ただし 1 と 3 の間に別セッションが本番へ新規ファイルを足すと、3 の push でそのファイルが消える。 典型的な症状は次のとおり。

• 共有ファイル（例: 関数のホワイトリスト）は新しい版が乗る。
• 登録先の関数が入った新規ファイルは消える。
• 結果として unknown command: X や X is not defined が出る。

手順（push する側）

1. pull → 上書き → push を 1 回の連続操作にする。 pull から push まで 5 分以上空いたら pull し直す。サブエージェントに反映を任せるときも、この順番を指示文に明記する。
2. 上書き後、push 前に構文チェックを走らせる（1 ファイルの構文エラーでプロジェクト全体が止まる）。

   node --check <staging>/src/<file>.js
   

3. push 後に別ディレクトリへ clasp pull し、次の 2 点を確認する。
   • 自分のファイルが本番と一致していること
   • 直前の pull に存在した他人のファイルが残っていること（ファイル数の比較だけでもよい）

参考実装（Node、要点のみ）:

// stage-push.mjs: FILES だけをステージングに重ねて push し、別ディレクトリで read-back
const FILES = ['FeatureA.js', 'ui/FeatureA.html'];
for (const f of FILES) fs.copyFileSync(`${WORK}/src/${f}`, `${STAGE}/src/${f}`);
for (const f of FILES.filter(x => x.endsWith('.js'))) execSync(`node --check "${STAGE}/src/${f}"`);
execSync('clasp push -f', { cwd: STAGE });
execSync('clasp pull', { cwd: VERIFY });          // VERIFY は .clasp.json だけ置いた空ディレクトリ
const bad = FILES.filter(f => read(`${VERIFY}/src/${f}`) !== read(`${WORK}/src/${f}`));
console.log(bad.length ? 'MISMATCH: ' + bad : 'read-back ok');

stage-pull.mjs は「STAGE を空にする → .clasp.json と .claspignore をコピー → clasp pull」だけでよい。

手順（消された側）

1. 実行結果が unknown command / is not defined になったら、自分のコードより先に本番からの消失を疑う。clasp pull で本番のファイル一覧を見る。
2. 消失を確認したら、最新の本番を pull し直してから自分のファイルを重ねて再 push し、read-back する。
3. 消した相手がまだ動いているなら、再 push だけでは足りない。 相手の次の push でまた消える（実例では 2 回連続で消えた）。
   • 相手の一時ディレクトリ（.clasp.json を含む最近更新されたディレクトリ）を探す。
   • その src/ に自分の変更ファイルを直接コピーし、相手の次の push に同乗させる。
   • 相手セッションへ「push 直前に pull し直す・push 後に残存確認する」と連絡する。
4. プロジェクトの引き継ぎメモに、時刻つきで事故と対処を記録する。

検証方法

• push 後の read-back で read-back ok が出ること。
• 機能の呼び出し（ホワイトリスト経由のコマンド実行など）が unknown command を返さないこと。
• 相手セッションからも「自分の push 後に、こちらの新規ファイルが残っている」報告を受けること。

やってはいけない

• 作業ツリーから直接 clasp push する（他人の書きかけが本番に乗る）。
• 朝に取ったスナップショットを使い回して夕方に push する。
• 消えたファイルを自分だけ再 push して終わる（並行相手が動いている限り再発する）。