自分では、設計もコーディングもドキュメント書きも絶対しない、と決意して開発続けているアプリケーション。
毎開発ごとに日報をつけていたら結構溜まってきて、日報まとめるだけでも面白いかと思って、お願いしてみた（日報も「今日の作業日報書いて」とやらせている）。
@doc/daily にはこのプロジェクトでの開発の日報が記録されている。ファイル名には日付がついている。この日報を解析し、このプロジェクト開発そのものを評価したい。ソフトウェア開発プロセス、品質管理、セキュリティ、設計手法、開発の効率性などについて詳細に調査してほしい。
cursor の auto なので、動いていたモデルが何かは不明。
BookMemo プロジェクト開発評価レポート
作成日: 2026年3月13日
評価対象: doc/daily 内の日報（2024年6月〜2026年3月、42件）
プロジェクト期間: 約2年間の継続開発
エグゼクティブサマリー
本レポートは、BookMemo（読書メモアプリ）プロジェクトの日報を解析し、ソフトウェア開発プロセス、品質管理、セキュリティ、設計手法、開発効率性の観点から評価を行う。
総合評価: B+（良好）
長期間にわたる継続的な開発で、段階的な改善と品質への取り組みが一貫して行われている。一方で、一部の技術的負債やセキュリティインシデントの経験から学び、プロセス改善に活かしている点が評価できる。
1. ソフトウェア開発プロセス
1.1 プロセスの特徴
| 観点 | 評価 | 詳細 |
|---|---|---|
| 計画性 | ◎ | Phase 1〜15 の段階的フェーズ管理、優先度付けされたタスク管理 |
| ドキュメント | ◎ | ARCHITECTURE.md、設計ドキュメント、実装計画の充実 |
| 振り返り | ◎ | 日報による継続的な記録、問題分析・教訓の文書化 |
| 変更管理 | ○ | Git によるバージョン管理、コミットメッセージの一貫性 |
1.2 強み
- 段階的アプローチ: 共通フック化（Phase 6, 7）、UI/UX改善（Phase 8）、PWA化、本番デプロイなど、明確なフェーズで進捗
-
設計ドキュメント駆動: 実装前に
design-*.md、implementation-plan.mdで設計を固める習慣 -
開発開始時プロンプト:
doc/development-startup-prompts.mdで最優先タスク確認を必須化（2025-10-13 に全文検索問題を受けて強化） -
バグ・機能メモ:
bug-feature-memo.mdによる課題の一元管理と優先度付け
1.3 改善点
- CI/CDの揺れ: GitHub Actions の E2E テスト自動化を導入後、課金リスクで削除（2024-07-19）。本番デプロイは復活したが、テスト自動化の安定化が課題
- リファクタリングの巻き戻し: useSearch.js の責務分離を試行→問題発生→巻き戻し（2025-01-21）。段階的アプローチの重要性を再認識
2. 品質管理
2.1 テスト戦略
| 観点 | 評価 | 詳細 |
|---|---|---|
| ユニットテスト | ◎ | 500件超のテストケース、Jest + React Testing Library |
| E2Eテスト | △ | Cypress 使用するが、メンテナンスコストにより最低限化（3本に絞り込み） |
| テスト設計 | ◎ | data-testid による安定化、getByText 撲滅の方針 |
| カバレッジ | ○ | 全体約54%など一部低いモジュールあり。新機能にはテスト追加を実施 |
2.2 品質向上の軌跡
- 2024-06-24: MemoAdd/MemoList のユニットテスト整備。BarcodeScanner テストは難航し describe.skip で一旦スキップ
- 2024-06-27: E2E テストの設計方針（1ファイル1シナリオ、data-testid 活用、force オプション）
- 2024-08-03: E2E テストを7本から3本に削減し、メンテナンスコストを軽減。ユニットテストでカバー
- 2025-10-13: getByText 撲滅をプロジェクト方針として明確化
2.3 品質保証の仕組み
- テストファースト: 安全性向上作業（2025-10-18）で Red→Green→Refactor を実践
- PropTypes: SearchResults に PropTypes.isRequired を導入し型安全性を強化
-
コンポーネント設計ガイドライン:
doc/component-design-guidelines.mdで設計パターンを文書化 - コードレビュー: 2026-01-17 に包括的コードレビューを実施し、総合評価 B+、改善優先事項を明確化
3. セキュリティ
3.1 セキュリティの変遷
| 時期 | 事象 | 対応 |
|---|---|---|
| 2024-06-26 | Firestore ルール本番化 | 認証ユーザーのみ自分のデータにアクセス可能に |
| 2025-08-12 | .env の Git コミット | git filter-branch で履歴から削除、.gitignore に環境変数追加 |
| 2025-09-28 | Google Books API キー露出 | 日報に記載→削除、環境別キー・制限設定を推奨 |
| 2026-03-07 | セキュリティ調査・対策 | APIキー削除、CSP 導入、本番デバッグ無効化、Firestore ルール簡素化 |
3.2 実施済み対策
- Firestore セキュリティルール: ユーザー単位のデータ分離、statusHistory サブコレクションの権限設定
- 環境変数管理: .gitignore による .env 除外、GitHub Secrets での本番管理
- CSP（Content Security Policy）: XSS 軽減、クリックジャッキング防止
-
XSS 対策: LinkifiedText で URL リンク化する際、
dangerouslySetInnerHTMLを避け React 要素として構築 - 本番デバッグ無効化: errorLogger のデバッグコマンドを開発時のみ有効化
3.3 残課題
- API キー制限: Google Books API キーに HTTP referrers 制限の設定が推奨される（2025-09-28 に指摘）
- Git 履歴: 過去の日報に含まれた API キーは履歴に残存。完全削除には git filter-repo 等が必要
4. 設計手法
4.1 アーキテクチャ
- 技術スタック: React (Vite)、Firebase (Firestore, Authentication)、Material-UI
- デプロイ: GitHub Pages / Firebase Hosting
- ルーティング: Hash Router（GitHub Pages の制約回避のため Browser Router から移行、2024-07-20）
4.2 設計パターン
| パターン | 実装例 | 効果 |
|---|---|---|
| カスタムフック | useTagHistory, useBookList, useBookActions, useSearchResultHandler | ロジックの再利用、責務分離 |
| 単一責任の原則 | MemoCard / MemoEditor への MemoList 分割、FullTextSearch の設定外部化 | 保守性向上 |
| デザインシステム | themePresets, createThemeFromPreset, cardStyles | 一貫したUI、テーマ切替 |
| エラーハンドリング | ErrorDialogContext, CommonErrorDialog | 統一されたエラー表示 |
4.3 設計の進化
- 共通フック化: タグ履歴（useTagHistory）→ 書籍関連（useBookList, useBookActions, useBookSearch）→ 検索結果ハンドラ（useSearchResultHandler）
- 責務分離: useBookFiltering, useBookStats, useHistoryValidation への抽出
- デザイン埋め込み値のトークン化: Phase A/B/C で typography, sizes, spacing を theme.custom に集約
- テスト設計の独立性: デザイン変更に強い data-testid、文字列非依存のテスト方針
4.4 技術的負債との向き合い
- useSearch.js: 494行の巨大フック。責務分離を試行したがモジュール解決エラーで巻き戻し。継続的な課題として記録
- BarcodeScanner テスト: カメラ・非同期のモックが困難。簡略化して要素存在確認に変更（2025-08-14）
5. 開発効率性
5.1 生産性の指標
| 指標 | 状況 |
|---|---|
| 開発期間 | 約2年（2024/06〜2026/03） |
| 日報数 | 42件 |
| 主要フェーズ | Phase 1〜15+ を段階的に完了 |
| テスト数 | ユニット 580件超、E2E 3本（コア機能に限定） |
5.2 効率を高めた要因
- 設計ドキュメント先行: 実装前に設計を固めることで手戻りを削減
- 段階的リリース: 大きな変更を分割し、各ステップで動作確認
- 問題の early 発見: 全文検索のリアルタイム検索問題を実装前にドキュメント化し、Firebase 無料枠超過を回避（2025-10-13）
- E2E テストの最適化: メンテナンスコストの高いテストを廃止し、ユニットテストでカバー（2024-08-03）
5.3 非効率の要因と対策
| 要因 | 事象 | 対策 |
|---|---|---|
| 環境変数の混在 | Vite/React 形式、eval によるアクセス問題 | import.meta.env に統一、テンプレート化 |
| UI 変更の影響 | E2E テストが DOM 変更に脆弱 | data-testid への移行、E2E 縮小 |
| 複雑なモック | BarcodeScanner, @zxing/library | テストを簡略化、要素存在確認に特化 |
| リファクタリングの失敗 | useSearch 分割時のエラー | 段階的アプローチ、問題時の巻き戻し手順を確立 |
6. 具体的な成果と学び
6.1 技術的成果
- PWA 対応: Service Worker、Web App Manifest、インストール促進、オフライン対応
- 全文検索: LocalStorage キャッシュ、レート制限、検索ボタン必須による Firebase 負荷制御
- 本番デプロイ: GitHub Actions による CI/CD、環境分離（開発/本番 Firebase プロジェクト）
- デザインシステム: テーマプリセット（library-classic, minimal-light, slim-compact）、LoadingIndicator の統一
6.2 プロセス改善の学び
- 実装前の設計確認: 重大な問題点を事前に議論することで無駄な実装を回避
- ドキュメント化の効果: 問題と解決策を記録し、同じ失敗を繰り返さない
- 段階的アプローチ: 一度に大きな変更を加えず、各ステップで検証
- テストの独立性: 状態のコントロール、セレクタの堅牢化を意識
6.3 ユーザー体験への配慮
- モバイルファースト: レスポンシブデザイン、タッチターゲット 44px 以上、ピンチイン・アウト無効化
- アクセシビリティ: prefers-reduced-motion 対応、キーボードナビゲーション
- エラーメッセージ: ユーザーフレンドリーな文言、CommonErrorDialog による統一表示
- PWA 起動時ダイアログ: ユーザー要望により起動時の自動表示を無効化（2025-10-25）
7. 推奨改善事項（優先度順）
優先度: 高
- デバッグログの本番対応: console.log が 279 箇所に存在。環境変数で制御するロガー関数の導入
- API キー制限の設定: Google Books API に HTTP referrers 制限を適用
優先度: 中
- useSearch.js の責務分離: 段階的アプローチで再挑戦
- MemoAdd.jsx の状態管理: 8つの状態変数の整理、useReducer の検討
- E2E テストの安定化: 3本のコアテストの保守性維持、必要に応じて拡充
優先度: 低
- TypeScript 移行: 長期的な型安全性の向上
- テストカバレッジ向上: 54% 前後のモジュールのカバレッジ改善
8. 結論
BookMemo プロジェクトは、計画的かつ段階的な開発により、読書メモアプリとしての主要機能を実装し、本番運用可能な状態まで成熟させている。日報からは以下の点が読み取れる。
- 継続的な学習と改善: セキュリティインシデント、設計の失敗から学び、プロセスやドキュメントに反映している
- 品質への意識: テスト戦略の見直し、設計ガイドラインの策定、コードレビューの実施
- 技術的深さ: カスタムフック、デザインシステム、PWA、全文検索など、モダンな技術を適切に採用
- ドキュメント文化: 設計ドキュメント、日報、bug-feature-memo による知見の蓄積
一方で、技術的負債（巨大フック、デバッグログ）やセキュリティの細部（API キー制限）には継続的な改善の余地がある。総合的に、健全な開発プロセスを持つプロジェクトと評価できる。
本レポートは doc/daily 内の日報を解析して作成されました。