ほとんどの AI エージェントが失敗するのは、モデルが悪いからではありません。
セッションのたびに記憶喪失の状態で起動するからです。
Claude に「pnpm を使って、npm は使わないよ」と伝える。
次のセッション：また npm を使おうとする。
「ここでは default export は使わないで」と伝える。
次のセッション：default export を書く。
あなたが行った修正はすべて、セッションが終了した瞬間に消えてしまいます。
これを解決する方法は、たった 1 つのファイルにあります。
この方法を見つけるまで、同じことを繰り返し言い続けて 3 ヶ月かかりました。
ここで学んだすべてを紹介します。
ほとんどの AI エージェントが失敗する理由
原因はモデルではありません。
モデルの下にある、欠けているレイヤーです。
→ プロンプトを書く
→ エージェントがタスクを実行
→ セッション終了
→ メモリが消える
→ 次のセッション：同じミス
→ 同じ指示を繰り返す
→ 永遠に
このループこそが、AI コーディングにおける時間の最大の浪費源です。
悪いコードのせいでも、ハルシネーションのせいでもありません。
繰り返しのせいです。
欠けているレイヤー：メモリ
誰もがどのモデルが最も賢いかに夢中になっています。
レイヤーを間違えています。
本当のアップグレードは、より賢いモデルではありません。
モデルが学習したことを保存する場所を与えることです。
→ プロンプト → エージェントに今何をすべきかを指示する
→ エージェント → タスクを実行する
→ メモリ → セッション間でコンテキストを永続化する
→ 永続的なコンテキスト → 繰り返しの修正が不要になる
→ 学習システム → エージェントは実際に時間とともに改善される
これが、ツールとチームメイトの違いです。
ツールは、あなたの指示を毎回ゼロから実行します。
チームメイトは昨日のことを覚えています。
すべての AI エージェントに必要な 5 つのメモリファイル
メモリが欠けているレイヤーだと納得できたら、次はそれがどこにあるのかという問題です。
5 つのファイル。それぞれに異なる役割があります。
→ CLAUDE.md — Claude 専用のブリーフィングドキュメント
→ AGENTS.md — ユニバーサルスタンダード。主要なツールはすべてこれを読み込みます
→ CLAUDE.local.md — あなた個人の設定。git にはコミットしません
→ MEMORY.md — AI が自身について自動的に書き留めるメモ
→ README.md — 人間のため。エージェントのためではありません
それぞれを見ていきましょう。
CLAUDE.md — すべての始まりとなったファイル
プロジェクトのルートに置いてください。
Claude はすべてのセッションの開始時にこれを読み込みます。
記憶喪失の新メンバーへのブリーフィングドキュメントだと思ってください。
優れた CLAUDE.md には 4 つのセクションがあります：
→ プロジェクトのコンテキスト — 1 行。「Next.js、Stripe、Postgres を使った E コマースアプリ」
→ コードスタイル — 「コードを適切にフォーマットする」ではなく「ES モジュール、名前付きエクスポート、2 スペースインデントを使用する」
→ コマンド — 正確な文字列。pnpm test:integration。「テストを実行する」ではありません。
→ アーキテクチャ — 「API ルートは /src/api/[resource]/route.ts に配置。DB アクセスにはリポジトリパターンを使用」
1# CLAUDE.md23## プロジェクトのコンテキスト4Next.js 14 の E コマースアプリ。Postgres + Stripe 統合。56## コードスタイル7- ES モジュールのみ8- 名前付きエクスポート、default エクスポートは禁止9- 2 スペースインデント10- TypeScript strict モード1112## コマンド13- インストール: pnpm install14- 開発: pnpm dev15- テスト: pnpm test:integration16- Lint: pnpm lint:fix1718## アーキテクチャ19- API ルート: /src/api/[resource]/route.ts20- DB アクセス: リポジトリパターンのみ21- コンポーネント: /src/components、1 ファイル 1 コンポーネント
目標は 300 行未満です。
すべての行が実際の作業と注意力を競い合います。
/init を実行すると、Claude が自動的にスターターファイルを生成します。
その後、大半を削除してください。
デフォルトのファイルには、Claude が package.json からすでに知っていることも含まれています。このファイルがないと Claude が間違えてしまうことだけを残してください。
[@imports](https://x.com/@imports) システム — 簡潔に保つ
CLAUDE.md にすべてを詰め込む必要はありません。
他のファイルをインポートできます：
参照
プロジェクト概要については @README.md を参照 次に参照
API 規則については @docs/api-patterns.md を参照 次に参照
利用可能な npm スクリプトについては @package.json を参照
インポートは再帰的に行えます — 最大 5 階層まで。
これで「1 つの巨大なファイル」問題を解決できます。
チームの場合：フロントエンドチームは docs/frontend-rules.md を管理します。
セキュリティチームは docs/security.md を管理します。
CLAUDE.md はそれらをすべてインポートするだけです。
1 つのルートファイル。多数の専門特化したソース。
AGENTS.md — ユニバーサルスタンダード
CLAUDE.md は Claude にしか効きません。
チームで Cursor、Copilot、Gemini CLI も使っている場合 — それらは CLAUDE.md を読み込みません。
AGENTS.md がこれを解決します。
1 つのファイル。主要なエージェントはすべてこれを読み込みます。
Claude Code、Cursor、GitHub Copilot、Gemini CLI、Windsurf、Aider、Zed、Warp などでサポートされています。
標準の Markdown です。特別なスキーマは必要なく、YAML も不要です。
1# AGENTS.md23## プロジェクト概要4Next.js 14、Postgres、Stripe で構築された E コマースプラットフォーム。56## ビルド & テスト7- インストール: pnpm install8- 開発: pnpm dev9- テスト: pnpm test10- Lint: pnpm lint:fix1112## コード標準13- TypeScript strict モード14- default エクスポートよりも名前付きエクスポート15- API ルートは /src/api/ 内で REST 規則に従う1617## テスト要件18- すべての PR にテストを含めること19- 単体テストは vitest、E2E は playwright
AI エージェント向けの README だと思ってください。
README.md は人間向け、AGENTS.md はベンダーに関わらずすべてのエージェント向けです。CLAUDE.md はその上に Claude 固有の情報を追加します。
補完し合うものであり、競合するものではありません。
自動メモリ — 自身でメモを取る AI
これは最も新しく、最も興味深いレイヤーです。
Claude Code は、セッション中に独自のメモリファイルを書き込むようになりました。
memory/ ├── MEMORY.md ← インデックス。毎セッション読み込まれる ├── debugging.md ← デバッグパターンに関するメモ ├── api-conventions.md ← API 設計の決定事項 └── ...
重要な変化はここです：
CLAUDE.md はあなたが書きます。あなたが指示を提供します。
MEMORY.md は Claude が書きます。学習した内容を記録します。
→ 人間がルールを書く
→ エージェントが作業中にパターンを発見する
→ エージェントが自身のメモを書く
→ 将来のセッションはより賢く始まる
直接トリガーすることもできます。生産的なセッションの終わりに、こう言うだけです：
「今日のコードベースについて学んだことをメモリファイルに更新して。」
学習内容は永続化されます。カスタム ORM ラッパーについて 5 回目の説明をする必要はもうありません。
/memory を実行すると、Claude が保存した内容をいつでも確認・編集できます。
/init してから削除するワークフロー
新しいプロジェクトでメモリファイルを素早くセットアップする最も速い方法：
- プロジェクトディレクトリで /init を実行
- Claude がコードベースに基づいてスターター CLAUDE.md を生成
- 不要なものを削除
ステップ 3 でほとんどの人が間違えます。
生成されたファイルはドラフトであり、完成品ではありません。
しばしば無駄な情報が含まれます。「このプロジェクトは JavaScript を使用しています。」— package.json を見ればわかります。
白紙の状態から書き始めるよりも、適切なドラフトを編集する方が優れています。
セットアップ後は、有機的に構築していきます。
Claude が間違った仮定をしたとき — 例えば、非推奨のパッケージをインポートし続ける場合 — その場で 1 回修正するだけでは不十分です。
こう伝えてください：「CLAUDE.md に追加して：@company/utils ではなく、常に @company/utils-v2 からインポートすること。」
この指示は、将来のすべてのセッションで永続化されます。
数週間おきに、Claude に CLAUDE.md のレビューとクリーンアップを依頼してください。
指示は蓄積されます。冗長になるものもあれば、競合し始めるものもあります。さっと見直すことで、鮮度を保てます。
私の実際のセットアップ
これを複数の本番プロジェクトでテストした結果、以下の構成に落ち着きました：
→ プロジェクトルートの AGENTS.md — どの AI ツールも読み込む共有指示。ビルドコマンド、コード標準、テスト要件。
→ [@imports](https://x.com/@imports) を使った CLAUDE.md — Claude 固有の動作向け。100 行未満に抑え、主に docs/ ファイルを参照。
→ CLAUDE.local.md — 個人のこだわり用。自分のテストデータ、サンドボックス URL、ショートカットコマンド。git にはコミットしない。
→ 自動メモリを有効化。 Claude が自身でメモを取る。月 1 回レビュー。
→ その他はすべて AGENTS.md へのシンボリックリンクに置き換え。 単一の情報源。
1# Symlink setup for multi-tool consistency2ln -sfn AGENTS.md .github/copilot-instructions.md3mkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc
エレガントではありません。
しかし、チーム内のすべてのツール間での指示のずれを排除します。
より大きな変化
ほとんどの開発者はこう考えています：
優れたモデル = 優れたエージェント
違います。
本当の公式は：
モデル + メモリ + 検索 + フィードバック = 役立つエージェント
メモリのない賢いモデルでも、明日にはテストコマンドを忘れています。
優れたメモリを持つ modest なモデルは、毎週着実に賢くなります。
メモリは複利的に効果を発揮する変数です。
モデルの知能はそうではありません。
私が AI ワークフローにもたらした最大の改善は、モデルを切り替えたことではありません。
モデルにメモリを与えたことです。
この違い：
「Claude、pnpm を使ってるよ」 — 毎回のセッション
と、
「Claude はもう知っている」 — 毎回のセッション
は、
ツールとチームメイトの違いです。
この記事が役に立ったなら：
→ リポストして、今も Claude に同じ指示を繰り返している開発者全員と共有しましょう
→ 寝ている間も成長するシステムについてもっと知るには、@sairahul1 をフォローしてください
→ ブックマークしてください。今夜セットアップすれば、明日からは修正する必要がなくなります
私は、AI、プロダクト作り、そしてあなたの代わりに動く仕組みについて書いています。
