repository-analyzer

リポジトリ解析ツール

目的

構造を自動的にスキャンし、技術スタックを検出して、依存関係をマッピングし、包括的なドキュメントを生成することで、なじみのないコードベースをすばやく理解できます。

SDAM ユーザー向け：後から参照できる、コードベースの構造に関する外部ドキュメントを作成します。 ADHD のあるユーザー向け：手動で調べることなく、すぐに概要を把握できます。コンテキストの切り替えにかかる時間を何時間も節約できます。 すべてのユーザー向け：新しいプロジェクトへの参加準備を、数日ではなく数分で済ませられます。

起動条件

• ユーザーが「リポジトリを解析して」「コードベースを理解したい」「プロジェクトをドキュメント化して」と言う
• 「このリポジトリには何がある？」「これはどう動く？」「コードベースの概要を知りたい」と依頼する
• 新しいプロジェクトへの参加準備を行う
• 技術的負債の評価を依頼する

基本的なワークフロー

1. リポジトリ構造をスキャンする

ステップ 1：ディレクトリ構造を取得する

# Use filesystem tools to map structure
tree -L 3 -I 'node_modules|.git|dist|build'

ステップ 2：種類別にファイル数を数える

# Identify languages used
find . -type f -name "*.js" | wc -l
find . -type f -name "*.py" | wc -l
find . -type f -name "*.go" | wc -l
# etc...

ステップ 3：コードベースの規模を測定する

# Count lines of code
cloc . --exclude-dir=node_modules,.git,dist,build

2. 技術スタックを検出する

言語：JavaScript、TypeScript、Python、Go、Rust、Java など

フレームワーク：

• フロントエンド：React、Vue、Angular、Svelte
• バックエンド：Express、FastAPI、Django、Rails
• モバイル：React Native、Flutter
• デスクトップ：Electron、Tauri

検出方法：

const detectFramework = async () => {
  // Check package.json
  const packageJson = await readFile('package.json');
  const dependencies = packageJson.dependencies || {};

  if ('react' in dependencies) return 'React';
  if ('vue' in dependencies) return 'Vue';
  if ('express' in dependencies) return 'Express';

  // Check requirements.txt
  const requirements = await readFile('requirements.txt');
  if (requirements.includes('fastapi')) return 'FastAPI';
  if (requirements.includes('django')) return 'Django';

  // Check go.mod
  const goMod = await readFile('go.mod');
  if (goMod.includes('gin-gonic')) return 'Gin';

  return 'Unknown';
};

3. 依存関係をマッピングする

Node.js の場合：

# Read package.json
cat package.json | jq '.dependencies'
cat package.json | jq '.devDependencies'

# Check for outdated packages
npm outdated

Python の場合：

# Read requirements.txt or pyproject.toml
cat requirements.txt

# Check for outdated packages
pip list --outdated

Go の場合：

# Read go.mod
cat go.mod

# Check for outdated modules
go list -u -m all

4. アーキテクチャパターンを特定する

検出する一般的なパターン：

• MVC（Model-View-Controller）：models/、views/、controllers/
• レイヤード：api/、services/、repositories/
• 機能ベース：features/auth/、features/users/
• ドメイン駆動：domain/、application/、infrastructure/
• マイクロサービス：services/ ディレクトリ内に複数のサービスがある
• モノレポ：ワークスペースまたはパッケージ構成

検出ロジック：

const detectArchitecture = (structure) => {
  if (structure.includes('models') && structure.includes('views') && structure.includes('controllers')) {
    return 'MVC Pattern';
  }
  if (structure.includes('features')) {
    return 'Feature-based Architecture';
  }
  if (structure.includes('domain') && structure.includes('application')) {
    return 'Domain-Driven Design';
  }
  if (structure.includes('services') && structure.includes('api-gateway')) {
    return 'Microservices Architecture';
  }
  return 'Custom Architecture';
};

5. 技術的負債を抽出する

指標を検索する：

# Find TODOs
grep -r "TODO" --include="*.js" --include="*.py" --include="*.go"

# Find FIXMEs
grep -r "FIXME" --include="*.js" --include="*.py" --include="*.go"

# Find HACKs
grep -r "HACK" --include="*.js" --include="*.py" --include="*.go"

# Find deprecated code
grep -r "@deprecated" --include="*.js" --include="*.ts"

複雑さを分析する：

// Identify long functions (potential refactor targets)
const analyzeFunctions = () => {
  // Functions > 50 lines = high complexity
  // Functions > 100 lines = very high complexity
  // Cyclomatic complexity > 10 = needs refactoring
};

6. ドキュメントを生成する

出力形式：

# {Project Name} - Repository Analysis

**Generated:** {timestamp}
**Analyzed by:** Claude Code Repository Analyzer

---

## 📊 Overview

**Primary Language:** {language}
**Framework:** {framework}
**Architecture:** {architecture pattern}
**Total Files:** {count}
**Lines of Code:** {LOC}
**Last Updated:** {git log date}

---

## 📁 Directory Structure

project/ ├── src/ │ ├── components/ │ ├── services/ │ └── utils/ ├── tests/ └── docs/

---

## 🛠 Technologies

### Frontend
- React 18.2.0
- TypeScript 5.0
- Tailwind CSS 3.3

### Backend
- Node.js 18
- Express 4.18
- PostgreSQL 15

### DevOps
- Docker
- GitHub Actions
- Jest for testing

---

## 📦 Dependencies

### Production (12 packages)
- express: 4.18.2
- pg: 8.11.0
- jsonwebtoken: 9.0.0
- ...

### Development (8 packages)
- typescript: 5.0.4
- jest: 29.5.0
- eslint: 8.40.0
- ...

### ⚠️ Outdated (3 packages)
- express: 4.18.2 → 4.19.0 (minor update available)
- jest: 29.5.0 → 29.7.0 (patch updates available)

---

## 🏗 Architecture

**Pattern:** Layered Architecture

**Layers:**
1. **API Layer** (`src/api/`): REST endpoints, request validation
2. **Service Layer** (`src/services/`): Business logic
3. **Repository Layer** (`src/repositories/`): Database access
4. **Models** (`src/models/`): Data structures

**Data Flow:**

クライアント → API → サービス → リポジトリ → データベース

---

## 🔍 Code Quality

**Metrics:**
- Average function length: 25 lines
- Cyclomatic complexity: 3.2 (low)
- Test coverage: 78%
- TypeScript strict mode: ✅ Enabled

**Strengths:**
- ✅ Well-structured codebase
- ✅ Good test coverage
- ✅ Type-safe with TypeScript

**Areas for Improvement:**
- ⚠️ 12 TODOs found (see Technical Debt section)
- ⚠️ 3 outdated dependencies
- ⚠️ Missing documentation in `/utils`

---

## 🐛 Technical Debt

### High Priority (3)
- **FIXME** in `src/services/auth.js:42`: JWT refresh token rotation not implemented
- **TODO** in `src/api/users.js:78`: Add rate limiting
- **HACK** in `src/utils/cache.js:23`: Using setTimeout instead of proper cache expiry

### Medium Priority (5)
- **TODO** in `src/components/Dashboard.jsx:15`: Optimize re-renders
- **TODO** in `tests/integration/api.test.js:100`: Add more edge cases
- ...

### Low Priority (4)
- **TODO** in `README.md:50`: Update installation instructions
- ...

---

## 🚀 Entry Points

**Main Application:**
- `src/index.js` - Server entry point
- `src/client/index.jsx` - Client entry point

**Development:**
- `npm run dev` - Start dev server
- `npm test` - Run tests
- `npm run build` - Production build

**Configuration:**
- `.env.example` - Environment variables
- `tsconfig.json` - TypeScript config
- `jest.config.js` - Test configuration

---

## 📋 Common Tasks

**Adding a new feature:**
1. Create component in `src/components/`
2. Add service logic in `src/services/`
3. Create API endpoint in `src/api/`
4. Write tests in `tests/`

**Database changes:**
1. Create migration in `migrations/`
2. Update models in `src/models/`
3. Run `npm run migrate`

---

## 🔗 Integration Points

**External Services:**
- PostgreSQL database (port 5432)
- Redis cache (port 6379)
- SendGrid API (email)
- Stripe API (payments)

**API Endpoints:**
- `GET /api/users` - List users
- `POST /api/auth/login` - Authentication
- `GET /api/dashboard` - Dashboard data

---

## 📚 Additional Resources

- [Architecture Diagram](./docs/architecture.png)
- [API Documentation](./docs/api.md)
- [Development Guide](./docs/development.md)

---

**Next Steps:**
1. Address high-priority technical debt
2. Update outdated dependencies
3. Increase test coverage to 85%+
4. Document utility functions

アーキテクチャパターンのライブラリについては patterns.md を、解析例については examples.md を参照してください。

高度な解析機能

Git 履歴の分析

# Find most changed files (hotspots)
git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head -10

# Find largest contributors
git shortlog -sn

# Recent activity
git log --oneline --since="30 days ago" --no-merges

コードの複雑さの指標

# Using complexity tools
npx eslint src/ --format json | jq '.[] | select(.messages[].ruleId == "complexity")'

# Or manual analysis
# Functions > 50 lines = candidate for refactoring
# Files > 500 lines = candidate for splitting

依存関係のセキュリティ

# Check for vulnerabilities
npm audit
pip-audit  # for Python
go mod tidy && go list -m all  # for Go

他のスキルとの連携

コンテキストマネージャー

リポジトリの概要を保存します：

remember: Analyzed ProjectX repository
Type: CONTEXT
Tags: repository, architecture, nodejs, react
Content: ProjectX uses React + Express, layered architecture,
         12 high-priority TODOs, 78% test coverage

エラーデバッガー

解析で一般的な問題が見つかった場合：

Invoke error-debugger for:
- Deprecated dependencies
- Security vulnerabilities
- Common antipatterns detected

ブラウザーアプリ作成ツール

可視化を生成します：

Create dependency graph visualization
→ browser-app-creator generates interactive HTML chart

品質チェックリスト

ドキュメントを提出する前に、次の項目を確認してください：

• ✅ ディレクトリ構造がマッピングされている
• ✅ 言語とフレームワークが特定されている
• ✅ 依存関係が一覧化されている
• ✅ アーキテクチャパターンが検出されている
• ✅ 技術的負債が記録されている
• ✅ エントリーポイントがドキュメント化されている
• ✅ 一般的なタスクが説明されている
• ✅ Markdown が適切にフォーマットされている

出力の提供

形式：~/.claude-artifacts/analysis-{project}-{timestamp}.md（Linux/macOS）または %USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.md（Windows）に保存される Markdown ファイル

ユーザーへの通知：

✅ **{Project Name} Analysis** complete!

**Summary:**
- {LOC} lines of code across {file_count} files
- Primary stack: {stack}
- Architecture: {pattern}
- {todo_count} TODOs found

**Documentation saved to:** {filepath}

**Key findings:**
1. {finding_1}
2. {finding_2}
3. {finding_3}

**Recommended actions:**
- {action_1}
- {action_2}

一般的な解析シナリオ

新しいプロジェクトへの参加準備

ユーザーがなじみのないプロジェクトに参加 → 解析ツールが数分で完全な概要を提示

技術的負債の評価

ユーザーがレガシーコードを評価する必要がある → 解析ツールがすべての TODO／FIXME／HACK を特定

依存関係の監査

ユーザーが古いパッケージを確認したい → 解析ツールがバージョン付きですべての古い依存関係を一覧表示

アーキテクチャのドキュメント化

ユーザーが既存のプロジェクトをドキュメント化する必要がある → 解析ツールが包括的なアーキテクチャドキュメントを生成

成功基準

✅ コードベースの構造全体がマッピングされている ✅ すべての技術スタックが正しく特定されている ✅ 依存関係がバージョン付きで記録されている ✅ アーキテクチャパターンが検出されている ✅ 技術的負債が明らかになっている ✅ 2 分未満でドキュメントが生成されている ✅ Markdown の出力がアーティファクトに保存されている ✅ 実行可能な推奨事項が提示されている

追加リソース

• パターンライブラリ - 一般的なアーキテクチャパターン
• 分析例 - 実際のリポジトリ分析例

クイックリファレンス

トリガーフレーズ

• 「リポジトリを分析」
• 「コードベースを理解」
• 「プロジェクトをドキュメント化」
• 「このリポジトリには何があるか」
• 「コードベースの概要」
• 「技術的負債レポート」

出力先

• Linux/macOS: ~/.claude-artifacts/analysis-{project}-{timestamp}.md
• Windows: %USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.md

分析の深さのオプション

• クイック（1分未満）：構成と言語のみ
• 標準（1～2分）：＋依存関係＋パターン
• 詳細（3～5分）：＋Git 履歴＋複雑度指標＋セキュリティ監査