はじめに

最近、会社でも「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に投下しようと思います！