timeout-prevention

タイムアウト防止スキル

進捗追跡と復旧の仕組みを備え、長い処理を管理しやすいチャンクに分割して、Claude Code のリクエストタイムアウトを防ぐための専門的な戦略です。

このスキルを使用する場面

次の場合に使用します。

• 大量の処理を行う場合（100 個以上のファイル、リポジトリなど）
• 長時間実行されるコマンドを実行する場合（60 秒超）
• 大規模なデータセットを処理する場合
• 複数のファイルを順番にダウンロードする場合
• 複雑な複数ステップのワークフローを実行する場合
• 応答の遅い外部 API を利用する場合
• タイムアウトのリスクがある処理全般

タイムアウトの制限を理解する

Claude Code のタイムアウト動作

• ツールのデフォルトタイムアウト：120 秒（2 分）
• リクエストタイムアウト：応答サイクル全体に適用
• タイムアウトの原因：
  • 長時間実行される bash コマンド
  • 大規模なファイル操作
  • 多数の項目を順番に処理すること
  • 適切なタイムアウト設定がないネットワーク操作
  • 進捗を示さないブロッキング処理

主な防止策

1. タスクの分割

大規模な処理を小さなバッチに分割します。

# ❌ BAD: Process all 1000 files at once
for file in $(find . -name "*.txt"); do
    process_file "$file"
done

# ✅ GOOD: Process in batches of 10
find . -name "*.txt" | head -10 | while read file; do
    process_file "$file"
done
# Then process next 10, etc.

2. 進捗チェックポイント

中断された場合に再開できるよう、進捗を保存します。

# Create checkpoint file
CHECKPOINT_FILE="progress.txt"

# Save completed items
echo "completed_item_1" >> "$CHECKPOINT_FILE"

# Skip already completed items
if grep -q "completed_item_1" "$CHECKPOINT_FILE"; then
    echo "Skipping already processed item"
fi

3. バックグラウンドプロセス

長時間かかる処理をバックグラウンドで実行します。

# Start long-running process in background
long_command > output.log 2>&1 &
echo $! > pid.txt

# Check status later
if ps -p $(cat pid.txt) > /dev/null; then
    echo "Still running"
else
    echo "Completed"
    cat output.log
fi

4. 段階的な処理

段階的に処理して結果を報告します。

# Process items one at a time with status updates
TOTAL=100
for i in $(seq 1 10); do  # First 10 of 100
    process_item $i
    echo "Progress: $i/$TOTAL"
done
# Continue with next 10 in subsequent calls

5. タイムアウトの設定

コマンドに明示的なタイムアウトを設定します。

# Use timeout command
timeout 60s long_command || echo "Command timed out"

# Set timeout in tool calls
yt-dlp --socket-timeout 30 "URL"
git clone --depth 1 --timeout 60 "URL"

実践的なパターン

パターン 1：ファイルのバッチ処理

# Define batch size
BATCH_SIZE=10
OFFSET=${1:-0}  # Accept offset as parameter

# Process batch
find . -name "*.jpg" | tail -n +$((OFFSET + 1)) | head -$BATCH_SIZE | while read file; do
    convert "$file" -resize 800x600 "thumbnails/$(basename $file)"
    echo "Processed: $file"
done

# Report next offset
NEXT_OFFSET=$((OFFSET + BATCH_SIZE))
echo "Next batch: Run with offset $NEXT_OFFSET"

使用方法：

# First batch
./process.sh 0

# Next batch
./process.sh 10

# Continue...
./process.sh 20

パターン 2：チェックポイントを使ったリポジトリのクローン

#!/bin/bash
REPOS_FILE="repos.txt"
CHECKPOINT="downloaded.txt"

# Read repos, skip already downloaded
while read repo; do
    # Check if already downloaded
    if grep -q "$repo" "$CHECKPOINT" 2>/dev/null; then
        echo "✓ Skipping $repo (already downloaded)"
        continue
    fi

    # Clone with timeout
    echo "Downloading $repo..."
    if timeout 60s git clone --depth 1 "$repo" 2>/dev/null; then
        echo "$repo" >> "$CHECKPOINT"
        echo "✓ Downloaded $repo"
    else
        echo "✗ Failed: $repo"
    fi
done < <(head -5 "$REPOS_FILE")  # Only 5 at a time

echo "Processed 5 repos. Check $CHECKPOINT for status."

パターン 3：進捗を追跡するダウンロード

#!/bin/bash
URLS_FILE="urls.txt"
PROGRESS_FILE="download_progress.json"

# Initialize progress
[ ! -f "$PROGRESS_FILE" ] && echo '{"completed": 0, "total": 0}' > "$PROGRESS_FILE"

# Get current progress
COMPLETED=$(jq -r '.completed' "$PROGRESS_FILE")
TOTAL=$(wc -l < "$URLS_FILE")

# Download next batch (5 at a time)
BATCH_SIZE=5
tail -n +$((COMPLETED + 1)) "$URLS_FILE" | head -$BATCH_SIZE | while read url; do
    echo "Downloading: $url"
    if yt-dlp --socket-timeout 30 "$url"; then
        COMPLETED=$((COMPLETED + 1))
        echo "{\"completed\": $COMPLETED, \"total\": $TOTAL}" > "$PROGRESS_FILE"
    fi
done

# Report progress
COMPLETED=$(jq -r '.completed' "$PROGRESS_FILE")
echo "Progress: $COMPLETED/$TOTAL"
[ $COMPLETED -lt $TOTAL ] && echo "Run again to continue."

パターン 4：レート制限を設けた並列実行

#!/bin/bash
MAX_PARALLEL=3
COUNT=0

for item in $(seq 1 15); do
    # Start background job
    (
        process_item $item
        echo "Completed: $item"
    ) &

    COUNT=$((COUNT + 1))

    # Wait when reaching max parallel
    if [ $COUNT -ge $MAX_PARALLEL ]; then
        wait -n  # Wait for any job to finish
        COUNT=$((COUNT - 1))
    fi

    # Rate limiting
    sleep 0.5
done

# Wait for remaining jobs
wait
echo "All items processed"

パターン 5：再開可能なステートマシン

#!/bin/bash
STATE_FILE="workflow_state.txt"

# Read current state (default: START)
STATE=$(cat "$STATE_FILE" 2>/dev/null || echo "START")

case $STATE in
    START)
        echo "Phase 1: Initialization"
        initialize_project
        echo "PHASE1" > "$STATE_FILE"
        echo "Run again to continue to Phase 2"
        ;;
    PHASE1)
        echo "Phase 2: Processing (Batch 1 of 3)"
        process_batch_1
        echo "PHASE2" > "$STATE_FILE"
        echo "Run again for Phase 3"
        ;;
    PHASE2)
        echo "Phase 3: Processing (Batch 2 of 3)"
        process_batch_2
        echo "PHASE3" > "$STATE_FILE"
        echo "Run again for Phase 4"
        ;;
    PHASE3)
        echo "Phase 4: Processing (Batch 3 of 3)"
        process_batch_3
        echo "PHASE4" > "$STATE_FILE"
        echo "Run again for finalization"
        ;;
    PHASE4)
        echo "Phase 5: Finalization"
        finalize_project
        echo "COMPLETE" > "$STATE_FILE"
        echo "Workflow complete!"
        ;;
    COMPLETE)
        echo "Workflow already completed"
        ;;
esac

コマンドの最適化

Bash コマンドの最適化

# ❌ SLOW: Multiple commands sequentially
git clone repo1
git clone repo2
git clone repo3

# ✅ FAST: Parallel with wait
git clone repo1 &
git clone repo2 &
git clone repo3 &
wait

ファイル操作の最適化

# ❌ SLOW: Process one file at a time
for file in *.txt; do
    cat "$file" | process > "output/$file"
done

# ✅ FAST: Parallel processing
for file in *.txt; do
    cat "$file" | process > "output/$file" &
done
wait

ネットワーク呼び出しの最適化

# ❌ SLOW: Sequential API calls
for id in {1..100}; do
    curl "https://api.example.com/item/$id"
done

# ✅ FAST: Batch API call
curl "https://api.example.com/items?ids=1,2,3,4,5"

Claude Code との統合

戦略 1：複数ターンのワークフロー

1 回の長い処理ではなく、複数のターンに分割します。

ターン 1：

Process first 10 repositories and report progress

ターン 2：

Process next 10 repositories (11-20)

ターン 3：

Process final batch and generate report

戦略 2：ステータス確認パターン

# Turn 1: Start background process
./long_operation.sh > output.log 2>&1 &
echo $! > pid.txt
echo "Started background process"

# Turn 2: Check status
if ps -p $(cat pid.txt) > /dev/null; then
    echo "Still running... Check again"
    tail -20 output.log
else
    echo "Completed!"
    cat output.log
fi

戦略 3：段階的な結果報告

処理を進めながら途中経過を報告します。

echo "=== Batch 1 Results ==="
process_batch_1
echo ""
echo "=== Batch 2 Results ==="
process_batch_2

エラー処理

グレースフルデグラデーション

# Try operation with timeout, fallback if fails
if timeout 30s expensive_operation; then
    echo "Operation completed"
else
    echo "Operation timed out, using cached result"
    cat cached_result.txt
fi

再試行ロジック

MAX_RETRIES=3
RETRY_COUNT=0

while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
    if timeout 60s risky_operation; then
        echo "Success!"
        break
    else
        RETRY_COUNT=$((RETRY_COUNT + 1))
        echo "Attempt $RETRY_COUNT failed, retrying..."
        sleep 5
    fi
done

ベストプラクティス

✅ 実施すること

1. 大規模な処理を分割する：一度に 5～10 個の項目を処理します
2. 進捗を保存する：チェックポイントファイルを使用します
3. 段階的に報告する：処理を進めながら結果を示します
4. タイムアウトを設定する：タイムアウト値を明示的に指定します
5. 適切に並列化する：同時処理は最大 3～5 件にします
6. 再開できるようにする：処理を再開可能にします
7. 進捗を監視する：完了率を表示します
8. 長時間のタスクをバックグラウンドで実行する：非同期処理には & を使用します

❌ 避けること

1. すべてを一度に処理しない：大規模なデータセットはバッチ処理します
2. 無期限にブロックしない：必ずタイムアウトを設定します
3. 状態を無視しない：実行のたびに進捗を保存します
4. 無言で処理しない：定期的に進捗を報告します
5. 無限に再試行しない：再試行回数に上限を設けます
6. 過剰に並列化しない：同時処理数を制限します
7. 成功を前提にしない：必ず戻り値コードを確認します
8. クリーンアップを省略しない：一時ファイルを削除します

よくあるシナリオ

シナリオ 1：YouTube 動画を 100 本ダウンロードする

# DON'T do this (will timeout)
yt-dlp -a urls.txt  # 100 URLs

# DO this instead
head -5 urls.txt | yt-dlp -a -
# Then process next 5 in another turn

シナリオ 2：リポジトリを 50 個クローンする

# DON'T
for repo in $(cat repos.txt); do
    git clone $repo
done

# DO
head -5 repos.txt | while read repo; do
    timeout 60s git clone --depth 1 $repo
done
# Continue with tail -n +6 in next turn

シナリオ 3：画像を 1000 枚処理する

# DON'T
for img in *.jpg; do
    convert $img processed/$img
done

# DO
find . -name "*.jpg" | head -20 | xargs -P 4 -I {} convert {} processed/{}
# Process next 20 in subsequent turn

監視とデバッグ

実行時間を追跡する

start_time=$(date +%s)
# ... operations ...
end_time=$(date +%s)
duration=$((end_time - start_time))
echo "Duration: ${duration}s"

すべてをログに記録する

LOG_FILE="operation.log"
{
    echo "Started at $(date)"
    perform_operations
    echo "Completed at $(date)"
} | tee -a "$LOG_FILE"

進捗インジケーター

TOTAL=100
for i in $(seq 1 10); do
    process_item $i
    echo -ne "Progress: $i/$TOTAL\r"
done
echo ""

復旧戦略

チェックポイントに基づく復旧

# Check last successful checkpoint
LAST_CHECKPOINT=$(cat .checkpoint 2>/dev/null || echo 0)
echo "Resuming from item $LAST_CHECKPOINT"

# Continue from checkpoint
for i in $(seq $((LAST_CHECKPOINT + 1)) $((LAST_CHECKPOINT + 10))); do
    process_item $i && echo $i > .checkpoint
done

トランザクションのような処理

# Create temporary workspace
TEMP_DIR=$(mktemp -d)
trap "rm -rf $TEMP_DIR" EXIT

# Work in temp, only commit on success
cd $TEMP_DIR
perform_operations
if [ $? -eq 0 ]; then
    mv $TEMP_DIR/results ~/final/
fi

---

バージョン：1.0.0 最終更新日：2025-11-07 重要な原則：長い処理を管理しやすいチャンクに分割し、進捗を追跡して再開できるようにします