> 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/29-continuous-feature-updates.md). # 29. 機能の継続更新 ## 機能は一度作って終わりではない 実際の開発では、新規機能を一度作って終わりにすることはほとんどありません。運用開始後も、画面項目、API項目、DBカラム、入力チェック、検索条件、表示条件などを追加・変更します。不具合修正、仕様変更、リファクタリング、テスト追加も繰り返されます。 初期開発と同じく、これらの更新もIssueから始めます。Issue本文またはIssue単位のSpecに今回の変更を整理し、完了時に採用した結果を機能単位の全体ドキュメントへ同期します。 更新を重ねると、最初の要件定義や設計書は「開発当初に何を作ろうとしたか」は示せても、「現在どう動くべきか」を完全には表せなくなります。AIに古い文書だけを渡すと、廃止された仕様や当初の設計を正しい前提として扱い、現在の実装と矛盾する修正を行う可能性があります。 そのため、継続的に更新する機能では、機能ごとに少なくとも次の2種類の情報を管理します。 * **現在の正しい仕様**：現時点で画面、API、DB、入力チェックなどがどう動くべきか * **変更履歴**：いつ、何を、なぜ変え、どこへ影響したか 要件、設計、実装、テストのどれか一つだけを正とするのではなく、更新のたびに相互の整合を確認することが重要です。 ## 更新を重ねると起きる問題 機能更新の記録方法を決めずに変更を積み重ねると、次の問題が起きます。 * 古い要件と現在仕様がずれ、どちらを優先すべきか分からなくなる * 仕様変更の理由が残らず、意図的な挙動を不具合と誤認する * どの変更で画面、API、DB、テストが変わったのか追えなくなる * AIが過去の仕様を正として判断し、廃止した挙動を復活させる * 変更対象外の既存機能を壊す修正や、不要なリファクタリングを行う * テスト観点が更新されず、新しい境界値や異常系の確認が漏れる * ドキュメントと実装が乖離し、次の変更でも誤った前提が引き継がれる 特に、コードだけが最新で文書が古い状態と、文書だけを更新してコードやテストが追従していない状態の両方に注意します。更新作業の完了条件には、実装だけでなく、現在仕様、変更履歴、テスト観点の更新を含めます。 ## 機能単位でドキュメントを管理する 何度も更新する機能を、プロジェクト全体で一つの `docs/requirements.md` だけにまとめると、変更対象、現在仕様、履歴の境界が曖昧になります。機能ごとに文書を分け、AIが今回読むべき範囲を明示できる構成を推奨します。 ``` docs/ features/ {feature-name}/ current-spec.md change-log.md ``` これは継続更新する機能の最小構成例です。機能で継続して有効な要件、設計、確認観点が長くなる場合は、同じディレクトリへ`requirements.md`、`design.md`、`test-plan.md`などを分けられます。今回の変更要件、設計、タスク、AIへの個別指示は、Issue本文または`docs/specs/{issue-number}/`へ置きます。 機能単位の文書とIssue単位の文書の主な役割は次のとおりです。同じファイル名でも配置場所で役割を区別します。 | ファイル | 主な役割 | | ---------------------------------------------------- | -------------------------------------------- | | 機能単位の`requirements.md`、`design.md`、`test-plan.md` | 継続して有効な要求、設計、確認観点を分けて管理する。現在仕様から参照する | | Issue単位の`requirements.md`、`design.md`、`test-plan.md` | 今回の変更要件、実装方針、確認計画と結果を管理する | | Issue単位の`tasks.md` | 今回の更新作業をレビュー可能な単位へ分割する | | `current-spec.md` | 過去の経緯ではなく、現在の正しい仕様を集約する | | `change-log.md` | 変更内容、変更理由、影響範囲、確認結果を時系列で残す | | Issue単位の`ai-instructions.md` | 今回の参照文書、変更可能範囲、禁止事項を示す。共通指示はAGENTS.mdなどで管理する | 例えば、利用者検索と画像アップロードを別々に管理する場合は、次のようにします。 ``` docs/ features/ user-search/ current-spec.md change-log.md photo-upload/ current-spec.md change-log.md ``` 既存プロジェクトに同等の文書や命名規則がある場合は、無理にこの名前へ変更せず、役割の対応関係を明確にします。複数機能にまたがる変更では、各機能の文書を更新したうえで、機能間の依存関係や更新順序も設計文書やタスクへ記録します。 この章の機能単位文書は、Issue単位のSpecとは役割が異なります。Specには今回の変更要件、設計、タスクを置き、Issue完了時に採用した結果だけを機能単位の`current-spec.md`と`change-log.md`へ反映します。過去IssueのSpecを現在仕様として参照しません。 ## current-spec.md で現在仕様を管理する `current-spec.md` は変更の経緯を並べる場所ではなく、**現在の正しい仕様**を一か所で確認するためのファイルです。新しく参加した開発者やAIが、過去の文書を時系列に読み解かなくても、現時点の期待する振る舞いを把握できる状態にします。 テンプレート例は次のとおりです。 ```markdown # 現在の仕様 ## 機能概要 ## 現在の画面仕様 ## 現在のAPI仕様 ## 現在のDB仕様 ## 現在の入力チェック ## 現在のエラーハンドリング ## 現在の権限・認証 ## 現在のテスト観点 ## 既知の制約 ## 仕様の対象外 ``` 運用時は次を守ります。 * `current-spec.md`が存在する機能では、AIへ更新を依頼する前に読ませる * 仕様変更後は、実装とテストの結果を確認して `current-spec.md` を最新化する * 「以前はどうだったか」ではなく、「現在どう動くべきか」を明確に書く * 画面、API、DBなどに該当事項がない場合も、未確認なのか対象外なのかを区別する * 機能として継続して対象外とすることを記載する。今回だけ変更しない範囲はIssue本文またはIssue単位のSpecへ置く `current-spec.md` と実装が矛盾している場合は、どちらかを機械的に正とせず、変更履歴、テスト、運用上の挙動を調査して人間が正しい仕様を決定します。不明点は推測で埋めず、未確認事項として残します。 ## change-log.md で変更理由を残す `change-log.md` は、機能がどのように変わってきたかを時系列で記録するファイルです。コード差分から分かる「何を変更したか」だけでなく、「なぜ変更したか」と「どこまで確認したか」を残します。 テンプレート例は次のとおりです。 ```markdown # 変更履歴 ## YYYY-MM-DD 変更タイトル ### 変更内容 ### 変更理由 ### 影響範囲 ### 変更したファイル ### 確認したこと ### 残課題 ``` 記録時は次を意識します。 * 何を変更したかだけでなく、なぜ変更したかを事実に基づいて残す * 画面、API、DB、バッチ、運用、他機能などの影響範囲を記録する * 実行した自動テストや手動確認と、その結果を残す * 残課題、未対応事項、未確認事項があれば明記する * 未来の自分や他の開発者が、変更の経緯と判断を追える粒度にする 変更理由が確認できない場合は、推測で理由を作りません。「理由は記録から確認できない」など、確認できた事実と不足情報を区別します。コミット履歴やPull Requestへの参照を記載する場合も、それだけに依存せず、機能上の要点を `change-log.md` に残します。 ## 更新前にAIへ確認させること 機能更新時は、いきなりコードを変更させません。まず調査だけを依頼し、次を確認させます。 現行コード、`current-spec.md`、最新の設定などはAssetとして扱います。旧要件、旧設計、過去メモ、移行元コードを参照する場合はReferenceであることを明示し、現在の正解としてコピーさせません。Asset同士に矛盾がある場合も、AIに優先順位を推測させず、人間が判断できるように差異と根拠を報告させます。 * 現在仕様 * 変更履歴 * 既存実装 * 既存テスト * 影響範囲 * 変更してよい範囲 * 変更してはいけない範囲 * 不明点 * 既存仕様を壊す可能性 調査結果は人間が確認し、誤った前提、見落とした関連処理、未決事項がないことを確認してから実装へ進みます。AIへの依頼例は次のとおりです。 ```markdown まず以下のファイルを読み、現在の仕様と過去の変更履歴を確認してください。 - docs/features/{feature-name}/current-spec.md - docs/features/{feature-name}/change-log.md - 対象Issueと、存在するdocs/specs/{issue-number}/配下のRequirements、Design、test-plan - 機能単位の要件・設計・確認観点が別文書にある場合は、その実在する参照先 文書がない場合は同等の既存文書を参照し、確認できない仕様は未確認事項として分けてください。 そのうえで、今回の変更が既存仕様に与える影響を整理してください。 まだ実装はしないでください。 出力には以下を含めてください。 - 現在仕様の要約 - 今回変更する内容 - 影響を受ける画面・API・DB・テスト - 変更してよい範囲 - 変更してはいけない範囲 - 実装前に確認すべき不明点 ``` 文書の確認だけで影響範囲を確定せず、実在するコード、設定、migration、テスト、呼び出し元も調査させます。文書と実装の不一致を見つけた場合は、勝手に修正させず、差異と判断に必要な情報を報告させます。 ## 更新時のタスク分解 機能更新では、次の観点を順に確認します。小さく低リスクな変更は一つの依頼へまとめられます。複数層にまたがる変更や高リスクな変更は、判断と差分を確認できるように工程を分けます。 ``` 1. 現在仕様の確認 2. 変更履歴の確認 3. 既存実装の調査 4. 影響範囲の整理 5. 要件・設計の更新 6. タスク分解 7. 小さな単位で実装 8. テスト追加・修正 9. 手動確認 10. current-spec.md の更新 11. change-log.md の更新 12. docs / README / API仕様の更新 13. 差分レビュー ``` 工程を分ける場合は各段階の結果を人間が確認し、次へ進める状態か判断します。特に、DB変更、公開APIの互換性変更、認証・権限変更、既存データの更新は、通常のコード修正と分け、移行方法とロールバック方法を確認してから実装します。 一回の依頼では、対象となる振る舞いと変更可能なファイルを限定します。仕様変更と関係のないリファクタリングは別タスクにし、差分へ混在させません。 ## 既存仕様を壊さないための確認観点 実装後は、変更した機能が動くことだけでなく、変更対象外の仕様が維持されていることを確認します。レビューでは少なくとも次を確認します。 ``` - 今回の変更対象以外を変更していないか - 現在仕様と矛盾していないか - 既存APIのレスポンスを壊していないか - 既存画面の表示や導線を壊していないか - DB変更が既存データに影響しないか - 入力チェックやエラーハンドリングが変わっていないか - 権限・認証に影響がないか - 既存テストが通るか - 新しいテスト観点が追加されているか - current-spec.md が更新されているか - change-log.md に変更理由が残っているか - Secretsや個人情報が混入していないか ``` 「影響なし」という報告だけで済ませず、どのコード、テスト、差分を根拠に判断したかを確認します。環境上実行できなかったテストや手動確認は、成功扱いにせず未確認として残します。 ## 更新後に更新要否を必ず確認するドキュメント 機能更新後は、変更内容に応じて次の文書を確認し、必要なものを更新します。 * `current-spec.md` * `change-log.md` * `requirements.md` * `design.md` * `tasks.md` * `test-plan.md` * `ai-instructions.md` * README * API仕様書 * 画面仕様書 * 運用メモ すべての小さな修正で、すべての文書を更新する必要はありません。例えば、利用者に見えない内部的な整理だけで現在仕様が変わらない場合、`current-spec.md` の本文変更が不要なこともあります。一方、修正が小さくても、現在の振る舞いや確認観点が変わるなら対応する文書を更新します。 基本ルールは次のとおりです。 ``` 現在の仕様が変わった場合は current-spec.md を更新する。 変更理由や影響範囲がある場合は change-log.md を更新する。 今回の確認計画と結果はIssue本文またはIssue単位の test-plan.md を更新する。 継続して使う確認観点は機能単位の文書または全体のテスト方針へ反映する。 今回のAIへの個別指示はIssue単位の ai-instructions.md などを更新する。 共通の作業ルールが変わった場合は AGENTS.md などを更新する。 ``` 文書更新は、実装から独立した後回し作業ではありません。差分レビューの対象に含め、コード、テスト、現在仕様、変更履歴が同じ変更内容を表していることを確認します。 ## 継続更新時のAIプロンプト例 次のプロンプトは、リポジトリの構成、機能名、実際に確認したファイルへ合わせて調整します。存在を確認していないファイル名、サービス名、仕様を推測で追加しないでください。 各プロンプトでは、参照ファイルをAssetとReferenceへ分けます。例に挙げた文書が存在しない場合は、存在する同等文書または依頼文を使い、プロンプトのためだけに作成しません。 ### 1. 機能更新前の影響調査プロンプト ```markdown 以下の機能を更新します。 対象機能： {feature-name} 今回の変更内容： {変更内容} まず実装は行わず、以下を確認してください。 参照ファイル： - docs/features/{feature-name}/current-spec.md - docs/features/{feature-name}/change-log.md - docs/features/{feature-name}/requirements.md - docs/features/{feature-name}/design.md - docs/features/{feature-name}/test-plan.md 確認してほしいこと： - 現在仕様の要約 - 今回の変更が影響する箇所 - 変更すべきファイル - 変更してはいけないファイル - 既存仕様を壊す可能性 - 追加・修正すべきテスト - 更新すべきドキュメント まだコードは変更しないでください。 ``` ### 2. Issue単位のtest-plan作成・更新プロンプト ```markdown 影響調査と更新した要件・設計を基に、実装前の確認計画を作成してください。 対象Issue： {issue-number} 対象機能： {feature-name} 作成・更新先： - docs/specs/{issue-number}/test-plan.md 参照ファイル： - docs/features/{feature-name}/current-spec.md - 対象Issueとdocs/specs/{issue-number}/配下の実在するRequirements、Design - 関連する既存テスト 要件の完了条件に対応させて、正常系、異常系、境界値、権限、DB、画面、API、回帰確認、自動テスト、手動確認を整理してください。 探索中で期待結果が確定していない項目は暫定と明記し、推測で確定しないでください。 Issue完了後も継続利用する確認観点は、機能単位のtest-planまたは全体のテスト方針への同期候補として示してください。 まだコードは変更しないでください。 ``` ### 3. 小さな実装依頼プロンプト ```markdown 先ほど整理した影響範囲に基づき、以下の範囲だけ実装してください。 対象機能： {feature-name} 今回実装する範囲： {今回実装する範囲} 変更してよいファイル： {変更してよいファイル} 変更してはいけないファイル： {変更してはいけないファイル} 参照ファイル： - docs/features/{feature-name}/current-spec.md - docs/features/{feature-name}/design.md - 対象Issueと、存在するdocs/specs/{issue-number}/配下のDesign、Tasks、test-plan 注意事項： - Issueで採用した変更だけを行い、対象外の既存仕様を変更しないでください - 今回指定した範囲以外のリファクタリングはしないでください - APIレスポンス形式を勝手に変更しないでください - DB変更が必要な場合は、実装前に提案として出してください - Secretsや個人情報を含めないでください 出力してほしい内容： - 変更概要 - 変更したファイル - 確認方法 - 追加・修正したテスト - ドキュメント更新が必要な箇所 ``` ### 4. current-spec.md 更新プロンプト ```markdown 今回の実装差分を確認し、対象機能の current-spec.md を最新化してください。 対象機能： {feature-name} 参照ファイル： - docs/features/{feature-name}/current-spec.md - docs/features/{feature-name}/design.md - docs/features/{feature-name}/test-plan.md 更新方針： - 過去の経緯ではなく、現在の正しい仕様として書いてください - 画面仕様、API仕様、DB仕様、入力チェック、エラーハンドリング、権限、テスト観点を必要に応じて更新してください - 今回変更していない仕様は勝手に変更しないでください - 不明な点は推測で補完せず、未確認事項として残してください ``` ### 5. change-log.md 更新プロンプト ```markdown 今回の変更内容を docs/features/{feature-name}/change-log.md に追記してください。 対象機能： {feature-name} 追記する日付： YYYY-MM-DD 変更タイトル： {変更タイトル} 追記内容には以下を含めてください。 - 変更内容 - 変更理由 - 影響範囲 - 変更したファイル - 確認したこと - 残課題 注意事項： - 事実として確認できる内容だけを書いてください - 推測で変更理由を作らないでください - Secretsや個人情報を含めないでください ``` ### 6. 継続更新後のレビュー依頼プロンプト ```markdown 以下の機能更新について、差分レビューを行ってください。 対象機能： {feature-name} 今回の変更内容： {変更内容} 参照ファイル： - docs/features/{feature-name}/current-spec.md - docs/features/{feature-name}/change-log.md - docs/features/{feature-name}/test-plan.md レビュー観点： - 現在仕様と矛盾していないか - 今回の変更対象以外を変更していないか - 既存API・既存画面・既存DBへの影響がないか - 必要なテストが追加・修正されているか - current-spec.md が最新化されているか - change-log.md に変更理由と影響範囲が残っているか - 不要なリファクタリングが混ざっていないか - Secretsや個人情報が含まれていないか 出力には以下を含めてください。 - 問題なし / 要修正 の判定 - 気になる差分 - 既存仕様への影響 - 追加で確認すべきこと - 修正提案 ``` ## まとめ 機能を安全に更新し続けるには、古い要件や設計だけに頼らず、機能単位で現在仕様と変更履歴を管理する必要があります。`current-spec.md` には現在どう動くべきかを、`change-log.md` には何をなぜ変えたかを記録します。 AIには、実装前に現在仕様、変更履歴、既存実装、既存テストを確認させ、影響範囲と変更禁止範囲を整理させます。その後、変更を小さなタスクへ分け、テスト、手動確認、文書更新、差分レビューまでを一つの更新サイクルとして扱います。 Issueの完了条件には、必要な全体ドキュメントへの同期と、同期結果・未確認事項のIssueへの記録を含めます。 最終的に仕様を決め、文書と実装の不一致を解消し、変更を採用する責任は人間にあります。現在仕様、変更理由、テスト観点を更新のたびに揃えることで、AIへ何度依頼しても、過去の前提に引きずられにくい開発運用を作れます。