> 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/18-preparation-files.md). # 18. 開発前に準備するファイル ## 目的 Codexによる実装を始める前に、目的、設計、作業順序、確認方法、変更上の制約をリポジトリ内の文書として準備します。会話だけに情報を置くと、依頼を分割したときや後日再開したときに前提が失われます。 標準的な準備ファイルは次の5つです。 ``` docs/requirements.md docs/design.md docs/tasks.md docs/test-plan.md docs/codex-instructions.md ``` これらは文書作成自体を目的とするものではありません。人間とCodexが同じ前提で、小さな差分を安全に積み上げるための作業面です。既存プロジェクトに同等の文書や命名規則がある場合は、それを優先します。 同じ機能を継続的に更新する場合は、プロジェクト全体で一組だけを管理するのではなく、機能単位に分けて現在仕様と変更履歴を加えます。具体的な構成と運用は「[29. 機能の継続更新](/engineering-handbook/codexwoshitana/29-continuous-feature-updates.md)」を参照してください。 ## `AGENTS.md`との役割分担 `AGENTS.md`は、特定タスクの要件書ではなく、AIコーディングエージェントがリポジトリで作業するときに常に守る共通指示を記録するファイルです。ビルドやテストの実行コマンド、コード規約、変更禁止範囲、Secretsの扱い、作業後の報告方法など、複数のタスクで繰り返し使うルールを置きます。 一方、`docs/codex-instructions.md`には、今回の変更目的、変更可能な範囲、参照する要件・設計、完了条件など、タスク固有の指示を置きます。両方が存在する場合は、最初に`AGENTS.md`を確認したうえで、タスク固有の指示書を読みます。同じ内容を両方へ重複して書かず、共通ルールと個別作業の差分が分かる状態を保ちます。 `AGENTS.md`はルートだけでなく、サブディレクトリにも配置できます。サブディレクトリのファイルは、そのディレクトリ以下にだけ適用する追加・上書き指示として扱います。作業対象のファイルごとに、ルートから対象ディレクトリまでの経路にある`AGENTS.md`を確認し、より対象に近い指示を優先します。ただし、利用するAIツールの仕様によって探索範囲や優先順位が異なる可能性があるため、導入時には各ツールの公式仕様も確認します。 `AGENTS.md`を用意する場合は、次を満たすようにします。 * READMEやCI設定など、リポジトリで確認できる事実に基づいて書く * 実在し、現在利用できるコマンドを具体的に書く * README、CONTRIBUTING、ツール固有の指示ファイルとの役割を分ける * 長い設計説明を転載せず、参照先と守るべき要点を示す * ディレクトリ構成、コマンド、開発ルールが変わったときに同時に更新する * APIキー、パスワード、個人情報などの値を書かない 作成・更新をAIへ依頼するための具体的なプロンプトは、「[27. Codex依頼プロンプト集](https://livlog-llc.gitbook.io/engineering-handbook/codexwoshitana/pages/ZRGsji69cuKMtK1Y1D2p#agentsmd作成更新プロンプト)」を参照してください。 ## 規模に応じた使い分け すべての変更で5ファイルを完全に埋める必要はありません。 | 変更規模 | 推奨する準備 | | -------- | -------------------------------------------------------- | | 小規模 | `docs/codex-instructions.md`に目的、対象、完了条件、確認方法を集約する | | 中規模 | `requirements`、`design`、`tasks`、`test-plan`を分け、指示書から参照する | | 大規模・高リスク | 5ファイルを分け、調査記録、移行計画、ロールバック手順も追加する | 文言修正や限定的な不具合修正では、`docs/codex-instructions.md`だけでも構いません。複数層、DB、公開API、認証・権限にまたがる変更では、要件、設計、タスク、テスト計画を分離することを推奨します。 ## `docs/requirements.md` ### 役割 何を、なぜ、誰のために作るかを定義します。実装方法ではなく、期待する振る舞いと完了条件を中心に記録します。 ```markdown # 要件定義 ## 背景 ## 目的 ## 対象ユーザー ## 対象機能 ## 実現したいこと ## 実現しないこと ## 入力 ## 出力 ## 画面・APIの振る舞い ## 完了条件 ## 注意点 ``` ### 記述のポイント * 「一覧を改善する」ではなく、「どの利用者が、何を判断できる状態にするか」を書く * 入力、出力、正常時、エラー時を観察可能な表現にする * 既存仕様を維持する条件を書く * 今回実現しないことを明記し、Codexの過剰実装を防ぐ * 完了条件に、実装だけでなくテスト、手動確認、文書更新を含める 要件の最終決定者は人間です。Codexには文章の整理、矛盾の指摘、境界値や異常系の候補出しを依頼します。 ## `docs/design.md` ### 役割 要件を既存リポジトリへどのように組み込むかを記録します。変更対象、既存処理との関係、API、画面、DB、エラー、ログ、影響範囲を明確にします。 ```markdown # 設計メモ ## 全体方針 ## 変更対象 ## 追加するファイル ## 変更するファイル ## 変更しないファイル ## API設計 ## 画面設計 ## DB設計 ## エラーハンドリング ## ログ出力 ## 既存仕様への影響 ## 未決事項 ``` ### 記述のポイント * ファイルパスやクラス名は、リポジトリ調査後に実在を確認して書く * 変更しない範囲を明示し、関係ない共通化や置換を防ぐ * APIではメソッド、パス、Request、Response、ステータス、互換性を書く * DBでは型、NULL、既定値、制約、インデックス、移行、既存データ、ロールバックを書く * 未決事項を推測で埋めず、人間が決定するまで残す Codexに複数案と利点・欠点を提示させることはできますが、採用案は人間が決めます。 ## `docs/tasks.md` ### 役割 Codexに依頼する作業を、確認可能な小さな単位へ分割します。依存関係と実装順序を明確にし、完了状態を共有します。 ```markdown # タスク一覧 ## 調査 - [ ] 既存処理を確認する - [ ] 変更対象ファイルを特定する ## 実装 - [ ] DTOを追加する - [ ] Serviceに処理を追加する - [ ] APIエンドポイントを追加する - [ ] 画面表示を追加する ## テスト - [ ] 正常系テストを追加する - [ ] 異常系テストを追加する - [ ] 既存テストを実行する ## ドキュメント - [ ] READMEを更新する - [ ] API仕様を更新する - [ ] 変更内容を記録する ``` ### 記述のポイント * 1項目を1回の依頼または1つのレビュー可能な差分に近づける * 「バックエンドを実装する」ではなく、DTO、Service、Controllerのように責務で分ける * 各タスクに対象ファイル、前提タスク、確認コマンドを追記してもよい * 完了印は、Codexの自己申告ではなく、人間が差分と結果を確認して付ける * 仕様変更とリファクタリングを別タスクにする ## `docs/test-plan.md` ### 役割 何を確認すれば実装を採用できるかを、実装前または実装中に整理します。自動テストだけでなく、画面、API、DB、既存機能の手動確認も含めます。 ```markdown # テスト計画 ## 確認対象 ## 正常系 ## 異常系 ## 境界値 ## 権限・認証 ## DB変更の確認 ## 画面確認 ## API確認 ## 既存機能への影響確認 ## 手動確認手順 ``` ### 記述のポイント * 要件の完了条件と対応させる * 入力値、前提データ、操作、期待結果を具体化する * 金額、権限、認証、日付、DB更新、外部連携は重点項目にする * 実行環境やテストデータの準備方法を書く * 自動化しない確認にも、再現可能な手順を残す * 失敗時にデータを戻す方法や副作用の確認を書く ## `docs/codex-instructions.md` ### 役割 Codexが作業する際の入口となる指示書です。他の4文書を参照させ、変更可能範囲、禁止事項、実行する確認、最終報告を固定します。 ```markdown # Codex開発指示 ## 背景 ## 目的 ## 参照するファイル - docs/requirements.md - docs/design.md - docs/tasks.md - docs/test-plan.md ## 変更してよい範囲 ## 変更してはいけない範囲 ## 実装方針 ## コーディング方針 ## テスト方針 ## 完了条件 ## 実行してほしい確認 ## 出力してほしい内容 ## 禁止事項 - 既存仕様を勝手に変更しない - 関係ない大規模リファクタリングをしない - Secrets、APIキー、パスワードを出力しない - 推測で外部仕様を作らない ``` ### 記述のポイント * 参照ファイルを作業開始時に読むよう明記する * 編集可能なディレクトリやファイルを具体的に指定する * 生成物、依存関係、DB変更の可否を書く * 既存のコーディング規約、`AGENTS.md`、READMEなどの指示を優先させる * テストやlintの正確なコマンドは、調査で確認した実在コマンドだけを書く * 実行できない確認は、理由と未確認事項を報告させる * 最終出力に、変更ファイル、要約、確認結果、残課題を含める ## 準備手順 1. 人間が`requirements.md`の背景、目的、対象、非対象を記述する 2. Codexにリポジトリ調査を依頼し、根拠となるファイルを列挙させる 3. 調査結果を基に、人間が`design.md`の方針を承認する 4. `tasks.md`で責務ごとに作業を分ける 5. `test-plan.md`で採用判断に必要な確認を定める 6. `codex-instructions.md`で作業範囲と禁止事項を固定する 7. Codexには一度に1つまたは少数のタスクだけを依頼する ## Codexに依頼すること * 文書間の矛盾、抜け漏れ、未決事項を指摘する * 要件を変えずに、確認可能なタスクへ分解する * 既存実装に基づき、設計に必要なファイル候補を提示する * 完了条件とテスト計画の対応不足を報告する ## 人間が確認すること * 文書が実装方法を不必要に固定しすぎていないか * 要件、設計、タスク、テストが相互に対応しているか * 存在しないファイル、コマンド、サービスを推測していないか * privateリポジトリでも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/18-preparation-files.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.