きっかけ:エージェントは毎回"初対面"から始まる
Claude Code を毎日使っていて、ずっと引っかかっていたことがあります。
セッションを開くたびに、エージェントは「初対面」のの状態から始まるんですよね。
昨日あれだけ一緒にコードを書いたのに、今朝また ls して、同じファイルを頭から読み直している。「このプロジェクトは何で、どういう規約で、どこを触ると何が壊れるか」を、毎回ゼロから組み立て直しているわけです。人間の新しいメンバーなら一度説明すれば覚えることを、エージェントはセッションごとに忘れ、一度学んだはずの地雷をまた踏みにいく。
そこで、プロジェクト直下に agent/ という「外部脳」を置く運用を始めました。エージェントにプロジェクトを正しく理解させ続けるための、記憶と状態の置き場です。
この記事の提案はシンプルです。AIと開発するなら、プロジェクトの記憶を管理する agent/ フォルダを置きましょう。 導入はスキル1個で済み、副次効果として、今回測定した理解系タスクではトークンが約30%減ることも確認できました。
この方法はこんな人向けです
- ✅ Claude Code / Codex / Cursor を毎日使う
- ✅ ある程度の規模のリポジトリを触っている
- ✅ 同じプロジェクトを何週間も育てている
- ✅ セッションをまたいで作業することが多い
逆に、使い捨てのスクリプトや一晩で終わるプロジェクトなら、たぶん要りません。
agent/ フォルダの中身
外部脳といっても、正体はただの Markdown 群です。用途ごとにファイルを分けてあります。
agent/
├── agent.md ← ルーター:「この質問はどこを見ればいいか」の索引
├── architecture.md ← 全体アーキテクチャ(データの流れ・レイヤー構成)
├── conventions.md ← 命名規則・ファイル配置・スタイルの決まり
├── data.md ← データモデル / スキーマ
├── api.md ← API・エンドポイント定義
├── state.md ← いま何がどこまで動いているか(セッション間の申し送り)
├── decisions.md ← 「なぜこう決めたか」の追記専用ADR
├── errors.md ← 踏んだ地雷と、プロジェクト固有の不変条件(invariants)
├── components.md ← UIコンポーネントの一覧と責務
└── graph/ ← 依存関係グラフ(「Aを触るとBが壊れる」の即答用)
全部を一度に読ませるわけではありません。中心にあるのは agent.md というルーターで、これだけがセッション開始時に必ず読まれます。
「全部読む」のではなく「必要なところへ最短で飛ぶ」ための地図、というわけです。
どう動くのか
ポイントは最後の一段です。次のセッションへの申し送りノートを、AIが自分で書く。人間は基本的に何もしません。Claude Code でも Codex でも、同じ外部脳に合流できます。
AGENTS.md と何が違うの?
経験者ほど「それ、AGENTS.md(CLAUDE.md)で良くない?」と思うはずです。役割が違います。
| AGENTS.md / CLAUDE.md | agent/ フォルダ | |
|---|---|---|
| 正体 | プロンプト(指示書) | 記憶(ナレッジベース) |
| 更新 | 人間が時々書き換える | AIが作業のたびに書き戻す |
| 中身 | 振る舞いのルール | プロジェクトの知識・状態・決定 |
| サイズ | 小さく一枚 | 構造化された複数ファイル |
AGENTS.md は「どう振る舞うか」を指示する静的な一枚。agent/ は「このプロジェクトについて何を知っているか」が育っていく動的な置き場です。この記事の構成では、AGENTS.md は agent/ への入口として使っています。
記憶が効いた実例:errors.md
なかでも効くのが errors.md です。コードを読むだけでは推測に頼るしかない、プロジェクト固有のルールを明文化しておきます。
# errors.md(抜粋)
■ 科目の識別子は id または code のどちらか一方が一致すればOK
両方一致(&&)を要求すると、履修一覧が常に空になる(過去に1度やらかした)
■ 日付・時限は必ず data.ts を正とする
API 側の値は欠落しうるため、そちらを信用しない
コードに複数のバグを仕込んで修正させる検証をしたとき、agent/ ありのセッションはこの不変条件を根拠にしてバグを診断しました。「識別子は id または code のはずなのに、ここだけ && になっている」という具合です。結果として、こちらが仕込んでいない既存の不整合まで見つけてきました。
規約を毎回コードから推測し直すのではなく、プロジェクトの記憶を参照して推論する。これが外部脳の本命です。トークンの話は、このあとの「うれしい副次効果」にすぎません。
副次効果:今回の実験では、トークンも約30%減少した
「毎回ドキュメントを読み込むぶん、トークンの無駄では?」という質問をよく受けます。もっともな指摘なので、実測しました。
- 同じ実プロジェクト(TokaiHub という React アプリ)のクローンを2つ用意
- 片方だけに
agent/を入れる(① BARE = なし / ② SKILL = あり) - まったく同じプロンプトを、それぞれ新規セッションに投げる
タスクは「まず構成を説明して。次に『お知らせ(News)』タブを新規コンポーネントとして追加し、既存ナビに組み込んで」。エージェントがまずプロジェクトを"理解"しないと始まらない、典型的なオンボーディング + 機能追加です。数値は各セッションの stream-json トランスクリプトから拾った実測値です。
| 指標 | ① BARE | ② SKILL(agent/ あり) |
|---|---|---|
| コスト | $1.44 | $1.11(−23%) |
| 出力トークン | 14,852 | 10,328(−30%) |
| APIターン数 | 31 | 28 |
| 読み込んだ文脈量(cache-read) | 2.19M | 1.52M(−30%) |
| 「お知らせ」画面の完成 | ✅ | ✅ |
できあがった画面は両方とも同等でした(EN/JP バイリンガル、ダークモード対応、ナビ配線込み)。成果物が同じなのに、今回測定した理解系タスクでは 出力トークンが約30%・コストが約23% 少なくなりました。
理由ははっきりしています。素のセッションは、プロジェクトを理解するために大量のファイルを読み、探索を広げます。この「毎回の再オリエンテーション」がトークンの大きな塊で、agent/ はそこを外部脳が肩代わりする。出力トークンが減っているのは、探索の途中経過や自己説明として吐き出すテキストが減ったためです。
ひとつ正直に添えておくと、この削減が効くのは「まずプロジェクトを理解してから何かする」タイプのタスクです。再オリエンテーションがほぼ要らないピンポイントな局所修正では、外部脳を読むぶんが上乗せになり、差が縮まったり逆転したりします。外部脳は「トークン削減術」としてではなく、記憶のインフラとして入れて、理解系タスクでは節約も付いてくる、と捉えるのが実態に合っています。
導入方法
この仕組みは agent-brain というスキルとして公開しています。入れたら、あとは普通に作業を始めるだけ。agent/ がなければエージェントが勝手に作り、勝手に育て、たまに勝手にドキュメントの間違いも直します。
Claude Code:
/plugin marketplace add MohamedFuad16/agent-brain
/plugin install agent-brain@agent-brain
OpenAI Codex:
codex plugin marketplace add MohamedFuad16/agent-brain
codex plugin add agent-brain@agent-brain
GitHub から直接(どのツールでも):
git clone --depth 1 https://github.com/MohamedFuad16/agent-brain /tmp/agent-brain
cp -R /tmp/agent-brain/plugins/agent-brain/skills/agent-brain ~/.claude/skills/agent-brain # Claude Code
cp -R /tmp/agent-brain/plugins/agent-brain/skills/agent-brain ~/.codex/skills/agent-brain # Codex
手で始めるなら、まずは agent.md(ルーター)・architecture.md・conventions.md・errors.md の4枚だけで十分です。あとは作業のたびに state.md と decisions.md が育っていきます。
おわりに
リポジトリはこちらです:https://github.com/MohamedFuad16/agent-brain
「うちのプロジェクトで測ったらこうだった」という報告は、素直に泣いて喜びます。大規模リポジトリでの続編も準備しているので、興味のある方はフォローしておいてください。
最後にひとつだけ。
AI はセッションを忘れます。
でも、プロジェクトが忘れる必要はありません。
agent/ フォルダは、その記憶をプロジェクト側に置くという、単純だけれど効果的な方法です。
最後まで読んでいただき、ありがとうございました🙏