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