ファイル除外パターン設計

概要

ファイル監視システムにおける効率的な除外パターン設計の専門知識を提供します。

.gitignore互換のglob pattern、プラットフォーム固有の一時ファイル除外、パフォーマンス最適化のための早期除外戦略により、ビルドシステムやファイル監視ツールの効率を大幅に改善できます。

詳細な手順や背景は references/Level1_basics.md と references/Level2_intermediate.md を参照してください。

ワークフロー

Phase 1: 要件分析とTask選択

目的: プロジェクト要件を分析し、適切なTaskを選択する

アクション:

1. プロジェクトタイプ、対象プラットフォーム、パフォーマンス要件を確認
2. 下記の「Task仕様ナビ」から実行すべきTaskを選択
3. references/Level1_basics.md で基礎知識を確認

Task選択ガイド:

• 新規プロジェクト → Pattern Designer
• 複数OS対応 → Platform Optimizer
• パフォーマンス問題 → Performance Tuner
• 検証が必要 → Pattern Validator

Phase 2: Task実行

目的: 選択したTaskを実行し、除外パターンを設計・最適化する

アクション:

1. agents/ の該当Task仕様書を参照
2. Task仕様に従って必要な入力を準備
3. Task実行（必要に応じて複数Taskを順次実行）
4. 各Taskの成果物を次のTaskへ引き継ぐ

Task実行順序の例:

Pattern Designer → Platform Optimizer → Performance Tuner → Pattern Validator

Phase 3: 検証と記録

目的: 成果物の検証と実行記録の保存

アクション:

1. Pattern Validator で最終検証を実施
2. 生成されたパターンファイルをプロジェクトに適用
3. scripts/log_usage.mjs を実行して記録を残す

検証コマンド:

node .claude/skills/file-exclusion-patterns/scripts/log_usage.mjs \
  --result success \
  --phase "Phase 2" \
  --agent "pattern-designer"

Task仕様ナビ

各Taskの詳細仕様は agents/ ディレクトリに配置されています。実行直前に該当ファイルを読み込んでください。

Pattern Designer

ファイル: agents/pattern-designer.md

目的: プロジェクト要件に基づいた除外パターンの設計

入力:

• プロジェクト情報（言語、パッケージマネージャ、ビルドツール等）
• カスタム要件（追加の除外パターン）

出力:

• .gitignore形式の除外パターンファイル
• 設計メモ（パターン選択の根拠）

参照リソース:

• references/Level1_basics.md - 基本パターン
• references/standard-patterns.md - プロジェクト別テンプレート
• references/glob-pattern-guide.md - glob構文リファレンス

使用タイミング:

• 新規プロジェクトで.gitignoreを作成する時
• 既存パターンを見直したい時
• プロジェクトタイプに応じた標準パターンが必要な時

Platform Optimizer

ファイル: agents/platform-optimizer.md

目的: Windows/macOS/Linux対応の最適化

入力:

• ターゲットプラットフォーム（Windows, macOS, Linux）
• ベース除外パターン（Pattern Designerの出力）

出力:

• プラットフォーム最適化パターン
• プラットフォーム互換性レポート

参照リソース:

• references/platform-specific-exclusions.md - OS別パターン集
• references/Level3_advanced.md - クロスプラットフォーム戦略

使用タイミング:

• 複数OSで開発するプロジェクトの設定時
• OS固有の一時ファイルを除外したい時
• プラットフォーム間の互換性問題を解決したい時

Performance Tuner

ファイル: agents/performance-tuner.md

目的: パフォーマンス最適化のためのパターン配置

入力:

• 除外パターンセット
• プロジェクト統計情報（ファイル数、ディレクトリ構造等）

出力:

• 最適化済み除外パターン（処理順序を最適化）
• パフォーマンス改善レポート

参照リソース:

• references/Level2_intermediate.md - 早期除外戦略
• references/Level4_expert.md - 大規模システム最適化

使用タイミング:

• ファイル監視が遅い時
• ビルド時間を短縮したい時
• 大規模プロジェクトでパフォーマンス問題が発生した時

Pattern Validator

ファイル: agents/pattern-validator.md

目的: 除外パターンの検証と修正提案

入力:

• 検証対象パターン
• プロジェクトコンテキスト（任意）

出力:

• 検証レポート（構文チェック、機能チェック）
• 修正済みパターン（問題がある場合）

参照リソース:

• references/glob-pattern-guide.md - 正しいglob構文
• references/Level3_advanced.md - アンチパターン集

使用タイミング:

• パターン設計後の最終確認時
• 既存パターンの問題を診断したい時
• アンチパターンを検出したい時

ベストプラクティス

すべきこと

• プロジェクト分析: Pattern Designerでプロジェクトタイプに適したベースパターンを選択する
• glob構文の確認: references/glob-pattern-guide.md で正しい構文を参照する
• OS対応: Platform Optimizerで複数OSの一時ファイルを適切に除外する
• パフォーマンス重視: Performance Tunerで頻繁にマッチするパターンを上位に配置する
• 検証の実施: Pattern Validatorで構文エラーやアンチパターンをチェックする
• 段階的実装: Task仕様に従い、入力→処理→検証のフローを守る
• 記録の保存: scripts/log_usage.mjs で実行結果を記録し、継続的改善に活用する

避けるべきこと

• 検証スキップ: Pattern Validatorを使わずにパターンを本番適用することを避ける
• アンチパターン: **/node_modules/*/ などの誤ったglob構文を使用しない
• プラットフォーム無視: OS固有の違いを考慮せず、すべての環境で同じパターンを使わない
• 順序の軽視: パフォーマンスを無視した無秩序なパターン配置を避ける
• 過剰な否定パターン: ! による否定パターンを多用しすぎない（保守性低下）
• 知識の欠如: globパターンの仕様を理解せずに見よう見まねでパターンを書かない
• テスト不足: 実際のプロジェクトで動作確認せずに複雑なパターンを導入しない

リソース参照

Task仕様書（agents/）

実行直前に読み込む、Taskの詳細仕様書：

# Pattern Designer - 基本パターン設計
cat .claude/skills/file-exclusion-patterns/agents/pattern-designer.md

# Platform Optimizer - プラットフォーム最適化
cat .claude/skills/file-exclusion-patterns/agents/platform-optimizer.md

# Performance Tuner - パフォーマンス最適化
cat .claude/skills/file-exclusion-patterns/agents/performance-tuner.md

# Pattern Validator - パターン検証
cat .claude/skills/file-exclusion-patterns/agents/pattern-validator.md

学習リソース（references/）

必要時に読み込む知識ベース：

# レベル別ガイド
cat .claude/skills/file-exclusion-patterns/references/Level1_basics.md
cat .claude/skills/file-exclusion-patterns/references/Level2_intermediate.md
cat .claude/skills/file-exclusion-patterns/references/Level3_advanced.md
cat .claude/skills/file-exclusion-patterns/references/Level4_expert.md

# 専門リソース
cat .claude/skills/file-exclusion-patterns/references/glob-pattern-guide.md
cat .claude/skills/file-exclusion-patterns/references/platform-specific-exclusions.md
cat .claude/skills/file-exclusion-patterns/references/standard-patterns.md

スクリプト実行（scripts/）

決定論的な処理を確実に実行：

# スキル構造の検証
node .claude/skills/file-exclusion-patterns/scripts/validate-skill.mjs

# 使用記録とメトリクス更新
node .claude/skills/file-exclusion-patterns/scripts/log_usage.mjs \
  --result success \
  --phase "Phase 2" \
  --agent "pattern-designer" \
  --notes "Node.js monorepo pattern created"

テンプレート・ツール（assets/）

出力で使用する素材：

# パターンビルダーテンプレート
cat .claude/skills/file-exclusion-patterns/assets/pattern-builder.ts

よく使うコマンド

# gitignore パターンを検証
npx gitignore-parser .gitignore

# ファイル監視の除外設定をテスト
chokidar 'src/**/*' --ignore 'node_modules/**'

# git で除外されているか確認
git check-ignore -v path/to/file

# 既にgit追跡されているファイルをキャッシュから削除
git rm --cached path/to/file

トラブルシューティング

パターンが効かない

症状: .gitignoreに追加したのにファイルが除外されない

原因と対処:

1. 既にgit追跡されている → git rm --cached <file> でキャッシュクリア
2. glob構文が間違っている → Pattern Validatorで検証
3. 否定パターンの順序 → 除外パターンの後に ! パターンを配置

パフォーマンスが改善しない

症状: 除外パターンを追加したが監視が遅い

原因と対処:

1. パターンの順序が非効率 → Performance Tunerで最適化
2. 複雑すぎるパターン → シンプルなディレクトリ除外に変更
3. 除外漏れ → Pattern Designerで標準パターンを確認

プラットフォーム間で動作が異なる

症状: WindowsとmacOSで除外結果が違う

原因と対処:

1. パスセパレータの問題 → / を使用（\ は避ける）
2. 大文字小文字の扱い → Platform Optimizerで確認
3. OS固有ファイルの除外漏れ → references/platform-specific-exclusions.md を参照

メトリクスとフィードバック

このスキルの使用状況とパフォーマンスは EVALS.json と LOGS.md で追跡されます。

レベルアップ条件:

• Level 1: 基本的な使用（1回以上、成功率50%以上）
• Level 2: プラットフォーム最適化の習得（5回以上、成功率70%以上）
• Level 3: パフォーマンスチューニングの習得（10回以上、成功率80%以上）
• Level 4: エキスパートレベルの運用（20回以上、成功率90%以上）

フィードバックの記録:

# 成功時
node scripts/log_usage.mjs --result success --phase "Phase 2" --agent "pattern-designer"

# 失敗時（改善のヒントを含める）
node scripts/log_usage.mjs --result failure --notes "glob syntax error detected"

変更履歴