agents-project-memory

Claude Code + Codex 向けプロジェクトメモリ（2026年1月）

セッションをまたいで Claude Code と Codex に安定した、適用範囲を限定した指示を与えながら、トークンコストを低く抑えられるようにプロジェクトメモリを設定します。単一の信頼できる情報源を使い、AGENTS.md を主要ファイルとして維持し、CLAUDE.md からそのファイルへのシンボリックリンクを作成します。

クイックリファレンス

メモリの種類	一般的な場所	目的
管理ポリシー	OS によって異なります（公式ドキュメントを参照）	組織全体の標準（セキュリティ、コンプライアンス）
プロジェクトメモリ	./AGENTS.md（主要ファイル）+ ./CLAUDE.md（AGENTS.md へのシンボリックリンク）	プロジェクト共通のコンテキストと規約
プロジェクトルール	./.claude/rules/*.md	モジュール化された、トピックに特化したルール（テスト、セキュリティ、スタイル）
ユーザーメモリ	~/.claude/CLAUDE.md	プロジェクト間で共通する個人の設定
プロジェクトメモリ（ローカル）	./CLAUDE.local.md（Git の追跡対象外）	ローカル限定のプロジェクト固有設定

読み込みの仕組み（概要）

Claude Code（CLAUDE.md のシンボリックリンク）:

• 再帰的な読み込み: 現在の作業ディレクトリからファイルシステムのルート（/）を含まない親ディレクトリまで読み込みます。
• 必要に応じた読み込み: cwd 配下のネストされた CLAUDE.md ファイルは、Claude がそれらのサブツリー内のファイルを読み込む場合にのみ読み込まれます。
• インポート: @path/to/file で追加のコンテキストを読み込みます（最大深度: 5、~ をサポート）。

Codex（AGENTS.md が主要ファイル）:

• リポジトリのルートまたは作業ディレクトリにある AGENTS.md を読み込みます。
• 簡潔に保ち、両方のツールをサポートする場合は CLAUDE.md と同じ内容にします。

ワークフロー（ベストプラクティス）

1. 最小限の主要メモリファイル（AGENTS.md、50～120 行）から始めます。プロジェクトの概要、構成、「壊してはならない」ルールを記載します。
2. 長いガイダンスや変更に弱いガイダンスは、.claude/rules/ に移します（ファイルごとに 1 つのトピック）。
3. 詳細なドキュメントをメモリにコピーする代わりに、@imports をナビゲーションとして使います。
4. メモリをコードと同様に扱います。PR レビュー、オーナーシップ、定期的な整理を行い、不要になったルールを削除します。
5. UI を変更する場合は、手戻りを避けるため、実装を始める前に具体的な値（色、価格、テキスト）を確認します。
6. 機能を提供する際は、機能ごとに 1 つのワークツリーを使い、プロジェクトの品質ゲートを実行してから、対象を絞った PR を 1 つ作成します。

実行ワークフロー（ワークツリー + ゲート + PR）

リポジトリにワークフロースクリプト（たとえば scripts/git/feature-workflow.sh）が含まれている場合は、AI コーディングセッションで次の手順を優先します。

# 1) Create isolated branch/worktree
./scripts/git/feature-workflow.sh start <feature-slug>
cd .worktrees/<feature-slug>

# 2) Implement + commit
git add -A
git commit -m "feat: <summary>"

# 3) Run project quality gate (example)
../../scripts/git/feature-workflow.sh gate

# 4) Open PR (gate may run again)
../../scripts/git/feature-workflow.sh pr --title "feat: <summary>"

ヘルパースクリプトがない場合は、Git のネイティブなワークツリーを使い、同じ方針を適用します。

• ワークツリーごとに 1 つの機能
• 機能ごとに対象を絞った PR を 1 つ
• PR 作成前にリポジトリ固有のゲートを実行

適用パスを任意指定できるルール

.claude/rules/testing.md、.claude/rules/security.md などを作成します。ルールがリポジトリの一部にのみ適用される場合は、適用範囲を指定します。

---
paths:
  - "src/api/**/*.ts"
---

コマンド（Claude Code）

• > /memory でメモリを表示し、直接編集します。
• > /init でプロジェクトメモリを初期化します（現在の動作については公式ドキュメントを参照）。

コマンド（Codex）

• AGENTS.md を直接編集します。特別なメモリコマンドは必要ありません。

クロスプラットフォーム戦略（AGENTS.md + CLAUDE.md）

複数のコーディングアシスタントをサポートする場合は、正規ファイルを 1 つにして、その内容をもう一方に反映します。

• macOS/Linux: CLAUDE.md から AGENTS.md へのシンボリックリンクを作成します。
• Windows: 開発者モードが有効でない限り、シンボリックリンクよりコピー（または小規模な同期スクリプト）を優先します。

メモリファイルではツール固有の主張を避け、移植性を保ち、プロジェクトに厳密に焦点を当てます。

プロジェクトメモリのトークン予算プロファイル

セッションで非常に大きなメモリペイロードが繰り返し含まれる場合は、このコンパクトなプロファイルを適用します。

コンパクトプロファイルのルール

1. AGENTS.md を短く保ちます（目標は 50～120 行）。
2. 長い一覧やチェックリストはスキルドキュメントに移し、パスを指定して参照します。
3. トピックごとに正規のポリシー記述を 1 つだけ維持し、繰り返す代わりにリンクします。
4. セッションごとにすべての情報を埋め込むのではなく、「必要に応じて読み込む」指示を優先します。
5. 必要に応じて、短いランタイムメモリと、より詳しいリファレンスドキュメントを併用します。

推奨する分割

• AGENTS.md（実行時）：プロジェクトの目標、厳守事項、ワークフローのルール、重要な安全上の制約。
• docs/* またはスキルの参照資料：長いリスト、例、任意のプレイブック、大規模な一覧。

品質ゲート

起動時のメモリが実用的なコンテキストの上限を超える場合は、新しいルールを追加する前に削減してください。

検証（簡易チェック）

• 同梱のリンターを実行します：bash frameworks/shared-skills/skills/agents-project-memory/scripts/lint_claude_memory.sh .
• メモリの変更をマージする前に、未解決の@importsとシークレットがないか手動で確認します。

リソース

リソース	用途
references/memory-patterns.md	パターンとアンチパターン
references/memory-examples.md	スタック別の完全な例
references/large-codebase-strategy.md	100K～1M LOC の戦略
data/sources.json	公式リンク

関連スキル

スキル	用途
agents-skills	スキル作成のパターン
agents-subagents	エージェント／サブエージェントの設定
docs-codebase	リポジトリのドキュメント作成パターン

ファクトチェック

• 最終回答の前に、ウェブ検索／ウェブ取得を使って、最新の外部情報、バージョン、価格、期限、規制、プラットフォームの動作を確認します。
• 一次情報を優先し、変動する情報については出典リンクと日付を記載します。
• ウェブにアクセスできない場合は、その制約を明示し、ガイダンスが未検証であることを示します。