project-memory

プロジェクトメモリー生成ツール

明白な情報ではなく、組織に蓄積された知識を引き継ぐプロジェクト指示ファイルを作成します。有能な同僚を迎え入れるベテラン記者のように考えてください。ジャーナリズムの仕組みを説明するのではなく、このプロジェクト特有の事情を説明します。

正式な指示ファイルを選ぶ

作成を始める前に、対象を決めます。

1. AGENTS.md が存在する場合は、それを更新します。CLAUDE.md が存在しない場合は、Claude Code で @AGENTS.md を読み込む1行だけの CLAUDE.md も作成します。Claude Code が読み込むのは AGENTS.md ではなく CLAUDE.md です。
2. CLAUDE.md だけが存在する場合は、それを更新します。
3. 両方が存在し、一方がもう一方を読み込んでいる場合は、読み込まれる正式なファイルを編集します。
4. どちらも存在しない場合は、AGENTS.md を作成します。Claude Code では、同じ1行の CLAUDE.md 読み込みファイルも作成します。

同じ指針のコピーを複数作成しないでください。親ディレクトリよりも限定的なルールがサブディレクトリに必要な場合に限り、ネストした指示ファイルを維持します。

プロジェクト指示は参考情報です

プロジェクト指示ファイルは、現在のクライアントに継続的なコンテキストを提供します。それ自体でルールを強制するものではありません。

Claude Code では、CLAUDE.md の内容はシステムプロンプトの後にユーザーコンテキストとして渡されます。Claude はそれを読み、従おうとしますが、曖昧または矛盾する指示への厳密な準拠を保証するものではありません。出典： https://code.claude.com/docs/en/memory

仕組み	用途	動作
プロジェクト指示ファイル	継続的に参照する事実、コマンド、規約、制約	参考情報
スキル	複数段階の手順や必要に応じて実行するワークフロー	関連する場合に読み込まれる
クライアントによる強制	常に実行する、または実行をブロックする必要がある操作	クライアントがブロックする場合にのみ確実に動作します。たとえば、終了コード 2 を返す Claude Code フックや、PreToolUse の deny を返すフックなどです。プロンプトフックは注意を促すだけです

クライアントフックを、共有動作の不可欠な仕組みとして使用しないでください。Claude Code と Codex の両方で機能させる必要があるルールは、プロジェクト指示ファイルに記載し、任意のクライアント側の強制については別途説明します。

「published/ への書き込みをブロックする」や「コミット前にアクセシビリティチェックを実行する」といった指示には、クライアントによる強制を使います。「事実確認のワークフロー」や「FOIA 書簡の作成」といった指示には、スキルを使います。継続的に参照するプロジェクト固有の事実やルールは、プロジェクト指示ファイルに記載します。

効果的な指示ファイルに関する Claude Code のガイダンスでは、明示的な対象・対象外リストを挙げています。出典： https://code.claude.com/docs/en/best-practices

ファイルに記載する内容

エージェントがリポジトリから確実に推測できない情報を含めます。

• プロジェクト固有のビルド、テスト、lint、検証コマンド。
• 一般的なデフォルトと異なるコードまたは編集上のルール。
• リポジトリの作法、ブランチ規約、承認の境界。
• アーキテクチャ上の決定や、分かりにくい依存関係。
• 環境要件、名前付き変数、秘密の値を含まない認証情報の参照先。
• よくある失敗と、既知の最小限の復旧手順。
• プロジェクト固有の情報源の取り扱い、公開、プライバシー、法的制約。

エージェントが簡単に見つけられる情報は除外します。

• 標準的な言語規約や一般的なアドバイス。
• 正式な情報源がある詳細な API ドキュメント。
• リポジトリのファイルごとの説明。
• セッションログ、進捗報告、頻繁に変わる情報。
• 長いチュートリアルや経緯の説明。
• 認証情報、トークン、非公開の値、個人情報。

ジャーナリズム関連のプロジェクトでは：

• デフォルトに優先する AP スタイルの設定、情報源の引用ルール、署名記事の方針、公開差し止めの扱い、情報源保護の不変条件、CMS 固有の事情（例：「記事のスラッグは、メトロ部門だけでなく全部門で重複しないようにする」）を含めます。
• 「公開前に事実を確認する」や、具体的な内容を伴わない「AP スタイルを使う」は除外します。どの報道機関も、どちらも理解しています。

各行について、次のように考えてください。この記述を削除すると、有能なエージェントがプロジェクト固有のミスを犯しやすくなるでしょうか。そうでなければ、削除します。

ファイルを小さく、対象を絞る

セクションは短くし、指示は簡潔にします。200行はレビューの目安であり、目標ではありません。ファイルが大きくなったら、次のようにします。

• 複数の手順からなる手順はスキルに移します。
• 標準となるリファレンスドキュメントへのリンクを記載します。
• 範囲の狭いディレクトリ規則は、ネストされた指示ファイルに記述します。
• 一時的なメモは、クライアントのメモリ機能または gitignore 対象のローカルメモファイルに移します。
• 重複したルールや、すでに適用されないルールを削除します。

両方のクライアントをサポートする場合は、共通のガイダンスを AGENTS.md に記述し、CLAUDE.md から読み込むようにします。クライアント固有のガイダンスは、ポータブルな方法では動作を表現できない場合にのみ追加し、クライアント名を明記します。

クライアント固有のスコープ設定オプション：

• Claude Code：paths: フロントマターを含む .claude/rules/ ファイルは、エージェントが一致するファイルを作業するときにのみ読み込まれます。@import は起動時にファイル全体を読み込むため、コンテキストサイズは削減されません。
• Codex：ネストされた AGENTS.md は、そのディレクトリと配下に適用されます。

クライアント固有の保存場所

Claude Code では、より具体的な場所が優先されます。参照元： https://code.claude.com/docs/en/memory

スコープ	Claude Code の場所	用途
管理ポリシー	Linux/WSL：/etc/claude-code/CLAUDE.md macOS：/Library/Application Support/ClaudeCode/CLAUDE.md Windows：C:\Program Files\ClaudeCode\CLAUDE.md	個人の設定では除外できない組織標準
プロジェクト	./CLAUDE.md または ./.claude/CLAUDE.md	バージョン管理にチェックインされる、チームで共有する指示
ユーザー	~/.claude/CLAUDE.md	複数のプロジェクトで適用する個人設定
ローカル	./CLAUDE.local.md	Gitignore 対象の個人的なプロジェクトメモ

Codex では、グローバルスコープから現在の作業ディレクトリまでの指示が読み込まれます。後のディレクトリが先のディレクトリを上書きし、同じディレクトリでは AGENTS.override.md が AGENTS.md より優先されます。参照元： https://developers.openai.com/codex/guides/agents-md

スコープ	Codex の場所	用途
ユーザー	~/.codex/AGENTS.md	複数のプロジェクトで適用する個人用の指示
プロジェクトとネストされたディレクトリ	リポジトリのルートから現在の作業ディレクトリまでの AGENTS.md	より狭いディレクトリスコープを持つ共有ルール
上書き	AGENTS.override.md	一時的または優先度の高い上書きが必要な場合に、同じディレクトリの AGENTS.md を置き換える

複数のエージェントを使用するジャーナリズムチームでは、共有する編集基準、ソースの取り扱いに関する不変条件、ファクトチェックの手順を、標準となる共有ファイルに記述します。これらのルールは、特定のクライアントではなく組織に属するものです。

アンチパターン

1. 指示が詳細すぎる。 重要なルールが一般的なアドバイスの中に埋もれてしまいます。Claude Code でルールが繰り返し無視される場合、ファイルが長すぎてルールが見落とされている可能性があります。
2. ネストされたファイル間の矛盾。 広い範囲に適用されるルールと狭い範囲に適用されるルールが、どちらのスコープが優先されるかを示さずに食い違っています。
3. クライアントファイルの重複。 2つのコピーが別々に更新され、異なるガイダンスを示すようになります。
4. 古くなった運用状況。 ポート、担当者、現在のステータスが、実態が変わった後も残っています。
5. 指示ファイルに秘密情報を記載する。 ファイルがバージョン管理にチェックインされます。

文体

• 短く、直接的な文を使います。
• プロジェクトで必要な場合に限り、正確なコマンドやパスを記載します。
• 重大な作業を承認できる人を明記します。
• 歓迎文、宣伝文、一般的な注意書きを削除します。
• 見出しは文頭のみ大文字にします。

自動メモリはプロジェクト指示とは別です

Claude Code v2.1.59 以降では、自動メモリは ~/.claude/projects/<project>/memory/ にメモを保存します。MEMORY.md の先頭200行が各セッションに読み込まれます。参照元：https://code.claude.com/docs/en/memory

Claude が訂正を通じて学習した内容を、ユーザーに書き留めるよう求めないでください。そうしたメモは自動メモリが管理します。プロジェクト指示には、チームが作成し、レビューする永続的な事実を記載します。

例：良い例と悪い例

悪い例：明らかなセットアップを説明しているだけで、組織固有の知識がありません。

# Project instructions

## Overview

Welcome to our newsroom's story tracking system. This React and Node.js app
helps editors and reporters collaborate on stories.

## Getting started

npm install
npm start

良い例：プロジェクト固有の動作だけを記録しています。

# Project instructions

## Overview

Story tracker for the metro desk. React + Supabase.

## Gotchas

- Story slugs must be unique across all desks, not only metro.
- "Hold" does not stop the autopublish cron. Use "Kill."
- The reporter dropdown caches for one hour. New hires do not appear sooner.

## Commands

npm run sync-ap  # Pull latest from AP. Runs automatically at :15.

## Credentials

The Supabase key is in the 1Password "Metro Desk" vault, not `.env`.

テンプレート

テンプレートは templates/ ディレクトリにあります。

テンプレート	用途
editorial-tool.md	ニュースルームのツール、ファクトチェッカー、AI アシスタント
event-website.md	カンファレンス、ワークショップ、キャンペーンサイト
publication.md	ニュースレター、ポッドキャスト、継続刊行物
research-project.md	調査報道、範囲を限定したデータ調査
content-pipeline.md	CMS のワークフロー、公開の自動化
digital-archive.md	歴史的なコレクション、文書リポジトリ

ワークフロー

1. 上記のルールに従って、正規の指示ファイルを特定します。
2. 既存のファイルと、対象範囲に適用されるすべての親またはネストされた指示ファイルを読みます。
3. 最も適したテンプレートを選び、プロジェクトに必要なセクションだけをコピーします。
4. ユーザーから書き直しを求められない限り、既存のガイダンスと順序を維持します。
5. プレースホルダーを、確認済みのプロジェクト情報に置き換えます。コマンド、担当者、パス、サービスの状態を推測で補わないでください。
6. 適用範囲が個別に定められたルールは、それぞれ該当するディレクトリに保管します。
7. 最終ファイルを確認し、重複、矛盾、古い情報、シークレットがないことを確かめます。
8. Claude Code で AGENTS.md を作成した場合は、上記で説明した1行のインポートファイルも作成します。

最小限のスターター

# Project instructions

## Commands

- Test: [exact command]
- Lint: [exact command]

## Project rules

- [Non-obvious rule that changes how work is done.]
- [Approval or safety boundary.]

## Known failure modes

- [Symptom]: [Cause and verified recovery.]

まずは小さく始めます。プロジェクトでエージェントにルールが必要だと実証されてから、ルールを追加してください。

参考ファイル

複数のエージェント、ランタイム、または担当者が1つのリポジトリで連携する場合は、Pinned repository ledger をお読みください。

最終更新日の確認

2026-05-09。確認済みの情報源：https://code.claude.com/docs/en/memory および https://code.claude.com/docs/en/best-practices。Codex の指示スコープは、2026-10-23 に OpenAI の公式ドキュメントに照らして確認しました。