> 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を単なるソースコード置き場ではなく、プロダクトの仕様、設計、判断、改善履歴を残す場所として扱います。 このページでは、リブログの小規模・継続開発における基本的な運用方針を整理します。 初めて対象プロダクトの開発に入る場合は、[初回の開発を始める](/engineering-handbook/aineitibu/19-development-flow/first-development.md)で、対象リポジトリの確認から最初のIssueへの着手までを確認します。 ## 基本方針 リブログの開発運用では、次の考え方を重視します。 * プロダクトの目的と責務を明確にする * READMEで概要と実行方法を確認できるようにする * docsに仕様、設計、運用メモを残す * 初期開発を含むすべての変更をIssueから始め、作業内容と判断理由を残す * APIキーやパスワードをリポジトリに含めない * AIに渡す前提情報やプロンプトを再利用できる形で残す * プロトタイプで確認した内容は、必要に応じてテストで固定する ## リポジトリの考え方 リポジトリは、プロダクトや技術要素の責務が分かる単位で分けます。 ただし、分割すること自体を目的にはしません。小さなプロダクトでは、画面、API、バッチ、ドキュメントを同じリポジトリで管理したほうが分かりやすい場合もあります。 分けるかどうかは、次の観点で判断します。 * 単独で公開・デプロイするか * 他のプロダクトから再利用するか * 更新頻度が大きく異なるか * セキュリティや公開範囲を分ける必要があるか * AIに作業単位として渡しやすいか ## READMEに書くこと READMEは、初めてリポジトリを見る人と、未来の自分のために書きます。 最低限、次の内容を記載します。 * プロダクトまたはツールの概要 * 主な機能 * 技術構成 * セットアップ手順 * 実行方法 * 環境変数 * デプロイ方法 * 注意事項 * 関連ドキュメント READMEには、詳細な設計をすべて書く必要はありません。詳しい仕様や設計は、docsディレクトリに分けます。 ## docsディレクトリに残すこと docsディレクトリには、コードだけでは読み取れない判断や前提を残します。 * 要件 * 仕様 * API設計 * DB設計 * 画面構成 * データ更新手順 * デプロイ手順 * 運用メモ * 既知の制約 * 今後の改善案 * AI向けプロンプト 特に、AIに作業を依頼する場合は、前提情報が不足していると意図しない実装になりやすくなります。docsは、AIと人間が同じ前提で作業するための共通資料でもあります。 ## Issueの使い方 Issueは、初期開発、機能追加、不具合修正、リファクタリング、文書更新など、すべての変更の入口として使います。初期開発もプロダクト全体を一つのIssueへまとめず、最小公開に必要な価値や土台をレビュー可能なIssueへ分けます。 Issueには、可能な範囲で次の内容を書きます。 * 背景 * 目的 * 変更対象 * 完了条件 * 確認方法 * 関連する仕様や画面 * AIに依頼する場合の作業範囲 * 全体ドキュメントへの反映先 変更に必要な要件、設計、タスクはIssue本文またはIssue単位のSpecへ整理します。作業が完了したら、結果だけでなく、判断理由や残課題も残し、採用した仕様と継続して使う判断を全体ドキュメントへ反映してからIssueを閉じます。 ## AIを使う少人数チームの協働 複数人がそれぞれAIを使う場合は、共通の目的、コア仕様、完了基準を共有し、Issue単位で担当を決めます。担当領域は固定しすぎず、作業中の担当者と、判断・レビューの相談先を明確にします。 行き詰まった作業は、途中の差分、確認結果、未決事項をIssueやDraft PRへ残して引き継ぎます。並列作業では共有契約への影響を確認し、取り込み時には統合後の動作を確認します。 初回の共同作業、担当の取り方、引き継ぎ、統合、実践記録の方針は、[AIと進める少人数チーム開発](/engineering-handbook/aineitibu/19-development-flow/team-development.md)を参照してください。 ## Secrets管理 APIキー、パスワード、アクセストークン、DB接続情報などの秘密情報は、privateリポジトリであってもコミットしません。 秘密情報は、次のような方法で管理します。 * 環境変数 * GitHub Secrets * サーバー側の設定ファイル * ローカル専用の設定ファイル `.env` などのローカル設定ファイルは、必要に応じて `.gitignore` に追加します。サンプルが必要な場合は、値を含まない `.env.example` を用意します。 ## AIネイティブ開発での運用 AIに作業を依頼する場合は、対象Issueと、Issue本文またはIssue単位のSpecに前提条件を明記します。 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)に従います。