はじめに
最近、会社でも「AIバンバン使っていこうぜ！」という空気になり、Claude Codeを相棒にコーディングする時間がめちゃくちゃ増えました。
最初は「おー、勝手にコード書いてくれる！すげー！」と単純に感動していたんですが、実プロジェクトで使い倒していくうちにある悩みが……。
そう、「 AI、毎回記憶リセットされすぎ問題 」です。
AIは賢い。でも毎回「初めまして」になる
新しい機能（Feature）を作ってもらうとき、だいたいこんなやり取りになります。
「要件はこれで」
「プロジェクト構成はこうなってて」
「命名規則はこうで」
「ここはService層に書いてね」
「レビューはgit diffベースで」
「あ、spec.mdとreview.mdも更新してね」
「最後にテストもよろしく！」
……これ、毎回言ってるんです。
AIは超優秀なんですが、悲しいかな、新しいタスクのたびに毎回が「初めまして」状態。「それ前も言ったじゃん！」と（心の中で）ツッコミを入れること数知れず。
だったら、僕の開発スタイルやプロジェクトのオキテを「最初からインストールしておけばいいのでは？」と思い立ちました。
CLAUDE.mdを書けば解決する？
最初は「じゃあルートディレクトリに CLAUDE.md を置いて、そこに全部書けば解決っしょ！」と思ってました。
でも、甘かった。実際に運用してみると CLAUDE.md だけでは厳しい現実に直面します。プロジェクトが育つにつれて、
- アーキテクチャの思想
- ドメイン知識
- 過去の設計の試行錯誤（ADR）
- 暗黙のルール
これらを全部一つのファイルにぶち込むとどうなるか？
「誰も（AIすら）読みたくない、超巨大なCLAUDE.md」が爆誕します。
結果、トークンを無駄に消費するだけで精度も落ちてしまいました。
CLAUDE.mdは「ルーター」にすればいい
そこで発想を転換しました。CLAUDE.md は知識を詰め込む辞書じゃなくて、 「受付の案内係（ルーター）」 でいいじゃん、と。
中身は極力シンプルに、これだけ。
Read relevant files under .ai/.
Project-specific rules override global standards.
Follow the project's workflow.
あとは必要に応じて、AIに勝手に .ai/ ディレクトリの中を漁ってもらうスタイルです。
AIに読ませる知識は分離する
最終的に、こんな感じのディレクトリ構成に落ち着きました。
.ai/
context/
architecture.md
domain.md
glossary.md
constraints.md
project-memory.md
workflows/
development.md
testing.md
review.md
templates/
spec.md
plan.md
review.md
decisions/
ここでの気付きは、 「人間向けのREADMEを書くのではなく、AIにプロジェクトの教科書を渡す感覚」 が大事だということです。
一番のブレイクスルーは「plan.md」だった
いろいろ試行錯誤して、一番効果がデカかったのは仕様書（spec）でもレビュー基準でもなく、plan.md でした。
作業を始めるときに、AIに以下のようなTODOリストを作らせます。
- [ ] API追加
- [ ] Service実装
- [ ] Test追加
- [ ] Documentation更新
そして、AIには作業が終わるたびに [x] と更新してもらいます。最初はただのTODOリストのつもりだったんですが、違いました。
これ、 「AIのステート（状態）管理」 としてめちゃくちゃ優秀なんです。
もし途中でトークン制限がきたりコンテキストがぶっ飛んだりしても、新しいセッションで「plan.md を読んで続きからよろしく！」と言えば完全復活します。RPGのセーブポイントみたいで超便利です。
Git diffを真実（Source of Truth）にする
もう一つ運用ルールとして決めたのが、 「ドキュメント更新のソースは Git diff にする」 ということ。
AIって、チャットの履歴をベースにドキュメントを書かせると、たまに幻覚（ハルシネーション）を見たり、大事な修正を忘れたりします。でも、実際に変更されたコード（Git diff）は嘘をつきません。
「チャット履歴じゃなくて、diffを見て spec.md や CHANGELOG.md を更新してね」と教え込むことで、更新の精度と信頼性が爆上がりしました。
AIにもオンボーディングが必要
開発チームに新しい人が入ってきたら、まずはオンボーディングしてドメイン知識を共有しますよね。AIも全く同じだなと思うようになりました。
だから context/ には、ドメイン知識やアーキテクチャの制約を置きます。さらに project-memory.md には、開発中に起きた「やらかし」や「学び」を蓄積していく運用にしています。
例えば、
Lesson:
ORCAへは直接アクセスしないこと。
必ず PersonalDataMatchingService を経由して処理すること。
みたいな泥臭いナレッジです。こういうのが溜まっていくと、半年後の自分（とAI）がめちゃくちゃ助かるはず。
グローバルな知識とプロジェクト知識を分ける
さらに欲を出して、設定を2つのレイヤーに分けました。
プロジェクトに依存しない「自分の開発スタイル（ワークフロー、テスト手法、レビュー基準）」は ~/.claude/ のようなグローバルな場所へ。
プロジェクト固有のドメイン知識はリポジトリ内の .ai/ へ。
この分離のおかげで、バックエンドだろうがフロントエンドだろうが、どんなフレームワークでも「いつもの俺の開発フロー」をAIに一発で再現させることができるようになりました。
最初から完成させない（ここ一番大事）
いろいろ書きましたが、一番強調したいのは 「最初から完璧なフレームワークを作ろうとしない」 ということです。
最初は気合を入れて全ファイルを用意しようとしてたんですが、途中でやめました。
まずは workflow.md だけ作って実戦投入する。困ったら testing.md を足す。また壁にぶつかったら review.md を足す……というアプローチに切り替えました。
「完成させてから使う」のではなく、「AIと一緒に開発しながら、必要になったものを育てていく」。これが一番自然だし、挫折しないコツだと思います。
最終的に目指したいもの
最終的な野望は、特定のAIに依存しない 「AI Development Framework」 を作ることです。
ai-dev-framework/
global/
project/
scripts/
こんな構成をGitで管理して、新しいプロジェクトを立ち上げるときに ./init-project.sh を叩くだけで準備完了。
Claudeでも、Cursorでも、GPTでも、他のローカルLLMでも、すぐに「いつもの相棒」として同じ開発フローで動ける土台。そんなのが作れたら最高に面白いなと企んでいます。
おわりに
まだ構想を練って走り出したばかりですが、単に「AIを便利ツールとして使う」フェーズから、「AIというチームメイトが働きやすい環境（OS）を構築する」フェーズに入ってきているのを肌で感じています。
しばらくはこのスタイルで実運用を回して、面白い知見（やらかし含む）が溜まったら、またQiitaに投下しようと思います！