> 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/5-development-operations.md). # 5. 開発運用方針 リブログでは、GitHubを単なるソースコード置き場ではなく、プロダクトの仕様、設計、判断、改善履歴を残す場所として扱います。 このページでは、リブログの小規模・継続開発における基本的な運用方針を整理します。 ## 基本方針 リブログの開発運用では、次の考え方を重視します。 * プロダクトの目的と責務を明確にする * READMEで概要と実行方法を確認できるようにする * docsに仕様、設計、運用メモを残す * Issueに作業内容と判断理由を残す * APIキーやパスワードをリポジトリに含めない * AIに渡す前提情報やプロンプトを再利用できる形で残す * プロトタイプで確認した内容は、必要に応じてテストで固定する ## リポジトリの考え方 リポジトリは、プロダクトや技術要素の責務が分かる単位で分けます。 ただし、分割すること自体を目的にはしません。小さなプロダクトでは、画面、API、バッチ、ドキュメントを同じリポジトリで管理したほうが分かりやすい場合もあります。 分けるかどうかは、次の観点で判断します。 * 単独で公開・デプロイするか * 他のプロダクトから再利用するか * 更新頻度が大きく異なるか * セキュリティや公開範囲を分ける必要があるか * CodexなどのAIに作業単位として渡しやすいか ## READMEに書くこと READMEは、初めてリポジトリを見る人と、未来の自分のために書きます。 最低限、次の内容を記載します。 * プロダクトまたはツールの概要 * 主な機能 * 技術構成 * セットアップ手順 * 実行方法 * 環境変数 * デプロイ方法 * 注意事項 * 関連ドキュメント READMEには、詳細な設計をすべて書く必要はありません。詳しい仕様や設計は、docsディレクトリに分けます。 ## docsディレクトリに残すこと docsディレクトリには、コードだけでは読み取れない判断や前提を残します。 * 要件 * 仕様 * API設計 * DB設計 * 画面構成 * データ更新手順 * デプロイ手順 * 運用メモ * 既知の制約 * 今後の改善案 * Codex向けプロンプト 特に、AIに作業を依頼する場合は、前提情報が不足していると意図しない実装になりやすくなります。docsは、AIと人間が同じ前提で作業するための共通資料でもあります。 ## Issueの使い方 Issueは、作業の依頼、調査、判断、改善案を残す場所として使います。 Issueには、可能な範囲で次の内容を書きます。 * 背景 * 目的 * 変更対象 * 完了条件 * 確認方法 * 関連する仕様や画面 * Codexに依頼する場合の作業範囲 作業が完了したら、結果だけでなく、判断理由や残課題も残します。 ## Secrets管理 APIキー、パスワード、アクセストークン、DB接続情報などの秘密情報は、privateリポジトリであってもコミットしません。 秘密情報は、次のような方法で管理します。 * 環境変数 * GitHub Secrets * サーバー側の設定ファイル * ローカル専用の設定ファイル `.env` などのローカル設定ファイルは、必要に応じて `.gitignore` に追加します。サンプルが必要な場合は、値を含まない `.env.example` を用意します。 ## AI協調開発での運用 CodexなどのAIに作業を依頼する場合は、Issueまたはdocsに前提条件を明記します。 AIに渡す情報は、次のように整理します。 * 何を作るのか * なぜ作るのか * どのファイルを変更するのか * 変更してはいけない範囲はどこか * 完了条件は何か * どのテストや確認を行うか AIが生成したコードは、そのまま採用しません。人間が確認し、必要に応じて修正、テスト、リファクタリングを行います。 ## プロトタイプから本実装へ育てる リブログでは、進化型プロトタイピングを基本にしています。 最初から完璧な設計を目指すのではなく、最小実装で動作を確認し、人間が判断し、必要な部分をテストで固定しながら本実装へ育てます。 プロトタイプを作るときは、次の点を明確にします。 * 何を検証するのか * 採用、修正、破棄の判断基準は何か * 検証専用か、本番投入を前提にするか * どの部分を後からテストで固定するか ## テストの扱い すべてを最初からテスト先行で進める必要はありません。 新規機能や仕様が曖昧な段階では、探索的に実装して動きを確認します。仕様が固まったら、重要なロジックからテストで固定します。 特に、次のような部分はテストの価値が高くなります。 * 日付判定 * 検索条件 * データ変換 * APIレスポンス * 金額や件数などの計算 * 地図データの変換 * 会話コマンドの分岐 ## ブランチと変更管理 小規模開発では、複雑なブランチ戦略よりも、変更内容が追いやすいことを重視します。 * mainブランチは公開・デプロイ可能な状態に保つ * 大きな変更は作業ブランチで行う * 変更内容が分かるコミットメッセージにする * まとめすぎた変更は避ける * 仕様変更、データ変更、画面変更をできるだけ分ける ## 公開後の運用 公開はゴールではなく、改善の開始点です。 公開後は、次の情報を残します。 * 公開日 * 変更内容 * 不具合対応 * データ更新履歴 * 利用者からの反応 * 次に改善すること リブログでは、作って終わりではなく、公開してから少しずつ育てることを大切にします。 プロダクト横断の公開方法と更新方法は、[デプロイ・運用一覧](/engineering-handbook/riburoguno/5-development-operations/deployment-operations.md)で確認します。秘密情報やAIへ渡す情報の扱いは、[セキュリティとAI利用時の情報管理](/engineering-handbook/riburoguno/5-development-operations/security-and-ai-usage.md)に従います。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://livlog-llc.gitbook.io/engineering-handbook/riburoguno/5-development-operations.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.