Claude CodeでAIが知識を自律更新する仕組みと誤操作を防ぐGit管理術

AIは毎回ゼロから始まる。それを終わらせる設計の話

セッションが切れるたびに、AIは何も知らない状態で戻ってくる。

昨日3時間かけて直したバグの原因も、なぜその設計にしたかも、まだ解決していない課題の一覧も消える。

これを解決しようとする設計がある。LLM Wikiというパターンと、Claude Code HooksとGit管理を組み合わせた設計だ。

71.5倍のトークン削減。2ヶ月の運用で浮かんだ知識腐敗の問題。800時間以上の自律運用データ。AIに自律性を与えながら、事故を防ぐ設計思想の話だ。

Claude Codeを毎日使っている身として、この設計を解説する。

LLM Wiki、Hooks、Gitの三位一体で何が変わるのか

LLM Wikiとは何か

LLM Wikiは、LLMが司書として機能し、自分の知識を構造化し続けるMarkdownデータベースだ。

従来のRAGとの違いはここにある。

• RAG: クエリのたびにゼロから検索・合成する
• LLM Wiki: 一度コンパイルして蓄積し、クエリするたびに成長するステートフルなシステム

約100記事を超えるとRAGよりコンパイル済みアプローチが優位になる。トークン削減は71.5倍だ。

構造は2層 + 入力パイプライン

システムの核心は2つの層で構成される。

1. KBL（Knowledge Base Layer）— 動的層

LLMが自動生成・保守する層だ。ソースを取り込むたびに成長する。概念ページ・エンティティページ・ソースサマリーが格納される。

1. Brand Foundation（BF）— 静的層

自分の声・トーン・ポジショニング・禁止表現を定義する。人間が主体的に管理し、LLMはここを読んでアウトプットのスタイルを合わせる。

外側に「raw/」という入力パイプラインがある。生ソースを放り込む場所だ。ここへのLLMの書き込みはHooksでブロックする。

ディレクトリ構成は以下の通りだ。

• llm-wiki/CLAUDE.md — Wikiの設計図
• llm-wiki/raw/ — 生ソース（LLMは読むのみ）
• llm-wiki/wiki/ — KBL（LLMが生成・保守）
• llm-wiki/brand-foundation/ — BF（人間のみ編集）

Hooksで「触ってはいけない場所」を物理的に守る

Claude CodeにはHooksという仕組みがある。ツール実行の前後にbashスクリプトを走らせて、実行をブロックできる機能だ。

「raw/への新規ファイル作成をブロックする」hookを書くと、LLMが誤ってrawに書き込もうとした瞬間に止まる。exit 2を返すと、Claude Codeはツールの実行を中止する。

例外がある。raw/内のファイルに「ingest済みかどうか」のフラグを書き込む必要があるため、新規作成はブロックしつつ、既存ファイルへの追記は許可する設計にする。

しんたろー：
CLAUDE.mdに禁止事項を書き連ねるより、Hooksで物理的にブロックする方が確実だ。CLAUDE.mdが短くなり、毎ターンのトークンも減る。信頼性も上がる。

開発者が本当に設計すべきもの——オントロジーと知識腐敗の話

2ヶ月運用して浮かんだ「知識が腐る」問題

長期記憶を実装しても、2ヶ月動かすと記憶の中身と現実が乖離し始める。

観測された問題は主に2つだ。

問題1: 未解決リストの肥大化

AIエージェントは作業の終わりに「次に調べるべきこと」を未解決リストに登録する。実装が終わっているのに「閉じました」と記録する手順を踏まなければ、リストには残り続ける。

問題2: AIが嘘の知識を書き込む

自由テキストのメモだけでは、「社内略称」「ベンダ正式名称」「バージョン違いの表記」「英語表記」が混在する。AIが社内略称でメモを書いたあと、正式名称で検索すると引けない。

5つの小さな機構で未解決リストの腐敗を防ぐ

これに対して足された機構が5つある。

1. 括弧書きの正規化 — 重複排除キーから「（...）」を除去して、表記ゆれによる二重登録を防ぐ
2. Gitコミットフックによる自動クローズ — コミットメッセージに「resolves:キーワード」を含めると、コミット後フックが走って対応する未解決課題を自動で解決済みに更新する
3. 知識保存時の類似度マッチ — 新しい知識を保存する際、未解決リスト全項目とタイトル類似度を比較して自動クローズ。Jaccard係数という手法を使う
4. 毎朝の状態一覧にヒントを追加 — 自動削除はしない。判断は開発者に委ねて、ヒントとしてsurfaceする
5. Undoツール — 誤った上書きを1行で取り消せる仕組み

特にGitコミットフックの設計が機能する。AIを介さないセーフティネットとして機能するからだ。

オントロジー層という解答

知識腐敗の根本解決としてオントロジー層がある。人間のメンタルモデルを機械に伝えるための層だ。

自由テキストに書かれた情報を「これはこの概念の話」「これとこれは連携関係」と構造化した形でもう1層持つ。

オントロジー層を持つことで、AIが「基幹Aって何？」と聞いたとき、定義・別名・関連概念の一覧が一発で返る状態を作れる。

しんたろー：
AIに何でも任せるのではなく、AIが書き込む知識の構造を設計する発想が核心だ。オントロジー層を明示的に設計するかどうかで、3ヶ月後の知識の質が変わる。

CLAUDE.mdのトークン問題

CLAUDE.mdは全ターンでコンテキストに含まれる。100行のCLAUDE.mdを35行に凝縮すると、キャッシュ読み取り率が89%から95%に改善する。

具体的な改善策は3つだ。

• 禁止リストを許可リストに変える — 7行の禁止事項より、6行の許可リストのほうがトークンが少ない
• Hooksに任せるルールをCLAUDE.mdから外す — 「rm -rf禁止」はHooksで自動ブロックする
• 具体例を1つ添える — 「コミットメッセージは分かりやすく」より「例: "fix: キャッシュ読み取り率が0%になるバグ修正（#42796）"」を添える

プロンプトキャッシュは5分で失効する。キャッシュが効いているときと壊れたときでコストが10〜20倍違う。

今日から使える実務への落とし込み

設計の優先順位をどこに置くか

AIへの指示（CLAUDE.md）とシステム制御（Hooks/Git Hooks）を分離する。

AIへの指示は「何をすべきか」の定義に絞り、「何をしてはいけないか」はHooksで物理的に制御する。

今すぐ確認できること・試せること

CLAUDE.mdの現状チェック:

• 禁止事項が5つ以上並んでいたら、許可リスト形式への書き換えを検討する
• Hooksで制御できる内容がCLAUDE.mdに書かれていないか確認する

知識ベースの構造設計:

• raw/（入力）とwiki/（コンパイル済み）を分離する
• LLMが書き込んでいい場所と、人間だけが書く場所を明確に分ける

Gitとの連携:

• コミットメッセージに「resolves:」キーワードを使う運用を試す
• コミットフックで未解決課題を自動クローズする仕組みを足す
• Undoツールを必ず用意する

モデル選択のコスト意識:

• 日常のファイル編集・テスト実行・git操作はSonnetを使う
• 設計判断やデバッグなど精度が必要な場面だけOpusを使う

Claude Code Routinesについて:

2026年4月にAnthropicが公開した機能で、Claude Codeをスケジュール実行・API呼び出し・GitHubイベントなどをトリガーに、クラウド上で自動実行できる仕組みだ。LLM Wikiのdigest生成やbacklog整理との相性が良い。

しんたろー：
ミスを前提とした取り消しルートを必ず用意する原則は重要だ。Undoツールを最初の実装に入れなかった経験があるため、設計の最初にUndoルートを考える癖をつける。

よくある質問

Q1: AIが勝手に知識を書き換えてしまうのが不安です。どう防げばいいですか？

二段構えが有効だ。

第一段: Claude CodeのHooksで「書き込んでいい場所」を物理的に制限する。raw/への新規ファイル作成をブロックするhookを書けば、AIが誤ってrawに書き込もうとした瞬間に止まる。

第二段: Gitのコミットメッセージに「resolves:キーワード」を使うコミット後フックを仕込む。AIが忘れても、開発者がコミットすれば知識の状態が確定する。

そして必ずUndoツールを用意する。誤った上書きが発生したとき、DB管理画面に直接ログインするしかない状態は運用として成立しない。

Q2: CLAUDE.mdが長すぎてトークンを消費しすぎます。どうすればいいですか？

禁止事項を列挙するのをやめて、許可リスト形式に書き換えることが最初の一手だ。「〜してはいけない」を7つ並べるより、「許可された操作：ファイル読み取り、コミット、npmインストール」と定義する方がトークンを節約できる。

次に、Hooksで制御できるルールをCLAUDE.mdから外す。「rm -rf禁止」といったガードレールはHooksで自動ブロックする方が確実で、プロンプトの肥大化を防げる。

実測では、100行を35行に凝縮したらキャッシュ読み取り率が89%から95%に改善した。CLAUDE.mdの軽量化は直接コスト削減につながる。

Q3: オントロジー層って具体的に何を書けばいいですか？用語集との違いは？

オントロジー層が用語集と違う点は3つだ。

1. 別名・表記ゆれを明示的に紐づける — 社内略称・ベンダ正式名称・英語表記を同一エンティティとして定義する
2. 関係性を構造化する — 業務ドメインの関係性を、AIが毎回推論しなくていい形で明示する
3. 出処と確信度を必須化する — AIが書き込んだ知識に「どこから来た情報か」「どれくらい確かか」を付与する

最初は小さく始めていい。自分のプロジェクトで「毎回AIに説明し直してること」を3つ書き出して、それをオントロジー層の最初のエントリにする。

AIを「ただのチャット相手」から卒業させる設計の話だった

LLM Wikiで知識を蓄積し、Hooksで書き込み先を物理的に制限し、Gitコミットフックで人間が確定操作を行う。この三位一体で、AIはプロジェクトの文脈を理解した共同開発者に変わる。

71.5倍のトークン削減。キャッシュ読み取り率89%→95%。800時間の自律運用。数字は出ている。あとは自分のプロジェクトで試すかどうかだけだ。

SNS運用の文脈管理をAIに任せたい人は、ThreadPostも使ってみてほしい。AIエージェントとの組み合わせで、投稿の一貫性を保ちながら自動化できる。

👉 ThreadPostでSNS運用を自動化する