GaoFei2025-0314/tidy

Tidy · プロジェクト整理規範

リポジトリ内のすべてのファイルは、次の3つの質問に答えなければなりません：

1. なぜ存在するのか？（必要性）——削除すると何が壊れますか？
2. なぜここにあるのか？（所属）——このプロジェクトのディレクトリ規則に従って、どのディレクトリに属しますか？
3. 他の人が理解できるか？（可読性）——ファイル名とREADMEだけで、新しい人がその役割を推測できますか？

ユーザーが /tidy と入力した場合、以下の「モード2：既存プロジェクトの整理」を直接実行します。

3層メカニズム

層	役割	実行主体
ディレクトリ規則 .claude/tidy.json	各トップレベルディレクトリの内容を宣言し、「どこに置くべきか」を判断からルックアップテーブルに変換	プロジェクト整理時に生成し、その後は長期メンテナンス
Hooks（プラグインと共にインストール）	セッション開始時にルールとディレクトリ規則を注入；新しいファイルをインターセプト；各ラウンド終了時に新規ファイルをチェック	自動（以下の「Hookプロンプト受信時」を参照）
本スキル	コード作成時の判断基準、古いプロジェクト整理のフロー	あなた

Hooksは新規ファイルのみをチェックし、既存プロジェクトの問題は「モード2」で整理します。

3つのチェック粒度

タイミング	実行内容
新規ファイル作成時	以下の4つの質問を確認（Hooksがあれば自動インターセプト）
区切り/タスク終了時	audit.py <ルートディレクトリ> --changed（gitプロジェクト、HEADからの変更のみ）または --since 2h（変更時刻基準、非gitプロジェクトでも使用可能）。Hooksがないツール（Codex、Cursor）は、毎回の成果物提出前に実行してください。
ユーザーがプロジェクト整理を要求	全量 audit.py <ルートディレクトリ> を実行し、「モード2」を実行

確認後、処理が不要な警告（意図的な成果物コピー、サードパーティファイル名）は、audit.py <ルートディレクトリ> --review <ルール> <パス> --reason <結論> で記録し、以降報告しないようにします。ファイル内容が変更されると再表示され、再確認を促します。

---

モード1：コード作成時（毎回適用）

新規ファイル作成前の4つの質問

質問	不合格時の対処
必要ですか？ 既存ファイルに書き込めませんか？一度きりのものですか？	既存ファイルにマージ；一度きりの内容は返信内に記述し、ファイルとして保存しない
どこに置く？ .claude/tidy.json のレイアウトに従っていますか？	既に宣言されたディレクトリに配置；新しいトップレベルディレクトリが必要な場合、まずレイアウトとREADME「ディレクトリ構造」に登録
名前は？ 名前が用途を説明し、同じディレクトリ内のスタイルと一貫していますか？	references/naming.md に従って命名
コミットすべきですか？ 生成物、依存関係、シークレット、大きなファイルですか？	.gitignore に追加し、バージョン管理対象外に

AIの最もよくある悪い習慣（禁止）

❌ 悪い習慣	✅ 正しい方法
ルートディレクトリに test.py、debug.js、check_xxx.py などの一時スクリプトを作成	.scratch/（確実に無視されるように）またはシステムの一時ディレクトリに書き込み、タスク終了後に削除
foo_v2.ts、foo_new.ts、foo.backup.ts、foo_old/ を複製	元のファイルを直接編集し、履歴はgitに任せる
作業ごとに IMPLEMENTATION_SUMMARY.md、FIX_REPORT.md を生成	要約は返信とコミットメッセージに記述；長期的な知識はREADMEや docs/ の既存ドキュメントにマージ
build/、out/、dist/、レンダリングされた動画/音声、ログをコミット	.gitignore に追加；READMEに生成方法を明記
node_modules/、.venv/ がコミットされたり、散らばっている	無視；多言語ツールチェーンはそれぞれ所定の位置に（structure.md「混合プロジェクト」を参照）
中国語、スペース、括弧を含むファイル名：提示词分享.md、final (1).mp4	ファイル名は英字のkebab-caseを使用し、中国語はファイルのタイトルに記述
スキャフォールドのサンプルを消していない、大量のコメントアウトされた古いコード、未使用の依存関係	参照がないことを確認して削除
同じ設定を2箇所に記述（.prettierrc + package.json#prettier）	1箇所のみ保持
「将来使うかもしれない」から空のディレクトリやファイルを事前に作成	使用時に作成

Hookプロンプト受信時

• 新規ファイルがインターセプトされた場合：指示に従って方法を変更——既存ファイルにマージ、ディレクトリ変更、名前変更、またはファイルとして保存しない。インターセプトを回避するためにBashでファイルを書き込まないでください（Stopチェックで検出されます）。
• 終了前チェックで問題がリストされた場合：1つずつ処理（一時ファイル削除、コピーのマージ、移動、.gitignore への追加）。処理が完了してから終了。
• ユーザーが明示的にそうするよう要求した場合（例：中国語のファイル名が必要）：ルールに従い、パスを .claude/tidy.json の allow に追加（例：{"non-portable-name": ["docs/課程/**"]}）、返信で説明。除外範囲は最小限にし、disable でルール全体を無効にしない。勝手に除外を追加しない。
• ローカルには保持するが、gitには入れたくないファイル（完成品、承認済みナレーション、モデルウェイトなど）：keepLocal に登録し理由を明記、.gitignore も追加。削除しない。
• 新しいトップレベルディレクトリが必要な場合：適切な既存ディレクトリがないことを確認してから、layout と README「ディレクトリ構造」に登録。

---

モード2：既存プロジェクトの整理

スクリプトは全て本スキルの scripts/ ディレクトリにあり、Python 3.9+ 標準ライブラリのみに依存します。

ステップ1：スキャン

python3 <skill>/scripts/audit.py <プロジェクトルート>            # テキストレポート
python3 <skill>/scripts/audit.py <プロジェクトルート> --format json

ステップ2：プロジェクトの理解と参照確認

スクリプトは発見的（ヒューリスティック）ですが、各警告は確認してから処理してください。テキストレポートは多数の同種問題を折りたたんで表示するため、1つずつ確認するには --all を追加します。結論を出す前に：

• README、package.json / pyproject.toml のスクリプトとエントリポイントを読む

• 削除または移動したい各ファイルの参照を確認：

  python3 <skill>/scripts/refs.py <プロジェクトルート> <ファイル> [<ファイル> ...]
  

  結論は4種類：in-use（明確な参照あり）、convention（フレームワークが規則に従ってロード）、maybe（弱い一致のみ）、unreferenced（見つからず）。unreferenced でも動的パスや外部呼び出しを考慮する。判断基準は references/file-necessity.md を参照。

ステップ3：整理案の提示と確認待ち

パス	アクション	移動先	理由
提示词分享.md	移動＋名前変更	docs/prompts.md	ルートディレクトリにドキュメントが散乱；非ASCIIファイル名
out/	.gitignore に追加	—	レンダリング成果物、npm run render で再生成可能
src/Root_old.tsx	削除	—	refs.py：unreferenced；内容は Root.tsx と同じ

アクションは7種類のみ：保持 / 移動 / 名前変更 / 削除 / アーカイブ / 無視 / ローカル保持（無視して削除せず、keepLocal に登録）。判断に迷う場合は「確認待ち」とマーク。警告が想定内（成果物コピー、連続フレームキャプチャ）の場合は、ルールに従って allow を追加するアクションとし、ファイルは削除しません。

削除と一括移動は、必ずユーザーの確認を得てから行ってください。 案が確定するまではファイルを操作しないでください。

ステップ4：実行

1. ワークスペースがクリーンであることを確認；gitリポジトリでない場合は、最初に git init と初期コミット（スナップショットとして）を提案。
2. python3 <skill>/scripts/audit.py <ルート> --fix-gitignore：無視されていない依存関係、生成物、ジャンクファイル、シークレットを .gitignore に自動追加（追記のみ、削除はしない）。gitに追跡されているものはリストアップされるので、git rm --cached が必要。
3. 移動/名前変更には git mv を使用；その後、古いパスに対して refs.py または grep を実行し、すべての参照（import、staticFile()、設定、スクリプト、ドキュメントリンク）を修正。
4. ビルド/テスト/lintを実行し、破損がないことを確認。
5. 構造変更とコード修正は別々のコミットにする。

ステップ5：ディレクトリ規則の固定（スキップしない）

整理が完了したら、ディレクトリ規則を生成し、今後のすべてのセッションで自動的に遵守されるようにします：

python3 <skill>/scripts/audit.py <ルート> --init     # 既存のトップレベルディレクトリから .claude/tidy.json のドラフトを生成

次に、各ディレクトリの説明を補完（TODO を置き換え）。記述は配置判断をガイドできるものにします。例："public/": "staticFile() で読み込まれる素材：画像、フォント、ナレーション"（単に「静的リソース」と書かない）。README「ディレクトリ構造」も更新します。設定形式は references/config.md を参照。

安全の基本線

• 再生成不可能なファイル（ユーザー素材、録音、手書きプロンプト、データ）は、確認なしに絶対に削除しない——適切なディレクトリに移動またはアーカイブ。
• .env などのシークレット内容は読み取らず、出力しない。シークレットがgitに追跡されていることが判明した場合は、ファイルを削除するだけでなく、ユーザーにシークレットのローテーションと履歴のクリーンアップを促す。
• ファイルが使用中かどうか不明な場合は、「確認待ち」とマークし、推測しない。

---

削除するか、アーカイブするか？

「gitに入れるか」と「削除するか」は別々に判断する。

このファイル……
├─ 低コストで再生成可能か？（ビルド成果物、キャッシュ、ログ、依存関係、一時的なフレームキャプチャ）
│    └─ はい → 削除 + .gitignore に追加
├─ 再生成可能だが、コストが高いか？（完成品、承認済みナレーション、レンダリング済みコースパッケージ、学習済みモデル——時間・費用・再承認が必要）
│    └─ はい → ローカル保持 + .gitignore に追加 + tidy.json の keepLocal に登録（理由を明記）、READMEに生成方法を記述
├─ gitに追跡されている古いコードか？
│    └─ はい → 直接削除（git履歴がアーカイブの役割を果たす）
├─ 再生成不可能で、まだ参照価値があるか？（調査ノート、古いプロンプト、デザイン案、決定記録）
│    └─ はい → docs/archive/ に移動、ファイル名に日付プレフィックスを追加、docs/archive/README.md に理由を一行記録
├─ 大容量の素材か？（音声・動画、データセット、モデル）
│    └─ はい → gitに入れない（またはGit LFSを使用）、READMEに取得方法を記述
└─ 再生成不可能で、価値もない → リストアップし、ユーザー確認後に削除

アーカイブの詳細は references/docs.md を参照。

参考ファイル

ファイル	内容	読むタイミング
references/structure.md	ルートディレクトリのホワイトリスト、各種プロジェクトの標準ディレクトリレイアウト（Node/TS、Remotion、Python、混合プロジェクト）	ファイルの配置場所決定、レイアウト設計時
references/file-necessity.md	ファイルの必要性判断、よくある削除可能なサンプル	削除可否判断時
references/naming.md	各言語の命名規則、禁止パターン	ファイルの新規作成または名前変更時
references/docs.md	READMEの最低要件、docs/ のレイアウト、アーカイブルール	ドキュメント作成、アーカイブ時
references/config.md	.claude/tidy.json のフィールド説明と例	ディレクトリ規則の生成または変更時
assets/README.template.md	READMEテンプレート	プロジェクトにREADMEがない場合
assets/gitignore/	.gitignore スニペット：汎用、Node、Python、メディア	無視ルールの補完時
assets/agents-rules.md	AGENTS.md に貼り付け可能なルール（Hooksをサポートしない他のAIツール向け）	プロジェクトがCursor/Codexなども使用する場合