Claude Code のドキュメントを .git/info/exclude で公開せず運用する — 除外設定と履歴管理の設計記録
個人で開発・運用している OSS リポジトリに Claude Code を導入した際、AI 用の設定やドキュメントを公開リポジトリに残さず、ローカルだけで運用したいという要件が出てきました。この記事では、そのうち特に検討に時間を割いた除外設定のユースケースと、AI 運用で分散しがちな履歴管理の設計の 2 点に絞って記録します。
対象は一人開発（個人 OSS）のリポジトリで、main / develop に PR・CI 必須のブランチ保護が設定済みの状態です。Claude Code はエディタ上から利用しており、主なタスクはリファクタリング・記事執筆・機能改善といった、反復的でローカル完結の作業が中心です。
1. 除外設定とそのユースケースの検討
LLM を前提とした現代のソフトウェア開発では、システム仕様書と、LLM が実装時に参照する仕様・コンテキストを分離して管理すべきか、という議論が活発になっています。システム仕様書は「何を作るか（要件・設計・振る舞い）」を定義する唯一の正（Single Source of Truth）とし、一方で LLM 向けの仕様は「どのように解釈・実装するか（実装ルール・制約・命名規則・禁止事項など）」を整理する補助的なコンテキストとして扱う、という考え方です。現時点で業界標準には至っていませんが、AI エージェントを活用する開発現場では、人間向けと LLM 向けで役割を分離したドキュメント設計が有望なアプローチとして注目されています。
この分離を踏まえると、CLAUDE.md のような LLM 向けの補助コンテキストは、システムの正本であるリポジトリに必ずしも同居させる必要はありません。個人開発では、これをローカルに置きつつ公開リポジトリには残さない、という選択が自然でした。問題は、その「残さない」をどの仕組みで実現するかです。
Git には無視の仕組みが複数あり、適用範囲がそれぞれ異なります。
.gitignoreはリポジトリ全体に効き、コミットされて全員に共有されます。ビルド成果物や依存など、誰にとっても無視すべきものを書く場所です。.git/info/excludeはこのクローンだけに効き、コミットされません。自分だけが無視したい、あるいは公開したくないファイルに使います。core.excludesFile（グローバル設定）はマシン上のすべてのリポジトリに効きます。.DS_Storeやエディタ設定など、OS・環境固有のファイル向けです。git update-index --skip-worktreeは、すでに追跡されているファイルのローカル変更を無視したいときに使います（未追跡ファイルには使えません）。
今回の要件を「無視したい」「公開したくない」「このリポジトリ固有（グローバルには広げたくない）」「対象はまだ追跡していない未追跡ファイル」の 4 つに分解すると、これらを同時に満たすのは .git/info/exclude だけでした。.gitignore は公開されてしまう点で、core.excludesFile は全リポジトリに広がる点で、skip-worktree は未追跡ファイルに使えない点で、それぞれ外れます。
補足すると、.gitignore に CLAUDE.md や .claude/ を書く案もありますが、その除外設定自体が公開リポジトリに残り、「このリポジトリは AI ツールを使っている」という痕跡になります。無視の設定そのものを公開したくない、という点が今回の判断の分かれ目でした。
.git/info/exclude は、.gitignore と同じ書式でありながら、.git/ の内部にあるためコミット・プッシュされない、ローカル限定の除外設定です。主要な AI ツールの規約ファイルをまとめて対象にしました。
# --- AI tooling (local only, never committed) ---
CLAUDE.md
CLAUDE.local.md
.claude/
AGENTS.md
GEMINI.md
COPILOT.md
.cursor/
.github/copilot-instructions.md
これにより、上記ファイルは未追跡かつ無視対象となり、git add . を実行しても誤ってステージされることがなくなります。混入を Git のレイヤーで防げるのが、この方式の利点です。
一方で、.git/info/exclude は .git/ 内部の設定のため、リポジトリのクローンには含まれません。別マシンで作業する場合や再クローンした場合は、この設定を手動で再設置する必要があります。公開されないことの裏返しとして受け入れるべきトレードオフです。
2. 履歴管理の設計
AI を使った開発では、何を変えたか、どんな会話をしたか、AI が何を学習したか、なぜそう決めたか、といった履歴が、Git・セッションログ・メモリ・手元のメモへと分散しがちです。これを 4 層に分け、それぞれを既存の仕組みへ割り当てることで、新規に作るものを最小化しました。
A 層はコード・コンテンツの変更です。何を変えたかの唯一の正本であり、Git のコミット履歴がそのまま実体になります。Conventional Commits（feat: fix: docs: など）で粒度と意図を揃え、後から追いやすくしています。これだけが公開される履歴です。
B 層は会話の継続性です。Claude Code のネイティブなセッション機能（--resume / --continue / /export など）に任せます。セッションログは ~/.claude/projects/<proj>/ 配下にローカル保存され、既定で一定期間保持されます。保持期間は設定で延長でき、起動時にトピック名を付けておくと後から見つけやすくなります。
C 層は学習・嗜好です。こちらも Claude Code のネイティブな auto memory に委ねます。好みや繰り返し出てくる規約は AI が自動で記録・参照するため、明示的に管理する必要はなく、内容を監査できれば十分です。
D 層は決定・作業の軌跡です。既存の仕組みで拾いきれないのはここだけなので、手動でキュレーションします。とはいえ大掛かりにはせず、設計判断の経緯（ADR）は設計仕様書内の「設計決定の経緯」章にまとめ、日々の作業は append-only のログファイルにセッションごと 1 エントリだけ追記する、という 2 点に留めました。作業ログの粒度は「作業 / 検証 / 次回」の 3 項目です。
## YYYY-MM-DD <session-name>
- 作業: 何をしたか（対象・スコープ）
- 検証: typecheck / build / git status 等
- 次回: フォローアップ（無ければ「なし」）
4 層のうち A から C は既存の仕組みがそのまま使えるため、新規に用意したのは D の作業ログ 1 ファイルだけです。AI 運用の履歴管理は、新しい仕組みを増やすより、既にあるレイヤーへ役割を割り当てるほうが破綻しにくい、というのが今回の結論でした。なお、D 層のファイル群も除外設定の対象に含めており、Git には追跡されずクローンにも伝播しないため、長期保全が必要なら別途バックアップを検討します。
まとめ
除外設定については、「無視する／公開しない／このリポジトリ固有／未追跡」という 4 条件を同時に満たすのは .git/info/exclude だけであり、.gitignore やグローバル設定とは役割が異なる、という整理に至りました。システム仕様と LLM 向け仕様を分離する近年の潮流とも、無理なく噛み合う選択だったと思います。
履歴管理については、履歴を 4 層に分け、A から C は Claude Code や Git のネイティブ機能へ割り当て、新規に用意するのは D 層の作業ログ 1 点のみに絞りました。新しい仕組みを増やすより既存レイヤーへ割り当てることで、個人開発に見合った最小構成に落とし込めたと考えています。
参考｜情報ソース
本記事の設計は、以下のドキュメント・記事の考え方やフォーマットを参考にしています。
- gitignore - Git Documentation —
.gitignoreの書式に加え、$GIT_DIR/info/excludeやcore.excludesFileといった無視の仕組みの優先順位が整理された公式リファレンス。 - Pro Git - ファイルの無視 — 無視設定の使い分け（共有 / ローカル / グローバル）を実例とともに解説した公式書籍の該当章。
- Claude Code settings —
CLAUDE.md・.claude/の配置やセッション・メモリなど、ローカル運用の前提となる公式設定ドキュメント。 - Conventional Commits — A 層で採用したコミットメッセージ規約の仕様。
- Architecture Decision Records（adr.github.io） — D 層で参考にした、設計判断を軽量に記録する ADR の考え方とテンプレート集。