repo-research

リポジトリ調査

GitHub リポジトリを深く調査するツールです。主な目的は、外部プロジェクトから着想を得て、ユーザー自身のプロジェクトに役立つ実行可能な改善提案を提供することです。

対象範囲：このスキルは、Claude Skills に限らず、あらゆる種類の GitHub リポジトリの調査に使用できます。オープンソースプロジェクト、ライブラリ、フレームワーク、ツールなどを調査できます。

依存関係の管理

このスキルの主要機能（単一／複数リポジトリの調査）には、事前に必要なスキルはありません。

テーマ主導の検索モードを使用する場合に限り、次の任意の依存関係が必要です。

依存スキル	用途	インストール元	必須かどうか
find-skills	GitHub でテーマに関連するリポジトリを検索	https://skills.sh/vercel-labs/skills/find-skills	任意

使用方法：

• GitHub URL を直接指定した場合、このスキルは既存の単一／複数リポジトリ調査モードをそのまま使用します
• テーマキーワード（例：「OCR 関連プロジェクトを調査」）を指定した場合、このスキルは次の処理を行います。
  1. 最初に find-skills がインストール済みか確認します
  2. インストールされていない場合は、インストール後に続行するよう案内します
  3. インストール後、find-skills を自動的に呼び出して検索します

---

設定

このスキルでは、設定ファイルを使用して出力ディレクトリなどの設定をカスタマイズできます。

設定ファイルの場所

skills/repo-research/assets/config.yaml

クイック設定

1. 設定例をコピーします。

cp skills/repo-research/assets/config.example.yaml skills/repo-research/assets/config.yaml

2. config.yaml を編集し、出力ディレクトリを設定します。

research:
  output_dir: "~/Documents/研究笔记"  # 支持绝对路径、相对路径、~ 展开

設定項目の説明

設定項目	説明	デフォルト値
research.output_dir	調査レポートの出力ディレクトリ	./research
research.report_format	レポート形式	markdown
research.shallow_clone	シャロークローンを使用	true
security.enabled	セキュリティ分析を有効化	true
security.prompt_analysis	プロンプトのセキュリティ検査	true

設定の読み込みロジック

1. 检查 skills/repo-research/assets/config.yaml 是否存在
2. 如果存在，读取配置
3. 如果 output_dir 为空或不存在，使用默认值 ./research
4. 支持路径展开：
   - `~` 展开为用户目录
   - 相对路径基于当前工作目录

デフォルトの動作（設定ファイルがない場合）

設定ファイルがない場合、または output_dir が空の場合は、デフォルトの動作が使用されます。

• 出力ディレクトリ：./research（現在の作業ディレクトリ内の research フォルダー）
• レポート形式：Markdown
• セキュリティ分析：有効

---

クイックスタート

# 单个仓库研究
/repo-research https://github.com/user/repo

# 多仓库对比研究
/repo-research https://github.com/user/repo-a https://github.com/user/repo-b

# 指定分析重点
/repo-research https://github.com/user/repo --focus=architecture

# 与现有技能整合
/repo-research https://github.com/user/repo --integrate-with=de-ai-polish

会話中のトリガー：「このリポジトリを調査して」「これらのプロジェクトを比較分析して」「自分のプロジェクトにどんなヒントがある？」など、同様の表現をユーザーが使うと自動的に有効になります。

---

設定

設定ファイル

このスキルでは、設定ファイルを使用して出力ディレクトリなどの設定をカスタマイズできます。

設定ファイルの場所

~/.openclaw/skills/repo-research/assets/config.yaml

設定例

# 研究报告输出目录
# 支持绝对路径、相对路径和 ~ 展开
output_dir: "/Users/yourname/Desktop/Clawd/99 - 🦐 大虾研究/09 - 📋 研究报告"

# 报告格式：markdown 或 json
report_format: markdown

# 是否自动打开报告（生成后）
auto_open_report: false

# 克隆深度：1 = 浅克隆（更快），0 = 完整克隆
clone_depth: 1

環境変数による上書き

環境変数でも設定できます（設定ファイルより優先されます）。

環境変数	説明
REPO_RESEARCH_OUTPUT_DIR	出力ディレクトリ
REPO_RESEARCH_FORMAT	レポート形式
REPO_RESEARCH_AUTO_OPEN	自動で開くかどうか
REPO_RESEARCH_CLONE_DEPTH	クローンの深さ

出力ディレクトリの構成

output_dir/
└── research/
    └── YYYYMMDD-topic-slug/
        ├── repo-name/                    # 克隆的仓库
        ├── repo-name-2/                  # 多仓库时有多个
        └── topic-slug-report.md          # 研究报告（如：twitter-skills-report.md）

---

ワークフロー

モードの選択

入力に応じて調査モードが自動的に選択されます。

入力の種類	調査モード	出力
GitHub URL が1つ	単一リポジトリの詳細調査	単一リポジトリの分析レポート＋着想に基づく提案
GitHub URL が複数	複数リポジトリの比較調査	比較分析レポート＋共通の着想
GitHub URL＋ローカルパス	比較・着想モード	差分分析＋改善提案
テーマ／キーワード	テーマ主導の検索調査	検索結果＋複数リポジトリの統合分析レポート

---

テーマ主導の検索調査モード

具体的な GitHub URL ではなく、テーマキーワードが指定された場合にこのモードを使用します。

起動条件

ユーザーが次のような要望を表したときに自動的に有効になります。

• 「X に関連するプロジェクトを探して」
• 「テーマ X を検索して調査して」
• 「X に関するオープンソースプロジェクトを探して」
• 「テーマ X で調査する価値のあるリポジトリはある？」

ワークフロー

Step 0: 依存関係の確認

# 检查 find-skills 是否已安装
if ! /find-skills --help >/dev/null 2>&1; then
    echo "⚠️  主题驱动搜索模式需要 find-skills 技能"
    echo "正在为您安装..."
    /skill-manager install https://skills.sh/vercel-labs/skills/find-skills
fi

会話での案内：

「テーマ検索機能を使用する必要があることを検出しました。依存関係を確認しています……」

Step 1: find-skills で関連リポジトリを検索

find-skills スキルを呼び出して検索します。

/find-skills <主题关键词>

例：

• /find-skills pdf converter - PDF 変換関連のスキルを検索
• /find-skills video transcription - 動画の文字起こし関連のスキルを検索
• /find-skills ocr - OCR 関連のスキルを検索

Step 2: 検索結果の整理

find-skills の結果から、次の項目を抽出します。

1. リポジトリ名
2. GitHub URL
3. 簡単な説明
4. 関連度スコア

検索結果の整理形式：

#	リポジトリ名	URL	説明	関連度
1	[name]	[url]	[説明]	⭐⭐⭐⭐⭐
2	[name]	[url]	[説明]	⭐⭐⭐⭐☆

Step 3: ユーザーによる確認と絞り込み

会話での質問：

「関連するリポジトリが [N] 件見つかりました。詳しく調査するプロジェクトを選択してください。」 「1. [N] 件すべてを調査」 「2. 番号を指定して選択（例：1,3,5）」 「3. 関連度の高い上位 [K] 件のみを調査」 「4. 独自に選択」

ユーザーの選択に基づいて、最終的な調査対象リストを決定します。

Step 4: 一括クローンと並列分析

4.1 調査ディレクトリの作成

⚠️ 重要：設定ファイルにある output_dir を優先して使用し、未設定の場合は現在の作業ディレクトリを使用します。

Python 方式（推奨）：

from scripts.config import get_research_dir

# 自动读取配置文件，返回研究目录路径
RESEARCH_DIR = get_research_dir(topic_slug)

Bash 方式（後方互換用）：

# 优先使用配置文件中的 output_dir，否则使用当前目录
SKILL_DIR="$HOME/.openclaw/skills/repo-research"
CONFIG_FILE="$SKILL_DIR/assets/config.yaml"

# 尝试从配置文件读取 output_dir
if [ -f "$CONFIG_FILE" ] && command -v python3 &> /dev/null; then
    OUTPUT_DIR=$(python3 -c "
from pathlib import Path
import sys
sys.path.insert(0, '$SKILL_DIR/scripts')
from config import get_output_dir
print(get_output_dir())
" 2>/dev/null)
else
    OUTPUT_DIR="${PWD}"
fi

RESEARCH_DATE=$(date +%Y%m%d)
# 将主题转换为 slug 格式（小写、空格替换为连字符）
TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')

# 使用绝对路径确保在正确位置
RESEARCH_DIR="${OUTPUT_DIR}/research/${RESEARCH_DATE}-${TOPIC_SLUG}"
mkdir -p "${RESEARCH_DIR}"
cd "${RESEARCH_DIR}"

4.2 一括クローン

for url in "${SELECTED_URLS[@]}"; do
    repo_name=$(basename "$url" .git)
    echo "正在克隆: $repo_name"
    git clone --depth 1 "$url" "$repo_name"
done

4.3 並列分析

クローンした各リポジトリに基本分析を実行します（「Step 2: 基本分析」を参照）。

Step 5: テーマの統合レポートを作成

テンプレートとして assets/topic-research-template.md を使用します。

レポートの構成

# [主题] 综合研究报告

> **研究日期**：YYYY-MM-DD
> **搜索主题**：[主题关键词]
> **研究仓库数**：[N] 个
> **报告路径**：`./research/YYYYMMDD-[topic-slug]/[topic-slug]-report.md`

---

## 执行摘要

### 研究概述

[用一段话概括：基于主题搜索了哪些类型的仓库，主要发现了什么]

### 一句话总结

[用一句话概括最关键的发现]

### 核心指标

| 指标 | 数值 |
|:-----|:-----|
| 搜索结果总数 | [N] 个仓库 |
| 深度研究数量 | [M] 个仓库 |
| 相关技术栈 | [列举主要技术] |
| 活跃项目占比 | [X%] |

---

## 搜索结果概览

### 仓库清单

| # | 仓库名 | 描述 | 语言 | Stars | 活跃度 |
|:-|:-------|:-----|:-----|:-----|:-------|
| 1 | [name] | [描述] | [lang] | [★] | 🟢 活跃 |
| 2 | [name] | [描述] | [lang] | [★] | 🟡 中等 |

### 分类汇总

**按技术类型**：
- [技术1]: [数量] 个项目
- [技术2]: [数量] 个项目

**按功能类型**：
- [功能1]: [数量] 个项目
- [功能2]: [数量] 个项目

---

## 技术栈分析

### 主流技术选择

| 技术 | 使用项目数 | 占比 | 代表项目 |
|:-----|-----------|:-----|:---------|
| [技术1] | [N] | [X%] | [项目A, 项目B] |
| [技术2] | [N] | [X%] | [项目C] |

### 技术趋势洞察

- **趋势1**：[描述观察到的技术趋势]
- **趋势2**：[描述观察到的技术趋势]

---

## 共性模式识别

### 架构共性

多个项目共同采用的架构模式：
1. **[模式名称]**：[描述]
   - 采用项目：[列举]
   - 优势分析：[分析]

### 功能共性

多个项目都实现的核心功能：
1. **[功能名称]**：[描述]
   - 实现方式差异：[对比]

### 文档共性

文档编写的共同特点：
- [观察到的文档模式]

---

## 项目对比分析

### 功能对比矩阵

| 功能 | 项目1 | 项目2 | 项目3 | 最优实现 |
|:-----|:-----|:-----|:-----|:---------|
| [功能1] | ✅ | ✅ | ❌ | [分析] |
| [功能2] | ✅ | ❌ | ✅ | [分析] |

### 架构对比

| 维度 | 项目1 | 项目2 | 项目3 | 值得学习 |
|:-----|:-----|:-----|:-----|:---------|
| 目录结构 | [描述] | [描述] | [描述] | [推荐] |
| 模块化 | [描述] | [描述] | [描述] | [推荐] |

### 代码质量对比

| 项目 | 代码组织 | 文档 | 测试 | 综合评分 |
|:-----|:---------|:-----|:-----|:---------|
| 项目1 | ⭐⭐⭐⭐☆ | ⭐⭐⭐☆☆ | ⭐⭐☆☆☆ | B+ |
| 项目2 | ⭐⭐⭐☆☆ | ⭐⭐⭐⭐☆ | ⭐⭐⭐☆☆ | B |

---

## 深度剖析（精选项目）

### 项目 A: [仓库名]

#### 为什么值得深入研究

[说明选择这个项目进行深度剖析的原因]

#### 架构亮点

- [亮点1]
- [亮点2]

#### 可借鉴的设计

1. **[设计点1]**：[描述可借鉴之处]
2. **[设计点2]**：[描述可借鉴之处]

### 项目 B: [仓库名]

[同上结构]

---

## 启发与建议

### 对本地项目的启发

#### 可直接借鉴

1. **[方面1]**
   - **来源**：[项目A/项目B]
   - **做法**：[描述具体做法]
   - **本地应用**：[如何应用到本地项目]
   - **优先级**：🔴 高 / 🟡 中 / 🟢 低
   - **预计工作量**：[X 小时]

#### 需要进一步探索

1. **[技术/模式]**
   - **为什么**：[说明价值]
   - **调研方式**：[如何调研]
   - **预期收益**：[说明]

### 最佳实践总结

从多个项目中提炼的最佳实践：
1. **[实践1]**：[描述]
2. **[实践2]**：[描述]

---

## 项目推荐

### 不同场景推荐

| 场景 | 推荐项目 | 理由 |
|:-----|:---------|:-----|
| 学习参考 | [项目名] | [理由] |
| 生产使用 | [项目名] | [理由] |
| 二次开发 | [项目名] | [理由] |
| 特定需求 | [项目名] | [理由] |

### 快速决策指南

- **如果你需要 X** → 推荐 [项目A]
- **如果你需要 Y** → 推荐 [项目B]
- **如果你需要 Z** → 推荐 [项目C]

---

## 附录

### 完整仓库列表

#### 深度研究的项目

1. **[项目名]** - [GitHub URL]
   - 描述：[描述]
   - 技术栈：[列举]
   - 最后更新：[日期]

#### 仅浏览的项目

1. **[项目名]** - [GitHub URL]
   - 相关度：⭐⭐☆☆☆

### 参考资源

- [相关文档链接]
- [相关文章链接]

---

**报告生成时间**：YYYY-MM-DD HH:MM
**研究者**：Claude Code + repo-research skill
**搜索工具**：find-skills skill

Step 6: セッションの報告

## 主题研究完成

**搜索主题**：[主题关键词]

**搜索结果**：找到 [N] 个相关仓库，深度分析了 [M] 个

**核心发现**：
1. [发现1]
2. [发现2]
3. [发现3]

**推荐项目**：
- 学习参考：[项目A]
- 生产使用：[项目B]

**详细报告已保存至**：`./research/YYYYMMDD-[topic-slug]/[topic-slug]-report.md`

---

従来の調査モード

（以下は従来の内容をそのまま保持……）

Step 1: 調査環境の準備

1.0 設定ファイルの読み込み

⚠️ 重要：最初に設定ファイルを読み込み、出力ディレクトリを確認します。

# 读取配置文件逻辑（在开始研究前执行）
import yaml
from pathlib import Path

def get_output_dir():
    """获取输出目录，优先使用配置文件中的设置"""

    # 默认输出目录
    default_output = "./research"

    # 配置文件路径
    skill_dir = Path(__file__).parent  # skill 所在目录
    config_path = skill_dir / "assets" / "config.yaml"

    if not config_path.exists():
        return default_output

    try:
        with open(config_path, 'r', encoding='utf-8') as f:
            config = yaml.safe_load(f)

        output_dir = config.get('research', {}).get('output_dir', '')

        if not output_dir or output_dir.strip() == '':
            return default_output

        # 展开 ~ 和环境变量
        output_dir = Path(output_dir).expanduser()

        # 如果是相对路径，基于当前工作目录
        if not output_dir.is_absolute():
            output_dir = Path.cwd() / output_dir

        return str(output_dir)

    except Exception:
        return default_output

1.1 調査ディレクトリの作成

統一されたディレクトリ構成：

research/
└── YYYYMMDD-[topic]/    # 日期+主题目录
    ├── repo-name/       # 研究的仓库（即使是单个仓库也在子目录中）
    ├── repo-b/          # 多仓库时会有多个子目录
    └── [topic-slug]-report.md        # 研究报告

# 单仓库示例：
# ~/Documents/研究笔记/20260213-vibe-working-tutorial/
#     └── vibe-working-tutorial/   <- 仓库内容
#     └── [topic-slug]-report.md

# 多仓库示例：
# ./research/20260213-pdf-tools-comparison/
#     ├── pdf-lib/
#     └── pdfkit/
#     └── [topic-slug]-report.md

設計原則：調査するリポジトリの数にかかわらず、${OUTPUT_DIR}/日付-テーマ/リポジトリ名/ という統一された構成を維持し、後からの管理や拡張を容易にします。

命名形式：YYYYMMDD-[topic-slug]

• topic-slug：テーマキーワードをハイフンでつないだ小文字の文字列
• 例：20260211-pdf-ocr-comparison、20260212-transcription-study

テーマの取得元（優先順位の高い順）：

1. ユーザー指定：呼び出し時に --topic パラメーターで指定
2. 会話での質問：短いテーマの説明をユーザーに自動で尋ねる
3. 自動推定：リポジトリ名または調査内容から推定（予備）

Bash ツールを使用して実行します。

⚠️ 重要：

1. 最初に skills/repo-research/assets/config.yaml を読み込み、output_dir を取得します
2. 設定ファイルがない場合、または output_dir が空の場合は、デフォルト値 ./research を使用します
3. パスでは ~ の展開と相対パスを使用できます

# Step 1: 读取配置文件获取输出目录
# 默认输出目录
OUTPUT_DIR="./research"

# 检查配置文件是否存在
CONFIG_FILE="skills/repo-research/assets/config.yaml"
if [ -f "$CONFIG_FILE" ]; then
    # 使用 grep 简单提取 output_dir（避免依赖 Python/yaml）
    CONFIG_OUTPUT=$(grep -E "^\s*output_dir:" "$CONFIG_FILE" | head -1 | sed 's/.*output_dir:[[:space:]]*//')
    # 移除引号
    CONFIG_OUTPUT=$(echo "$CONFIG_OUTPUT" | tr -d "\"'")
    # 如果非空，使用配置值
    if [ -n "$CONFIG_OUTPUT" ] && [ "$CONFIG_OUTPUT" != '""' ]; then
        # 展开 ~ 为用户目录
        OUTPUT_DIR="${CONFIG_OUTPUT/#\~/$HOME}"
    fi
fi

# Step 2: 如果是相对路径，基于当前工作目录
if [[ "$OUTPUT_DIR" != /* ]]; then
    OUTPUT_DIR="${PWD}/${OUTPUT_DIR}"
fi

# Step 3: 创建研究目录
REPO_DATE=$(date +%Y%m%d)
TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')

RESEARCH_DIR="${OUTPUT_DIR}/${REPO_DATE}-${TOPIC_SLUG}"
mkdir -p "${RESEARCH_DIR}"
cd "${RESEARCH_DIR}"

echo "研究目录已创建: ${RESEARCH_DIR}"

テーマについての質問：

「今回の調査に使う短いテーマの説明を入力してください（ディレクトリ名に使用します。例：pdf-ocr、agent-framework）：」

1.2 リポジトリのクローン

⚠️ 重要：単一リポジトリでも複数リポジトリでも、ディレクトリ構成を統一するため、すべてサブディレクトリにクローンします。

# 统一方式：所有仓库都克隆到子目录
# 这样可以保持 research/日期-主题/ 目录结构的一致性
# 单仓库和多仓库的区别只在于克隆的次数

for url in "${URLS[@]}"; do
    repo_name=$(basename "$url" .git)
    git clone --depth 1 "$url" "$repo_name"
done

# 单仓库示例（实际也是克隆到子目录）：
# research/20260213-vibe-working-tutorial/
#     └── vibe-working-tutorial/   <- 仓库内容
#     └── [topic-slug]-report.md                <- 研究报告

# 多仓库示例：
# research/20260213-pdf-tools-comparison/
#     └── pdf-lib/                 <- 仓库A
#     └── pdfkit/                  <- 仓库B
#     └── [topic-slug]-report.md                <- 研究报告

---

Step 2: 基本分析（各リポジトリに対して）

2.1 プロジェクトの種類を特定する

特徴	プロジェクトの種類	分析の重点
package.json	Node.js/フロントエンド	依存関係、スクリプト、ビルド設定
requirements.txt/pyproject.toml	Python	仮想環境、依存関係管理
go.mod	Go	モジュール構造、依存関係
Cargo.toml	Rust	Edition、機能、依存関係
SKILL.md	Claude Skill	スキル定義、frontmatter

2.2 コアファイルを優先して読む

# 必读文件（按优先级）
README.md          # 项目说明、快速开始
LICENSE            # 许可证
package.json/pyproject.toml/go.mod  # 依赖元数据

2.3 プロジェクト構造を分析する

Glob ツールを使って調べます。

glob "**/*"           # 所有文件
glob "**/*.md"        # 文档
glob "src/**/*.ts"    # 源代码
glob "tests/**/*"     # 测试

2.4 技術スタックを特定する

• フロントエンド：React/Vue/Svelte/Next.js/Nuxt + 状態管理 + スタイル方式
• バックエンド：Node.js/Python/Go/Rust + フレームワーク + ORM
• ツールチェーン：Vite/Webpack + Jest/Pytest + ESLint/Prettier

---

ステップ 3：複数リポジトリの比較分析（複数リポジトリモード）

3.1 比較の観点

観点	比較内容	気づきのポイント
アーキテクチャ設計	ディレクトリ構造、モジュール分割	参考にできる構成方法は何か
機能の実装	コア機能、API 設計	同種の機能における異なる実装方法
技術選定	フレームワーク、依存関係、ツールチェーン	なぜこれらの技術が選ばれているのか
ドキュメントの品質	README、コメント、API ドキュメント	ドキュメントの書き方の違い
コードスタイル	命名、構造、パターン	どのスタイルがより明確か

3.2 共通点の抽出

複数のリポジトリに共通する点を特定します。

• 共通する技術選定（例：どれも Markdown をフォーマットとして使用）
• 共通する設計パターン（例：どれもプラグインアーキテクチャを使用）
• 共通する問題解決方法

3.3 違いの分析

主な違いとその理由を特定します。

• なぜ A は Markdown を使い、B は JSON を使うのか
• なぜ A にはテストがあり、B にはないのか
• 異なる実装方法の長所と短所

---

ステップ 4：ローカルプロジェクトとの比較（気づきモード）

4.1 ローカルプロジェクトを特定する

会話で質問します：

「ローカルプロジェクトと比較しますか？必要な場合は、プロジェクトのパス（相対パスまたは絶対パス）を指定してください。」

よくあるローカルプロジェクトの種類：

• ./test/de-ai-polish - ローカルスキル
• ./skills/xxx - 既存のスキル
• ./test/yyy - テストプロジェクト

4.2 差異分析のフレームワーク

分析項目	外部リポジトリ	ローカルプロジェクト	違い	気づき
ディレクトリ構造	[説明]	[説明]	[相違点]	[参考にできる点]
コア機能	[説明]	[説明]	[相違点]	[補完できる点]
ドキュメントの方式	[説明]	[説明]	[相違点]	[改善できる点]
検出ルール	[列挙]	[列挙]	[相違点]	[学べる点]

4.3 気づきを得るための質問

比較するときは、次の質問に答えます。

1. 機能について

   • 外部リポジトリにあって、自分にはない機能は何か
   • 自分にあって、外部リポジトリにない機能は何か
   • 取り入れられる機能はどれか

2. アーキテクチャについて

   • 外部リポジトリのディレクトリ構造は、より明確か
   • モジュールの分割方法は参考になるか
   • 設定方法はより柔軟か

3. 実装について

   • 検出ルールの整理方法にはどのような違いがあるか
   • レポート生成形式にはどのような長所と短所があるか
   • ユーザーとのやり取りの方法から学べることは何か

4. ドキュメントについて

   • README の構成はより理解しやすいか
   • 例はより豊富か
   • API ドキュメントはより充実しているか

---

ステップ 5：レポートを生成する

5.1 単一リポジトリレポートの構成

テンプレートとして assets/report-template.md を使用します。

5.2 複数リポジトリ比較レポートの構成

テンプレートとして assets/comparison-template.md を使用します。

5.3 気づきレポートの構成

# [研究主题] 启发式分析报告

> 研究日期：YYYY-MM-DD
> 研究仓库：[列出所有仓库]
> 对比项目：[本地项目路径]
> 报告路径：`./research/YYYYMMDD-[topic-slug]/[topic-slug]-report.md`

---

## 核心发现

### 一句话总结

[用一句话概括最关键的启发]

---

## 对比分析

### 功能对比

| 功能 | 仓库A | 仓库B | 本地项目 | 启发 |
|:-----|:------|:------|:---------|:-----|
| [功能1] | ✅ | ✅ | ❌ | [建议] |
| [功能2] | ✅ | ❌ | ✅ | [分析] |

### 架构对比

| 维度 | 仓库A | 仓库B | 本地项目 | 启发 |
|:-----|:------|:------|:---------|:-----|
| 目录结构 | [描述] | [描述] | [描述] | [建议] |
| 模块划分 | [描述] | [描述] | [描述] | [建议] |

### 规则/检测方式对比

| 检测项 | 仓库A | 仓库B | 本地项目 | 启发 |
|:-------|:------|:------|:---------|:-----|
| [规则1] | [实现] | [实现] | [实现] | [可学习] |

---

## 具体启发

### 可直接借鉴的方面

1. **[方面1]**
   - **外部做法**：[描述]
   - **本地现状**：[描述]
   - **改进建议**：[具体建议]
   - **优先级**：高/中/低

2. **[方面2]**
   - **外部做法**：[描述]
   - **本地现状**：[描述]
   - **改进建议**：[具体建议]
   - **优先级**：高/中/低

### 需要进一步探索的方面

1. **[方面1]**：[为什么值得探索]
2. **[方面2]**：[为什么值得探索]

---

## 行动建议

### 立即可做的改进

- [ ] [改进1] - 预计时间：[X小时]
- [ ] [改进2] - 预计时间：[X小时]

### 需要进一步调研的

- [ ] [调研项1] - 调研方式：[如何调研]
- [ ] [调研项2] - 调研方式：[如何调研]

---

## 附录

### 仓库详细信息

- **仓库A**：[名称](URL) - [一句话描述]
- **仓库B**：[名称](URL) - [一句话描述]

### 参考链接

- [相关文档]
- [相关文章]

5.4 セッション報告の形式

## 研究完成

**研究仓库**：
- [仓库名A]：[一句话描述]
- [仓库名B]：[一句话描述]

**对比项目**：[本地项目路径]

**核心启发**：
1. [启发1]
2. [启发2]
3. [启发3]

**立即可做的改进**：
- [ ] [改进1]
- [ ] [改进2]

**详细报告已保存至**：`./research/YYYYMMDD-[topic-slug]/[topic-slug]-report.md`

---

ベストプラクティス

調査戦略

1. 気づきを優先：調査の最終的な目的は「自分にとって何の役に立つか」です
2. 比較を軸にする：比較を通して違いを見つけ、その違いから気づきを得ます
3. 具体的で実行可能にする：気づきを具体的な改善提案に落とし込みます

気づきを引き出す原則

1. 違いから学ぶ：実装方法が異なれば、その背景に異なる考慮事項があることが多いです
2. 共通点からまとめる：複数のリポジトリが共通して選択している方法には、多くの場合理由があります
3. 細部から読み取る：小さな細部に設計思想が表れていることがあります

---

リソース

assets/

• report-template.md：単一リポジトリレポートのテンプレート
• comparison-template.md：複数リポジトリ比較レポートのテンプレート
• topic-research-template.md：トピック主導の検索調査レポートのテンプレート（新規）

---

高度な機能 (v0.4.0)

Zread MCP の実装方法を参考に、ローカル分析機能を強化します。

1. コードのセマンティック検索

ローカルにクローン済みのリポジトリを利用して、コードを詳細に検索します。

起動方法

ユーザーが次のような要望を示したときに起動します。

• 「関数 X を検索」
• 「クラス Y を探す」
• 「このプロジェクトが Z をどう実装しているか確認」
• --search パラメーターを直接使用

使用方法

# 搜索函数定义
/repo-research https://github.com/user/repo --search="function:parse*"

# 搜索类定义
/repo-research https://github.com/user/repo --search="class:*Handler"

# 搜索导入
/repo-research https://github.com/user/repo --search="import:react"

# 搜索特定模式
/repo-research https://github.com/user/repo --search="pattern:console\.log"

内部実装

scripts/search.py の CodeSearcher クラスを呼び出します。

• Grep ツールを使ってパターンマッチングを実行
• 複数の言語に対応：Python, JavaScript, TypeScript, Go, Rust, Java
• 複数のパターンに対応：function, class, import, doc, pattern

---

2. 詳細なコード分析

基本的な分析を超えて、アーキテクチャや品質の側面から詳細な洞察を提供します。

分析の種類

種類	説明	起動パラメーター
アーキテクチャ分析	ディレクトリ構造、モジュール分割、エントリーファイル、アーキテクチャパターン	--analyze=architecture
品質分析	コード統計、コメント率、技術的負債、潜在的な問題	--analyze=quality
完全分析	アーキテクチャと品質の両方の観点を含む	--analyze=full

使用方法

# 架构分析
/repo-research https://github.com/user/repo --analyze=architecture

# 质量分析
/repo-research https://github.com/user/repo --analyze=quality

# 完整分析
/repo-research https://github.com/user/repo --analyze=full

内部実装

• アーキテクチャアナライザー (scripts/analyzer/architecture.py):

  • ディレクトリ構造の分析
  • エントリーファイルの特定
  • モジュール／パッケージ構造の特定
  • 設定ファイルの検出
  • アーキテクチャパターンの検出（MVC、マイクロサービス、プラグイン、monorepo）

• 品質アナライザー (scripts/analyzer/quality.py):

  • コード統計（行数、言語の分布）
  • コメントのカバレッジ分析
  • 技術的負債の検出（TODO、FIXME、deprecated）
  • 問題の検出（ハードコードされたキー、console.log、大きなファイル）

---

3. インテリジェントな質疑応答

Claude Code の LLM 機能を利用して、リポジトリについての自然言語での質問に回答します。

起動方法

ユーザーが次のような要望を示したときに起動します。

• 「このプロジェクトは何をするものですか？」
• 「このプロジェクトはどのように使いますか？」
• 「アーキテクチャはどのようになっていますか？」
• 「主なモジュールは何ですか？」
• --ask パラメーターを直接使用

使用方法

# 询问项目概述
/repo-research https://github.com/user/repo --ask="这个项目是做什么的？"

# 询问使用方法
/repo-research https://github.com/user/repo --ask="如何使用这个项目？"

# 询问架构
/repo-research https://github.com/user/repo --ask="架构是怎样的？"

内部実装

1. 質問の分類（scripts/qa.py の QuestionClassifier）：

   • 意図の認識：overview, architecture, usage, api, dependencies
   • エンティティの抽出：機能名、コンポーネント名、ファイル名
   • コンテキストの特定：読み取る必要があるファイル

2. 回答の生成：

   • Grep/Glob で関連コードを検索
   • read_file で重要なファイルを読み取る
   • Claude Code の LLM 機能を組み合わせて、自然言語の回答を生成

---

4. 組み合わせて使用する

高度な機能を組み合わせて、より強力な分析を実現できます。

# 搜索 + 分析
/repo-research https://github.com/user/repo --search="function:parse*" --analyze=architecture

# 问答 + 报告
/repo-research https://github.com/user/repo --ask="这个项目如何使用？" --output=report

---

scripts/ ディレクトリ構造

scripts/
├── __init__.py           # 模块导出
├── search.py             # 语义搜索
├── qa.py                 # 智能问答
├── architecture.py       # 架构分析
├── quality.py            # 质量分析
└── security.py           # 安全分析 (v0.5.0 新增)

---

セキュリティ分析モジュール (v0.5.0)

OWASP Agentic AI Top 10 と一般的な脆弱性パターンに基づいて設計されており、スキル内に存在する可能性のある悪意のあるコードやセキュリティ上のリスクを特定します。

起動方法

# 安全分析模式
/repo-research https://github.com/user/skill --analyze=security

# 完整分析（包含安全）
/repo-research https://github.com/user/skill --analyze=full

检测能力

类别	检测内容	风险等级
命令执行	os.system, subprocess, eval(), exec()	🔴 高
敏感文件访问	读写 ~/.ssh/, ~/.aws/, .env 等	🔴 高
网络外泄	HTTP POST、WebSocket、数据上传	🟡 中
代码混淆	base64.b64decode, chr() 拼接等	🔴 高
权限提升	sudo, chmod 777, 修改 PATH	🔴 高
硬编码凭证	API Key、Token、Password	🔴 高
下载执行	`curl	bash, wget
持久化	crontab, systemd, LaunchAgents	🟡 中
Skill 特有	安装钩子、MCP 服务器风险	🟡 中

风险等级

等级	条件	建议
🔴 critical	存在命令执行、下载执行等	强烈不建议使用，需完整审计
🟠 high	多个高危发现或硬编码凭证	审计后使用，限制权限
🟡 medium	少量中危发现	使用前检查，测试环境验证
🟢 low	仅低危或无发现	可安全使用

使用示例

# 分析一个 skill 的安全性
/repo-research https://github.com/example/skill --analyze=security

# 在研究报告对话框中，会自动包含安全分析章节
# 如果检测到高风险，会有明显的警告提示

未来计划

• 依赖分析模块 (dependency analysis)
• 性能分析模块 (performance analysis)
• 更智能的问答系统