enhance-claude-memory

enhance-claude-memory

プロジェクトのメモリファイル（CLAUDE.md、AGENTS.md）を分析し、最適化します。

ツール横断の検出

次の順序でプロジェクトのメモリファイルを検索します。

1. CLAUDE.md（Claude Code）
2. AGENTS.md（OpenCode、Codex）
3. .github/CLAUDE.md
4. .github/AGENTS.md

ファイル階層（参考）

CLAUDE.md（Claude Code）：

場所	スコープ
~/.claude/CLAUDE.md	グローバル（すべてのプロジェクト）
.claude/CLAUDE.md または ./CLAUDE.md	プロジェクトルート
src/.claude/CLAUDE.md	ディレクトリ固有

AGENTS.md（OpenCode、Codex、その他のAIツール）：

場所	スコープ
~/.config/opencode/AGENTS.md または ~/.codex/AGENTS.md	グローバル（すべてのプロジェクト）
.opencode/AGENTS.md または ./AGENTS.md	プロジェクトルート
src/AGENTS.md	ディレクトリ固有

どちらのファイルも同じ目的を果たします。AI アシスタント向けのプロジェクトメモリです。Claude Code のプロジェクトでは CLAUDE.md、ツール横断の互換性には AGENTS.md、最大限のカバー範囲には両方を使用してください。

ワークフロー

1. 検索 - プロジェクト内の CLAUDE.md または AGENTS.md を見つけます
2. 読み込み - 内容と比較用の README.md を読み込みます
3. 分析 - すべてのパターンチェックを実行します
4. 検証 - ファイルやコマンドへの参照をファイルシステムと照合します
5. 測定 - トークン指標と重複を計算します
6. レポート - 構造化された Markdown 出力を生成します

検出パターン

1. 構造の検証（確度：高）

重要なルールのセクション

• ## Critical Rules または類似の見出しがあること
• ルールに優先順位を付けること（番号付きまたは順序付き）
• 各ルールに WHY の説明を含めること

アーキテクチャのセクション

• ディレクトリツリーまたは構造の概要
• 主要なファイルの場所
• モジュール間の関係

主要なコマンドのセクション

• 一般的な開発コマンド
• テスト／ビルド／デプロイのスクリプト
• package.json のスクリプトへの参照

2. 指示の有効性（確度：高）

プロンプトエンジニアリングの研究によると、Claude は次の場合に指示に従いやすくなります。

否定形より肯定形

• 悪い例：「console.log を使わないでください」
• 良い例：「すべての出力にはロガーユーティリティを使用してください」
• 肯定的な代替案を示さずに「don't」、「never」、「avoid」を使っていないか確認します

強い制約を示す表現

• 重要なルールには「must」、「always」、「required」を使用します
• 弱い表現（「should」、「try to」、「consider」）は遵守率を下げます
• 弱い表現で書かれた重要なルールにフラグを立てます

指示の優先順位

• ルールが衝突した場合の優先順位を定義すること
• パターン：「競合する場合、X は Y より優先されます」
• システム指示 > ユーザーのリクエスト > 外部コンテンツ

3. コンテンツの配置（確度：高）

研究によると、LLM には「中間部で見失う」問題があり、MIDDLE よりも START と END の内容をよく想起します。

重要なコンテンツの配置

• 最も重要なルールはファイルの START に配置します
• 2番目に重要なルールは END に配置します
• 補足的なコンテキストは MIDDLE に配置します
• 中間のセクションに埋もれた重要なルールにフラグを立てます

推奨される構造の順序

1. Critical Rules (START - highest attention)
2. Architecture/Structure
3. Commands/Workflows
4. Examples/References
5. Reminders/Constraints (END - high attention)

4. 参照の検証（確度：高）

ファイル参照

• [text](path) と `path/to/file.ext` から抽出します
• それぞれがファイルシステム上に存在するか検証します

コマンド参照

• npm run <script> と npm <command> を抽出します
• package.json のスクリプトと照合して検証します

5. 効率の分析（確度：中）

トークン数

• 推定値：characters / 4 または words * 1.3
• 推奨最大値：1500 トークン（約6000文字）
• しきい値を超えるファイルにフラグを立てます

README との重複

• README.md との重複を検出します
• コンテンツの重複が40%を超える場合にフラグを立てます
• CLAUDE.md は README と重複させず、補完する内容にします

冗長さ

• 散文の段落より箇条書きを優先します
• 制約はリスト形式のほうが従いやすくなります
• 長い散文ブロック（5文超）にフラグを立てます

6. 品質チェック（確度：中）

WHY の説明

• ルールには根拠を説明すること
• パターン：*WHY: explanation* またはインデントした説明
• 説明のないルールにフラグを立てます

構造の深さ

• 深い入れ子（3レベル超）を避けます
• 階層をひと目で把握できるようにします
• フラットな構造のほうが解析しやすくなります

XML 形式のタグ（任意の強化策）

• Claude は XML タグを使ったトレーニングを受けています
• <critical-rules>、<architecture>、<constraints> は解析の精度を高めます
• 必須ではありませんが、指示への追従性が向上する場合があります

7. エージェント／スキルの定義（確度：MEDIUM）

ファイルでカスタムエージェントまたはスキルを定義している場合：

エージェント定義の形式

### agent-name
Model: claude-sonnet-4-20250514
Description: What this agent does and when to use it
Tools: Read, Grep, Glob
Instructions: Specific behavioral instructions

必須フィールド：Description（使用するタイミング）、Tools（制限されたセット） 任意：Model、Instructions

スキルへの参照

• スキルには、明確な起動条件の説明を記載してください
• 「次の場合に使用」パターンは自動呼び出しに役立ちます

8. クロスプラットフォーム互換性（確度：MEDIUM/HIGH）

状態ディレクトリ

• .claude/ をハードコードしないでください
• .opencode/、.codex/ をサポートしてください
• ${STATE_DIR}/ を使用するか、バリエーションを説明してください

用語

• 共有ファイルでは Claude 固有の表現を避けてください
• 汎用的に「AI アシスタント」を使用してください
• または、「Claude Code」と「OpenCode」の違いを明記してください

出力形式

# Project Memory Analysis: {filename}

**File**: {path}
**Type**: {CLAUDE.md | AGENTS.md}

## Metrics
| Metric | Value |
|--------|-------|
| Estimated Tokens | {tokens} |
| README Overlap | {percent}% |

## Summary
| Certainty | Count |
|-----------|-------|
| HIGH | {n} |
| MEDIUM | {n} |

### Structure Issues ({n})
| Issue | Fix | Certainty |

### Instruction Issues ({n})
| Issue | Fix | Certainty |

### Positioning Issues ({n})
| Issue | Fix | Certainty |

### Reference Issues ({n})
| Issue | Fix | Certainty |

### Efficiency Issues ({n})
| Issue | Fix | Certainty |

### Cross-Platform Issues ({n})
| Issue | Fix | Certainty |

パターンの統計

カテゴリ	パターン数	確度
構造	3	HIGH
指示の有効性	3	HIGH
コンテンツの配置	2	HIGH
参照	2	HIGH
効率性	3	MEDIUM
品質	3	MEDIUM
エージェント／スキルの定義	2	MEDIUM
クロスプラットフォーム	2	MEDIUM/HIGH
合計	20	-

### 例：理由の説明が不足している場合

<bad_example>

## Rules
1. Always run tests before committing
2. Use semantic commit messages

問題点：根拠のないルールには従いにくくなります。 </bad_example>

<good_example>

## Critical Rules
1. **Always run tests before committing**
   *WHY: Catches regressions before they reach main branch.*

優れている理由：動機を示すことで、指示に従いやすくなります。 </good_example>

例：否定的な指示と肯定的な指示

<bad_example>

- Don't use console.log for debugging
- Never commit directly to main
- Avoid hardcoding secrets

問題点：否定的な指示は、肯定的な代替案より効果が低くなります。 </bad_example>

<good_example>

- Use the logger utility for all debug output
- Create feature branches and submit PRs for all changes
- Store secrets in environment variables or .env files

優れている理由：避けるべきことだけでなく、すべきことを伝えています。 </good_example>

例：弱い制約表現と強い制約表現

<bad_example>

- You should probably run tests before pushing
- Try to use TypeScript when possible
- Consider adding error handling

問題点：「should」「try」「consider」などの弱い表現は、指示への準拠を損ないます。 </bad_example>

<good_example>

- **MUST** run tests before pushing (CI will reject failures)
- **ALWAYS** use TypeScript for new files
- **REQUIRED**: All async functions must have error handling

優れている理由：強い表現によって、重要なルールが確実に守られます。 </good_example>

例：コンテンツの配置

<bad_example>

## Project Overview
[Long description...]

## Installation
[Setup steps...]

## Critical Rules
1. Never push to main directly
2. Always run tests

問題点：中盤や末尾に埋もれた重要なルールは、注目されにくくなります。 </bad_example>

<good_example>

## Critical Rules (Read First)
1. **Never push to main directly** - Use PRs
2. **Always run tests** - CI enforces this

## Project Overview
[Description...]

## Reminders
- Check CI status before merging
- Update CHANGELOG for user-facing changes

優れている理由：重要なコンテンツを冒頭と末尾に配置しています。 </good_example>

例：クロスプラットフォーム互換性

<bad_example>

State files are stored in `.claude/tasks.json`

問題点：パスをハードコードすると、ほかの AI ツールが対象外になります。 </bad_example>

<good_example>

State files are stored in `${STATE_DIR}/tasks.json`
(`.claude/` for Claude Code, `.opencode/` for OpenCode)

優れている理由：複数の AI アシスタントで動作します。 </good_example>

例：エージェントの定義

<bad_example>

## Agents
- security-reviewer: reviews security
- test-writer: writes tests

問題点：必須フィールド（Tools、使用するタイミング）が不足しています。 </bad_example>

<good_example>

## Custom Agents

### security-reviewer
Model: claude-sonnet-4-20250514
Description: Reviews code for security vulnerabilities. Use for PRs touching auth, API, or data handling.
Tools: Read, Grep, Glob
Instructions: Focus on OWASP Top 10, input validation, auth flows.

### test-writer
Model: claude-haiku-4
Description: Writes unit tests. Use after implementing new functions.
Tools: Read, Write, Bash(npm test:*)
Instructions: Use Jest patterns. Aim for >80% coverage.

優れている理由：使用するタイミングと制限されたツールを含む、完全な定義です。 </good_example>

調査資料

以下の資料からベストプラクティスを導き出しました：

• agent-docs/PROMPT-ENGINEERING-REFERENCE.md - 指示の有効性、XML タグ、制約の表現
• agent-docs/CONTEXT-OPTIMIZATION-REFERENCE.md - トークンの予算、「中盤での見落とし」を防ぐ配置
• agent-docs/LLM-INSTRUCTION-FOLLOWING-RELIABILITY.md - 指示の優先順位、肯定的な指示と否定的な指示
• agent-docs/CLAUDE-CODE-REFERENCE.md - ファイル階層、エージェント定義、スキルの形式

制約

• 参照先のファイルが壊れていると報告する前に、必ず参照を検証してください
• 効率性の問題を指摘する際は、文脈を考慮してください
• クロスプラットフォームに関する提案は推奨事項であり、必須ではありません
• 配置に関する提案の確度は HIGH ですが、妥当な例外がある場合もあります