Antigravityとgit worktreeで、AI駆動のMarkdownドキュメントチーム構築・差分管理手法

1. ゴール

チームでGoogleDocsやOneDriveのドキュメントを作っていくとき、「誰が、いつ、なぜここを書き換えたのか」が後からわからなくなるのは、よくある問題です。この記事では、この問題をシステム的に解決しつつ、AIを「共同執筆者」としてプロセスに巻き込みます。

今回目指すのは、以下の3つを実現するストレスの少ないドキュメント作成チーム環境です。

AIとの協働による「初期作成ブースト」: ドキュメントをゼロから書き始める一番しんどい作業をAIに任せ、執筆のハードルを大きく下げる。
Gitで「テキトーな共同編集」の廃止: Git/GitHubの仕組みを使い、変更の意図と責任の所在がはっきりわかる、透明性の高い合意形成フローを作る。
レビューにおける「人間の疲れ」を減らす: 表記揺れなどの細かい指摘による心理的な摩擦を、AIに一次レビューさせることでシステム的に防ぐ。

2. 前提条件と環境：ツールの準備

まず、ベースとなるAntigravity（生成AI+エディタ）と、Git操作を快適にするための拡張機能をインストールします。

エディタ: Antigravity（または VS Code）をインストール。
拡張機能「Markdown Preview Enhanced」「Markdown Preview Mermaid Support」: マークダウンのプレビューと、その上でMermaid形式の図の表示をサポート。
拡張機能「GitHub Pull Requests」: エディタ内でPRの作成・レビューを完結させるために使用。
Git環境: ローカルにGitがインストールされており、GitHubのリポジトリにアクセスできること。

3. 概念の再定義：Googleドキュメント型「同期編集」の落とし穴

Googleドキュメントのような同期型ツールは、個人がサクッとメモを書くのには最高の手軽さを持っています。しかし、チーム運用においてはこの「手軽さ」が逆に首を絞めることになります。

「なぜ変えたか」が残らない: 変更履歴は自動保存の記録に過ぎず、「なぜそのパラグラフを追加したのか」というコミットメッセージにあたる意図が残せない。
議論のプロセスが消える: コメント機能で議論しても「解決」を押した瞬間に見えなくなり、後から来たメンバーには「なぜその結論になったのか」が追えなくなる。
意図せぬ上書き事故: 同時編集できるがゆえに、他人の意図を汲まずにうっかり消してしまう事故が起きやすい。

これは言い換えれば「手軽さを優先した結果、組織としてのドキュメントのガバナンスを手放している」状態です。そこで本運用では、GitとMarkdownの組み合わせを採用し、独立したブランチで意図をまとめ、レビューを経てから合流させる「透明で評価可能なシステム」へ移行します。

4. 初期構築：git worktreeによる並行作業環境の作成

Gitでドキュメントを管理する際、一番ネックになるのが「ブランチを切り替える（checkout）たびにファイルの中身が書き換わる」という認知負荷です。これを解消するため、git worktreeを使って物理的にフォルダを分け、Antigravity上でまとめて管理します。

ここでは、Documents/DocProjects/ProjectA_Workspace というディレクトリに環境を作る手順を、2つのパターンで紹介します。既存のローカルプロジェクトを直接変換するのは手順が複雑で事故が起きやすいため、「完全に新規で作る」か「GitHubからクローンする」アプローチをとります。

ステップ1：ベースとなるリポジトリの準備

パターンA：完全に空っぽから新しく作る場合

まだGitHubにもリポジトリがなく、ローカルでゼロからプロジェクトを立ち上げるケースです。

mkdir -p Documents/DocProjects/ProjectA_Workspace
cd Documents/DocProjects/ProjectA_Workspace

# .bare という名前で空のベアリポジトリを初期化
git init --bare .bare

💡 補足: git worktree はリポジトリ内に1つ以上のコミットが存在しないと新しいブランチを展開できません。完全に空の状態で立ち上げる場合は、一度通常のディレクトリとしてクローンし、ダミーのコミット（READMEの追加など）を打つ必要があります。手軽に始めるなら、GitHub上で「READMEを追加してリポジトリを作成」し、以下のパターンBで進めるのが最もスムーズです。

パターンB：GitHubにある既存のリポジトリを使って作る場合（推奨）

すでにGitHub上にリポジトリがある（またはGitHubで空のリポジトリを新規作成し、READMEを追加した）ケースです。最後の .bare を忘れないように指定してください。

mkdir -p Documents/DocProjects/ProjectA_Workspace
cd Documents/DocProjects/ProjectA_Workspace

# GitHubから .bare という名前でベアリポジトリとしてクローン
git clone --bare https://github.com/your-org/your-doc-repo.git .bare

ステップ2：作業ディレクトリ（worktree）の展開

次に、メインブランチと、そこから派生させた作業用ブランチを別々のフォルダとして展開します。エラーを防ぐため、必ず一度 .bare ディレクトリの中に入ってから実行してください。

# 1. ベアリポジトリの内部へ移動する（必須）
cd .bare

# 2. 展開先を「一段上のディレクトリ（../）」に指定して main ブランチを展開する
git worktree add ../main main

# 3. mainを起点に新しい作業ブランチ（feature-doc）を作成し、同様に一段上に展開する
git worktree add -b feature-doc ../feature-doc main

# 4. 作業が終わったら、元のワークスペース階層に戻る
cd ..

これにより、ディレクトリ構造は以下のようになります。実体である .bare と、作業用のディレクトリ群が並列に配置され、システム的に整合性が保たれます。

ステップ3：専用の「マルチルートワークスペース」として構築・保存する

もしAntigravityで既存のプロジェクトを開いた状態だとマルチルートワークスペースを開くことができないので、ここでは確実に空っぽのAntigravityを開いてからマルチルートワークスペースを開きます。

クリーンな環境の用意: Antigravityで Ctrl+Shift+N（Macは Cmd+Shift+N）を押下し、完全に空の新規ウィンドウを立ち上げる。
フォルダのマウント: 新規ウィンドウ上で「File > Add Folder to Workspace...」を選択し、まず main フォルダを追加する。続いて同じ操作で feature-doc フォルダを追加する。
ワークスペースの永続化: 「File > Save Workspace As...」を実行し、親ディレクトリ（ProjectA_Workspace）の直下に doc-env.code-workspace などの任意の名前で設定ファイルを保存する。

次回以降はこの .code-workspace ファイルを開くのみで、左側のエクスプローラーに「現在の正解（main）」と「編集中の案（feature-doc）」だけが並列に配置された専用環境が即座に復元されます。

5. 定常運用：AIと一緒に書き、視覚的に比較する

環境さえ作ってしまえば、日々の運用は非常にシンプルです。AIを「ペアプログラミングの相棒」のように扱い、人間が白紙から悩む時間をなくし、人間関係の摩擦を減らすフローを回します。

AIとのペアライティング（白紙からの脱却）: 箇条書きのメモやざっくりした要件をAntigravityのAgentに渡し、Markdownの構造化されたドラフトを作らせる。人間は「ゼロから書く」苦痛から解放され、「生成されたものを編集・評価する」上位の作業に集中できる。
差分の可視化（どこが変わったか一目でわかる）: エディタの標準機能を使い、main のファイルと feature-doc のファイルを同時選択した状態で右クリックして「Compare Selected（選択項目の比較）」を実行する。
一次レビューアとしてのAI（気を遣わないレビュー）: 表記揺れや些細な文脈のズレなど、人間同士だと「細かすぎて指摘しづらい」部分を、AIに一次チェックさせる。人間関係の配慮というノイズをシステムで排除し、純粋な内容のブラッシュアップに集中できる。

6. 資産化：レビューを「流れるチャット」から「残る資産」へ

Googleドキュメントのコメント機能で行っていた議論は、GitHubのPull Request（PR）とインラインコメントに置き換えます。これにより、ドキュメントがどう育ってきたかの文脈を、すべて組織の資産として残すことができます。

議論の文脈を永続化する: 議論を「解決して消えるチャット」ではなく、コードの変更履歴と紐づいた状態（PR）で残す。AIの提案をなぜ採用したのかという根拠も含めて永続化できる。
すべてをエディタ内で完結させる: 「GitHub Pull Requests」拡張機能を使い、ブラウザを開かずにAntigravity内でレビューと修正を終わらせる。これにより作業のコンテキストスイッチを防ぐ。

7. まとめ

本アーキテクチャの導入は、手軽さゆえにブラックボックス化しやすいドキュメント管理を、AIの力を借りて「誰もが読み書きしやすく、かつ責任の所在がクリアな状態」へと引き上げます。

執筆スピードの向上: AIがドラフト生成を担い、「白紙」の苦痛を排除する。
認知負荷の低減: git worktree により、ブランチの切り替え作業という無駄なオーバーヘッドをなくす。
心理的安全性の確保: AIをクッションに挟むことで、人間同士の些細な指摘による摩擦を回避する。

初期構築のひと手間はかかりますが、長期的には「チームの合意形成のスピード」と「ドキュメントの信頼性」を両立させる、極めて合理的な選択肢となります。