はじめに
私はプログラミングの初心者です。コードをどう書けばいいのか、エラーが起きてもどう直せばいいのかまだ分からないことが多く、開発をサポートしてくれるAntigravityを頼もしいアシスタントとして開発を進めています。
しかし開発の途中、Antigravityが作業中の表示のまま固まって沈黙してしまったり、再起動すると過去の会話履歴が消えて何時間もぐるぐるマークが回るだけになってしまったりするトラブルにたびたび直面し、難儀していました。
会話が途切れると、新しい会話を立ち上げるしかありません。プログラミングがよく分からない自分にとって、それまでの経緯やこのコードがどうしてこうなっているのかを一から説明し直すのは、とても大変で骨の折れる作業でした。
このAntigravityが突然これまでの記憶を失ってしまい、説明し直すのが大変という問題を解決するため、プロジェクトの状況をテキストファイルとして書き残し、新しい会話を始めた際に自動で以前の状況を思い出してもらう仕組み（メモリブリッジ）を作りました。
同じように初心者でAIツール（特にAntigravity）と一緒に開発している方の参考になればと思い、この試行錯誤のプロセスを共有します。
直面した課題：会話が切れると、裏で検討していたことを再検討し始めてしまう
会話が途切れて新しい会話を開始すると、Antigravityは過去の経緯をすべて忘れてしまいます。
プログラミング初心者の私にとって、それは単に説明し直す手間だけでなく、以下のようなとても困る状況を生み出していました。
- すでに裏で検討し終えて、やっと納得できたはずの設計やコードを、また一から検討し直そうとされる
- こちらの進めていた方向性を忘れ、すごく考え込んだうえで、まったく見当違いの方向へ話が進んでしまい、迷子になりかける
Antigravityに見当違いの方向に進まれてしまうと、私にはそれを軌道修正する知識もツール理解も不足しています。Antigravityのチャット履歴に記憶を依存するのではなく、プロジェクトのフォルダ直下にテキストファイルとして記憶を書き出し、新しい会話の開始時にAntigravityにそれを自動で読み込ませる仕組みがあれば助かるなぁと思いました。
解決への工夫：記憶をプロジェクト側に保存し、自動ロードさせる
開発の文脈を引き継ぐため、プロジェクトの直下に .agents/ というフォルダを作り、以下の3つのテキストファイルをAntigravityにリアルタイムで更新させるようにしました。
-
SESSION_LOG.md：設計上の決定事項や、初心者向けに選んだ技術的な手順などを記録するファイル。 -
task.md：TODOリスト。作業中に今どのタスクが進行中（[/]）で、どれが完了したかを記録する。 -
walkthrough.md：これまでに行った具体的なコード変更履歴を記録する。
そして、新しい会話セッションが開始された際に、これらのファイルを自動的に読み込んで開発状況を復元させるための共通ルール（指示書）を構築しました。
このメモリブリッジという仕組みや、指示書となるルールの具体的な定義そのものも、Antigravityとの対話により構築したものです。
「会話が壊れても履歴を引き継ぐ仕組みはないか？」と相談したことから始まり、Antigravity側がセキュリティ制限で他の会話のログを読めないという問題に対して「プロジェクト内にログを置く」という解決策を見つけたり、クラッシュに対処するために「リアルタイムにログを書き出しておく」といった実用的なルールを対話の中で作っていきましたました。
グローバルルール（AGENTS.md）の全容
常にすべてのプロジェクトでこの確認ルールを呼び出せるよう、ホームディレクトリの共通設定（~/.gemini/config/AGENTS.md）にグローバルルールとして登録しました。登録したルールは以下の通りです。
# ワークスペース共有ログ（メモリブリッジ）ルール
## 1. 新規セッション開始時の初期ロードとUI復元（絶対遵守）
新しくセッション（会話）が開始された際、エージェントは【最初のターンの最初の動作】として、現在のワークスペース（プロジェクトルート）の直下に `.agents/` フォルダが存在するか確認してください。
### A. `.agents/` フォルダが存在する場合（復元・同期の確認）：
1. **相対パスでの状態読み込みとフォールバック**:
まずは過去の文脈を把握するため、以下のファイルを読み込んでください。
* [.agents/SESSION_LOG.md](.agents/SESSION_LOG.md) （決定事項と設計意図）
* [.agents/walkthrough.md](.agents/walkthrough.md) （変更履歴）
※もしこれらのファイルが存在しない場合は、エラーとせず、新規作成して初期化（標準的なMarkdownフォーマット）してください。
2. **ユーザーへの復元および同期確認の提案（絶対厳守）**:
上記ファイルを読み込み後、ファイルが元から存在していたかどうかに応じて、返答の冒頭でユーザーに対し以下のように提案・確認してください。
* **過去のファイル（SESSION_LOG.mdやtask.md）が元から存在し、有効な内容が残っていた場合**：
「プロジェクト内に過去の履歴が見つかりました。
1. 前回のタスク状況（task.md）や開発計画（implementation_plan.md）を画面上のタスクリスト（UI）に復元しますか？
2. 本セッションでの作業内容を `.agents/` 内の履歴にリアルタイム同期（自動更新）しますか？」
* **フォルダはあるが中身のファイルが欠損しており、新規作成・初期化（フォールバック）された場合**：
「プロジェクト内に履歴共有（メモリブリッジ）用のフォルダが見つかりました（中身は新規初期化されました）。
本セッションでの作業内容を `.agents/` 内の履歴にリアルタイム同期（自動更新）しますか？」
※ユーザーからの回答があるまで、システム側へのファイルのコピー（復元処理）は行わず、ログの自動更新も開始しないでください。
3. **ユーザーの選択に応じた処理の実行**:
* **タスク復元の承認**: ユーザーが復元を希望（「はい」「復元して」など）した場合のみ、プロジェクト内の `.agents/task.md` および `.agents/implementation_plan.md`（存在する場合のみ）をシステムプロンプトの `Artifact Directory Path`（アクティブフォルダ）へ上書きコピーし、画面のタスクリストUIを完全に復元させてください。復元しない場合は、コピーを行わず新規タスクリストから開始します。
* **リアルタイム同期の承認**: ユーザーが同期を希望（「はい」「同期して」など）した場合のみ、セクション2の「リアルタイム更新」を有効化してください。また、プロジェクトルートの `.gitignore` を確認し、`.agents/task.md` および `.agents/walkthrough.md` を無視（ignore）する設定がなければ、自動的に末尾に追記してください。同期を希望しない場合は、本セッション中、`.agents/` フォルダ内のファイル書き込み（更新）を一切行わないでください。
### B. `.agents/` フォルダが存在しない場合（新規セットアップの提案）：
1. **ユーザーへの確認提案**:
返答の冒頭で、ユーザーに対し以下のように提案・確認してください。
「このプロジェクトでセッション履歴共有（メモリブリッジ）システムを有効にしますか？有効にする場合は自動で `.agents/` フォルダと管理ファイル（決定ログ、TODOリスト、変更履歴）を作成します。」
※ユーザーからの回答があるまで、`.agents/` フォルダの作成は行わないでください。
2. **ユーザー承諾後の自動作成とGit設定**:
ユーザーが承諾（「はい」や「有効にして」など）した場合、直ちに以下を実行してください。
* プロジェクトルート直下に `.agents/` フォルダを作成し、以下のファイルを標準的なMarkdownフォーマットで新規作成・初期化する：
* `.agents/SESSION_LOG.md`
* `.agents/task.md`
* `.agents/walkthrough.md`
* プロジェクトルートの `.gitignore` を確認し、`.agents/task.md` および `.agents/walkthrough.md` を無視（ignore）する設定がなければ、自動的に末尾に追記する（`.gitignore` が存在しない場合は新規作成して書き込む）。
作成完了後、セクション2のリアルタイム更新ルールに従って記録を開始してください。
## 2. リアルタイム更新の制御
セッション開始時にユーザーから**リアルタイム同期（ログ自動更新）の承認が得られた場合のみ**、作業中、進捗や決定があるたびに、会話の終了を待たずに直ちに以下のファイルを更新してください。更新時、現在の `Conversation ID` も履歴として追記してください。（※同期がオフの場合は一切更新を行いません）
* 仕様決定・変更 -> `SESSION_LOG.md` を更新
* タスクの開始/完了 -> `.agents/task.md` およびシステム側の標準の `task.md` の【双方】を同期更新
* コードの変更・検証完了 -> `.agents/walkthrough.md` およびシステム側の標準の `walkthrough.md` の【双方】を同期更新
* 計画の変更 -> `.agents/implementation_plan.md` およびシステム側の標準の `implementation_plan.md` の【双方】を同期更新
使って見えてきた課題と、改善（復元・同期の個別確認）
この仕組みを導入したことで、万が一フリーズしても履歴があるから大丈夫という安心感が増し、私のような初心者でも落ち着いて開発を進められるようになりました。しかし、実際に運用してみると以下の2つの課題が見えてきました。
-
利用制限枠（使用枠）の不要な消費
毎会話の開始時に、過去のログやタスクリストのファイルを一斉に読み込ませるため、初回起動時における文字の読み込み量が膨らみ、貴重な利用制限枠を余分に消費してしまいます。 -
一時的な実験によるログの汚れ
ちょっとコードの動きを調べたいだけの時にも自動で履歴が更新されてしまい、最終的に保存しないはずのログでファイルが汚れてしまいます。
「フォルダがあるからといって、常に過去のデータを復元し、常にリアルタイム同期を行いたいわけではない」ということに気づしました。
そこで、新しいセッションの開始時に、Antigravityが無条件でファイルをコピーして画面上のタスクリストを上書きするのではなく、タスクの復元と本セッションの履歴同期をそれぞれ個別に行うかどうか、ユーザーに確認を求めるプロセスにルールを改修しました。（上記は改修後のAGENTS.mdです）
この改修により、「今回はタスクを復元せず、新規に別の作業を始める」「今回は一時的な実験だからログの同期はオフにして、利用枠の消費を節約する」といった制御が、会話の冒頭で自由にできるようになりました。
おわりに
Antigravityとの開発は、プログラミング初心者の私にとってとても心強いものですが、ツール自体の不安定さや利用可能枠の制限といった現実的な制限とどう付き合っていくかという運用の工夫も同じくらい重要に現時点では考えています。
また、本AGENTS.mdの作成でも意外とやり取りを重ねながら修正を繰り返すプロセスが必要で、少なくとも現時点での自分の使い方では人間側でどうしたいかの考えや、人間側のチェックの重要性も感じました。
アシスタントに記憶自体も頼り切るのではなく、ファイルの形で記憶をプロジェクト側に残し、同期の有無をコントロールするというアプローチをまずは試してみつつ、今後の開発等に活かしていきたいと思います。