Temp File Management（一時ファイル管理）

目的

一時ファイルと中間ファイルを適切に管理するためのルールとベストプラクティスを提供します。ファイルの配置場所、命名規則、クリーンアップ方法など、プロジェクトの整理整頓を維持するための具体的なガイドラインを含みます。

いつアクティベートするか

• 一時ファイルを作成する時（データ処理の中間結果、ダウンロードファイルなど）
• 中間ファイルを作成する時（議事録処理、PDF解析、Web scrapingの結果など）
• ファイルパスを指定する時
• データ処理スクリプトを書く時

クイックチェックリスト

ファイル作成前

• 一時ファイルはtmp/ディレクトリに作成する
• ファイル名に意味のある名前を付ける（処理内容がわかる）
• タイムスタンプやUUIDを含めて一意性を確保する
• 既存ファイルを上書きしないようにする

コード記述時

• ファイルパスは変数に格納する（ハードコーディングしない）
• 絶対パスではなく、プロジェクトルートからの相対パスを使用する
• pathlib.Pathを使用する（文字列連結は避ける）
• ファイル作成後にログ出力する

クリーンアップ

• 処理完了後に不要なファイルは削除する
• エラー時もクリーンアップする（try-finally）
• 長期間保存が必要なファイルは_docs/に移動する

詳細なガイドライン

1. ファイル配置ルール

tmp/ ディレクトリ

用途: 一時的なファイル、中間ファイル、処理結果のキャッシュ

特徴:

• .gitignoreに含まれており、Gitにコミットされない
• プロジェクトのルートディレクトリを汚さない
• 処理完了後に削除可能

使用例:

from pathlib import Path

# ✅ 良い例：tmp/ディレクトリに作成
output_path = Path("tmp/minutes_processing_result.json")
output_path.parent.mkdir(parents=True, exist_ok=True)
with open(output_path, "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False, indent=2)

悪い例:

# ❌ 悪い例：ルートディレクトリに作成
output_path = "processing_result.json"
with open(output_path, "w") as f:
    json.dump(data, f)

---

_docs/ ディレクトリ

用途: 知識蓄積、重要な意思決定の記録、調査結果のメモ

特徴:

• .gitignoreに含まれており、Gitにコミットされない
• Claudeのメモリとして機能
• プロジェクトの歴史や決定事項を記録

使用例:

# 重要な調査結果や意思決定を記録
decision_path = Path("_docs/decision-baml-adoption.md")
decision_path.parent.mkdir(parents=True, exist_ok=True)
with open(decision_path, "w", encoding="utf-8") as f:
    f.write("# BAML採用の理由\n\n...")

---

2. ファイル命名規則

基本ルール

1. 意味のある名前: 処理内容がわかる名前を付ける
2. スネークケース: 小文字とアンダースコアを使用（snake_case）
3. タイムスタンプ: 実行時刻を含めて一意性を確保
4. 拡張子: 適切な拡張子を使用（.json, .csv, .txt, .pdfなど）

パターン例

データ処理結果:

from datetime import datetime

# タイムスタンプ付き
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
output_path = Path(f"tmp/minutes_processing_{timestamp}.json")

議事録処理の中間ファイル:

# 会議体IDを含める
conference_id = 123
output_path = Path(f"tmp/conference_{conference_id}_members.json")

Web scrapingの結果:

# URLのドメインやページ名を含める
domain = "city.example.jp"
output_path = Path(f"tmp/scraping_{domain}_members.html")

UUID使用例:

import uuid

# 完全に一意なファイル名
unique_id = uuid.uuid4()
output_path = Path(f"tmp/temp_file_{unique_id}.json")

---

3. ファイルパスの指定

pathlibを使用する

推奨: pathlib.Pathを使用

理由:

• OS間のパス区切り文字の違いを吸収
• パス操作が直感的
• 型安全

良い例:

from pathlib import Path

# ✅ 良い例：pathlibを使用
base_dir = Path("tmp")
output_path = base_dir / "processing_result.json"
output_path.parent.mkdir(parents=True, exist_ok=True)

悪い例:

# ❌ 悪い例：文字列連結
output_path = "tmp/" + "processing_result.json"

# ❌ 悪い例：os.path.join
import os
output_path = os.path.join("tmp", "processing_result.json")

---

相対パスを使用する

推奨: プロジェクトルートからの相対パス

良い例:

# ✅ 良い例：相対パス
output_path = Path("tmp/processing_result.json")

悪い例:

# ❌ 悪い例：絶対パス（環境依存）
output_path = Path("/Users/okodoon/project/tmp/processing_result.json")

---

ディレクトリの自動作成

推奨: mkdir(parents=True, exist_ok=True)を使用

from pathlib import Path

output_path = Path("tmp/subfolder/result.json")
output_path.parent.mkdir(parents=True, exist_ok=True)
# parents=True: 親ディレクトリも作成
# exist_ok=True: 既存ディレクトリがあってもエラーにしない

---

4. ファイル操作のベストプラクティス

ファイル書き込み

from pathlib import Path
import json

def save_json(data: dict, output_path: Path) -> None:
    """JSONファイルを保存する"""
    # ディレクトリを自動作成
    output_path.parent.mkdir(parents=True, exist_ok=True)

    # ファイルに書き込み
    with open(output_path, "w", encoding="utf-8") as f:
        json.dump(data, f, ensure_ascii=False, indent=2)

    # ログ出力
    print(f"✅ Saved: {output_path}")

ファイル読み込み

from pathlib import Path
import json

def load_json(input_path: Path) -> dict:
    """JSONファイルを読み込む"""
    if not input_path.exists():
        raise FileNotFoundError(f"File not found: {input_path}")

    with open(input_path, "r", encoding="utf-8") as f:
        data = json.load(f)

    return data

---

5. クリーンアップ

処理完了後に削除

from pathlib import Path

temp_file = Path("tmp/temp_data.json")

try:
    # 一時ファイルを作成・使用
    with open(temp_file, "w") as f:
        f.write("temporary data")

    # 処理を実行
    process_data(temp_file)

finally:
    # 処理完了後に削除
    if temp_file.exists():
        temp_file.unlink()
        print(f"🗑️ Deleted: {temp_file}")

コンテキストマネージャーを使用

from pathlib import Path
from tempfile import NamedTemporaryFile

# 自動的にクリーンアップされる一時ファイル
with NamedTemporaryFile(mode="w", suffix=".json", delete=True) as tmp:
    tmp.write('{"key": "value"}')
    tmp.flush()

    # ファイルを使用
    process_data(Path(tmp.name))
# ブロックを抜けると自動的に削除される

古いファイルの一括削除

from pathlib import Path
from datetime import datetime, timedelta

def cleanup_old_files(directory: Path, days: int = 7) -> None:
    """指定日数より古いファイルを削除"""
    cutoff_time = datetime.now().timestamp() - (days * 86400)

    for file_path in directory.glob("*"):
        if file_path.is_file() and file_path.stat().st_mtime < cutoff_time:
            file_path.unlink()
            print(f"🗑️ Deleted old file: {file_path}")

# 使用例：7日以上古いファイルを削除
cleanup_old_files(Path("tmp"), days=7)

---

6. エラーハンドリング

ファイル存在チェック

from pathlib import Path

input_path = Path("tmp/input.json")

# ファイルが存在するかチェック
if not input_path.exists():
    raise FileNotFoundError(f"Input file not found: {input_path}")

# ファイルを読み込み
with open(input_path, "r") as f:
    data = f.read()

書き込みエラーのハンドリング

from pathlib import Path

output_path = Path("tmp/output.json")

try:
    output_path.parent.mkdir(parents=True, exist_ok=True)
    with open(output_path, "w") as f:
        f.write(data)
    print(f"✅ Saved: {output_path}")

except PermissionError:
    print(f"❌ Permission denied: {output_path}")

except OSError as e:
    print(f"❌ OS error: {e}")

---

完全な実装例

データ処理スクリプト

from pathlib import Path
from datetime import datetime
import json
import logging

# ロギング設定
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def process_minutes(input_file: Path) -> Path:
    """議事録を処理して結果を保存"""
    # 出力パスを生成（タイムスタンプ付き）
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    output_path = Path(f"tmp/minutes_processed_{timestamp}.json")

    try:
        # 入力ファイルを読み込み
        logger.info(f"📖 Reading: {input_file}")
        with open(input_file, "r", encoding="utf-8") as f:
            data = json.load(f)

        # 処理を実行
        processed_data = {
            "timestamp": timestamp,
            "source": str(input_file),
            "result": data  # 実際の処理ロジック
        }

        # 結果を保存
        output_path.parent.mkdir(parents=True, exist_ok=True)
        with open(output_path, "w", encoding="utf-8") as f:
            json.dump(processed_data, f, ensure_ascii=False, indent=2)

        logger.info(f"✅ Saved: {output_path}")
        return output_path

    except FileNotFoundError:
        logger.error(f"❌ Input file not found: {input_file}")
        raise

    except json.JSONDecodeError as e:
        logger.error(f"❌ Invalid JSON: {e}")
        raise

    except Exception as e:
        logger.error(f"❌ Processing failed: {e}")
        # エラー時も一時ファイルをクリーンアップ
        if output_path.exists():
            output_path.unlink()
        raise

# 使用例
if __name__ == "__main__":
    input_file = Path("data/minutes.json")
    output_file = process_minutes(input_file)
    print(f"Processing completed: {output_file}")

---

リファレンス

• Python pathlib documentation
• project-conventions: プロジェクト規約
• development-workflows: 開発ワークフロー

---

まとめ

このスキルは、一時ファイルと中間ファイルを適切に管理するためのルールを提供します。

重要なポイント

✅ 一時ファイルはtmp/ディレクトリに作成 ✅ pathlib.Pathを使用してパス操作 ✅ 意味のある名前とタイムスタンプで一意性を確保 ✅ 処理完了後にクリーンアップ ✅ エラー時もクリーンアップ（try-finally）

プロジェクトを整理整頓された状態に保つため、このルールを必ず守ってください。