safe-project-organizer

安全なプロジェクト整理

概要

このスキルを使用すると、Claude Code がプロジェクト構造を分析し、ファイルの移動、未使用ディレクトリの削除、フォルダー構成の変更など、安全な整理方法を提案できます。多段階の検証、ドライランによるプレビュー、明示的なユーザー確認を通じて、安全性を優先します。

安全性の基本原則

1. 読み取り専用の分析フェーズ

• すべての分析操作は読み取り専用です
• スキャン中に変更は行われません
• 変更を加える前に、プロジェクト全体のスナップショットを作成します

2. ドライランによる検証

• すべての操作で、実行前に変更をプレビューします
• 影響を受けるファイルパスを正確に表示します
• 影響の指標（移動、削除、作成されるファイル数）を算出します

3. 明示的なユーザー確認

• 操作カテゴリごとに確認を求めます
• 変更内容の詳細な概要を表示します
• 提案を選択して承認できるようにします

4. ロールバック可能なアトミック操作

• 各操作を元に戻せます
• 変更前にバックアップ参照を作成します
• 監査証跡として操作ログを保持します

5. 保護対象のファイルパターン

以下のパターンに一致するファイルは変更しません：

• .git/、.svn/、.hg/（バージョン管理）
• node_modules/、vendor/、venv/、.venv/（依存関係）
• .env*、secrets.*、credentials.*（機密データ）
• package-lock.json、yarn.lock、pnpm-lock.yaml（ロックファイル）
• dist/、build/、.next/、.nuxt/（ビルド成果物）

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

以下のような状況で、このスキルを使用してください：

プロジェクトの整理：

• 「プロジェクトのルートにファイルが多すぎて散らかっています」
• 「整理すべき空のディレクトリがあります」
• 「ドキュメントファイルがあちこちに散らばっています」

標準化：

• 「このプロジェクトは標準的なディレクトリ構成に従っていません」
• 「ルートでソースファイルと設定ファイルが混在しています」
• 「保守性を高めるために、ファイルを種類別に整理したいです」

移行の準備：

• 「このプロジェクトを引き継ぐ予定なので、整理しておく必要があります」
• 「このコードベースは、新機能を追加する前に、より適切な整理が必要です」
• 「プロジェクト構成を標準化したいです」

安全性への懸念：

• 「誤って何かを壊してしまわないか心配です」
• 「変更を加える前に、何が変わるのかを正確に確認する必要があります」
• 「データを失わずに、安全に再整理したいです」

安全に使用するワークフロー

ステップ 1：初回スキャン（読み取り専用）

--scan フラグを指定して、プロジェクト整理スクリプトを実行します：

python3 scripts/project_organizer.py /path/to/project --scan

実行内容：

• プロジェクト全体の構造をスキャンします
• ファイルの種類、数、サイズを特定します
• 空のディレクトリを検出します
• 保護対象のファイルを一覧表示します
• 変更は一切行いません

出力例：

🔍 Scanning project: /path/to/project
📋 This is a READ-ONLY scan. No changes will be made.

✅ Scan complete!
   📁 Directories: 24
   📄 Files: 156
   🔒 Protected items: 42
   📂 Empty directories: 3

ステップ 2：提案の生成（引き続き読み取り専用）

--analyze フラグを使用して、整理の提案を生成します：

python3 scripts/project_organizer.py /path/to/project --analyze

実行内容：

• 詳細な分析を行います
• 整理の提案を生成します
• 提案の件数を表示します
• 変更は引き続き行いません

ステップ 3：変更のプレビュー（詳細な確認）

--preview フラグを使用して、何が変わるのかを正確に確認します：

python3 scripts/project_organizer.py /path/to/project --preview

実行内容：

• すべての提案の詳細なプレビューを表示します
• 操作の種類（移動、削除、作成）ごとにまとめます
• リスクレベル（🟢 低、🟡 中、🔴 高）を表示します
• 各操作の安全性チェックを表示します
• 影響を受けるファイルパスを正確に一覧表示します
• 変更は一切行いません

プレビュー出力例：

📋 PREVIEW MODE - No changes will be made
============================================================

📊 Total Suggestions: 8

🎯 By Action:
   MOVE: 5
   DELETE: 2
   CREATE_DIR: 1

⚠️  By Risk Level:
   🟢 LOW: 6
   🟡 MEDIUM: 2

📝 Detailed Suggestions:

MOVE Operations (5):
1. 🟢 Documentation/config files organized in docs/ directory
   FROM: CONTRIBUTING.md
   TO:   docs/CONTRIBUTING.md
   Safety Checks:
      ✓ File is not a primary config
      ✓ No imports reference this file path
      ✓ Not in protected patterns

DELETE Operations (2):
1. 🟢 Empty directory with no files or subdirectories
   PATH: old_backup/temp
   Safety Checks:
      ✓ Directory is empty
      ✓ Not a protected path
      ✓ No version control markers

ステップ 4：ドライラン（シミュレーションのみ）

--execute フラグを使用して、ドライランのシミュレーションを行います：

python3 scripts/project_organizer.py /path/to/project --execute

実行内容：

• すべての操作をシミュレーションします
• 実際に行われる内容を表示します
• すべての安全性チェックを検証します
• 成功、失敗、スキップの結果を報告します
• 実際の変更は行いません

ステップ 5：実際の実行（確認が必要）

十分に確認した後に限り、--execute-real フラグを使用します：

python3 scripts/project_organizer.py /path/to/project --execute-real

実行内容：

• 明示的な確認を求めます
• 承認された変更を実行します
• 監査ログ（.project_organizer.log）を作成します
• 進行状況をリアルタイムで表示します
• プロジェクトを実際に変更します

確認プロンプト：

⚠️  WARNING: This will make REAL changes. Type 'yes' to confirm: yes

操作の種類と安全性

移動操作

低リスク（🟢）：

• ドキュメントファイルを docs/ に移動する
• 設定ファイルを config/ に移動する
• スクリプトを scripts/ に移動する

中リスク（🟡）：

• ソースファイルを種類別に分類する
• 整理用のディレクトリを作成する

実施される安全性チェック：

• ソースファイルが存在し、アクセス可能である
• ソースが保護対象のパターンに該当しない
• 移動先がすでに存在しない
• 親ディレクトリを安全に作成できる

削除操作

低リスク（🟢）：

• 本当に空のディレクトリを削除する
• 一時ファイルを削除する

実施される安全性チェック：

• 対象が存在する
• ディレクトリが完全に空である
• 保護対象のパスではない
• バージョン管理のマーカーがない

ディレクトリ作成操作

低リスク（🟢）：

• 標準ディレクトリ（src/、docs/、tests/）を作成する
• 整理用の構造を作成する

実施される安全性チェック：

• 対象がすでに存在しない
• 名前の競合がない
• 標準的なディレクトリパターンである
• 親ディレクトリを作成できる

保護対象のファイルパターン

このスキルは、以下のパスが変更されないよう自動的に保護します。

バージョン管理

• .git/、.git/**
• .svn/、.svn/**
• .hg/、.hg/**

依存関係

• node_modules/、node_modules/**
• vendor/、vendor/**
• venv/、venv/**
• .venv/、.venv/**

ビルド成果物

• dist/、dist/**
• build/、build/**
• .next/、.next/**
• .nuxt/、.nuxt/**
• out/、out/**

機密データ

• .env*
• secrets.*
• credentials.*

ロックファイル

• package-lock.json
• yarn.lock
• pnpm-lock.yaml
• Gemfile.lock
• Pipfile.lock
• poetry.lock

キャッシュファイル

• __pycache__/、__pycache__/**

ベストプラクティス

スキルを実行する前に

1. 変更をコミットする：現在の作業がすべてバージョン管理にコミットされていることを確認します
2. 重要なファイルをバックアップする：最近のバックアップ、または利用可能な git stash を用意します
3. プロジェクトを確認する：重要なファイルやディレクトリを把握します
4. アクセス権を確認する：必要な権限があることを確認します

実行中

1. 必ずスキャンから始める：まず --scan を実行してプロジェクトを把握します
2. 提案を慎重に確認する：生成された提案をすべて確認します
3. プレビューモードを使用する：実行前に必ず --preview を使用します
4. ドライランでテストする：--execute を使用して、安全に変更をシミュレートします

実行後

1. プロジェクトが動作することを確認する：プロジェクトが引き続き正しくビルド・実行できるかテストします
2. 操作ログを確認する：変更内容を .project_organizer.log で確認します
3. 個別にコミットする：整理に関する変更は、機能に関する変更とは分けてコミットします
4. ドキュメントを更新する：古いファイルパスを参照しているドキュメントを更新します

安全性チェックリスト

--execute-real を使用する前に、以下を確認してください。

• プロジェクトがバージョン管理にコミットされている
• すべての提案をプレビューモードで確認した
• ドライランが正常に完了した
• 重要なファイルが移動されない
• ビルド・テストのプロセスが引き続き動作する
• 共有プロジェクトの場合、チームメンバーに通知した

エラー処理とトラブルシューティング

よくある問題

権限が拒否される：

• 書き込み権限があることを確認します
• ファイルの所有者を確認します
• 適切な権限が必要な場合があります

パスが保護されている：

• 保護対象のパターンを確認します
• そのパスを変更すべきか確認します
• 必要に応じてパターンを調整します

変更が反映されない：

• --execute だけでなく --execute-real を使用したことを確認します
• 操作ログを確認します
• 確認プロンプトで「yes」と入力したことを確認します

復元方法

Git による復元：

git status                    # See what changed
git checkout -- .            # Restore all changes
git reset --hard HEAD        # Full reset to last commit

操作ログの確認：

cat .project_organizer.log    # Review detailed operation log

カスタマイズ

カスタム保護パターンの追加

スクリプト内の PROTECTED_PATTERNS リストを編集します。

PROTECTED_PATTERNS = [
    # Existing patterns...
    'my_important_dir/**',    # Custom protection
    '*.critical',             # Protect critical files
]

カスタム整理ルール

MOVABLE_ROOT_FILES 辞書を編集します。

MOVABLE_ROOT_FILES = {
    'assets': ['*.png', '*.jpg', '*.svg'],  # Move images to assets/
    'data': ['*.csv', '*.json', '*.xml'],   # Move data files
}

カスタム安全性バリデーター

SafeProjectOrganizer クラスを拡張します。

def _custom_safety_check(self, path: Path) -> bool:
    """Your custom safety logic"""
    # Return True if safe, False if should be protected
    return True

Claude Code との連携

スキルツールとして

このスキルは Claude Code のワークフローと自然に統合されます:

1. ユーザーリクエスト: 「プロジェクト構造を整理して」
2. スキルの有効化: Safe Project Organizer が読み込まれます
3. 順次実行: 5 ステップのワークフローを自動的に実行します
4. ユーザーの確認: 続行する前に各ステップを確認します
5. 安全性の検証: すべての操作に安全チェックが含まれます

ユーザー操作の例

シンプルなクリーンアップ:

User: "My project root is messy, can you help organize it?"
Claude: [Uses skill to scan and suggest safe improvements]

対象を絞った整理:

User: "I have too many documentation files scattered around"
Claude: [Uses skill to identify and suggest grouping docs/ folder]

移行前のクリーンアップ:

User: "I need to clean up before handing this project to another team"
Claude: [Uses skill for comprehensive safe reorganization]

リソース

scripts/

• project_organizer.py - 包括的な安全機能を備えた、主要な安全なプロジェクト整理スクリプト

このスクリプトには以下が含まれます:

• 多段階の分析と実行
• 保護パターンの検出
• リスクレベルの分類
• 包括的な安全チェック
• 監査証跡の生成
• ロールバック情報の保持

このスクリプトは、手動でのプロジェクト整理タスクのために Claude Code とは独立して実行できます。

---

安全性の保証: このスキルは明示的な確認なしにファイルを変更することはなく、常に変更をプレビューし、重要なプロジェクトデータを保護するための包括的な安全チェックを含みます。

---

必須のユーザー検証要件

ポリシー: ユーザーの確認なしに修正を主張しない

重要: いかなる問題、バグ、不具合が「修正された」「解決された」「動作している」「完了した」と主張する前に、以下の検証プロトコルが必須です:

ステップ 1: 技術的検証

• 関連するすべてのテスト (ビルド、型チェック、単体テスト) を実行する
• コンソールエラーがないことを確認する
• 修正のスクリーンショット/証拠を取得する

ステップ 2: ユーザー検証の依頼

必須: AskUserQuestion ツールを使用して、修正の検証をユーザーに明示的に依頼します:

"I've implemented [description of fix]. Before I mark this as complete, please verify:
1. [Specific thing to check #1]
2. [Specific thing to check #2]
3. Does this fix the issue you were experiencing?

Please confirm the fix works as expected, or let me know what's still not working."

ステップ 3: ユーザーの確認を待つ

• ユーザーが応答するまで、成功の主張を進めてはいけません
• ユーザーの確認なしにタスクを「完了」としてマークしてはいけません
• ユーザーの検証なしに「修正された」「解決された」「動作している」といった表現を使用してはいけません

ステップ 4: ユーザーのフィードバックに対応する

• ユーザーが確認した場合: 修正を文書化し、完了としてマークします
• ユーザーが問題を報告した場合: デバッグを続行し、検証サイクルを繰り返します

禁止される行為 (ユーザーの検証なし)

• バグが「修正された」と主張すること
• 機能が「動作している」と述べること
• 問題を「解決済み」としてマークすること
• 機能を「完了」と宣言すること
• 修正に関するあらゆる成功の主張

ユーザー検証の依頼前に必要な証拠

1. 技術テストに合格していること
2. Playwright/スクリーンショットによる視覚的な確認
3. 実行された具体的なテストシナリオ
4. 変更内容の明確な説明

覚えておいてください: 何かが修正されたかどうかの最終的な判断権限はユーザーにあります。例外はありません。