> 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/aineitibu/21-requirements-and-design.md). # 21. 要件整理と設計方針の作成 ## 目的 実装前に、解決する問題と既存リポジトリへ組み込む方法を分けて整理します。要件は人間が主導し、AIは整理、質問、選択肢の提示を補助します。 ## 要件は人間が決める AIは利用者、事業、運用の背景を完全には理解していません。次の事項は人間が決めます。 * 誰のどの問題を解決するか * 何を正しい振る舞いとするか * 優先順位と完了条件 * 許容できる不便、性能、運用負荷 * 今回実現しないこと AIには、Issue本文または存在するRequirementsを読ませ、曖昧な用語、入力不足、異常系、境界値、既存仕様との矛盾候補を質問として出させます。小規模変更ではIssue本文に要件を集約し、複雑または高リスクな変更ではIssue単位のSpecへ分けます。実装結果を左右する質問への回答は、要件へ反映してから実装へ進みます。 ## 要件の書き方 要件は、画面やクラスの構造ではなく、外から観察できる振る舞いで書きます。 悪い例: ``` サービスクラスに検索メソッドを追加する。 ``` 良い例: ``` 利用者が状態を指定すると、該当する項目だけを更新日時の降順で確認できる。 未指定の場合は従来と同じ一覧を返す。 ``` 後者であれば、実装方式を固定せず、手動確認とテストの期待結果を定義できます。 ## 「今回はやらないこと」を決める 進化型プロトタイピングでは、最小の価値を早く確認するため、非対象を明示します。 * 複数条件の高度な検索は行わない * 管理画面以外には表示しない * 既存データの一括補正は行わない * APIのバージョン変更は行わない * 共通基盤の置き換えは行わない 非対象は将来の否定ではなく、今回の差分を安全に限定するための境界です。 ## 設計案を作る リポジトリ調査後、AIに次の形式で設計案を出させることができます。 1. 推奨案とその理由 2. 代替案 3. 各案の利点、欠点、移行コスト 4. 変更ファイル候補 5. API、DB、画面、テストへの影響 6. 未決事項と人間に必要な判断 提案は、既存パターンに合わせた最小変更を第一候補とします。将来使うかもしれないという理由だけの抽象化や、新しい依存関係の追加は避けます。 ## 設計で確認する領域 ### Java・REST API * Request、Response、DTOの責務 * Validationとエラー形式 * Serviceの業務ロジック * Repositoryとトランザクション境界 * HTTPメソッド、パス、ステータス、互換性 ### DB * カラム型、NULL、既定値、制約、インデックス * 既存データへの適用方法 * 展開順序と旧コードとの互換期間 * ロック、処理時間、バックアップ、ロールバック ### フロントエンド * 表示状態、入力、エラー、ローディング、空状態 * APIとの契約 * 既存コンポーネントとスタイルの再利用 * レスポンシブ表示とアクセシビリティ ### 運用 * ログ、監視、問い合わせ時に必要な情報 * 機密情報を出力しないこと * 障害時の切り戻し方法 * 文書や手順書の更新対象 ## 未決事項を残す 調査しても決められない事項は、Issue本文または存在するDesignの`未決事項`へ残します。複数回参照する判断や、影響範囲が広い変更では、Issue単位のSpecへ残します。Issue完了後も有効な判断はADRなどの全体ドキュメントへ同期します。 ```markdown ## 未決事項 - [ ] 未指定時に全件を返すか、既定状態だけを返すか（担当者確認） - [ ] 既存データの初期値（運用担当者確認） ``` 未決事項が実装結果を左右する場合、AIに推測させてはいけません。仮実装が必要なら、仮定、差し替え箇所、採用しない可能性を明記し、人間が承認します。 ## 手順 1. 人間が背景、目的、対象、非対象、完了条件を書く 2. AIに曖昧さと不足を質問させる 3. 人間が回答し、要件を確定または暫定化する 4. リポジトリ調査結果を参照して設計案を作らせる 5. 人間が案を比較し、採用方針を決める 6. 変更対象、変更しない範囲、未決事項を設計へ記録する 7. 完了条件に対応する確認方法を決め、必要ならIssue単位のtest-planを作る 8. 高リスク変更は移行、テスト、ロールバックも承認する 9. 確認方法を含めて実装、テスト、文書同期のタスクを分解する ## AIに依頼すること * 要件を勝手に変更せず、不明点を質問にする * 要件と非対象の矛盾を指摘する * 既存コードに沿った複数の設計案を比較する * 影響範囲、リスク、未決事項を明示する ## 人間が確認すること * 要件が利用者や業務の目的に合うか * 設計が要件を満たし、過剰になっていないか * 公開API、DB、認証・権限の判断が承認済みか * 未決事項を暗黙の仮定で実装しようとしていないか