memory-md-management

Memory.md 管理

監査、品質評価、的を絞った改善など、プロジェクトのメモリファイルを包括的に管理できます。このスキルは、CLAUDE.md などのドキュメントファイルを高品質に保つことで、コーディングエージェントがプロジェクトの最適なコンテキストを得られるようにします。

概要

CLAUDE.md などのプロジェクトメモリファイルは、コーディングエージェントのセッションにプロジェクト固有のコンテキストを提供するための主要な仕組みです。このスキルは、検出、品質評価、レポート、改善というライフサイクル全体を管理します。ドキュメントを最新かつ実用的で簡潔な状態に保つため、5 フェーズのワークフローに従います。

このスキルは、コマンド／ワークフロー、アーキテクチャの明確さ、見落としやすいパターン、簡潔さ、最新性、実用性という 6 つの観点で標準化された品質基準に照らして、CLAUDE.md ファイルを評価します。各ファイルには、具体的な改善案とともに、スコア（0～100）と評価（A～F）が付与されます。

使用する場面

次のような場合に、このスキルを使用してください。

• ユーザーが CLAUDE.md の「確認」「監査」「更新」「改善」「修正」「保守」を明示的に依頼した場合
• ユーザーが「CLAUDE.md の品質」「ドキュメントレビュー」「プロジェクトメモリの最適化」に言及した場合
• 新しいプロジェクト用のプロジェクトメモリファイルを一から作成する必要がある場合
• ユーザーが Claude によるコードベースの理解を深めたいと依頼した場合
• ドキュメントが古くなっている場合
• 新しいコードベースで作業を始めるにあたり、既存のドキュメントを把握する必要がある場合
• セッション中にユーザーが # を押して、学んだ内容をメモリファイルに反映する場合

トリガーフレーズ：「audit CLAUDE.md」「check documentation quality」「improve project context」「review CLAUDE.md」「validate documentation」

手順

フェーズ 1：検出

リポジトリ内のすべての CLAUDE.md ファイルを検索します。

find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50

ファイルの種類と場所：

種類	場所	用途
プロジェクトルート	./CLAUDE.md	プロジェクトの主要なコンテキスト（Git にコミットされ、チームと共有されます）
ローカルの上書き設定	./.claude.local.md	個人用／ローカル設定（Git の追跡対象外で、共有されません）
グローバルのデフォルト設定	~/.claude/CLAUDE.md	すべてのプロジェクトに適用されるユーザー共通のデフォルト設定
パッケージ固有	./packages/*/CLAUDE.md	モノレポ内のモジュールレベルのコンテキスト
サブディレクトリ	任意のネストされた場所	機能／ドメイン固有のコンテキスト

フェーズ 2：品質評価

各 CLAUDE.md ファイルについて、references/quality-criteria.md を読み、次の基準に照らして評価します。

評価基準	配点	確認内容
コマンド／ワークフロー	20 点	ビルド／テスト／デプロイのコマンドが記載され、動作しますか？
アーキテクチャの明確さ	20 点	Claude がコードベースの構造を理解できますか？
見落としやすいパターン	15 点	注意点や特有の挙動が記載されていますか？
簡潔さ	15 点	冗長な記述がなく、情報が凝縮されていますか？
最新性	15 点	現在のコードベースの状態を反映していますか？
実用性	15 点	指示は実行可能で、そのままコピーして使えますか？

品質スコア： A（90～100）、B（70～89）、C（50～69）、D（30～49）、F（0～29）

フェーズ 3：品質レポートの出力

重要：更新を行う前に、必ず品質レポートを出力してください。

形式：

## CLAUDE.md Quality Report

### Summary
- Files found: X
- Average score: X/100
- Files needing update: X

### File-by-File Assessment
#### 1. ./CLAUDE.md (Project Root)
**Score: XX/100 (Grade: X)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | X/20 | ... |
| Architecture clarity | X/20 | ... |
| Non-obvious patterns | X/15 | ... |
| Conciseness | X/15 | ... |
| Currency | X/15 | ... |
| Actionability | X/15 | ... |

**Issues:**
- [List specific problems]

**Recommended additions:**
- [List what should be added]

フェーズ 4：的を絞った更新

レポートを出力した後、更新する前にユーザーの確認を求めます。

更新の詳しい原則については、references/update-guidelines.md をお読みください。

主な原則：

1. 的を絞った追加のみを提案する - コマンド、注意点、パターン、設定
2. 最小限にとどめる - 明らかな情報、一般的な助言、一度きりの修正は避ける
3. 差分を示す - ファイル、変更内容（差分形式）、説明

差分形式：

### Update: ./CLAUDE.md
**Why:** [Brief explanation of why this helps]

```diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev
+ ```

### Phase 5: Apply Updates

After user approval, use Edit tool to apply changes. Preserve existing content structure.

## Examples

### Example 1: Quality Assessment

**User request:** "Check if my CLAUDE.md is good"

**Response:**
~~~markdown
## CLAUDE.md Quality Report

### Summary
- Files found: 1
- Average score: 65/100
- Files needing update: 1

### File-by-File Assessment

#### 1. ./CLAUDE.md
**Score: 65/100 (Grade: C)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | 10/20 | Only npm install documented |
| Architecture clarity | 15/20 | Basic tree, missing module relationships |
| Non-obvious patterns | 5/15 | No gotchas documented |
| Conciseness | 15/15 | Concise and dense |
| Currency | 10/15 | Some outdated paths |
| Actionability | 10/15 | Some vague instructions |

**Issues:**
- Missing test command
- Missing build command
- No documentation of auth flow complexity
- References to old src/structure

**Recommended additions:**
- Add Commands section with test/build
- Document auth module gotcha
- Update architecture paths

例 2：ゼロから作成する

ユーザーのリクエスト：「この React プロジェクト用の CLAUDE.md を作成してください」

応答：

I'll create a CLAUDE.md for your React project. Let me first analyze the codebase structure.

[Scans package.json, src/, and key config files]

## CLAUDE.md Quality Report

### Summary
- Files found: 0
- Creating new CLAUDE.md at project root

### Proposed CLAUDE.md Content:

# Project Name

## Commands

| Command | Description |
|---------|-------------|
| `npm install` | Install dependencies |
| `npm run dev` | Start dev server (Vite on port 5173) |
| `npm run build` | Production build |
| `npm run test` | Run Vitest tests |
| `npm run lint` | ESLint check |

## Architecture

src/ ├── components/ # 再利用可能な UI コンポーネント ├── pages/ # ルートページ ├── hooks/ # カスタム React フック ├── lib/ # ユーティリティと API クライアント └── main.tsx # エントリーポイント

## Gotchas

- Vite requires files in `public/` for static assets
- State updates in `useEffect` need proper dependency arrays

このファイルを作成しますか？

### Example 3: Update Proposal

**User request:** "Update my CLAUDE.md with what you learned"

**Response:**
```markdown
### Update: ./CLAUDE.md

**Why:** Discovered that tests require database setup which wasn't documented.

```diff
## Testing

+ **Prerequisites:** Start test database first with `docker-compose up -d test-db`
+ `npm run test` - Run all tests
+ `npm run test:unit` - Unit tests only (no DB required)

API_BASE_URL に関する問題も見つかりました：

## Environment

- `API_BASE_URL` - API endpoint (default: localhost:3000)
+ `API_BASE_URL` - API endpoint (required for production, defaults to http://localhost:3000 in dev)

これらの変更を適用しますか？

## Best Practices

1. **Always read references before acting**: Quality criteria, templates, and update guidelines contain essential details
2. **Report before editing**: Never modify CLAUDE.md without first presenting a quality report
3. **Preserve existing structure**: When updating, maintain the existing organization and style
4. **Be project-specific**: Only add information specific to this codebase, not generic advice
5. **Verify commands work**: Before suggesting commands, mentally or actually verify they execute correctly
6. **Use progressive disclosure**: Keep SKILL.md lean, reference detailed rubrics in separate files
7. **Score consistently**: Apply the same scoring standards across all files for fair comparison

## Constraints and Warnings

1. **Never modify without approval**: Always get user confirmation before editing CLAUDE.md files
2. **Don't remove content without asking**: If suggesting deletions, explicitly mark them and get approval
3. **Respect `.claude.local.md`**: These are personal settings; never suggest modifying them in shared docs
4. **Avoid generic advice**: Do not add "write good code" type content - focus on project-specific patterns
5. **Keep diffs concise**: Show only the actual changes, not entire file contents
6. **Verify file paths**: Ensure all referenced files exist before documenting them
7. **Score objectively**: Use the rubric consistently; don't inflate scores for incomplete documentation