claude-md-enhancer

CLAUDE.md ファイルエンハンサー

このスキルは、Claude Code プロジェクト向けに、包括的な CLAUDE.md ファイルの生成と改善を提供します。既存ファイルを分析してベストプラクティスに照らして検証し、プロジェクトの種類、技術スタック、チーム規模に合わせたガイドラインを生成します。

機能

• 🆕 対話型の初期化：リポジトリを調査し、プロジェクトの種類と技術スタックを検出して、確認を求めたうえで、カスタマイズされた CLAUDE.md ファイルを作成するインテリジェントなワークフロー
• ✨ 100% ネイティブ形式に準拠：生成されるすべてのファイルは、プロジェクト構成図、セットアップ手順、アーキテクチャセクション、ファイル構成の説明を含む、Claude Code の公式形式に従います（/update-claude-md スラッシュコマンドと同じ形式です）
• 既存ファイルの分析：現在の CLAUDE.md ファイルをスキャンし、構成、完全性、品質を評価します
• ベストプラクティスの検証：Anthropic のガイドライン（ファイルの長さ、必須セクション、書式基準）に照らして確認します
• 新規ファイルの生成：新しいプロジェクト向けに、CLAUDE.md ファイルを一から作成します
• 既存ファイルの改善：不足しているセクションを追加し、構成を改善して、最新のベストプラクティスに更新します
• モジュール型アーキテクチャ：サブディレクトリ（backend/、frontend/、docs/）に、コンテキストに応じた CLAUDE.md ファイルを配置できます
• 技術スタックのカスタマイズ：特定の技術（TypeScript、Python、Go、React、Vue など）に合わせてガイドラインを調整します
• チーム規模への適応：チームの規模（個人、小規模 <10、大規模 10+）に応じて複雑さを調整します
• テンプレートの選択：プロジェクトの複雑さと開発フェーズに基づいて、適切なテンプレートを選択します

入力要件

分析と改善の場合

既存の CLAUDE.md ファイルの内容またはファイルパスを指定します。

{
  "mode": "enhance",
  "file_path": "CLAUDE.md",
  "content": "[existing CLAUDE.md content]",
  "project_context": {
    "type": "web_app",
    "tech_stack": ["typescript", "react", "node", "postgresql"],
    "team_size": "small",
    "phase": "mvp"
  }
}

新規ファイルの生成の場合

プロジェクトのコンテキストを指定します。

{
  "mode": "create",
  "project_context": {
    "type": "api",
    "tech_stack": ["python", "fastapi", "postgresql", "docker"],
    "team_size": "medium",
    "phase": "production",
    "workflows": ["tdd", "cicd", "documentation_first"]
  },
  "modular": true,
  "subdirectories": ["backend", "database", "docs"]
}

コンテキストパラメーター

• type：プロジェクトの種類（web_app、api、fullstack、cli、library、mobile、desktop）
• tech_stack：技術の配列（例：["typescript", "react", "node"]）
• team_size：solo、small（<10）、medium（10-50）、large（50+）
• phase：開発フェーズ（prototype、mvp、production、enterprise）
• workflows：主要なワークフロー（tdd、cicd、documentation_first、agile など）

出力形式

分析レポート

{
  "analysis": {
    "file_size": 450,
    "line_count": 320,
    "sections_found": [
      "Quick Navigation",
      "Core Principles",
      "Tech Stack",
      "Workflow Instructions"
    ],
    "missing_sections": [
      "Testing Requirements",
      "Error Handling Patterns"
    ],
    "issues": [
      {
        "type": "length_warning",
        "severity": "medium",
        "message": "File exceeds recommended 300 lines (320 lines)"
      },
      {
        "type": "missing_section",
        "severity": "low",
        "message": "Consider adding 'Testing Requirements' section"
      }
    ],
    "quality_score": 75,
    "recommendations": [
      "Split into modular files (backend/CLAUDE.md, frontend/CLAUDE.md)",
      "Add testing requirements section",
      "Reduce root file to <150 lines"
    ]
  }
}

生成される内容

完全な CLAUDE.md ファイルの内容、または追加する特定のセクション：

# CLAUDE.md

This file provides guidance for Claude Code when working with this project.

## Quick Navigation

- [Backend Guidelines](backend/CLAUDE.md)
- [Frontend Guidelines](frontend/CLAUDE.md)
- [Database Operations](database/CLAUDE.md)
- [CI/CD Workflows](.github/CLAUDE.md)

## Core Principles

1. **Test-Driven Development**: Write tests before implementation
2. **Type Safety First**: Use TypeScript strict mode throughout
3. **Component Composition**: Favor small, reusable components
4. **Error Handling**: Always handle errors with proper logging
5. **Documentation Updates**: Keep docs in sync with code changes

[... additional sections based on template ...]

使用方法

例 1：新しいプロジェクトの CLAUDE.md を初期化する（対話型）

Hey Claude—I just added the "claude-md-enhancer" skill. I don't have a CLAUDE.md file yet. Can you help me create one for this project?

処理内容：

1. Claude が CLAUDE.md の有無を確認します（この場合は存在しません）。
2. Claude が組み込みコマンドを使用してリポジトリを調査します。
3. Claude がプロジェクトの種類、技術スタック、チーム規模、ワークフローを分析します。
4. Claude が検出結果を示し、確認を求めます。
5. 設定を確認します。
6. Claude がカスタマイズされた CLAUDE.md ファイルを作成します。
7. Claude がベストプラクティスに従って内容を改善します。

対話型の流れ：

• ✋ 作成前にユーザーの確認が必要です
• 🔍 検出内容をすべて確認できます
• ⚙️ 実行前に設定を調整できます

例 2：既存の CLAUDE.md を分析する

Hey Claude—I just added the "claude-md-enhancer" skill. Can you analyze my current CLAUDE.md file and tell me what's missing or could be improved?

例 2：TypeScript プロジェクト用の新しい CLAUDE.md を生成する

Hey Claude—I just added the "claude-md-enhancer" skill. Can you create a CLAUDE.md file for my TypeScript React project with a team of 5 developers? We use PostgreSQL, Docker, and follow TDD practices.

例 3：既存ファイルを改善する

Hey Claude—I just added the "claude-md-enhancer" skill. Can you enhance my existing CLAUDE.md by adding missing sections and improving the structure? Here's my current file: [paste content]

例 4：モジュール型アーキテクチャを生成する

Hey Claude—I just added the "claude-md-enhancer" skill. Can you create a modular CLAUDE.md setup for my full-stack project? I need separate files for backend (Python/FastAPI), frontend (React), and database (PostgreSQL).

初期化ワークフロー（新規プロジェクト）

プロジェクトに CLAUDE.md が存在しない場合、このスキルはインテリジェントな初期化ワークフローを提供します。

ワークフローの手順

Step 1: 検出

• スキルがプロジェクトのルートに CLAUDE.md が存在するか確認します
• 見つからない場合は、初期化ワークフローが開始されます

Step 2: リポジトリの調査

• Claude Code に組み込まれている explore コマンドを使用します
• プロジェクトの構造、ファイル、ディレクトリを分析します
• 設定ファイル（package.json、requirements.txt、go.mod など）を調査します
• 既存のドキュメントを確認します

Step 3: インテリジェント分析

• プロジェクト種別の検出: web_app、api、fullstack、cli、library、mobile、desktop
• 技術スタックの検出: TypeScript、Python、React、FastAPI、PostgreSQL、Docker など
• チーム規模の推定: プロジェクトの複雑さに基づきます（solo、small、medium、large）
• 開発フェーズ: prototype、mvp、production、enterprise
• ワークフローの検出: TDD、CI/CD、ドキュメント優先、アジャイル
• 構成の推奨: 単一ファイルとモジュール化アーキテクチャのどちらかを提案します

Step 4: ユーザーの確認 ✋

• 検出した内容をすべてわかりやすい形式で表示します
• 推奨する CLAUDE.md の構成を示します
• 設定の確認または調整をユーザーに求めます
• 続行する前に、ユーザーの明示的な承認が必要です

Step 5: ファイルの作成

• 確認済みの設定に基づいて、カスタマイズした CLAUDE.md を生成します
• 推奨された場合は、モジュール化されたファイル（backend/、frontend/ など）を作成します
• 技術に応じたベストプラクティスを適用します

Step 6: 強化

• 生成した内容を検証します
• 品質を向上させます
• 内容に漏れがないことを確認します

Step 7: まとめ

• 作成したファイルを表示します
• 次の手順を案内します
• すぐに使用できる状態になります

インタラクティブな例

User: "I need a CLAUDE.md for this project"

Claude: "I'll explore your repository first to understand the project.
        [Explores using built-in commands]

        Based on my exploration, here's what I discovered:

        Project Type: Full-Stack Application
        Tech Stack: TypeScript, React, Node.js, PostgreSQL, Docker
        Team Size: Small (2-9 developers)
        Development Phase: MVP
        Workflows: TDD, CI/CD

        Recommended Structure: Modular architecture
        - Root CLAUDE.md (navigation hub)
        - backend/CLAUDE.md (API guidelines)
        - frontend/CLAUDE.md (React guidelines)

        Would you like me to create these files?"

User: "Yes, please proceed"

Claude: "Creating customized CLAUDE.md files...
        ✅ Created CLAUDE.md (100 lines)
        ✅ Created backend/CLAUDE.md (150 lines)
        ✅ Created frontend/CLAUDE.md (175 lines)

        Your project is ready for AI-assisted development!"

スクリプト

workflow.py

新しいプロジェクトの対話型初期化ワークフローを管理します。

主な関数:

• check_claude_md_exists() - CLAUDE.md が存在するか確認します
• generate_exploration_prompt() - Claude がリポジトリを調査するよう案内します
• analyze_discoveries() - 調査結果を分析します
• generate_confirmation_prompt() - ユーザー確認用のプロンプトを作成します
• get_workflow_steps() - ワークフローの全手順を取得します

analyzer.py

既存の CLAUDE.md ファイルを分析し、構成、セクション、品質上の問題を特定します。

主な関数:

• analyze_file() - CLAUDE.md の構成を解析して分析します
• detect_sections() - 存在するセクションと不足しているセクションを特定します
• calculate_quality_score() - ファイルの品質を採点します（0～100）
• generate_recommendations() - 実行可能な改善案を提示します

validator.py

ベストプラクティスおよび Anthropic のガイドラインに照らして CLAUDE.md ファイルを検証します。

主な関数:

• validate_length() - ファイルの長さを確認します（300 行を超える場合は警告）
• validate_structure() - 必須セクションが含まれていることを確認します
• validate_formatting() - Markdown の書式品質を確認します
• validate_completeness() - 重要な情報が含まれていることを確認します

generator.py

テンプレートに基づいて、新しい CLAUDE.md の内容または不足しているセクションを生成します。

主な関数:

• generate_root_file() - メインの CLAUDE.md オーケストレーターを作成します
• generate_context_file() - コンテキストに応じたファイル（backend、frontend など）を作成します
• generate_section() - 個別のセクション（技術スタック、ワークフローなど）を生成します
• merge_with_existing() - 既存のファイルに新しいセクションを追加します

template_selector.py

プロジェクトのコンテキストに基づいて、適切なテンプレートを選択します。

主な関数:

• select_template() - プロジェクト種別とチーム規模に基づいてテンプレートを選択します
• customize_template() - テンプレートを技術スタックに合わせて調整します
• determine_complexity() - 適切な詳細レベルを算出します
• recommend_modular_structure() - サブディレクトリの構成を提案します

ベストプラクティス

重要な検証ルール ⚠️

「完了と判断する前に、必ず公式のネイティブな例と照合して出力を検証してください。」

CLAUDE.md の生成を確定する前に、次の手順を実施してください。

1. /update-claude-md スラッシュコマンドの形式と出力を比較します
2. 必須セクションについて、Claude Code の公式ドキュメントを確認します
3. ネイティブ形式のセクション（概要、プロジェクト構成、ファイル構成、セットアップとインストール、アーキテクチャなど）がすべて含まれていることを確認します
4. examples/ フォルダー内の参考例と照合します

新規プロジェクトの場合

1. 最小限のテンプレート（50～100 行）から始め、必要に応じて拡張します
2. 主要コンポーネントが 3 つを超えるプロジェクトでは、モジュール型アーキテクチャを使用します
3. 技術スタックの概要をすぐに含めます
4. チームが 5 人を超える前に、ワークフローの手順を追加します

機能を拡張する場合

1. 変更前に分析します。まず現在の構成を把握します
2. カスタムコンテンツを維持します。置き換えるのではなく、拡張のみ行います
3. 変更後に検証します。改善によって既存のパターンが崩れていないことを確認します
4. Claude Code でテストします。ガイドラインが意図どおりに機能することを確認します

一般的なガイドライン

1. ルートファイルは簡潔に保つ - 最大 150 行とし、ナビゲーションハブとして使用します
2. コンテキストに応じたファイルを使用する - backend/CLAUDE.md、frontend/CLAUDE.md など
3. 重複を避ける - 各ガイドラインは一度だけ記載します
4. 外部ドキュメントにリンクする - 公式ドキュメントをコピーしないでください
5. 定期的に更新する - 四半期ごと、または技術スタックの変更時にガイドラインを見直します

制限事項

技術的な制約

• テンプレートを正確に選択するには、有効なプロジェクトコンテキストが必要です
• 技術スタックの検出はキーワードに基づくため、手動での調整が必要な場合があります
• モジュール型ファイルの生成では、標準的なディレクトリ構造を前提としています

対象範囲

• プロジェクト固有のビジネスロジックではなく、CLAUDE.md の構成に焦点を当てています
• ベストプラクティスの推奨事項は一般的な内容のため、業界固有のカスタマイズが必要な場合があります
• 検証はガイドラインに基づくものであり、強制ではありません（承認なしで自動修正は行いません）

使用しない場合

• Claude 以外の AI ツールの場合（これは Claude Code 専用です）
• Claude Code や同様の AI アシスタントを使用しないプロジェクトの場合
• 高度に専門化された分野のガイドライン（法務、医療コンプライアンス）が必要な場合

テンプレートのカテゴリ

規模別

• 最小限（50 行） - 個人開発者、プロトタイプ、ハッカソン
• コア（100～150 行） - 小規模チーム、MVP、標準的なプロジェクト
• 詳細（200～300 行） - 大規模チーム、本番システム、エンタープライズ

プロジェクトの種類別

• Web アプリ - フロントエンド中心（React、Vue、Angular）
• API - バックエンドサービス（REST、GraphQL、マイクロサービス）
• フルスタック - フロントエンドとバックエンドを統合
• CLI - コマンドラインツールとユーティリティ
• ライブラリ - 再利用可能なパッケージとフレームワーク
• モバイル - React Native、Flutter、ネイティブ iOS/Android

技術スタック別

• TypeScript/Node - 最新の JavaScript エコシステム
• Python - Django、FastAPI、Flask
• Go - Gin、Echo、ネイティブサービス
• Java/Kotlin - Spring Boot、エンタープライズ Java
• Ruby - Rails、Sinatra

品質指標

ファイル品質スコア（0～100）

以下に基づいて算出します：

• 長さの適切さ（25 点） - 短すぎず、長すぎない
• セクションの網羅性（25 点） - 必須セクションが含まれている
• 書式の品質（20 点） - Markdown の構成が適切
• 内容の具体性（15 点） - 一般的な内容ではなく、プロジェクトに合わせて調整されている
• モジュール型の構成（15 点） - 適切な場合にサブディレクトリのファイルを使用している

推奨事項の優先度

• 重大 - 必須セクションが不足している、ファイルが長すぎる（400 行超）
• 高 - 重要なセクションが不足している、書式に問題がある
• 中 - 任意のセクションを追加できる、小規模な改善点がある
• 低 - あると便利な拡張、スタイル上の提案

高度な機能

モジュール型アーキテクチャのサポート

コンテキストに応じたファイルを自動生成します：

project-root/
├── CLAUDE.md                 # Root orchestrator (100-150 lines)
├── backend/
│   └── CLAUDE.md            # Backend-specific (150-200 lines)
├── frontend/
│   └── CLAUDE.md            # Frontend-specific (150-200 lines)
├── database/
│   └── CLAUDE.md            # Database operations (100-150 lines)
└── .github/
    └── CLAUDE.md            # CI/CD workflows (100-150 lines)

技術スタックの検出

以下から技術を自動検出します：

• package.json（Node.js/TypeScript）
• requirements.txt または pyproject.toml（Python）
• go.mod（Go）
• Cargo.toml（Rust）
• pom.xml または build.gradle（Java）

チーム規模への適応

詳細度を調整します：

• 個人：最小限のガイドライン。効率性を重視
• 小規模（10 人未満）：コアガイドラインとワークフローの基本
• 中規模（10～50 人）：詳細なガイドラインとチームの連携
• 大規模（50 人以上）：包括的なガイドラインとプロセスの徹底

参考資料

• Anthropic Claude Code ドキュメント: https://docs.claude.com/en/docs/claude-code
• CLAUDE.md のベストプラクティス: コミュニティのパターンと Anthropic のガイダンスに基づいています
• CLAUDE.md のサンプルファイル: examples/ フォルダーに、さまざまなプロジェクトの種類とチーム規模を対象とする 6 つの参考実装があります

バージョン

バージョン: 1.0.0 最終更新日: 2025年11月 対応: Claude Code 2.0+、Claude Apps、Claude API

覚えておいてください。目標は Claude の効率とコンテキスト認識を高めることであり、官僚的な手続きを増やすことではありません。シンプルに始め、実際の利用状況に基づいて改善し、可能であれば品質チェックを自動化してください。