> For the complete documentation index, see [llms.txt](https://livlog-llc.gitbook.io/engineering-handbook/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://livlog-llc.gitbook.io/engineering-handbook/riburoguno/4-development-philosophy.md). # 4. 開発思想 リブログ合同会社では、開発を単なる実装作業ではなく、記録を意味に変えるためのプロセスとして捉えています。 Webサービス、API、ブログ、地図、AI、オープンデータを組み合わせながら、小さく作り、公開し、改善することを基本方針としています。 ## 基本方針 リブログの開発では、次の考え方を大切にしています。 1. 小さく作る 2. まず動かして理解する 3. 人間が確認して判断する 4. 確定した振る舞いをテストで固定する 5. 使いながら改善する 6. データを資産として残す 7. 技術を目的化しない 8. AIと協調する 9. 個人の記録を社会的価値に変える ## 小さく作る 最初から完成度の高い大規模なサービスを目指すと、公開までに時間がかかりすぎます。 リブログでは、まず最小限の形で動くものを作ります。 * まず一覧が出る * まず地図に表示できる * まず検索できる * まずAPIが返る * まずMarkdownで管理できる このように、最初の一歩を小さくすることで、開発を前に進めやすくしています。 ## まず公開する リブログでは、公開することを重視しています。 公開されていないサービスは、利用者から見れば存在しないものです。\ 完成していなくても、公開することで初めて改善のきっかけが生まれます。 公開することで、次のことが分かります。 * 何が伝わるか * 何が分かりにくいか * どの機能が必要か * どのデータが不足しているか * どの画面が使いにくいか * どのコンテンツに価値があるか リブログでは、公開をゴールではなく、改善のスタート地点と考えます。 ## 使いながら改善する リブログのサービスは、公開後も継続的に改善します。 最初の設計どおりにすべてが進むことはありません。\ 実際に使ってみると、必要な機能、不要な機能、分かりにくい表現、足りないデータが見えてきます。 そのため、リブログでは、開発前の仕様を絶対視しすぎません。 仕様を決めることは重要です。\ しかし、実際に作って見えてくることも同じくらい重要です。 ## プロトタイピングを重視する リブログでは、プロトタイピング開発を重視しています。 特に、以下のようなサービスでは、最初から詳細仕様を固めるよりも、動く画面やAPIを作ったほうが判断しやすくなります。 * 地図を使うサービス * 写真を使うサービス * 検索条件が複雑なサービス * AIを活用するサービス * オープンデータを加工するサービス * 新しい体験を作るサービス プロトタイプを作ることで、仕様の曖昧さを具体化できます。 ## 進化型プロトタイピングを基本とする リブログの開発は、単なる試作品づくりではありません。 基本方針は、次の流れです。 ``` 探索的プロトタイピング → 人間による確認 → テストで仕様固定 ``` これは、最初からすべての仕様を確定してから実装する進め方ではありません。 まず最小限の実装を作り、実際の動作を確認しながら、何が正しい振る舞いなのかを具体化します。そのうえで、人間が内容を確認し、採用する振る舞いを決め、最後にテストで固定します。 この方式を、リブログでは **実装先行・テスト固定型開発** と呼びます。 より一般的には、**進化型プロトタイピング**、または **探索的実装を取り入れた進化型開発** に近い考え方です。 ### 実装先行・テスト固定型開発 実装先行・テスト固定型開発では、次の順番で開発を進めます。 ``` 最小実装 → 動作・業務確認 → テスト追加 → リファクタリング ``` 最初の実装は、完成品ではありません。 目的は、仕様を確定することではなく、仕様を具体化することです。 実際に動く画面、API、検索結果、変換結果を見ながら、次のことを確認します。 * この動きで利用者に伝わるか * 業務や目的に合っているか * データの扱いに無理がないか * 画面やAPIの責務が分かりやすいか * 追加すべき条件や例外があるか * この実装を本実装として育てるか、作り直すか 確認して正しいと判断した振る舞いは、後からテストで固定します。 これにより、実装の柔軟さと、長期運用に必要な安全性を両立します。 ### 捨てるプロトタイプとは違う プロトタイピングには、大きく分けて2種類あります。 1つ目は、確認のためだけに作り、確認後に捨てるプロトタイプです。 2つ目は、小さく作った実装を評価し、修正し、テストを追加し、リファクタリングしながら本実装へ育てていく進化型プロトタイプです。 リブログの開発方針は、後者です。 もちろん、検証の結果として捨てる判断をすることもあります。 しかし基本的には、動くものを作り、確認し、必要に応じて整えながら本実装へ育てていくことを重視します。 ### 方式を切り替える すべての開発を実装先行にするわけではありません。 リスクが高い処理や、すでに正しい振る舞いが明確な処理では、テストを先に書くほうが適しています。 リブログでは、対象に応じて方式を切り替えます。 | 対象 | 基本方針 | | ---------- | ----------------- | | 新規機能・PoC | 実装先行で探索する | | 既存仕様が曖昧な改修 | 実装先行で具体化する | | UI・画面調整 | 実装先行で確認する | | 地図表示・写真表示 | 実装先行で体験を確認する | | 不具合修正 | テストで再現してから修正する | | 金額・在庫・権限処理 | テスト先行を優先する | | 複雑な状態遷移 | テストで条件を整理してから実装する | | データ変換ロジック | 代表ケースをテスト化して固定する | このため、リブログの開発は、全面的なテスト駆動開発ではありません。 **進化型プロトタイピングを中心に、重要部分だけテスト先行を使い、確認済みの振る舞いを後からテストで固定するハイブリッド型の開発方式**です。 ### Readyの考え方 生成AIに作業を依頼する場合でも、何も決まっていない状態で丸投げするのではありません。 最低限、次の内容を明確にしてから依頼します。 * 今回検証したい仮説 * プロトタイプで確認する項目 * 採用・修正・破棄の判断基準 * プロトタイプの品質水準 * 本番投入可能な実装か、検証専用か * 入力データと期待する出力の例 * 既存仕様との関係 * 触ってよい範囲と触ってはいけない範囲 これにより、AIによる実装を探索に活用しながらも、判断の責任は人間側に残します。 ### リブログに合っている理由 リブログのサービスでは、地図、写真、オープンデータ、AI生成文、検索条件など、実際に動かしてみないと判断しにくい要素が多くあります。 そのため、最初から厳密な仕様を作り込みすぎるよりも、まず動くものを作り、人間が確認し、正しい振る舞いをテストで固定するほうが現実的です。 この方針は、次のような開発に特に向いています。 * 朝夕日和の検索条件や地図表示 * 言の場の地名検索や表示形式 * 水のみち散策のGeoJSON表示 * 樹辞苑の木材分類や詳細ページ * NOBY APIの会話コマンド処理 * AI生成コンテンツの構成確認 リブログでは、まず動かして理解し、その後に仕様とテストを固めます。 ## テストとの向き合い方 リブログでは、テストを軽視しているわけではありません。 ただし、すべての開発を厳密なテスト駆動開発で進めるのではなく、プロダクトの段階やリスクに応じてテストの使い方を変えます。 ### 初期段階 初期段階では、まず動くものを作ることを優先します。 * 画面が表示されるか * APIが返るか * データが取得できるか * 地図に表示できるか * 検索条件が機能するか * AI生成結果が目的に合っているか この段階では、仕様が変わりやすいため、過剰なテストコードはかえって開発速度を落とす場合があります。 ### 仕様固定段階 動作確認によって正しい振る舞いが見えてきたら、重要な処理からテストを追加します。 * 日付判定 * 検索条件 * SQL条件 * データ変換 * ファイル出力 * APIレスポンス * ランキング計算 * 権限や状態遷移 特に、朝夕日和の日付範囲判定や、KML to GeoJSON APIの変換処理のように、ロジックの正しさが重要な部分ではテストの価値が高くなります。 ### Red / Green / Refactorとの関係 テスト駆動開発では、一般的に Red / Green / Refactor のサイクルが使われます。 ``` Red: 失敗するテストを書く Green: テストを通す最低限の実装をする Refactor: 動作を保ったままコードを整理する ``` この考え方は、リブログでも重要です。 ただし、リブログではすべての開発を最初から Red で始めるわけではありません。 新規機能や探索的な開発では、まず最小実装を作り、動作を確認します。その後、正しいと判断した振る舞いをテスト化し、そこから Red / Green / Refactor の考え方で安全に改善します。 つまり、リブログでは次のように扱います。 ``` Explore: 最小実装で探索する Fix: 正しい振る舞いを決める Test: テストで固定する Refactor: 安全に整理する ``` 既存不具合や重要な業務ロジックでは、最初から Red / Green / Refactor を使います。 一方で、新規機能、UI、AI、地図表示のように正解を探索する必要があるものは、Explore → Fix → Test → Refactor を基本にします。 ### テストで固定する対象 すべてをテストすることは目的ではありません。 リブログでは、壊れると困る振る舞い、判断が複雑な処理、後から変更されやすい処理を優先してテストします。 たとえば、次のような部分です。 * 朝夕日和の日付範囲判定 * 年跨ぎ検索条件 * 朝日・夕日の切り替え条件 * KML to GeoJSONの変換結果 * GeoJSONの出力構造 * NOBY APIのコマンド判定 * 連続コマンド処理 * 樹辞苑のカテゴリ判定 * 検索条件の組み立て テストは、開発を遅くするためのものではなく、確認済みの振る舞いを将来も守るためのものです。 ## AIとの協調開発 リブログでは、生成AIを、開発プロセスの中に組み込んでいます。 AIは、コードを書くためだけの道具ではありません。\ 以下のような場面で活用しています。 * アイデア整理 * 要件定義 * 仕様書作成 * 画面設計 * API設計 * SQL作成 * コード生成 * リファクタリング * テスト観点整理 * Markdown文書作成 * ブログ記事構成 * 画像生成指示 * 開発方針書作成 ## AIに任せること、任せないこと AIに任せることは、主にたたき台の作成と整理です。 ### AIに任せること * 文章の初稿 * コードの初稿 * 仕様の整理 * 抜け漏れ確認 * テスト観点の洗い出し * リファクタリング案 * プロンプト作成 * 技術比較 * ドキュメント整形 ### 人間が判断すること * 何を作るか * 何を公開するか * 何を削るか * 何を優先するか * どの表現がリブログらしいか * どのデータを信頼するか * 最終的な仕様 * 最終的な責任 AIは開発者の代替ではなく、開発者の判断を支える道具です。 ## ドキュメントを重視する リブログでは、ドキュメントを重要な技術資産と考えています。 個人開発や小規模開発では、コードを書いた本人しか分からない状態になりがちです。\ しかし、サービスを長く運用するためには、なぜその設計にしたのか、どのデータを使っているのか、どのように公開しているのかを残す必要があります。 ### 残すべき情報 * サービスの目的 * 利用しているデータ * API仕様 * DB設計 * 画面構成 * デプロイ手順 * 既知の制約 * 今後の改善点 * 技術選定理由 * AIに渡す開発プロンプト Livlog Engineering Handbook も、その一部です。 ## オープンデータ活用の考え方 リブログでは、国土数値情報、自治体データ、公開API、位置情報、写真情報などを活用しています。 オープンデータは、そのまま使うだけでは価値が伝わりにくい場合があります。\ リブログでは、オープンデータを加工し、検索しやすくし、地図や記事と組み合わせることで、利用者にとって意味のある形に変換します。 ### 重視すること * 出典を明確にする * データの更新時期を確認する * 加工内容を記録する * 元データと生成データを区別する * 利用者に分かりやすい形で表示する ## 個人の記録を社会的価値に変える リブログの開発では、個人の体験や記録を出発点にすることがあります。 たとえば、旅の記録、散策の記録、DIYの経験、地域で見つけた情報などです。 それらは、個人の記録のままでは一度きりの体験で終わります。\ しかし、整理し、データ化し、公開することで、他の誰かにとって役立つ情報になります。 リブログでは、この変換を大切にしています。 ## 開発における価値観 リブログの開発では、次の価値観を大切にします。 ### 1. 早く作るより、長く残る形にする 短期的に動くものを作るだけではなく、後から見ても理解できる構成を目指します。 ### 2. 複雑にしすぎない 技術的に高度な構成よりも、運用できる構成を重視します。 ### 3. データを雑に扱わない データはサービスの中核です。\ 出典、加工、更新、再利用を意識します。 ### 4. AIを活用するが、AI任せにしない AIの出力は便利ですが、そのまま正しいとは限りません。\ 最終判断は人間が行います。 ### 5. 公開することで価値を生む 作ったものは、公開して初めて誰かに届きます。\ 公開を恐れず、改善を続けます。 ## 今後の開発方針 リブログでは、今後も以下の方針で開発を進めます。 * 既存プロダクトの改善 * 技術文書の整備 * API仕様の明確化 * AIネイティブ開発の標準化 * オープンデータ活用の拡大 * 地図サービスの強化 * 写真・メディア管理の改善 * 会話AI領域の研究 * 小規模サービスの継続的な公開 リブログの開発は、完成を目指すものではなく、記録と改善を積み重ねていくものです。