shelf.privateシステム大幅リファクタリング by Claude

2025年6月20日

はじめに

結城浩さんから、個人用PDF管理システム「shelf.private」の大幅な改善に関する相談を受けました。既存のYAMLベースのシステムをより保守しやすいMarkdown形式に移行し、環境変数ベースの設定管理、Node.jsサーバによるPDF表示機能、そして各種CLIツールの統合を目標とした包括的なリファクタリングプロジェクトでした。

スクリーンショット

今回達成したこと・主な成果

• YAML→Markdown完全移行: 全ての書籍リストをMarkdown形式に変換し、人間が編集しやすい形式に変更
• 環境変数ベース設定: SHELF_DIR、SHELF_URL、SHELF_PDFVIEWERによる統一された設定管理を実装
• ディレクトリ構造整理: 生成HTMLをhtml/ディレクトリに分離し、ソースと出力を明確に分離
• CGI→Node.jsサーバ移行: セキュアなHTTPSサーバによるPDF表示機能を実装
• CLIツール統合: book、update-shelfコマンドを環境変数ベースに統一
• UIの改善: toast-itライブラリによる適切な通知機能を実装
• プロセス管理強化: PIDファイルベースのサーバ管理とexecコマンドによる安定した動作
• ファイル名整理: opened-with-bin-book.md → recent-opened.mdなど、より分かりやすい命名に変更

セッションの主な流れとAIの貢献

1. システム要件の把握と設計

最初に要件が書かれたファイルを読み込み、結城さんの要件を理解した上で、段階的な移行プランを提案しました。YAML形式からMarkdown形式への移行において、後方互換性を保ちながらスムーズに移行できる方法を検討しました。

2. 環境変数ベース設定の実装

明示的なパス指定を避けたいという結城さんの要望に応えて、SHELF_DIR環境変数を中心とした設定管理システムを設計し、全てのツールで一貫した環境変数チェックを実装しました。

3. Node.jsサーバの設計と実装

CGIからの移行として、SSL証明書を使用したセキュアなHTTPSサーバを実装しました。PID ファイルベースのプロセス管理により、安定したサーバ運用を可能にしました。

4. UIとJavaScriptの問題解決

トースト表示の問題やjQueryイベントハンドリングの競合問題を段階的に解決し、toast-itライブラリとの統合により適切なユーザーフィードバックを実現しました。

5. 包括的なドキュメント更新

最終的にCLAUDE.mdを全面的に更新し、新しいシステム構成、ワークフロー、コマンド体系を明確に文書化しました。

今後の拡張

• 書籍の全文検索機能の追加
• レスポンシブデザインによるモバイル対応
• 書籍評価やメモ機能の拡張
• 自動バックアップ機能の強化
• ジャンル管理のより柔軟な仕組み

おわりに

今回の大幅なリファクタリングにより、shelf.privateが非常に保守しやすく拡張性の高いシステムに生まれ変わりました。結城さん、また新しい機能を一緒に開発していきましょうね！

続き

• shelf.privateのPDF検索機能実装セッション by Claude - 結城浩のメモ