開発の軌跡と学び - 367コミットから見る10ヶ月間の成長
2025年10月から12月にかけて、GitHubで367コミットを実施し、ほぼ毎日機能追加・改善を行いました。この記事では、開発の軌跡と、そこから得た学びや反省点について振り返ります。
時期別の設計意図（README・コミットに基づく）
medicine-recommend-system のREADMEおよびコミット履歴に基づき、各時期の設計意図を整理しました。機能の「何を」だけでなく「なぜその順で・なぜその形で」行ったかを振り返るための記述です。
2025年10月 — 基盤構築とUI/UX（205コミット）
設計意図: まず「相談フローとして成立する最低限の体験」を整え、その上で多様なユーザー（言語・属性）と管理者が使えるようにする。
- 多言語対応を早めに着手した理由: ドラッグストアでは外国人利用者が増えており、現場のニーズを満たすには最初から多言語を前提にした方が、後から入れるより設計が素直だったため。
- 症状検出の拡充: キーワードベースで網羅を広げ、医薬品タイプ分類と組み合わせて「聞き取り→推奨」の一連の流れを成立させるため。
- UI/UX（モーダル・オンボーディング・FAQ）: 初回利用者でも迷わず使えるようにし、相談の入口を明確にするため。
- 管理者機能（フィードバック・セッション・詳細症状）: 運用で「不適切な応答」や「落ちているセッション」を把握し、安全と改善のループを回すため。
2025年11月 — パフォーマンスと基盤の確立（51コミット）
設計意図: レスポンス時間とスケールを現実的な水準にし、Render Manual Scaling を見据えてインスタンス間で状態を共有できるようにする。
- ハイブリッド推奨: ルールベースを主軸にし、LLMはNLU・質問生成などに限定することで、「推奨結果の再現性」と「安全性」を担保するため。
- マルチインスタンス対応: Render で複数インスタンスを立てたときにセッションが分断されないよう、PostgreSQLでセッションとグローバル状態を共有する設計にしたため。
- 二段階スコアリング・API削減（約67%）: 全候補に重い処理をかけず、簡易スコアで絞ってから詳細スコアを回すことで、体感速度とAPIコストの両立を図ったため。
- 漢方薬34種のルール統合: 証（ショ）や生薬構成に基づくルールを明示的に持ち、一般用漢方の範囲で一貫した推奨ができるようにするため。
2025年12月 — 機能拡張（111コミット）
設計意図: 「身体的症状だけ」から、感情・緊急・店舗・その他まで入力の種類を広げ、それぞれに適したフローと安全策を用意する。
- LLMトリアージ（5カテゴリ→Otherは20種サブ分類）: 入力を振り分けてから専用フローに渡すことで、医薬品推奨と店舗案内・カウンセリングなどを混同しないようにするため。信頼度閾値や心臓緊急の優先チェックで、安全性を先に確保する設計。
- カウンセリング（感情・不眠・眠気）: 身体的症状以外のニーズにも応えつつ、医薬品推奨への移行条件・終了条件を明示し、相談の範囲をはっきりさせるため。
- 店舗案内・遺失物: ドラッグストア内でのスマートフォン利用を想定し、在庫・施設・営業時間などの質問を早期に処理して、医薬品フローへの負荷を減らすため。
- 緊急事案検出: 火災・医療緊急・不審者などを検出した場合は最優先で案内し、かつ医療用語・文脈による誤検知を抑えるため。
- 方言対応: 地域差のある表現を標準語の症状に写し、NLUの入力品質を上げるため。
- 成分重複チェック: 複数製品の併用で過剰摂取にならないよう、リスク成分を共通化して検出し、深刻度別に表示するため。
- イースターエッグ・シーズンUI: 利用体験を柔らかくしつつ、医薬品推奨のメッセージや緊急案内の邪魔をしないよう、表示条件と優先度を分離したため。
2026年2月 — 保守性・運用・クラウド（README更新・SRP・移行）
設計意図: コードの責務を分け、テスト・変更をしやすくする。同時に、コストと運用負荷を現実的な形にし、ブロック時もユーザーに案内が届くようにする。
- SRPに基づく分割（app.py スリム化・ルート・core/handlers/services）: 単一ファイルに責務が集中しないようにし、今後の機能追加や修正を局所化するため。
- GCP Cloud Run・Neon PostgreSQL 移行: Render・Cloud SQLから、スケールとコストに合わせた構成に移し、GitHub 連携でデプロイを安定させるため。
- ブロック時のUI・DB永続化: 不適切入力でブロックしても、案内メッセージをセッションに追加してDBに保存し、GET /api/sessions で取得できるようにして、画面に必ず案内が表示されるようにするため。
- 不適切ワードの拡張・プレーンテキスト案内: 絶対ブロックとセキュリティブロックを分け、ユーザーには分かりやすいプレーンテキストで案内するため。
開発の軌跡
October 2025 - 基盤構築とUI/UX改善（205コミット）
10月は、システムの基盤を構築し、UI/UXの改善に注力しました。
実装した主な機能
- 多言語対応: 日本語・英語・中国語・韓国語への対応を開始
- 症状検出: 包括的な症状キーワードの追加と医薬品タイプ分類の精度向上
- UI/UX: ユーザー情報モーダル、オンボーディングガイド、FAQセクションの実装
- 管理者機能: フィードバック機能、セッション管理、詳細症状情報の表示
学んだこと
この時期は、機能追加を優先しすぎたことが課題でした。コードの可読性やメンテナンス性を後回しにした結果、後で大きなリファクタリングが必要になりました。
反省点:
- 機能追加の前に、コードの構造を整えるべきだった
- テストを書きながら開発を進めるべきだった
良かった点:
- ユーザーフィードバックを迅速に反映できた
- 多言語対応により、より多くのユーザーに対応できた
November 2025 - パフォーマンス最適化と基盤の確立（51コミット）
11月は、パフォーマンス最適化と基盤の確立に注力しました。
実装した主な機能
- ハイブリッド推奨システム: ルールベースとAIの融合による高精度な推奨を実現
- マルチインスタンス対応: PostgreSQLベースのセッション管理システムを実装
- パフォーマンス最適化: 二段階スコアリングによる高速化、ChatGPT API呼び出しの統合（約67%削減）
- 漢方薬推奨アルゴリズム: 34種類の漢方薬に対する詳細なルールを統合
学んだこと
パフォーマンス最適化の重要性: API呼び出し回数を約67%削減したことで、レスポンス時間が大幅に短縮されました。ユーザー体験の向上に直結することを実感しました。
マルチインスタンス対応の難しさ: PostgreSQLベースのセッション管理を実装する際、セッションの同期や競合状態の処理に苦労しました。しかし、この経験により、分散システムの基礎を学ぶことができました。
良かった点:
- パフォーマンス最適化により、ユーザー体験が大幅に向上
- マルチインスタンス対応により、スケーラビリティが向上
December 2025 - 機能の爆発的拡張（111コミット）
12月は、機能の爆発的拡張が行われました。
実装した主な機能
- LLMトリアージ機能: 5つのカテゴリへの自動分類
- カウンセリング機能: 感情的症状への共感的な対応
- 店舗案内機能: 2,362件の商品データベースに対応
- 緊急事案検出機能: 火災、医療緊急、不審者などの自動検出
- 方言対応機能: 全国の方言を標準語に変換
- 成分重複チェック機能: 30種類のリスク成分を検出
- イースターエッグ機能: 13種類の特別イベント対応
学んだこと
機能追加の速度と品質のバランス: 12月は機能追加に注力しましたが、コードの品質を維持することが難しくなりました。後でSRP改善計画を実施する必要がありました。
ユーザー体験の重要性: イースターエッグ機能のような、ユーザーが楽しめる機能を追加することで、システムへの親しみやすさが向上しました。
良かった点:
- 多様な機能を実装し、システムの価値が大幅に向上
- ユーザーフィードバックを迅速に反映できた
開発を通じて学んだこと
1. 「システムを誤らせない設計」の重要性
医療情報システムとして、安全性は最優先事項です。このプロジェクトを通じて、「正しく動く」だけでなく「誤らせない」設計の重要性を改めて実感しました。
具体例:
- 診断名検出機能により、市販薬では対応が難しい疾患を早期に検出
- 成分重複チェック機能により、過剰摂取のリスクを防止
- 緊急事案検出機能により、緊急事態に適切に対応
2. 継続的な改善の重要性
367コミットという数字は、継続的な改善の積み重ねの結果です。ほぼ毎日機能追加・改善を行うことで、システムは急速に進化しました。
学んだこと:
- 小さな改善の積み重ねが、大きな価値につながる
- ユーザーフィードバックを迅速に反映することが重要
- 完璧を目指すのではなく、まず動くものを作り、継続的に改善する
3. コードの可読性とメンテナンス性
開発初期段階では、機能追加を優先していたため、コードの可読性やメンテナンス性を後回しにしました。その結果、後で大きなリファクタリングが必要になりました。
学んだこと:
- 機能追加の前に、コードの構造を整えるべき
- SRP（Single Responsibility Principle）を守ることで、コードの可読性とメンテナンス性が向上
- テストを書きながら開発を進めることで、リファクタリングが容易になる
4. パフォーマンス最適化の重要性
API呼び出し回数を約67%削減したことで、レスポンス時間が大幅に短縮されました。ユーザー体験の向上に直結することを実感しました。
学んだこと:
- キャッシュ機能の実装により、パフォーマンスが大幅に向上
- 早期リターン処理により、不要な処理をスキップできる
- 二段階スコアリングにより、処理速度と精度のバランスを取れる
5. ユーザー体験の重要性
イースターエッグ機能のような、ユーザーが楽しめる機能を追加することで、システムへの親しみやすさが向上しました。
学んだこと:
- 機能だけでなく、ユーザー体験も重要
- 小さな工夫が、ユーザーの満足度を大きく向上させる
- アクセシビリティ機能により、より多くのユーザーに対応できる
失敗から学んだこと
1. コードの可読性を後回しにした
開発初期段階では、機能追加を優先していたため、コードの可読性やメンテナンス性を後回しにしました。その結果、後で大きなリファクタリングが必要になりました。
学んだこと:
- 機能追加の前に、コードの構造を整えるべき
- SRPを守ることで、コードの可読性とメンテナンス性が向上
- テストを書きながら開発を進めることで、リファクタリングが容易になる
2. テストの不足
開発初期段階では、テストを書きながら開発を進めていませんでした。その結果、リファクタリング時にテストの追加が必要になりました。
学んだこと:
- テストを書きながら開発を進めることで、リファクタリングが容易になる
- 単体テストにより、バグの早期発見が可能
- 統合テストにより、システム全体の動作を確認できる
3. ドキュメントの不足
開発初期段階では、ドキュメントを後回しにしていました。その結果、後でドキュメントを作成する必要がありました。
学んだこと:
- ドキュメントを書きながら開発を進めることで、後で振り返りやすくなる
- READMEの充実により、他の開発者や将来の自分が理解しやすくなる
- コメントの適切な使用により、コードの理解が容易になる
4. 本番利用で起きた「恋の病」エラー（ユーザー相談から得た教訓）
本ツールは医薬品相談を目的としていますが、実際の利用では「恋の悩み」のような感情的な相談も入力されます。和歌山県データ利活用コンペティションで、会場の方が実際に利用してくださった際に「恋の病」と入力され、当時のシステムではエラーになってしまう事象が発生しました。
そこで、感情的症状（恋愛の悩み・緊張・不安・不眠など）を受け止めるカウンセリングフローを設け、LLMトリアージで Emotional カテゴリに振り分けたうえで、共感的な返信と必要に応じた医薬品推奨への誘導を行う対策を実施しました。本番のユーザー入力に触れたことで、「医薬品以外の相談が来たときもエラーにせず、適切な案内をする」という設計の重要性を強く認識した思い出深い障害事例です。
今後の展望
短期目標（1年以内）
- 精度向上: より多くの相談事例データの蓄積
- UI/UX改善: より直感的な操作感の実現
- テストカバレッジの向上: 単体テストと統合テストの充実
- ドキュメントの充実: APIドキュメントとユーザーガイドの作成
中期目標（3-5年）
- 物理学的思考の応用: 統計力学や情報理論の知識を活用し、より精密な医薬品推奨アルゴリズムの開発
- データ分析の深化: 量子統計や確率論の観点から、ユーザーデータの分析精度を向上
- システムの最適化: 熱力学のエントロピー概念を応用し、システムの効率性と安定性を追求
長期目標（10年以上）
- 信頼性が求められる基盤・インフラ領域での実務経験: 「止めてはいけないシステム」を任されるエンジニアになる
- 技術・ドメイン・運用を横断的に理解: プロジェクト全体の安全性・正確性に責任を持つ立場へ
- 「この人に任せれば大丈夫」と言われる信頼ベースのリーダー: チームや将来の自分が引き継げる設計を目指す
ブログとREADMEの対応方針
本ブログの医薬品相談ツール関連記事は、medicine-recommend-system のREADMEやコミットを参照して執筆しています。運用方針としては、ブログは**「記事公開時点のスナップショット」**を基本とし、READMEを更新するたびにブログの日付や文言を逐一合わせることはしません。一方で、大きな仕様変更（例：推奨アルゴリズムの変更、新機能の追加、クラウド移行など）や、読者の理解に影響する重要な更新があった場合は、該当する記事を都度更新するようにしています。READMEが「生きたドキュメント」として日々更新されるのに対し、ブログは「その時点での設計意図や経験を残す記録」として位置づけています。
まとめ
367コミットという数字は、継続的な改善の積み重ねの結果です。このプロジェクトを通じて、「システムを誤らせない設計」の重要性を改めて実感しました。
今後も、現場の声を大切にしながら、より良いシステムの構築を目指していきます。そして、物理学科としての知識を活かし、より精密なアルゴリズムの開発に取り組んでいきます。
「人や社会に影響を与えるシステムは、誤ってはいけない」 - この信念を胸に、今後も開発を続けていきます。