AI AgentのコンテキストファイルをGitの作業ブランチから分離して管理する

こんにちは
AI Agentと一緒に開発していると、どんどん生まれるコンテキストファイルたちをどう管理するかというところに悩んでしまいますよね。

具体的には以下のような困りごとがあります。

• AIのコーディングエージェントのコンテキストが育ってきたら吐き出してAIの思考を整理したいためある程度の間隔で更新がある。
• AIの作るファイルなので決定的ではなく各開発者のローカルで差異が必ず生じる
• コードをマージする際にコンフリクトが生じやすい
• レビューの時に邪魔
• とはいえ.gitignoreで無視してローカルだけに保持するのではなくバックアップも兼ねてリモートで管理したい

そんな時に出会ったのがai-docsです。というか正確にいうと作ったのがこれです。
https://github.com/trknhr/ai-docs

そもそも何が問題だったのか？

ChatGPTやClaudeなどのAIと一緒に作業していると、プロンプト用のメモリファイルやコンテキスト用の構成ファイルがどんどん増えていきます。
そのままmainブランチに入れていく運用も悪くないんですが、コミットのタイミングも悩みますし何より前述の通り複数開発者との相性が劇的に悪い。

ということで、AI用ファイルは別ブランチ＋worktreeで管理しようと思い立ったのが2日前。なんとなく会社のミーティング中に呟いたら作ってみればと言われ、AI時代らしくサクッと実装しましたのでコードの中身はヤバいです。がまぁ動いたのでよしとします。

どう実装したか

ChatGPTに雑に相談しつつ理想の形を考えました。話してるだけだとちょっと完成形が掴めなかったのでローカルでworktreeを試したりしてこれならそこそこ使えるんじゃないかという確信を得られるまで色々と話しました。

• 話した結果を一枚の仕様ファイルにまとめて、Claude Codeでざっくり実装してもらう
• ローカルで実際に使ってみて本当に思った通りの挙動かを確認する
• 想定と違う挙動は実装を見つつClaudeCodeに直させたり、面倒なときは自分で直したり

ai-docsは何をしてくれるか

ai-docsは、AIアシスタントが生成する「コンテキストファイル群」を、Gitの専用ブランチに分離・管理できるCLIツールです。
以下が特徴です

• @ai-docs/usernameという孤立ブランチを作成
• そのブランチを.ai-docs/以下にworktreeとしてマウント
• memory-bank/ や CLAUDE.mdは孤立ブランチにて管理
• mainブランチでは.gitignoreを自動更新しメインブランチではトラックしないようにする
• remoteやlocalで該当ファイルに更新があった場合はpull / pushコマンドで雑な同期ができる

苦労したポイント

1. ClaudeCodeがカジュアルに rm -rfを書いてくる

最初のバージョンでは rm -rf を多用していたため.gitディレクトリそのものが壊れて大変なことになりました。軽く試したリポジトリがもうすでにpush済みだったので助かりましたが、実行前にAIの書いたコードはちゃんと確認しないとダメだなぁと反省しました。
最終的にはremoveするのは--forceのオプションをつけたときだけで基本的にはgitのコマンドそのものを使うようにしています。

2. GitHub Actionsに何度もハマった

自動リリースのためにGoReleaserとGitHub Actionsを組み合わせたのですが、毎回設定ミスで失敗。AIに聞いてもなんか焦点が定まらずであまり効率よく進められませんでした。またgoreleaserのバージョンがここ最近変わっていたりしてAIによるブーストが弱く結局ドキュメントを読む必要がありました。
全体的にここの知見はもっと貯めてもっと高速にリリースできる勘所を得ないとと感じます

使い方

私のメインPCがmacなこともあり、なのでmacでの使用を想定しています

brew tap trknhr/homebrew-tap
brew install ai-docs

# 初期化(設定ファイルの生成されてない場合は2回initする必要があります)
ai-docs init -v

# AIファイルの変更をpush
ai-docs push -v

# リモートの変更をpull
ai-docs pull -v

--dry-run や --forceなども対応していて、動作確認にも便利です。
設定ファイルも初期化時に自動生成されます。

まとめ

ai-docsのポイントは以下の3つです：

• 作業ブランチを汚さない：AI用ファイルは別ブランチに隔離
• Git worktreeですぐアクセス：.ai-docs/経由で常に見れる
• 同期がラク：pull/push で現在の変更もリモート変更も反映

まだまだ荒削りですが十分実用には耐える仕上がりになったと思っています。
AIと共存する開発に迷っている人、ぜひ使ってみてください！

GitHub - trknhr/ai-docs

もしこの記事が参考になったら、XやGitHubで感想もらえると嬉しいです。ではまた！