🛠️ 運用設計書

Finance Analysis Application - チャット記録・復元システム
📅 最終更新: 2025-07-29 | Version 2.1 (ファイル構成統一)
📋 システム概要

Finance Analysis Applicationの開発において、Claude Codeとの対話内容を記録・管理し、VSCodeクラッシュやセッション中断時の復元を支援するシステムです。

🎯 主要機能

  • 2時間毎の自動セッション記録
  • 手動セッション保存
  • 緊急時復元機能
  • プロジェクトコンテキスト管理

💾 ファイル構成

financeanalysis/ ├── .claude-history/ # チャット履歴 │ ├── conversation-log.md # 対話記録 │ ├── session_*.md # 個別セッション │ ├── auto-save.log # 自動保存ログ │ └── auto-save.pid # プロセスPID ├── operations/ # 運用スクリプト │ └── scripts/ │ ├── auto-session-save.sh # 自動保存 │ ├── save-claude-session.sh # 手動保存 │ └── quick-restore.sh # 復元 ├── old/ # 古いファイル │ ├── docs/chat-history/ # 旧チャット履歴 │ ├── operations/scripts/ # 旧スクリプト │ └── misc/ # その他古いファイル └── project-context.md # プロジェクト情報
⚡ 基本コマンド

🔄 自動保存システム（推奨）

自動保存開始

npm run auto-session:start # 2時間毎の自動記録を開始

自動保存停止

npm run auto-session:stop # 自動記録を停止

動作状況確認

npm run auto-session:status # プロセス状況・保存ファイル数を確認
✅ 推奨運用: 開発開始時に npm run auto-session:start を実行し、自動記録を有効にしてください。

📝 手動保存システム

セッション手動保存

npm run save-session "作業内容の説明" # 重要な作業完了時に手動記録 # 例: npm run save-session "XBRL機能実装完了" npm run save-session "マスターデータ問題解決"

緊急時復元

npm run restore-session # VSCodeクラッシュ時等の状況復元

🔧 直接コマンド（上級者向け）

./operations/scripts/auto-session-save.sh start # 自動保存開始 ./operations/scripts/auto-session-save.sh stop # 自動保存停止 ./operations/scripts/auto-session-save.sh status # 状況確認 ./operations/scripts/save-claude-session.sh "説明" # 手動保存 ./operations/scripts/quick-restore.sh # 復元実行
🚨 ケース別対応方法

Case 1: VSCodeクラッシュ・予期しない終了

❌ 問題: VSCodeが突然終了し、作業内容や進行状況が不明になった

対応手順

  1. 即座に復元実行
    cd /path/to/financeanalysis npm run restore-session
  2. 状況確認
    • プロジェクト基本情報の確認
    • 最近の変更ファイルの確認
    • Git状態の確認
    • 最新セッション記録の確認
  3. Claude Code再起動
    # 復元情報を元にClaude Codeで説明 "VSCodeがクラッシュしたため、セッションを復元しています。 前回は[具体的なタスク]に取り組んでいました。 現在のプロジェクト状態は上記の通りです。"

Case 2: 長時間作業後の記録保存

⚠️ 状況: 重要な実装や問題解決が完了し、記録を残したい

対応手順

npm run save-session "年度クリック機能実装完了" # 作業内容を分かりやすく記録
💡 記録のコツ:
  • 実装した機能名を具体的に記載
  • 解決した問題を明記
  • 次回作業時の参考情報を含める

Case 3: 自動保存プロセスの異常

❌ 問題: 自動保存が動作していない、またはエラーが発生している

診断手順

  1. 状況確認
    npm run auto-session:status
  2. ログ確認
    cat .claude-history/auto-save.log # エラーメッセージを確認
  3. プロセス強制停止・再起動
    npm run auto-session:stop sleep 3 npm run auto-session:start

Case 4: ディスク容量不足

⚠️ 問題: セッションファイルが蓄積してディスク容量を圧迫

対応手順

# 古いセッションファイルを手動削除（14日以上前） find .claude-history -name "session_*.md" -mtime +14 -delete # 容量確認 du -sh .claude-history # ファイル数確認 ls -1 .claude-history/session_*.md | wc -l
💡 自動クリーンアップ: システムは自動的に14日以上古いセッションファイルを削除します。手動削除は通常不要です。
📁 ファイル構成と設定

重要ファイル一覧

ファイル 役割 更新頻度 Git管理
project-context.md プロジェクト全体のコンテキスト 手動更新 ✓
.claude-history/conversation-log.md 対話記録サマリー 自動更新 ✓
.claude-history/session_*.md 個別セッション記録 2時間毎 ✗
.claude-history/auto-save.log 自動保存ログ 自動更新 ✗
operations/scripts/auto-session-save.sh 自動保存スクリプト 開発時のみ ✓
operations/scripts/save-claude-session.sh 手動保存スクリプト 開発時のみ ✓
operations/scripts/quick-restore.sh 緊急復元スクリプト 開発時のみ ✓

設定項目

📝 package.json スクリプト

"auto-session:start": "nohup ./operations/scripts/auto-session-save.sh start &", "auto-session:stop": "./operations/scripts/auto-session-save.sh stop", "auto-session:status": "./operations/scripts/auto-session-save.sh status", "save-session": "./operations/scripts/save-claude-session.sh", "restore-session": "./operations/scripts/quick-restore.sh"

🔧 auto-session-save.sh 設定

SAVE_INTERVAL=7200 # 2時間（秒） SESSION_DIR=".claude-history" LOG_FILE="$SESSION_DIR/auto-save.log"

.gitignore 設定

# セッションファイルは除外 .claude-history/session_*.md .claude-history/auto-save.log .claude-history/auto-save.pid # 重要ファイルは保持 !.claude-history/conversation-log.md !project-context.md
🔧 トラブルシューティング

よくある問題と解決方法

❌ 「自動保存プロセスは動作していません」

原因: プロセスが開始されていない、または異常終了した
# 解決方法 npm run auto-session:start npm run auto-session:status # 確認

❌ 「既存の自動保存プロセスが動作中です」

原因: 複数のプロセスが起動しようとしている
# 解決方法 npm run auto-session:stop sleep 3 npm run auto-session:start

❌ 「operations/scripts/save-claude-session.shが見つかりません」

原因: スクリプトファイルが存在しない、または実行権限がない
# 解決方法 ls -la operations/scripts/*.sh # ファイル確認 chmod +x operations/scripts/*.sh # 実行権限付与 git status # Git状態確認

❌ セッションファイルが生成されない

原因: ディスクアクセス権限、またはディスク容量不足
# 解決方法 ls -la .claude-history/ # ディレクトリ確認 df -h . # ディスク容量確認 mkdir -p .claude-history # ディレクトリ作成

緊急時の手動復旧

🚨 全システム異常時の手動復旧手順
  1. プロセス強制停止
    pkill -f auto-session-save rm -f .claude-history/auto-save.pid
  2. ディレクトリ再作成
    mkdir -p .claude-history touch .claude-history/conversation-log.md
  3. 権限修正
    chmod +x operations/scripts/*.sh chmod 755 .claude-history
  4. システム再起動
    npm run auto-session:start npm run save-session "緊急復旧後テスト"
💡 運用ベストプラクティス

🎯 推奨運用フロー

開発開始時

  1. プロジェクトディレクトリに移動
  2. npm run auto-session:start で自動記録開始
  3. npm run restore-session で前回状況確認（任意）
  4. Claude Code開始

重要な作業完了時

  1. npm run save-session "作業内容" で手動記録
  2. git add . && git commit -m "..." でコード保存
  3. project-context.md を必要に応じて更新

開発終了時

  1. 最終状況を手動記録
  2. 自動保存は継続（停止不要）
  3. 重要な変更をGitにコミット

✅ Good Practices

  • 自動保存を常時稼働
  • 重要な節目で手動記録
  • 具体的な作業説明を記載
  • project-context.mdの定期更新
  • 復元スクリプトでの状況確認

❌ Bad Practices

  • 自動保存プロセスの頻繁な停止
  • 曖昧な作業説明での記録
  • セッションファイルの手動削除
  • プロセス確認を怠る
  • 緊急時の復元手順を忘れる

📊 定期メンテナンス

頻度 作業内容 コマンド
毎日 自動保存状況確認 npm run auto-session:status
週1回 セッション数確認 ls -1 .claude-history/session_*.md | wc -l
週1回 スクリプト権限確認 ls -la operations/scripts/*.sh
月1回 project-context.md更新 手動編集
月1回 古いファイル整理 du -sh old/ .claude-history/
必要時 ログファイル確認 tail -20 .claude-history/auto-save.log

🗂️ ファイル整理済み（2025-07-29）

✅ 完了済み: ファイル構成整理・クリーンアップ
  • 実行スクリプト統一: operations/scripts/ 配下に集約
  • 古いファイル移動: old/ フォルダに整理済み
  • パス統一: package.json・CLAUDE.md・運用設計書更新済み
  • 動作確認: 全機能正常動作確認済み
⚙️ システム仕様

技術仕様

🔄 自動保存システム

  • 保存間隔: 7200秒（2時間）
  • プロセス管理: PIDファイルベース
  • ログ出力: タイムスタンプ付き
  • クリーンアップ: 14日自動削除

📝 記録内容

  • Git状態: ブランチ、変更ファイル
  • プロジェクト情報: 作業ディレクトリ
  • ファイル変更: 過去2時間の更新
  • システム情報: タイムスタンプ、環境

パフォーマンス特性

項目 仕様 備考
セッションファイルサイズ 3-5KB/ファイル プロジェクト規模に依存
保存処理時間 1-3秒 Git状態確認込み
復元処理時間 2-5秒 ファイル読込み込み
最大セッション数 約168ファイル 14日間×12回/日

セキュリティ考慮事項

⚠️ 重要: セッションファイルにはプロジェクト情報が含まれます
  • セッションファイルはGit管理外（.gitignore設定済み）
  • 機密情報の記録は避ける
  • APIキーなどの環境変数は記録対象外
  • ローカル環境のみでの運用推奨