cc-recommender CLAUDE.md

cc-recommender Development Guide

このドキュメントは、cc-recommender プロジェクトの開発ガイドラインを定義します。 新しいコードを追加・変更する際は、必ずこのガイドラインに従ってください。

プロジェクト概要

Claude Code のスキル、プラグイン、MCP サーバーを推薦する MCP サーバー。 プロジェクトを分析し、適切な拡張機能を提案します。

アーキテクチャ原則

1. レイヤードアーキテクチャ

presentation (tools) → business logic (services) → data access (repositories)
                    ↓
                 config, utils, types

依存関係のルール:

• 上位レイヤーは下位レイヤーに依存できる
• 下位レイヤーは上位レイヤーに依存してはいけない
• 同一レイヤー内での依存は最小限に

2. 単一責任の原則 (SRP)

• 各ファイルは1つの責務のみを持つ
• 大きくなりすぎた場合は分割を検討

3. 直接インポートの原則

原則: 直接個別ファイルからインポート

例外: 以下のディレクトリのみ index.ts を使用可能

• types/index.ts - 型定義の公開 API（頻繁に使用されるため）
• tools/handlers/index.ts - MCP ツールの公開 API（外部インターフェース）

// ✅ 許可: 公開 API からのインポート
import { Recommendation, ProjectInfo } from "../../types/index.js";
import { recommendSkills, searchSkills } from "../../tools/handlers/index.js";

// ✅ 推奨: その他は直接個別ファイルからインポート
import { analyzeProject } from "../../services/analyzer/project-analyzer.service.js";
import { calculateScore } from "../../services/recommender/scoring/scorer.js";

// ❌ 禁止: services/, config/, utils/ などに index.ts を作成
import { analyzeProject } from "../../services/analyzer/index.js"; // NG

理由:

• インポート元が明確
• 循環依存の防止
• 未使用コードの検出が容易
• 外部 API は index.ts で明示化
• 内部実装は直接インポートで変更に強く

ディレクトリ構造

src/
├── config/              # 設定ファイル（定数、マッピング）
│   ├── constants.ts     # アプリケーション定数
│   ├── file-mappings.ts # ファイル拡張子とフレームワークのマッピング
│   ├── curated-list-sources.ts # キュレーションリストソース定義
│   ├── direct-skill-sources.ts # 直接スキルソース定義
│   ├── env.ts           # 環境変数設定
│   └── scoring-config.ts # スコアリングの重み・閾値
│
├── repositories/        # データアクセス層
│   ├── recommendation.repository.ts # データベース読み込み・キャッシュ
│   └── remote-data.repository.ts    # リモートデータ取得（CDN/GitHub）
│
├── utils/              # 共通ユーティリティ
│   └── glob-matcher.ts # Glob パターンマッチング
│
├── types/              # 型定義（ドメイン別に分割）
│   ├── index.ts        # 型定義の公開 API
│   ├── domain-types.ts # ドメイン型（Recommendation, Author, etc.）
│   ├── service-types.ts # サービス型（ProjectInfo, ScoredRecommendation）
│   └── raw-types.ts    # 外部データ型（RawPluginEntry, etc.）
│
├── schemas/            # Zod バリデーションスキーマ
│   └── tool-schemas.ts # MCP ツールの入力スキーマ
│
├── services/           # ビジネスロジック層
│   ├── analyzer/       # プロジェクト分析サービス
│   │   ├── parsers/    # 言語別パーサー
│   │   │   ├── package-json.parser.ts
│   │   │   ├── requirements-txt.parser.ts
│   │   │   ├── go-mod.parser.ts
│   │   │   └── （その他言語用パーサー）
│   │   └── project-analyzer.service.ts # メイン分析ロジック
│   │
│   ├── fetchers/       # 外部データ取得
│   │   ├── mcp/        # MCP サーバー取得
│   │   │   ├── mcp-fetcher.ts
│   │   │   └── official-mcp-fetcher.ts
│   │   ├── plugins/    # プラグイン取得
│   │   │   └── plugin-fetcher.ts
│   │   └── skills/     # スキル取得
│   │       ├── common/  # 共通ユーティリティ
│   │       │   ├── github-api.ts # GitHub API 呼び出し
│   │       │   ├── skill-parser.ts # スキルパース処理
│   │       │   └── types.ts # フェッチャー用の内部型
│   │       ├── curated-list-fetcher.ts # キュレーションリスト取得
│   │       ├── direct-skill-fetcher.ts # 直接スキル取得
│   │       └── skill-fetcher.ts # メインフェッチャー
│   │
│   ├── recommender/    # 推薦サービス
│   │   ├── scoring/    # スコアリングロジック
│   │   │   └── scorer.ts
│   │   ├── recommendation.service.ts # メイン推薦ロジック
│   │   ├── search.service.ts         # 検索機能
│   │   ├── quality-scorer.ts         # 品質スコア算出
│   │   └── formatters.ts             # 結果フォーマッター
│   │
│   └── security-scanner.service.ts # セキュリティスコア取得
│
├── tools/              # MCP ツール層（プレゼンテーション）
│   └── handlers/       # 各ツールの実装
│       ├── index.ts    # ツールの公開 API
│       ├── recommend-skills.tool.ts
│       ├── search-skills.tool.ts
│       ├── get-skill-details.tool.ts
│       ├── list-categories.tool.ts
│       └── get-stats.tool.ts
│
├── server/             # MCP サーバー設定
│   ├── mcp-server.ts   # サーバーセットアップ
│   └── tool-registry.ts # ツール登録
│
└── index.ts            # エントリーポイント（最小限）