project-memory

プロジェクトメモリ

目次

• 概要
• このスキルを使うタイミング
• 主な機能
  • 1. 初期設定 - メモリ基盤の作成
  • 2. CLAUDE.md の設定 - メモリを考慮した動作
  • 3. AGENTS.md の設定 - 複数ツールのサポート
  • 4. メモリファイルの検索
  • 5. メモリファイルの更新
  • 6. メモリファイルの保守
• テンプレートとリファレンス
• ワークフローの例
• 他のスキルとの連携
• 成功基準

概要

docs/project_notes/ に構造化されたメモリシステムを構築し、プロジェクトの組織的な知識を維持します。このスキルでは、4 つの主要なメモリファイル（バグ、決定事項、重要な事実、課題）を用意し、これらを自動的に参照・維持するように CLAUDE.md と AGENTS.md を設定します。その結果、コーディングセッションや異なる AI ツール間で、過去の決定事項、問題の解決策、重要な設定の詳細を記憶するプロジェクトが実現します。

このスキルを使うタイミング

次の場合にこのスキルを呼び出してください。

• 時間とともに知識が蓄積される新しいプロジェクトを始めるとき
• プロジェクトですでに繰り返し発生するバグや、記録しておくべき決定事項があるとき
• ユーザーが「プロジェクトメモリを設定して」や「決定事項を記録して」と依頼したとき
• ユーザーがバグ修正、アーキテクチャ上の決定、または完了した作業を記録したいとき
• 見覚えのある問題に遭遇したとき（「以前にもこれを解決しませんでしたか？」）
• アーキテクチャの変更を提案する前に、既存の決定事項を確認するとき
• 複数の開発者や AI ツール（Claude Code、Cursor など）を使うプロジェクトで作業するとき

主な機能

1. 初期設定 - メモリ基盤の作成

プロジェクトで初めて呼び出されたときは、次の構造を作成します。

docs/
└── project_notes/
    ├── bugs.md         # Bug log with solutions
    ├── decisions.md    # Architectural Decision Records
    ├── key_facts.md    # Project configuration and constants
    └── issues.md       # Work log with ticket references

ディレクトリ名の理由： memory/ ではなく docs/project_notes/ を使うことで、AI 専用のツールではなく、一般的なエンジニアリングの整理方法に見えます。これにより、開発者による導入と保守が促進されます。

初期ファイルの内容： このスキルの references/ ディレクトリにあるテンプレートをコピーしてください。

• references/bugs_template.md を初期の bugs.md に使用します
• references/decisions_template.md を初期の decisions.md に使用します
• references/key_facts_template.md を初期の key_facts.md に使用します
• references/issues_template.md を初期の issues.md に使用します

各テンプレートには、書式例と使用上のヒントが含まれています。

2. CLAUDE.md の設定 - メモリを考慮した動作

プロジェクトの CLAUDE.md ファイルに次のセクションを追加するか、更新します。

## Project Memory System

This project maintains institutional knowledge in `docs/project_notes/` for consistency across sessions.

### Memory Files

- **bugs.md** - Bug log with dates, solutions, and prevention notes
- **decisions.md** - Architectural Decision Records (ADRs) with context and trade-offs
- **key_facts.md** - Project configuration, credentials, ports, important URLs
- **issues.md** - Work log with ticket IDs, descriptions, and URLs

### Memory-Aware Protocols

**Before proposing architectural changes:**
- Check `docs/project_notes/decisions.md` for existing decisions
- Verify the proposed approach doesn't conflict with past choices
- If it does conflict, acknowledge the existing decision and explain why a change is warranted

**When encountering errors or bugs:**
- Search `docs/project_notes/bugs.md` for similar issues
- Apply known solutions if found
- Document new bugs and solutions when resolved

**When looking up project configuration:**
- Check `docs/project_notes/key_facts.md` for credentials, ports, URLs, service accounts
- Prefer documented facts over assumptions

**When completing work on tickets:**
- Log completed work in `docs/project_notes/issues.md`
- Include ticket ID, date, brief description, and URL

**When user requests memory updates:**
- Update the appropriate memory file (bugs, decisions, key_facts, or issues)
- Follow the established format and style (bullet lists, dates, concise entries)

### Style Guidelines for Memory Files

- **Prefer bullet lists over tables** for simplicity and ease of editing
- **Keep entries concise** (1-3 lines for descriptions)
- **Always include dates** for temporal context
- **Include URLs** for tickets, documentation, monitoring dashboards
- **Manual cleanup** of old entries is expected (not automated)

3. AGENTS.md の設定 - 複数ツールのサポート

プロジェクトに AGENTS.md ファイルがある場合（エージェントのワークフローや複数ツールを使うプロジェクトで使用）、同じメモリプロトコルを追加します。これにより、Claude Code、Cursor、GitHub Copilot、その他の AI ツールのどれを使っても一貫性が保たれます。

AGENTS.md が存在する場合： 上記と同じ「Project Memory System」セクションを追加します。

AGENTS.md が存在しない場合： 作成するかどうかをユーザーに尋ねます。複数の AI ツールを使うプロジェクトは多く、共有のメモリプロトコルを活用できます。

4. メモリファイルの検索

問題に遭遇したときや決定を下すときは、メモリファイルを積極的に検索します。

bugs.md を検索する：

# Look for similar errors
grep -i "connection refused" docs/project_notes/bugs.md

# Find bugs by date range
grep "2025-01" docs/project_notes/bugs.md

decisions.md を検索する：

# Check for decisions about a technology
grep -i "database" docs/project_notes/decisions.md

# Find all ADRs
grep "^### ADR-" docs/project_notes/decisions.md

key_facts.md を検索する：

# Find database connection info
grep -A 5 "Database" docs/project_notes/key_facts.md

# Look up service accounts
grep -i "service account" docs/project_notes/key_facts.md

より複雑な検索には Grep ツールを使用します：

• すべてのメモリファイルを検索：Grep(pattern="oauth", path="docs/project_notes/")
• コンテキストを考慮した検索：Grep(pattern="bug", path="docs/project_notes/bugs.md", -A=3, -B=3)

5. メモリファイルの更新

ユーザーから更新を依頼された場合、または解決済みの問題を記録する場合は、適切なメモリファイルを更新します。

バグのエントリーを追加する：

### YYYY-MM-DD - Brief Bug Description
- **Issue**: What went wrong
- **Root Cause**: Why it happened
- **Solution**: How it was fixed
- **Prevention**: How to avoid it in the future

決定事項を追加する：

### ADR-XXX: Decision Title (YYYY-MM-DD)

**Context:**
- Why the decision was needed
- What problem it solves

**Decision:**
- What was chosen

**Alternatives Considered:**
- Option 1 -> Why rejected
- Option 2 -> Why rejected

**Consequences:**
- Benefits
- Trade-offs

重要な事実を追加する：

• カテゴリ別に整理します（GCP プロジェクト、データベース、API、ローカル開発など）。
• 分かりやすいように箇条書きを使用します。
• 本番環境と開発環境の両方の詳細を含めます。
• 簡単に参照できるよう URL を追加します。
• 保存してはいけない情報に関するセキュリティガイドラインは、references/key_facts_template.md を参照してください。

作業ログのエントリーを追加する：

### YYYY-MM-DD - TICKET-ID: Brief Description
- **Status**: Completed / In Progress / Blocked
- **Description**: 1-2 line summary
- **URL**: https://jira.company.com/browse/TICKET-ID
- **Notes**: Any important context

6. メモリファイルのメンテナンス

古いエントリーを定期的に整理します：

• 手動での整理（自動化なし）はユーザーの責任です。
• 関連性がなくなった非常に古いバグのエントリー（6 か月以上前のもの）を削除します。
• 完了した作業のうち、3 か月以上前のものを issues.md からアーカイブします。
• すべての決定事項を保持します（簡潔で、経緯を把握するために役立ちます）。
• プロジェクト設定が変更されたら、key_facts.md を更新します。

競合の解決：

• decisions.md の決定事項と競合する提案をする場合は、その決定を再検討する理由を説明します。
• 選択が変わった場合は、決定事項のエントリーを更新します。
• 変更の経緯が分かるよう、改訂日を追加します。

テンプレートと参考資料

このスキルには、適切な書式を示すテンプレートファイルが references/ に含まれています。

• references/bugs_template.md - バグのエントリー形式と例
• references/decisions_template.md - ADR 形式と例
• references/key_facts_template.md - 重要な事実の整理方法と例（セキュリティガイドラインを含む）
• references/issues_template.md - 作業ログの形式と例

初期メモリファイルを作成する際は、これらのテンプレートを docs/project_notes/ にコピーし、プロジェクトに合わせてカスタマイズします。

ワークフローの例

シナリオ 1：既知のバグに遭遇した場合

User: "I'm getting a 'connection refused' error from the database"
-> Search docs/project_notes/bugs.md for "connection"
-> Find previous solution: "Use AlloyDB Auth Proxy on port 5432"
-> Apply known fix

シナリオ 2：アーキテクチャの変更を提案する場合

Internal: "User might benefit from using SQLAlchemy for migrations"
-> Check docs/project_notes/decisions.md
-> Find ADR-002: Already decided to use Alembic
-> Use Alembic instead, maintaining consistency

シナリオ 3：ユーザーからメモリの更新を依頼された場合

User: "Add that CORS fix to our bug log"
-> Read docs/project_notes/bugs.md
-> Add new entry with date, issue, solution, prevention
-> Confirm addition to user

シナリオ 4：プロジェクト設定を調べる場合

Internal: "Need to connect to database"
-> Check docs/project_notes/key_facts.md
-> Find Database Configuration section
-> Use documented connection string and credentials

効果的なメモリ管理のヒント

1. 先回りして対応する：解決策を提案する前にメモリファイルを確認します。
2. 簡潔にする：エントリーは短く保ちます（説明は 1～3 行）。
3. 日付を記載する：時系列を把握できるよう、必ず日付を含めます。
4. リンクを含める：チケット、ドキュメント、監視ダッシュボードへの URL を含めます。
5. 選別する：あらゆるバグではなく、繰り返し発生する問題や教訓となる問題に注目します。

他のスキルとの連携

project-memory スキルは、他のスキルを補完します。

• requirements-documenter：要件 -> 決定事項（ADR から要件を参照）
• root-cause-debugger：バグの診断 -> バグログ（修正後に解決策を記録）
• code-quality-reviewer：品質上の問題 -> 決定事項（品質基準を記録）
• docs-sync-editor：コードの変更 -> 重要な事実（設定の変更時に更新）

これらのスキルを併用する場合は、フォローアップとしてメモリファイルの更新も検討してください。

成功基準

以下を満たしている場合、このスキルは正常に導入されています。

• docs/project_notes/ ディレクトリに、4 つすべてのメモリファイルが存在する
• CLAUDE.md にプロトコルを記載した「Project Memory System」セクションが含まれている
• AGENTS.md に同じプロトコルが含まれている（ファイルが存在する場合、またはユーザーから依頼された場合）
• メモリファイルがテンプレートの形式とスタイルガイドラインに従っている
• AI アシスタントが変更を提案する前にメモリファイルを確認する
• ユーザーがメモリの更新を簡単に依頼できる（「これを bugs.md に追加して」など）
• メモリファイルが AI 生成物ではなく、一般的なエンジニアリングドキュメントのように見える