> 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/28-practical-examples.md). # 28. 実践例 ## 目的 準備文書、Codexへの依頼、小さな実装、テスト固定、人間の確認を、Java、DB、フロントエンド、不具合修正の例で示します。ファイル名やコードは汎用例であり、実際には既存リポジトリの構成を調査して置き換えます。 ## 例1：Java REST APIを追加する ### 要件ファイル例 ```markdown # 要件定義 ## 背景 管理担当者が未処理の申請を確認するために、状態指定可能な一覧APIが必要である。 ## 対象ユーザー 認証済みの管理担当者。 ## 実現したいこと `status`を指定すると該当する申請を更新日時の降順で返す。 ## 実現しないこと 複数状態の同時指定、全文検索、一般利用者への公開は行わない。 ## 入力 `status`: `PENDING`または`COMPLETED`。未指定時の扱いは既存一覧仕様を維持する。 ## 出力 申請ID、状態、表示名、更新日時。 ## 完了条件 権限のある利用者が一覧を取得でき、不正な状態は既存形式の400エラーとなり、権限のない利用者は取得できない。 ``` ### 設計ファイル例 ```markdown # 設計メモ ## 全体方針 既存の一覧APIと例外形式を維持し、任意のstatus条件だけを追加する。 ## 変更対象 既存調査で確認したRequest、Service、Repository、Controller、対応テスト。 ## API設計 GET /api/requests?status=PENDING 200: 既存の一覧Response配列 400: 未定義のstatus 403: 管理権限なし ## DB設計 スキーマ変更なし。既存statusカラムを検索条件に使用する。 ## 既存仕様への影響 status未指定時のレスポンスを変更しない。 ``` ### タスク分解例 ```markdown - [ ] 既存一覧APIと権限テストを調査する - [ ] status用RequestとValidationを追加する - [ ] Repositoryへ既存命名に沿った検索を追加する - [ ] Serviceへ条件分岐を追加する - [ ] Controllerでクエリを受け取る - [ ] 正常、未指定、不正値、権限なしのテストを追加する - [ ] API仕様を更新する ``` ### Codex指示例 ``` 今回はstatus用RequestとValidationだけを実装してください。 既存の一覧API、列挙型、Validationエラー形式を調査し、同じパターンへ合わせてください。 Service、Repository、Controllerは変更しないでください。 status未指定は許可し、未定義値は既存形式の400へ変換できる状態にしてください。 対象の単体テストを実行し、変更ファイル、結果、次タスクへの前提を報告してください。 ``` 同様にRepository、Service、Controller、テスト、文書を分けて依頼します。 ### 実装後の確認観点 * `status=PENDING`と`status=COMPLETED`が正しい結果を返す * 未指定時に既存仕様が変わらない * 不正値が500ではなく既存形式の400になる * 管理権限の有無を確認する * 空配列、並び順、日時形式が契約どおりである * Entityの不要な項目や個人情報を返していない * クエリ回数と性能が既存一覧から悪化していない ## 例2：DBカラム追加を伴う機能変更 注文に内部メモ用の`note`カラムを追加する例を考えます。名称、型、長さは既存DBの規約に合わせます。 ### 要件と事前確認 * 誰が入力・閲覧できるか * NULLと空文字をどう区別するか * 最大長と文字種 * APIレスポンスへ含めるか * 既存データはNULLのままでよいか * 検索やインデックスが必要か * ログや外部画面へ出してよい情報か 内部メモに個人情報や機密情報を保存する可能性がある場合は、アクセス制御、保持期間、ログ、エクスポートも人間が判断します。 ### ALTER文の扱い Codexには、使用中のmigrationツールと既存ファイルを調査させてからmigration案を作らせます。直接DBへALTER文を実行させません。 汎用的な案は次のようになりますが、実際の型、構文、命名はDB製品と既存規約で確認します。 ```sql ALTER TABLE orders ADD COLUMN note VARCHAR(500) NULL; ``` この例をそのまま採用せず、ロック、テーブル規模、既定値、DDLトランザクション、適用時間を確認します。 ### 既存データへの影響確認 1. 対象テーブルの件数と利用状況を確認する方法を決める 2. 既存行でNULLを許容するか決める 3. バックフィルが必要ならmigrationと分ける 4. 新旧アプリケーションが共存できる展開順序を決める 5. バックアップ、監視、失敗時の停止条件を決める Codexに本番件数や既存値を推測させません。 ### 変更の分割 ``` 1. migration追加 2. Entityのmapping追加 3. Repositoryの保存・取得確認 4. Request / Response DTO追加 5. Serviceの権限と更新処理 6. APIまたは画面追加 7. Integration Test 8. API・DB・運用文書更新 ``` ### テスト観点 * 既存行を読み込める * NULL、空文字、最大長、超過時の扱い * 作成、更新、再取得で値が保持される * 権限のない利用者が閲覧・更新できない * APIに含めない設計なら漏えいしない * transaction失敗時に一部だけ更新されない * migrationを空のDBと既存相当データの両方へ適用できる ### ロールバック観点 カラム削除はデータを失うため、単純な逆ALTERだけをロールバックと考えません。 * アプリケーションを旧版へ戻しても追加カラムを無視できるか * migrationを戻す必要があるか、それとも前進修正するか * 保存済みデータの退避が必要か * 適用途中の失敗をどう検知するか * ロールバック判断者と手順が明確か ## 例3：画面表示を修正する 一覧画面へ状態ラベルを追加する例です。 ### 変更対象の確認 Codexには、画面の入口からデータ取得、表示コンポーネント、CSS、関連テストまでを先に調査させます。 * TemplateまたはComponent * API clientとResponse型 * 状態を表示する既存コンポーネント * ページ固有CSSと共通CSS * Story、Unit Test、E2E Testの有無 ### 変更の分割 1. APIに必要な項目が既にあるか確認する 2. Response型またはView Modelを必要な場合だけ変更する 3. HTMLまたはComponentへラベルを追加する 4. 既存のデザイン規則に沿ってCSSを追加する 5. 必要なJavaScriptの表示分岐を追加する 6. テストと手動表示確認を行う API項目が不足していても、フロントエンドの依頼中に契約を勝手に変更させません。バックエンド設計へ戻ります。 ### Codex指示例 ``` 一覧の各行へ、既にResponseに含まれるstatusを表示する変更だけを行ってください。 既存のBadgeコンポーネントと色の規則を再利用してください。 共通CSS、API、他画面は変更しないでください。 PENDING、COMPLETED、未知の値、データなし、APIエラーの表示を確認してください。 既存のlintとフロントエンドテストを実行し、手動確認手順も報告してください。 ``` ### 表示確認 * 長い表示名や狭い画面でも崩れない * ラベルが色だけに依存せず、文字でも識別できる * キーボード操作、読み上げ、コントラストに問題がない * ローディング、空、エラー状態が維持される * 既存の一覧操作や他画面の共通スタイルを壊していない * ブラウザのコンソールエラーがない ## 例4：不具合修正 日付境界で翌日のデータが一覧に混ざる不具合を例にします。 ### 再現条件の整理 ```markdown ## 症状 指定日の一覧に翌日0時台のデータが含まれる。 ## 再現条件 アプリケーションの基準タイムゾーンとDB保存時刻が異なる環境で、日付の終了境界付近のデータを登録する。 ## 期待結果 指定したローカル日付の開始以上、翌日の開始未満だけを返す。 ``` タイムゾーンや実際の期待境界は、人間が業務仕様として確認します。 ### 原因調査 Codexには、次を変更せずに報告させます。 * 入力日付のparse箇所 * タイムゾーンの設定元 * Serviceでの期間計算 * Repositoryの比較条件 * DBカラム型 * 既存の日付テスト ### 再現テスト 期待仕様が確定しているため、可能なら修正前に失敗するテストを追加します。 * 当日開始直前・ちょうど・直後 * 翌日開始直前・ちょうど・直後 * タイムゾーン差がある場合 * 夏時間を扱うシステムなら切り替え日 テストが修正前にも成功する場合、再現条件またはテスト対象が誤っているため、修正へ進みません。 ### 修正 原因箇所だけを最小変更し、関係ない日付処理の共通化は別タスクにします。期間条件は、通常、開始を含み終了を含まない形など、既存仕様とDBクエリに合う方式を選びます。 ### 確認 1. 再現テストが修正前に失敗したことを確認する 2. 修正後に再現テストが成功することを確認する 3. 関連する既存テストを実行する 4. 実際のAPIまたは画面で境界データを確認する 5. 他の日付検索、集計、バッチへの影響を確認する 6. 原因、修正、再発防止を文書またはPull Requestへ記録する ## 実践例に共通する人間の確認 * 要件と「今回はやらないこと」を人間が決めたか * Codexが実在する構成と既存パターンを調査したか * 変更を責務単位に分割したか * 動作と業務上の妥当性を人間が確認したか * 高リスクな振る舞いをテストで固定したか * Secretsや個人情報をコード、ログ、文書へ含めていないか * 最終差分を人間がレビューし、取り込みを承認したか --- # 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/28-practical-examples.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.