Syllabus Hack開発記：メンテナンス性を高めるファイル構成と実装戦略

なぜAstroを選んだのか？静的部分と動的部分（React）の共存

サイトの表示速度と、クイズアプリのような動的機能を両立させるための選択として、 Astro を採用しました。

「Island Architecture」を活用し、いかに軽量でパワフルな学習プラットフォームを構築したか、その選定理由から紐解きます。

アイランド・アーキテクチャ：必要な部分だけを「動的」に

Astroの最大の特徴は、ページ全体を静的なHTMLとして出力しつつ、クイズの操作部分だけを Reactコンポーネント として動作させる「アイランド・アーキテクチャ」です。

これにより、学習記事の読み込みは一瞬で終わり、かつクイズを解く際にはアプリのような 滑らかな操作感 を提供することが可能になりました。

Page Bundle パターンの採用：コンテンツとアセットをひとまとめに管理

記事フォルダの中に markdown と画像を同居させる Page Bundle パターンを徹底しています。

これにより、記事の移動や削除が容易になり、メンテナンス性が劇的に向上しました。具体的なディレクトリ構造とそのメリットについて解説します。

ディレクトリ単位での自己完結による高い運用の柔軟性

src/data/post/{category}/{slug}/ というフォルダの中に、記事本文（index.md）とカバー画像（cover.png）をセットで配置しています。

この構成により、アセット管理が 直感的 になり、将来的に数千記事へと増大しても、リンク切れやファイル迷子を防げる堅牢な構造を実現しました。

クイズデータの構造化：JSONによる拡張性と試験マスタデータの分離

膨大な試験問題を効率的に管理するため、問題データを JSON として外部化。さらに、試験名やIDを定義する マスタデータ と分離することで、新しい試験区分（APや高度試験など）の追加をスムーズに行える設計思想を紹介します。

ロジックとデータの分離：多角的な試験区分への対応

クイズの表示ロジックは一つですが、読み込む JSONファイル を切り替えるだけで、ITパスポートから高度試験まで瞬時に対応できます。

データの構造を統一し、マスタデータでメタ情報を管理することで、開発の手間を最小限に抑えつつ、コンテンツの 網羅性 を高めることができました。

デザインシステムの設計：Tailwind CSS とダークモード対応の工夫

統一感のあるデザインをスピーディーに実装するため、 Tailwind CSS をフル活用。さらに、学習者の集中力を妨げないよう、OS設定に連動したシームレスなダークモード対応をどのように実装したか、そのこだわりを共有します。

Tailwind CSS による高速開発とダークモードの最適化

ユーティリティファーストなスタイリングにより、 レスポンシブ対応 やコンポーネントのデザイン調整を、極めて短期間で完了させることができました。

また、夜間の学習でも目が疲れにくいよう、 ダークモード を標準搭載し、学習に没頭できるミニマルな視覚体験を追求しています。

今後の機能拡張を見据えたアーキテクチャの解説

現在の構成は完成形ではありません。フラッシュカード機能や学習ログの保存など、将来の 機能拡張 を見据えて、どのような「遊び」を設計に持たせているか、開発者視点での裏話を公開します。

モジュール化された設計がもたらす将来の拡張性

各パーツを独立した コンポーネント として設計しているため、後から新しい学習機能を追加することが容易です。

今後、学習データをローカルストレージと連携させたり、AIによるパーソナライズ機能を統合したりと、プロダクトを 永続的 に進化させていくための盤石な土台を築いています。

まとめ：学習効率を最大化するためのシステム設計思想

良い学習体験は、良いシステム設計から生まれます。

SyllabusHackが技術的にどのような思想で成り立っているかを知ることで、あなたの 個人開発 や技術への理解がより深まることを願っています。