claude-md-manager

CLAUDE.md マネージャー

Claude Code のプロジェクト動作を設定する、効果的な CLAUDE.md ファイルを作成・管理します。

基本的なワークフロー

1. モードを判断する

新しい CLAUDE.md を作成する場合：

• プロジェクト構成、技術スタック、規約を分析します
• WHAT／WHY／HOW のフレームワークを使って、焦点を絞ったドキュメントを作成します
• 100 行未満を目標にします（最大 300 行）

既存の CLAUDE.md を更新する場合：

• 現在の内容を監査し、冗長な記述、古い情報、アンチパターンを確認します
• 外部ファイルに移すべき指示を特定します
• 簡潔さと関連性を高めます

2. プロジェクトを分析する（新規ファイルの場合）

次を確認します：

• スタックを把握するための package.json、Cargo.toml、pyproject.toml など
• アーキテクチャのパターンを把握するためのディレクトリ構成
• プロジェクトの背景を把握するための既存の README.md
• ワークフローを把握するための .github/、Makefile、スクリプト
• テスト規約を把握するためのテストディレクトリ

3. WHAT／WHY／HOW のフレームワークを適用する

WHAT — 技術的な実態：

• 技術スタックと主要な依存関係
• ディレクトリ構成とアーキテクチャ
• 主要なファイルとエントリーポイント

WHY — 背景と目的：

• プロジェクトの機能
• 特定のパターンが存在する理由
• 各ディレクトリの機能上の目的

HOW — 実用的なワークフロー：

• ビルドコマンド（パッケージマネージャー固有の内容）
• テストの実行
• 開発ワークフロー
• デプロイプロセス

4. 検証レビュー

CLAUDE.md の作成または更新後、OSGrep を使って、記述内容を実際のコードベースと照合します。これにより、古いコマンド、誤ったパス、変化した規約を検出できます。

検証手順

1. コマンドを検証する

# For each command documented, verify it exists
osgrep "dev server startup configuration" -p $REPO -m 3
osgrep "test runner setup" -p $REPO -m 3
osgrep "build script configuration" -p $REPO -m 3

2. ディレクトリ構成を検証する

# Verify directories contain what's documented
osgrep "component definitions" -p $REPO/src/components -m 3
osgrep "API route handlers" -p $REPO/src/routes -m 3

3. @import の参照を検証する

# Check each @path/to/file reference exists
test -f $REPO/docs/architecture.md && echo "EXISTS" || echo "MISSING"

4. 規約を検証する

# Verify conventions match actual code patterns
osgrep "error handling patterns" -p $REPO -m 5
osgrep "state management approach" -p $REPO -m 5

検証レポートの形式

## Validation Report
- [x] `pnpm dev` - Verified in package.json scripts
- [x] `/src/components` - Contains 23 .tsx files
- [ ] `/src/services` - **EMPTY** - No files found
- [ ] `@agent_docs/testing.md` - **MISSING**
- [ ] "No class components" - **VIOLATION**: Found 2 in /src/legacy/

/review による詳細な検証（任意）

大規模なコードベースや四半期ごとの監査では、複数のエージェントによるレビューを実行します：

/compounding-engineering:workflows:review CLAUDE.md

これにより、architecture-strategist エージェントと pattern-recognition-specialist エージェントが呼び出され、構成に関する記述と規約の正確性を徹底的に検証します。

簡潔さのルール

コンテキストの予算： Claude のコンテキストウィンドウは共有されています。CLAUDE.md の各行は、会話履歴やシステムプロンプトとコンテキストを取り合います。LLM が一貫して従える指示は約 150〜200 件で、システムプロンプトだけですでに約 50 件を使用しています。

目標：

• 理想：60 行未満（HumanLayer の本番ファイルと同程度）
• 良好：100 行未満
• 最大：300 行（超える場合はリファクタリングします）

手法：

• コードをコピーする代わりに file:line 形式で参照します
• タスク固有のドキュメントは agent_docs/ に移します
• Claude がコードから推測できる内容は削除します
• 明白な指示は削除します（Claude はコードのパターンを読み取ります）

段階的開示パターン

CLAUDE.md が 100 行を超えたら、目的別のファイルに分割します：

agent_docs/
├── building.md          # Build process details
├── testing.md           # Test conventions and execution
├── code-conventions.md  # Style and patterns
├── architecture.md      # System design decisions
└── deployment.md        # Release process

CLAUDE.md から参照します：

# Detailed Guides
- Building: @agent_docs/building.md
- Testing: @agent_docs/testing.md
- Architecture: @agent_docs/architecture.md

Claude は関連する場合にのみ、これらを読み込みます。

agent_docs/ 以外の方法

agent_docs/ を補完する、段階的開示の仕組みがほかに 3 つあります：

• .claude/rules/*.md — YAML frontmatter の paths: glob を使った、パス単位で適用されるモジュール式の指示です。一致するファイルがコンテキストに含まれる場合に、条件付きで読み込まれます。特定のファイルパスにのみ適用する指示に使用します。ルールの詳細は references/memory-hierarchy.md を参照してください。
• スキル（.claude/skills/）— 特定の状況でのみ必要となるドメイン知識です。CLAUDE.md は毎回のセッションで読み込まれますが、スキルは必要に応じて読み込まれ、非アクティブなときにコンテキストを消費しません。
• カスタムサブエージェント（.claude/agents/*.md）— エージェント固有の指示は CLAUDE.md ではなく、エージェント定義に記述します。エージェントファイルでは、ツールの制限やモデルの選択を設定できます。

ファイルインポート構文

CLAUDE.md は @path/to/file 形式のインポートに対応しています：

• @README.md — プロジェクトのルートからインポートします
• @docs/guide.md — サブディレクトリからインポートします
• @~/.claude/personal.md — 個人設定（コミットされません）
• 最大 5 階層まで再帰的に動作します
• コードブロック内では評価されません
• メインの CLAUDE.md と階層が競合しないよう、インポートするファイルは ## 見出しレベルから始めてください

避けるべきアンチパターン

次のパターンは避けてください：

1. LLM によるリンティング - CLAUDE.md の指示は参考情報であり、エージェントはコンテキストの制約が厳しいと無視する場合があります。確実に実行するにはフックを使用してください：

   # WRONG - Don't add to CLAUDE.md:
   "Always run eslint before committing"
   
   # RIGHT - Use a hook instead (deterministic, runs every time)
   

2. 自動生成された CLAUDE.md - /init の生成結果は最適とは限りません。手動で作成してください。

3. 網羅的なスタイルガイド - Claude は既存のコードパターンから学習します。

4. ルートファイルにタスク固有の指示を記載すること - 代わりに agent_docs/ を使用してください。

5. コードスニペットを直接記載すること - 最新の状態を保てる file:line 参照を使用してください。

6. シークレットや認証情報 - CLAUDE.md は公開情報として扱ってください。

7. 禁止事項のみの制約 - 代替案のない単なる禁止（「X を絶対にしない」）は、エージェントを行き詰まらせます。「X を絶対にしない」という指示には、必ず「— 代わりに Y をする」を続けてください。

8. 説明のないファイル参照 - 文脈のない @path のインポートは無視されます。各インポートの目的を説明し、いつ、なぜ読むべきかを示してください（例：@agent_docs/testing.md — テストの規約とカバレッジのしきい値。テストを作成または変更する際に読んでください。）。

テンプレート構成

# Project Name

Brief description of what this project does.

## Stack
- [Framework] with [Key libraries]
- [Database/Storage]
- [Key tooling]

## Structure
- `/src` - Application code
- `/tests` - Test suites
- `/docs` - Documentation

## Commands
- Dev: `npm run dev`
- Test: `npm test`
- Build: `npm run build`

## Conventions
- [Critical convention 1]
- [Critical convention 2]

## Workflow
- Branch naming: `feature/description`
- Commits: Conventional Commits format
- PR: Rebase before merge

## Architecture Notes
@docs/architecture.md (if complex)

監査チェックリスト（更新時）

既存の CLAUDE.md を確認する際は、次の点をチェックしてください：

• 100 行未満ですか？そうでない場合、別ファイルに切り出す候補を特定してください
• コードを直接記載せず、file:line 参照を使用していますか？
• タスク固有のドキュメントは agent_docs/ にありますか？
• リンティングやスタイルの強制がありませんか（フックを使用してください）？
• 認証情報やシークレットが含まれていませんか？
• 明白な指示や推測できる指示が含まれていませんか？
• すべてのコマンドが実際に動作しますか？
• アーキテクチャ情報は現在も正確ですか？
• OSGrep による検証を実行しましたか？（コマンド、ディレクトリ、規約）
• ファイル参照は現在も有効ですか？
• 否定的な指示に代替案が添えられていますか？
• ファイルのインポートに、いつ、なぜ読むべきかの説明がありますか？
• パス固有の指示は、ルートの CLAUDE.md ではなく .claude/rules/ にありますか？

グローバル登録

プロジェクトの CLAUDE.md を作成または更新する際は、プロジェクトのディレクトリと有効なプランを記載した項目が ~/.claude/agent_docs/active-projects.md にあることを確認してください。

階層構造のファイル

モノレポでは、複数の階層に CLAUDE.md を配置してください：

/CLAUDE.md              # Repo-wide conventions
/frontend/CLAUDE.md     # Frontend-specific
/backend/CLAUDE.md      # Backend-specific
/services/auth/CLAUDE.md # Service-specific

各ファイルは簡潔にし、適用範囲に合った内容にします。

リソース

• references/best-practices.md - 効果的なパターンの詳細
• references/memory-hierarchy.md - 指示の配置、.claude/rules/、CLAUDE.local.md
• references/templates.md - プロジェクトの種類に応じたテンプレート（9 種類）
• scripts/analyze_project.py - プロジェクト構造の自動分析