自分では、設計もコーディングもドキュメント書きも絶対しない、と決意して開発続けているアプリケーション。

毎開発ごとに日報をつけていたら結構溜まってきて、日報まとめるだけでも面白いかと思って、お願いしてみた（日報も「今日の作業日報書いて」とやらせている）。

@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 内の日報を解析して作成されました。