From 0c9425f800c5ce30831ae01403348ba520716bef Mon Sep 17 00:00:00 2001
From: ayato <2044taiga@gmail.com>
Date: Wed, 25 Jun 2025 13:20:53 +0900
Subject: [PATCH 1/3] =?UTF-8?q?docs:=20CLAUDE.md=E3=82=92=E5=88=86?=
 =?UTF-8?q?=E5=89=B2=E3=81=97=E3=81=A6=E3=83=89=E3=82=AD=E3=83=A5=E3=83=A1?=
 =?UTF-8?q?=E3=83=B3=E3=83=88=E6=A7=8B=E6=88=90=E3=82=92=E6=94=B9=E5=96=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- docs/フォルダを作成し、ドキュメントを機能別に分割
- CLAUDE.mdを簡潔にし、各ドキュメントへの参照に変更
- 可読性向上、保守性向上、トークン数節約を実現

分割内容:
- docs/project-overview.md (プロジェクト概要)
- docs/development-commands.md (開発コマンド集)
- docs/architecture.md (アーキテクチャ設計)
- docs/development-guidelines.md (開発ガイドライン)
- docs/refactoring-tasks.md (リファクタリングタスク)
- docs/setup.md (セットアップ手順)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .claude/settings.local.json    |  22 +++
 .vscode/settings.json          |   3 +
 CLAUDE.md                      | 246 +++------------------------------
 docs/architecture.md           |  67 +++++++++
 docs/development-commands.md   |  68 +++++++++
 docs/development-guidelines.md |  97 +++++++++++++
 docs/project-overview.md       |  37 +++++
 docs/refactoring-tasks.md      | 135 ++++++++++++++++++
 docs/setup.md                  | 159 +++++++++++++++++++++
 system-index.txt               |   1 +
 10 files changed, 611 insertions(+), 224 deletions(-)
 create mode 100644 .claude/settings.local.json
 create mode 100644 .vscode/settings.json
 create mode 100644 docs/architecture.md
 create mode 100644 docs/development-commands.md
 create mode 100644 docs/development-guidelines.md
 create mode 100644 docs/project-overview.md
 create mode 100644 docs/refactoring-tasks.md
 create mode 100644 docs/setup.md
 create mode 100644 system-index.txt

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
new file mode 100644
index 0000000..f3f9371
--- /dev/null
+++ b/.claude/settings.local.json
@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ffmpeg:*)",
+      "Bash(git checkout:*)",
+      "Bash(make test:*)",
+      "Bash(ros run:*)",
+      "Bash(rm:*)",
+      "Bash(./visp:*)",
+      "Bash(ros build:*)",
+      "Bash(ls:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git rm:*)",
+      "Bash(git stash:*)",
+      "Bash(git push:*)",
+      "Bash(git pull:*)",
+      "Bash(mkdir:*)"
+    ],
+    "deny": []
+  }
+}
\ No newline at end of file
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..6418298
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,3 @@
+{
+  "makefile.configureOnOpen": false
+}
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index 43f233c..60d5028 100644
--- a/CLAUDE.md
+++ b/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では同名関数の再定義が警告なしに行われるため特に注意が必要です。
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..0262619
--- /dev/null
+++ b/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`システム
+- 段階的なテスト実行サポート
\ No newline at end of file
diff --git a/docs/development-commands.md b/docs/development-commands.md
new file mode 100644
index 0000000..3e0cc61
--- /dev/null
+++ b/docs/development-commands.md
@@ -0,0 +1,68 @@
+# 開発コマンド
+
+## ビルド
+
+### スタンドアロンバイナリをビルド
+```bash
+ros build visp.ros
+```
+
+### Homebrewでインストール（推奨配布方法）
+```bash
+brew tap ogrew/visp
+brew install visp
+```
+
+## テスト
+
+### 完全なテストスイートを実行
+```bash
+make test
+```
+
+### Roswellで直接テスト実行
+```bash
+ros run --eval "(push #p\"./\" asdf:*central-registry*)" \
+        --eval "(ql:quickload :visp/test)" \
+        --eval "(rove:run :visp/test :style :spec)"
+```
+
+## 開発用REPL
+
+### プロジェクトを開発用REPLに読み込み
+```bash
+ros run --eval "(push #p\"./\" asdf:*central-registry*)" \
+        --eval "(ql:quickload :visp)"
+```
+
+## 推奨ワークフロー
+
+### 1. mainから最新を取得
+```bash
+git checkout main && git pull origin main
+```
+
+### 2. 作業用ブランチを作成（命名規則例）
+```bash
+git checkout -b feature/新機能名
+git checkout -b fix/バグ修正名  
+git checkout -b docs/ドキュメント更新名
+git checkout -b refactor/リファクタリング内容
+```
+
+### 3. 作業・コミット・プッシュ
+```bash
+git add . && git commit -m "適切なコミットメッセージ"
+git push -u origin ブランチ名
+```
+
+### 4. GitHub でPull Request作成
+```bash
+gh pr create --title "タイトル" --body "説明"
+```
+
+## 段階的開発の原則
+
+- **小さな変更を積み重ねる**: 大きな変更は複数のPRに分割
+- **各PR毎にテスト実行**: `make test`で既存機能への影響を確認
+- **バイナリビルド確認**: `ros build visp.ros`で実行可能性を検証
\ No newline at end of file
diff --git a/docs/development-guidelines.md b/docs/development-guidelines.md
new file mode 100644
index 0000000..7197388
--- /dev/null
+++ b/docs/development-guidelines.md
@@ -0,0 +1,97 @@
+# 開発ガイドライン
+
+## ブランチ運用とワークフロー
+
+### mainブランチ保護
+- **mainブランチは保護されており、直接コミットできません**
+- すべての作業は専用のfeatureブランチで行う必要があります
+- 変更はPull Request経由でのみmainにマージ可能です
+
+### ブランチ命名規則
+```bash
+feature/新機能名          # 新機能追加
+fix/バグ修正名           # バグ修正
+docs/ドキュメント更新名    # ドキュメント更新
+refactor/リファクタリング内容 # リファクタリング
+```
+
+## 関数名の重複チェック
+
+新しい関数を定義する際は、既存の関数名との重複を避けるため以下を確認してください：
+
+### 1. 既存関数の検索
+```bash
+grep -r "defun 関数名" src/
+```
+
+### 2. パッケージエクスポートの確認
+`src/package.lisp`で同名のシンボルがエクスポートされていないかチェック
+
+### 3. テスト実行
+関数定義後は必ず`make test`を実行して既存機能に影響がないことを確認
+
+**重要**: Common Lispでは同じパッケージ内で同名関数を再定義すると警告なしに上書きされるため、特に注意が必要です。
+
+## コード品質
+
+### 命名規則
+- 関数名: ケバブケース（`validate-merge-files`）
+- 変数名: ケバブケース（`input-file`）
+- 定数: アッパーケース（`*DEFAULT-CODEC*`）
+- 述語関数: `-p`サフィックス（`file-exists-p`）
+
+### docstring
+- 全ての公開関数にdocstringを追加
+- 引数と戻り値の説明を含める
+- 使用例を可能な限り記載
+
+### エラーハンドリング
+- 段階的に`(uiop:quit 1)`から例外ベースへ移行
+- ユーザーフレンドリーなエラーメッセージ
+- 適切なクリーンアップ処理
+
+## テストガイドライン
+
+### テストファイル構成
+```
+t/
+├── util-test.lisp          # ユーティリティ関数テスト
+├── ffmpeg-test.lisp        # FFmpegコマンド構築テスト
+├── validate-test.lisp      # 検証ロジックテスト
+└── integration-test.lisp   # 統合テスト
+```
+
+### テスト実行
+```bash
+# 全テスト実行
+make test
+
+# 特定のテストファイル実行
+ros run --eval "(ql:quickload :visp/test)" \
+        --eval "(rove:run :visp/test/util)"
+```
+
+### テストカバレッジ
+- 成功ケースと失敗ケースの両方をテスト
+- エラーケースの段階的改善
+- エンドツーエンドテストの充実
+
+## Pull Request ガイドライン
+
+### PR作成前チェックリスト
+- [ ] `make test`が成功する
+- [ ] `ros build visp.ros`でビルドが成功する
+- [ ] 新機能に対応するテストが追加されている
+- [ ] docstringが適切に記載されている
+- [ ] 既存機能への影響がない
+
+### PRタイトル・説明
+- **タイトル**: 変更内容を簡潔に表現
+- **説明**: 変更の背景、目的、影響範囲を記載
+- **テスト計画**: 動作確認手順を明記
+
+### レビュー観点
+- コードの可読性・保守性
+- テストの網羅性
+- パフォーマンスへの影響
+- セキュリティ観点での問題
\ No newline at end of file
diff --git a/docs/project-overview.md b/docs/project-overview.md
new file mode 100644
index 0000000..edc227f
--- /dev/null
+++ b/docs/project-overview.md
@@ -0,0 +1,37 @@
+# プロジェクト概要
+
+VispはffmpegのミニマルなCommon Lispラッパーです。動画の解像度変換、コーデック変換、音声除去などの一般的な動画処理を簡素化し、出力ファイル名を自動生成します。
+
+## 主要機能
+
+### 処理モード
+- **通常モード**: 単一ファイル処理（各種変換オプション適用）
+- **バッチモード**: ディレクトリ処理（入力がディレクトリの場合自動）
+- **マージモード**: `--merge`で複数MP4ファイル結合
+- **GIFモード**: `--gif`でアニメーションGIF変換
+
+### 変換オプション
+- 解像度変換（hd=1280x720、fhd=1920x1080など事前定義マッピング）
+- コーデック変換（H.264、H.265、VP9など）
+- フレームレート調整
+- 音声除去
+- ファイル形式変換
+
+### 自動化機能
+- 出力ファイル名の自動生成
+- 入力形式の自動判別
+- バッチ処理での一括変換
+
+## ターゲットユーザー
+
+- コマンドライン環境での動画処理を必要とするユーザー
+- ffmpegの複雑なオプションを簡素化したいユーザー
+- Common Lispベースのツールチェーンを利用する開発者
+- 動画処理の自動化やバッチ処理を行いたいユーザー
+
+## 設計思想
+
+- **ミニマリズム**: 必要最小限の機能に集中
+- **自動化**: 手動設定を最小限に抑制
+- **透明性**: ffmpegコマンドの表示とドライラン機能
+- **拡張性**: Common Lispによる柔軟な機能拡張
\ No newline at end of file
diff --git a/docs/refactoring-tasks.md b/docs/refactoring-tasks.md
new file mode 100644
index 0000000..d1ffb78
--- /dev/null
+++ b/docs/refactoring-tasks.md
@@ -0,0 +1,135 @@
+# リファクタリングタスク
+
+## 高優先度
+
+### ffmpeg実行エラーハンドリング強化
+**対象**: `ffmpeg.lisp:3`の`run-cmd`関数
+
+**現在の問題:**
+- ffmpeg実行失敗時のエラー情報が不十分
+- 出力ディレクトリの書き込み権限チェックなし
+- 処理中断時の一時ファイル削除なし
+
+**改善策:**
+1. ffmpegの詳細エラーメッセージ取得
+2. 事前の書き込み権限チェック
+3. 処理中断時のクリーンアップ処理
+
+## 中優先度
+
+### コード品質改善
+
+#### validate-merge-files関数の分割
+**対象**: `validate.lisp:41`の`validate-merge-files`関数（約70行）
+
+**問題**: 単一の関数が複数の責任を持ち、可読性が低下
+
+**改善策**:
+- ファイル存在チェック関数の分離
+- MP4形式チェック関数の分離
+- 重複ファイルチェック関数の分離
+
+#### マジックナンバーの定数化
+**対象**: `ffmpeg.lisp:20`のGIF fps計算など
+
+**改善策**:
+- `const.lisp`に定数を追加
+- 意味のある定数名を付与
+
+#### 命名の一貫性改善
+**対象**: `options.lisp:11`
+
+**問題**: `repeat`フィールドと`--loop`オプション名の不整合
+
+**改善策**:
+- フィールド名を`loop`に統一、または
+- オプション名を`--repeat`に変更
+
+### テスト改善
+
+#### エラーケーステストの改善
+**現在の問題:**
+- validate系関数のエラーケースがテストされていない
+- `(uiop:quit 1)`によるプロセス終了がテストフレームワークと非互換
+- テストカバレッジが不十分で潜在的バグの発見が困難
+
+**改善アプローチ（段階的実装推奨）:**
+1. 1つの関数から例外ベースに段階的変更
+2. 各段階でのバイナリビルド動作確認
+3. エラーケーステストの段階的追加
+4. リグレッション防止の強化
+
+**注意**: 大規模な一括変更は避け、小さな改善を積み重ねる方式を採用する。
+
+#### 統合テストの充実
+**追加すべきテスト:**
+- 実際のffmpeg実行を含むエンドツーエンドテスト
+- エラーケースの異常系テスト
+- バッチ処理でのファイル競合テスト
+
+## 低優先度
+
+### 新機能追加
+
+#### 設定ファイル（プリセット）機能の追加
+頻繁に使用するオプション組み合わせをプリセットとして保存：
+
+```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     # 高圧縮（ファイルサイズ優先）
+```
+
+#### プログレス表示機能
+長時間処理での進捗表示：
+
+```bash
+visp --input large-video.mp4 --res 4k --progress
+# [████████████████████████████████] 85% (02:45 remaining)
+```
+
+#### メタデータ保持オプション
+元ファイルのメタデータ（タイトル、作成日時など）を保持：
+
+```bash
+visp --input video.mp4 --res fhd --keep-metadata
+```
+
+#### カスタムフィルタ機能
+フィルタチェーンのカスタマイズ：
+
+```bash
+visp --input video.mp4 --filters "blur=3,sharpen=1,fade=in:0:30"
+```
+
+### パフォーマンス最適化
+- バッチモードでの並列処理対応
+- ffprobeの結果キャッシュ（同じファイルの重複解析回避）
+- 大きなファイル処理時のメモリ最適化
+
+## その他
+
+### ドキュメント改善
+- 内部関数のdocstring充実
+- アーキテクチャ図の追加
+- エラー解決ガイドの作成
+- パフォーマンス指標の文書化
+
+### 開発環境整備
+- CI/CDパイプラインでの自動テスト
+- コードカバレッジ測定
+- リンター設定の強化
+- 依存関係の自動更新
+
+### 国際化対応
+- 日本語コメントの英語化
+- エラーメッセージの多言語対応
+- ヘルプメッセージの国際化
\ No newline at end of file
diff --git a/docs/setup.md b/docs/setup.md
new file mode 100644
index 0000000..f2f9222
--- /dev/null
+++ b/docs/setup.md
@@ -0,0 +1,159 @@
+# セットアップ手順
+
+## 前提条件
+
+### システム要件
+- macOS, Linux, または Windows (WSL推奨)
+- ffmpeg がシステムPATHに設定済み
+- Git がインストール済み
+
+### ffmpegのインストール
+
+#### macOS (Homebrew)
+```bash
+brew install ffmpeg
+```
+
+#### Ubuntu/Debian
+```bash
+sudo apt update
+sudo apt install ffmpeg
+```
+
+#### Windows (Chocolatey)
+```bash
+choco install ffmpeg
+```
+
+## 開発環境セットアップ
+
+### 1. Roswellのインストール
+
+#### macOS (Homebrew)
+```bash
+brew install roswell
+```
+
+#### Linux
+```bash
+# Ubuntu/Debian
+sudo apt install roswell
+
+# または手動インストール
+curl -L https://github.com/roswell/roswell/releases/latest/download/roswell_amd64.deb -o roswell.deb
+sudo dpkg -i roswell.deb
+```
+
+### 2. Common Lisp環境の初期化
+```bash
+ros setup
+ros install sbcl-bin
+ros use sbcl-bin
+```
+
+### 3. プロジェクトのクローン
+```bash
+git clone https://github.com/ogrew/visp.git
+cd visp
+```
+
+### 4. 依存関係の確認
+```bash
+# ffmpegが利用可能かチェック
+ffmpeg -version
+
+# Roswellの動作確認
+ros --version
+```
+
+## ビルドとテスト
+
+### 開発用ビルド
+```bash
+# プロジェクトをREPLに読み込み
+ros run --eval "(push #p\"./\" asdf:*central-registry*)" \
+        --eval "(ql:quickload :visp)"
+```
+
+### テスト実行
+```bash
+# 全テストを実行
+make test
+
+# または手動実行
+ros run --eval "(push #p\"./\" asdf:*central-registry*)" \
+        --eval "(ql:quickload :visp/test)" \
+        --eval "(rove:run :visp/test :style :spec)"
+```
+
+### プロダクションビルド
+```bash
+# スタンドアロンバイナリを生成
+ros build visp.ros
+```
+
+ビルド成功時、実行可能ファイル `visp` が生成されます。
+
+## トラブルシューティング
+
+### ffmpeg not found エラー
+```bash
+# ffmpegのインストール確認
+which ffmpeg
+
+# PATHの設定確認
+echo $PATH
+```
+
+### Roswell初期化エラー
+```bash
+# Roswellの再初期化
+ros setup
+ros install sbcl-bin
+```
+
+### テスト失敗
+```bash
+# 依存関係の再インストール
+ros run --eval "(ql:quickload :visp :force t)"
+```
+
+### ビルドエラー
+```bash
+# クリーンビルド
+rm -rf ~/.cache/common-lisp/
+ros build visp.ros
+```
+
+## エディタ設定
+
+### VS Code
+推奨拡張機能：
+- `commonlisp-vscode` - Common Lisp サポート
+- `Parinfer` - 括弧の自動整形
+
+### Emacs
+SLIME の設定例：
+```elisp
+(setq inferior-lisp-program "ros -Q run")
+(require 'slime)
+(slime-setup '(slime-fancy))
+```
+
+### Vim/Neovim
+Vlime プラグインの使用を推奨：
+```vim
+Plug 'vlime/vlime', {'rtp': 'vim/'}
+```
+
+## 実行確認
+
+セットアップ完了後、以下のコマンドで動作確認：
+
+```bash
+# ヘルプ表示
+./visp --help
+
+# ドライラン実行
+./visp --input sample.mp4 --res hd --dry-run
+```
\ No newline at end of file
diff --git a/system-index.txt b/system-index.txt
new file mode 100644
index 0000000..65361ae
--- /dev/null
+++ b/system-index.txt
@@ -0,0 +1 @@
+visp.asd

From f5039291d212d8407dc8a131b067c737dc07c549 Mon Sep 17 00:00:00 2001
From: ayato <2044taiga@gmail.com>
Date: Wed, 25 Jun 2025 13:30:59 +0900
Subject: [PATCH 2/3] =?UTF-8?q?docs:=20refactoring-tasks.md=E3=82=92?=
 =?UTF-8?q?=E5=AE=9F=E8=A3=85=E7=8F=BE=E7=8A=B6=E3=81=AB=E5=9F=BA=E3=81=A5?=
 =?UTF-8?q?=E3=81=84=E3=81=A6=E5=85=A8=E9=9D=A2=E6=9B=B4=E6=96=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

4段階の分析を実施して内容を大幅改善:
1. 現状コード全体の詳細読み込み
2. エンジニア目線での技術的改善点洗い出し
3. ユーザ目線での機能要望分析
4. 実装との乖離修正と優先度再整理

主な変更点:
- 既に実装済み機能の削除・修正(validate-output-path等)
- 実際の行数修正(validate-merge-files: 70行→114行)
- より具体的で実装可能な改善提案
- エンジニア・ユーザ両目線の要望を適切な優先度で配置
- 関数名・行番号等の正確な参照情報追加

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/refactoring-tasks.md | 167 ++++++++++++++++++++++++--------------
 1 file changed, 107 insertions(+), 60 deletions(-)

diff --git a/docs/refactoring-tasks.md b/docs/refactoring-tasks.md
index d1ffb78..c1948c2 100644
--- a/docs/refactoring-tasks.md
+++ b/docs/refactoring-tasks.md
@@ -1,49 +1,35 @@
 # リファクタリングタスク
 
-## 高優先度
+## 高優先度（品質・安定性の改善）
 
-### ffmpeg実行エラーハンドリング強化
-**対象**: `ffmpeg.lisp:3`の`run-cmd`関数
+### validate-merge-files関数の分割
+**対象**: `validate.lisp:41`の`validate-merge-files`関数（114行）
 
-**現在の問題:**
-- ffmpeg実行失敗時のエラー情報が不十分
-- 出力ディレクトリの書き込み権限チェックなし
-- 処理中断時の一時ファイル削除なし
-
-**改善策:**
-1. ffmpegの詳細エラーメッセージ取得
-2. 事前の書き込み権限チェック
-3. 処理中断時のクリーンアップ処理
-
-## 中優先度
-
-### コード品質改善
-
-#### validate-merge-files関数の分割
-**対象**: `validate.lisp:41`の`validate-merge-files`関数（約70行）
-
-**問題**: 単一の関数が複数の責任を持ち、可読性が低下
+**問題**: 単一の関数が複数の責任を持ち、可読性・保守性が低下
 
 **改善策**:
-- ファイル存在チェック関数の分離
-- MP4形式チェック関数の分離
-- 重複ファイルチェック関数の分離
+- ファイル存在・形式チェック関数の分離 (`validate-merge-files-basic`)
+- 音声・解像度・fps互換性チェック関数の分離 (`validate-merge-compatibility`)
+- メタデータ取得・検証の分離 (`extract-and-validate-metadata`)
 
-#### マジックナンバーの定数化
-**対象**: `ffmpeg.lisp:20`のGIF fps計算など
+### 命名の一貫性改善
+**対象**: `options.lisp:11`と`options.lisp:51`
+
+**問題**: `repeat`フィールドと`--loop`オプション名の不整合
 
 **改善策**:
-- `const.lisp`に定数を追加
-- 意味のある定数名を付与
+- フィールド名を`loop`に統一し、関連する関数名も変更
+- `validate-repeat` → `validate-loop`への変更も必要
 
-#### 命名の一貫性改善
-**対象**: `options.lisp:11`
+### エラーハンドリングの詳細化
+**対象**: `ffmpeg.lisp:33`の`run-cmd`関数
 
-**問題**: `repeat`フィールドと`--loop`オプション名の不整合
+**現状**: 基本的なエラーハンドリングは実装済み（`validate-output-path`、`cleanup-partial-output`）
 
-**改善策**:
-- フィールド名を`loop`に統一、または
-- オプション名を`--repeat`に変更
+**追加改善:**
+- ffmpeg実行失敗時のstderr詳細取得と表示
+- エラーコード別の対処方法ガイダンス表示
+- 権限エラーの具体的な解決策提示
 
 ### テスト改善
 
@@ -67,55 +53,116 @@
 - エラーケースの異常系テスト
 - バッチ処理でのファイル競合テスト
 
-## 低優先度
+## 中優先度（パフォーマンス・保守性の向上）
+
+### パフォーマンス最適化
+
+#### ffprobeキャッシュ機能
+**対象**: `video.lisp`の各メタデータ取得関数
+
+**問題**: 同じファイルの重複解析でパフォーマンス低下
+
+**改善策**:
+- ファイルパス＋更新日時をキーとしたキャッシュ実装
+- メモリ使用量制限付きのLRUキャッシュ
+
+#### バッチ処理の並列化
+**対象**: `main.lisp:35`のバッチモード処理
+
+**改善策**:
+- 複数ファイルの並列処理対応
+- CPU数に基づく適切な並列度制御
+
+### コード品質改善
 
-### 新機能追加
+#### 関数レベルdocstring追加
+**対象**: 特に複雑なロジック関数
 
-#### 設定ファイル（プリセット）機能の追加
-頻繁に使用するオプション組み合わせをプリセットとして保存：
+**優先対象**:
+- `build-concat-filter` (ffmpeg.lisp:71) - 複雑なフィルタ文字列生成
+- `parse-args-to-options` (options.lisp:25) - 長いオプション解析ループ
+- `generate-output-filename` (util.lisp:76) - 複雑なファイル名生成ロジック
 
+#### マジックナンバーの定数化
+**対象**: `ffmpeg.lisp:59`のGIF fps計算
+
+**現状**: `(/ fps 2.0)` でハードコード
+
+**改善策**:
+- `+gif-fps-divider+` 定数を `const.lisp` に追加
+- GIFサイズ調整の設定可能化
+
+## 低優先度（新機能追加）
+
+### 日常利便性機能
+
+#### プリセット機能
 ```bash
-visp --preset mobile-hd --input video.mp4  # プリセット使用
-visp --save-preset mobile-hd --res hd --fps 30 --codec h264  # プリセット保存
+visp --save-preset mobile-hd --res hd --fps 30 --codec h264
+visp --preset mobile-hd --input video.mp4
 ```
+- `~/.visp/presets.json`での設定管理
+- プリセット一覧表示 (`--list-presets`)
 
-#### 品質設定オプションの追加
-ユーザビリティ向上のための品質プリセット：
-
+#### 品質設定オプション
 ```bash
-visp --input video.mp4 --quality high    # 高品質（低圧縮）
-visp --input video.mp4 --quality medium  # 標準品質
-visp --input video.mp4 --quality low     # 高圧縮（ファイルサイズ優先）
+visp --input video.mp4 --quality high    # CRF 18相当
+visp --input video.mp4 --quality medium  # CRF 23相当
+visp --input video.mp4 --quality low     # CRF 28相当
 ```
+- 内部的にはCRF値やビットレート調整
+- コーデック別の最適化
 
 #### プログレス表示機能
-長時間処理での進捗表示：
-
 ```bash
 visp --input large-video.mp4 --res 4k --progress
 # [████████████████████████████████] 85% (02:45 remaining)
 ```
+- ffmpegの進捗パース
+- 残り時間推定アルゴリズム
 
-#### メタデータ保持オプション
-元ファイルのメタデータ（タイトル、作成日時など）を保持：
+### 実用性向上機能
+
+#### バッチ処理改善
+```bash
+visp --input /videos --recursive --include "*.mp4,*.mov"
+```
+- サブディレクトリ再帰処理
+- 拡張子フィルタリング
+- 処理結果サマリー表示
 
+#### メタデータ保持オプション
 ```bash
 visp --input video.mp4 --res fhd --keep-metadata
 ```
+- 元ファイルのタイトル、作成日時等の保持
+- メタデータの選択的保持・削除
 
-#### カスタムフィルタ機能
-フィルタチェーンのカスタマイズ：
+#### 出力ファイル名テンプレート
+```bash
+visp --output-template "%{name}_%{resolution}_%{date}.%{ext}"
+# video_1920x1080_20241225.mp4
+```
+- カスタマイズ可能な出力ファイル名
+- 変数展開（解像度、日付、元ファイル名等）
 
+### 高度機能
+
+#### カスタムフィルタ機能
 ```bash
 visp --input video.mp4 --filters "blur=3,sharpen=1,fade=in:0:30"
 ```
+- フィルタチェーンのカスタマイズ
+- よく使うフィルタのエイリアス定義
 
-### パフォーマンス最適化
-- バッチモードでの並列処理対応
-- ffprobeの結果キャッシュ（同じファイルの重複解析回避）
-- 大きなファイル処理時のメモリ最適化
+#### プレビュー機能
+```bash
+visp --input video.mp4 --res fhd --preview
+```
+- 最初の5秒間の変換結果をプレビュー生成
+- サムネイル生成機能
 
-## その他
+## その他（開発環境・ドキュメント）
 
 ### ドキュメント改善
 - 内部関数のdocstring充実
@@ -130,6 +177,6 @@ visp --input video.mp4 --filters "blur=3,sharpen=1,fade=in:0:30"
 - 依存関係の自動更新
 
 ### 国際化対応
-- 日本語コメントの英語化
-- エラーメッセージの多言語対応
-- ヘルプメッセージの国際化
\ No newline at end of file
+- エラーメッセージの統一（日英混在の解決）
+- ヘルプメッセージの改善
+- 多言語対応の基盤整備
\ No newline at end of file

From 7385863b0e5bb79fd420f7121d242f55b83fa2a7 Mon Sep 17 00:00:00 2001
From: ayato <2044taiga@gmail.com>
Date: Wed, 25 Jun 2025 13:36:07 +0900
Subject: [PATCH 3/3] =?UTF-8?q?fix:=20.gitignore=E3=82=92=E4=BF=AE?=
 =?UTF-8?q?=E6=AD=A3=E3=81=97=E4=B8=8D=E8=A6=81=E3=83=95=E3=82=A1=E3=82=A4?=
 =?UTF-8?q?=E3=83=AB=E3=82=92=E9=99=A4=E5=A4=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Claude Code設定ファイル(.claude/)を除外
- VS Code設定ファイル(.vscode/)を除外
- システム一時ファイル(system-index.txt)を除外
- 既存の間違った.gitignore記述を修正

これらは個人の開発環境設定ファイルのため、
リポジトリには含めるべきではない。

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .claude/settings.local.json | 22 ----------------------
 .gitignore                  |  8 +++++++-
 .vscode/settings.json       |  3 ---
 system-index.txt            |  1 -
 4 files changed, 7 insertions(+), 27 deletions(-)
 delete mode 100644 .claude/settings.local.json
 delete mode 100644 .vscode/settings.json
 delete mode 100644 system-index.txt

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
deleted file mode 100644
index f3f9371..0000000
--- a/.claude/settings.local.json
+++ /dev/null
@@ -1,22 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(ffmpeg:*)",
-      "Bash(git checkout:*)",
-      "Bash(make test:*)",
-      "Bash(ros run:*)",
-      "Bash(rm:*)",
-      "Bash(./visp:*)",
-      "Bash(ros build:*)",
-      "Bash(ls:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git rm:*)",
-      "Bash(git stash:*)",
-      "Bash(git push:*)",
-      "Bash(git pull:*)",
-      "Bash(mkdir:*)"
-    ],
-    "deny": []
-  }
-}
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index be7e963..c8a7c48 100644
--- a/.gitignore
+++ b/.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/
diff --git a/.vscode/settings.json b/.vscode/settings.json
deleted file mode 100644
index 6418298..0000000
--- a/.vscode/settings.json
+++ /dev/null
@@ -1,3 +0,0 @@
-{
-  "makefile.configureOnOpen": false
-}
\ No newline at end of file
diff --git a/system-index.txt b/system-index.txt
deleted file mode 100644
index 65361ae..0000000
--- a/system-index.txt
+++ /dev/null
@@ -1 +0,0 @@
-visp.asd