docs: CLAUDE.mdを分割してドキュメント構成を改善

.gitignore

@@ -26,4 +26,10 @@
 visp
 
 # Ignore ASDF index
-system-index.txt.claude/settings.local.json
+system-index.txt
+
+# Claude Code settings
+.claude/
+
+# Editor settings
+.vscode/

CLAUDE.md

@@ -6,239 +6,37 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Claude Codeとのやり取りは**日本語**で行ってください。コードコメントやドキュメント作成時も日本語を使用してください。
 
-## プロジェクト概要
+## ドキュメント構成
 
-VispはffmpegのミニマルなCommon Lispラッパーです。動画の解像度変換、コーデック変換、音声除去などの一般的な動画処理を簡素化し、出力ファイル名を自動生成します。
+このプロジェクトのドキュメントは以下のように構成されています：
 
-## 開発コマンド
+### 基本ドキュメント
+- **[プロジェクト概要](docs/project-overview.md)** - Vispの目的、機能、設計思想
+- **[セットアップ手順](docs/setup.md)** - 開発環境の構築とインストール方法
+- **[開発コマンド](docs/development-commands.md)** - ビルド、テスト、ワークフローコマンド
 
-### ビルド
-```bash
-# スタンドアロンバイナリをビルド
-ros build visp.ros
+### 技術ドキュメント
+- **[アーキテクチャ](docs/architecture.md)** - システム設計、コンポーネント構成、データ構造
+- **[開発ガイドライン](docs/development-guidelines.md)** - コーディング規約、ブランチ運用、PR作成手順
+- **[リファクタリングタスク](docs/refactoring-tasks.md)** - 改善予定項目と優先度
 
-# Homebrewでインストール（推奨配布方法）
-brew tap ogrew/visp
-brew install visp
-```
+## 重要な指針
 
-### テスト
-```bash
-# 完全なテストスイートを実行
-make test
-
-# Roswellで直接テスト実行
-ros run --eval "(push #p\"./\" asdf:*central-registry*)" \
-        --eval "(ql:quickload :visp/test)" \
-        --eval "(rove:run :visp/test :style :spec)"
-```
-
-### 開発用REPL
-```bash
-# プロジェクトを開発用REPLに読み込み
-ros run --eval "(push #p\"./\" asdf:*central-registry*)" \
-        --eval "(ql:quickload :visp)"
-```
-
-## アーキテクチャ
-
-### 核となるコンポーネント
-- **main.lisp**: エントリーポイントと実行フローの制御
-- **options.lisp**: CLI引数解析とvisp-options構造体
-- **validate.lisp**: 入力検証とオプション互換性チェック
-- **ffmpeg.lisp**: FFmpegコマンド構築と実行
-- **video.lisp**: ffprobeを使用した動画メタデータ抽出
-- **util.lisp**: ファイル名生成とパースユーティリティ
-- **const.lisp**: 解像度マップ、コーデック設定、ファイル拡張子
-
-### 実行フロー
-1. **初期化**: ffmpeg可用性チェック、CLI引数をvisp-options構造体に解析
-2. **検証**: モード（通常/マージ/GIF/バッチ）に基づく検証ディスパッチ
-3. **モード選択**: 適切な処理モードへのルーティング
-4. **コマンド構築**: 検証済みオプションに基づくffmpegコマンド生成
-5. **実行**: ffmpeg実行またはドライラン出力表示
-
-### 処理モード
-- **通常モード**: 単一ファイル処理（各種変換オプション適用）
-- **バッチモード**: ディレクトリ処理（入力がディレクトリの場合自動）
-- **マージモード**: `--merge`で複数MP4ファイル結合
-- **GIFモード**: `--gif`でアニメーションGIF変換
-
-### 主要データ構造
-- **visp-options構造体**: 全解析済みオプションを含む中央設定オブジェクト
-- **解像度定数**: 事前定義マッピング（hd=1280x720、fhd=1920x1080など）
-- **コーデックマップ**: 拡張子とピクセルフォーマット付きエンコーダー設定
-
-## 依存関係
-
-### ランタイム
-- **UIOP**: 唯一のCommon Lisp依存関係（SBCLに含まれる）
-- **ffmpeg/ffprobe**: システムPATHで利用可能である必要がある
-
-### 開発環境
-- **SBCL + Roswell**: ビルドとRELP開発用
-- **Rove**: テストフレームワーク（Quicklisp経由で読み込み）
-
-## テストフレームワーク
-
-`t/`ディレクトリのテストファイルでRoveテストライブラリを使用。ユーティリティ関数、ffmpegコマンド構築、出力処理をカバー。
-
-## 開発ガイドライン
-
-### ブランチ運用とワークフロー
-
-#### mainブランチ保護
+### 開発原則
 - **mainブランチは保護されており、直接コミットできません**
 - すべての作業は専用のfeatureブランチで行う必要があります
 - 変更はPull Request経由でのみmainにマージ可能です
+- 小さな変更を積み重ねる段階的開発を推奨
 
-#### 推奨ワークフロー
-```bash
-# 1. mainから最新を取得
-git checkout main && git pull origin main
-
-# 2. 作業用ブランチを作成（命名規則例）
-git checkout -b feature/新機能名
-git checkout -b fix/バグ修正名  
-git checkout -b docs/ドキュメント更新名
-git checkout -b refactor/リファクタリング内容
-
-# 3. 作業・コミット・プッシュ
-git add . && git commit -m "適切なコミットメッセージ"
-git push -u origin ブランチ名
-
-# 4. GitHub でPull Request作成
-gh pr create --title "タイトル" --body "説明"
-```
-
-#### 段階的開発の原則
-- **小さな変更を積み重ねる**: 大きな変更は複数のPRに分割
-- **各PR毎にテスト実行**: `make test`で既存機能への影響を確認
-- **バイナリビルド確認**: `ros build visp.ros`で実行可能性を検証
+### テストとビルド
+- 新機能追加時は必ず `make test` でテスト実行
+- ビルド確認は `ros build visp.ros` で実施
+- エラーケーステストの改善が重要な課題
 
 ### 関数名の重複チェック
+新しい関数定義時は以下を確認：
+1. `grep -r "defun 関数名" src/` で既存関数チェック
+2. `src/package.lisp` でエクスポート重複チェック
+3. テスト実行で既存機能への影響確認
 
-新しい関数を定義する際は、既存の関数名との重複を避けるため以下を確認してください：
-
-1. **既存関数の検索**: `grep -r "defun 関数名" src/` で既存の関数定義をチェック
-2. **パッケージエクスポートの確認**: `src/package.lisp`で同名のシンボルがエクスポートされていないかチェック
-3. **テスト実行**: 関数定義後は必ず`make test`を実行して既存機能に影響がないことを確認
-
-Common Lispでは同じパッケージ内で同名関数を再定義すると警告なしに上書きされるため、特に注意が必要です。
-
-## 今後のリファクタリングタスク
-
-### 高優先度
-
-#### ffmpeg実行エラーハンドリング強化
-`ffmpeg.lisp:3`の`run-cmd`関数でエラーハンドリングが不十分：
-
-**現在の問題:**
-- ffmpeg実行失敗時のエラー情報が不十分
-- 出力ディレクトリの書き込み権限チェックなし
-- 処理中断時の一時ファイル削除なし
-
-**改善策:**
-1. ffmpegの詳細エラーメッセージ取得
-2. 事前の書き込み権限チェック
-3. 処理中断時のクリーンアップ処理
-
-### 中優先度
-
-#### 設定ファイル（プリセット）機能の追加
-頻繁に使用するオプション組み合わせをプリセットとして保存：
-
-```bash
-visp --preset mobile-hd --input video.mp4  # プリセット使用
-visp --save-preset mobile-hd --res hd --fps 30 --codec h264  # プリセット保存
-```
-
-#### 品質設定オプションの追加
-ユーザビリティ向上のための品質プリセット：
-
-```bash
-visp --input video.mp4 --quality high    # 高品質（低圧縮）
-visp --input video.mp4 --quality medium  # 標準品質
-visp --input video.mp4 --quality low     # 高圧縮（ファイルサイズ優先）
-```
-
-#### コード品質改善
-- `validate.lisp`の`validate-merge-files`関数（41行目、約70行）を小さな関数に分割
-- マジックナンバーの定数化（`ffmpeg.lisp:20`のGIF fps計算など）
-- エラーメッセージの日英統一
-- 関数レベルdocstringの追加
-
-#### 統合テストの充実
-- 実際のffmpeg実行を含むエンドツーエンドテスト
-- エラーケースの異常系テスト
-- バッチ処理でのファイル競合テスト
-
-#### エラーケーステストの改善
-現在のテストスイートは成功ケースのみをカバーしており、`(uiop:quit 1)`を呼ぶエラーケースがテストできない問題がある：
-
-**現在の問題:**
-- validate系関数のエラーケースがテストされていない
-- `(uiop:quit 1)`によるプロセス終了がテストフレームワークと非互換
-- テストカバレッジが不十分で潜在的バグの発見が困難
-
-**改善アプローチ（段階的実装推奨）:**
-1. 1つの関数から例外ベースに段階的変更
-2. 各段階でのバイナリビルド動作確認
-3. エラーケーステストの段階的追加
-4. リグレッション防止の強化
-
-**注意:** 大規模な一括変更は避け、小さな改善を積み重ねる方式を採用する。
-
-### 低優先度
-
-#### プログレス表示機能
-長時間処理での進捗表示：
-
-```bash
-visp --input large-video.mp4 --res 4k --progress
-# [████████████████████████████████] 85% (02:45 remaining)
-```
-
-#### メタデータ保持オプション
-元ファイルのメタデータ（タイトル、作成日時など）を保持：
-
-```bash
-visp --input video.mp4 --res fhd --keep-metadata
-```
-
-#### パフォーマンス最適化
-- バッチモードでの並列処理対応
-- ffprobeの結果キャッシュ（同じファイルの重複解析回避）
-- 大きなファイル処理時のメモリ最適化
-
-#### カスタムフィルタ機能
-フィルタチェーンのカスタマイズ：
-
-```bash
-visp --input video.mp4 --filters "blur=3,sharpen=1,fade=in:0:30"
-```
-
-### その他
-
-#### ドキュメント改善
-- 内部関数のdocstring充実
-- アーキテクチャ図の追加
-- エラー解決ガイドの作成
-- パフォーマンス指標の文書化
-
-#### 開発環境整備
-- CI/CDパイプラインでの自動テスト
-- コードカバレッジ測定
-- リンター設定の強化
-- 依存関係の自動更新
-
-#### 命名の一貫性改善
-- `options.lisp:11`: `repeat`フィールドと`--loop`オプション名の不整合解決
-- `encoder-available-p`→`encoder-exists-p`など関数名の明確化
-- 変数名の統一（キャメルケース vs ケバブケース）
-
-#### 国際化対応
-
-- 日本語コメントの英語化
-- エラーメッセージの多言語対応
-- ヘルプメッセージの国際化
+**注意**: Common Lispでは同名関数の再定義が警告なしに行われるため特に注意が必要です。

docs/architecture.md

@@ -0,0 +1,67 @@
+# アーキテクチャ設計
+
+## 核となるコンポーネント
+
+- **main.lisp**: エントリーポイントと実行フローの制御
+- **options.lisp**: CLI引数解析とvisp-options構造体
+- **validate.lisp**: 入力検証とオプション互換性チェック
+- **ffmpeg.lisp**: FFmpegコマンド構築と実行
+- **video.lisp**: ffprobeを使用した動画メタデータ抽出
+- **util.lisp**: ファイル名生成とパースユーティリティ
+- **const.lisp**: 解像度マップ、コーデック設定、ファイル拡張子
+
+## 実行フロー
+
+1. **初期化**: ffmpeg可用性チェック、CLI引数をvisp-options構造体に解析
+2. **検証**: モード（通常/マージ/GIF/バッチ）に基づく検証ディスパッチ
+3. **モード選択**: 適切な処理モードへのルーティング
+4. **コマンド構築**: 検証済みオプションに基づくffmpegコマンド生成
+5. **実行**: ffmpeg実行またはドライラン出力表示
+
+## 主要データ構造
+
+### visp-options構造体
+全解析済みオプションを含む中央設定オブジェクト。以下のフィールドを持つ：
+
+- 入力ファイル/ディレクトリパス
+- 出力設定（解像度、コーデック、フォーマット）
+- 処理オプション（フレームレート、音声除去、ループ設定）
+- モードフラグ（マージ、GIF、バッチ、ドライラン）
+
+### 解像度定数
+事前定義マッピング：
+- hd = 1280x720
+- fhd = 1920x1080
+- 4k = 3840x2160
+- その他の標準解像度
+
+### コーデックマップ
+拡張子とピクセルフォーマット付きエンコーダー設定：
+- H.264 (libx264)
+- H.265 (libx265) 
+- VP9 (libvpx-vp9)
+- AV1 (libaom-av1)
+
+## 依存関係
+
+### ランタイム
+- **UIOP**: 唯一のCommon Lisp依存関係（SBCLに含まれる）
+- **ffmpeg/ffprobe**: システムPATHで利用可能である必要がある
+
+### 開発環境
+- **SBCL + Roswell**: ビルドとREPL開発用
+- **Rove**: テストフレームワーク（Quicklisp経由で読み込み）
+
+## テストフレームワーク
+
+`t/`ディレクトリのテストファイルでRoveテストライブラリを使用。以下をカバー：
+
+- ユーティリティ関数のユニットテスト
+- ffmpegコマンド構築ロジックのテスト
+- オプション解析と検証のテスト
+- 出力処理のテスト
+
+### テスト実行環境
+- Quicklisp経由でのRove読み込み
+- プロジェクトローカルの`:visp/test`システム
+- 段階的なテスト実行サポート