> 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/27-prompt-templates.md). # 27. Codex依頼プロンプト集 ## 目的 この章のテンプレートは、実際のリポジトリ、要件、変更範囲、コマンドに置き換えてCodexへ渡すためのものです。`<...>`は必ず実在する内容へ置き換えます。 どの依頼でも、リポジトリ内の指示を優先し、Secretsを出力またはコミットせず、不明点を推測しないことを明記します。 ## 開発前のリポジトリ調査プロンプト ``` この段階では実装せず、既存リポジトリの調査だけを行ってください。 目的: <追加・修正したい機能の概要> 確認すること: 1. AGENTS.md、README、開発規約 2. package.json / pom.xml / build.gradle、Dockerfile、CI設定 3. DBマイグレーションと設定 4. src配下のController / Service / Repository / Entity / DTO / View 5. 関連するUnit / Integration / E2E Test 6. 命名、例外処理、ログ、Validation、テストの既存パターン 7. 想定される変更対象と、変更しない方がよい範囲 8. 実在するビルド、lint、テストコマンド 出力: - 技術構成 - 関連処理の流れ - 根拠となるファイルパス - 変更対象候補 - リスク - 未確認事項 事実、推測、提案を分けてください。環境変数やSecretsの値は表示しないでください。 ``` ## 要件整理プロンプト ``` 次の背景と要望を、docs/requirements.mdの形式で整理してください。 実装や設計はまだ行わないでください。 背景: <背景> 要望: <要望> 対象ユーザー: <利用者> 既存仕様: <維持すべき仕様> 次の観点で不足や曖昧さを質問として列挙してください: - 入力と出力 - 正常系、異常系、境界値 - 権限と認証 - 既存データと互換性 - 今回実現しないこと - 確認可能な完了条件 不明点を推測で補わず、要件案と要確認事項を分けてください。 ``` ## 設計方針作成プロンプト ``` docs/requirements.mdとリポジトリ調査結果を読み、既存実装に沿った設計案を作成してください。 まだコードは変更しないでください。 制約: - 既存仕様と公開APIの互換性を維持する - 新しい依存関係は、必要性を説明できる場合だけ候補にする - 関係ないリファクタリングを含めない - 未決事項を推測で確定しない 出力はdocs/design.mdの構成に合わせ、次を含めてください: - 推奨案と理由 - 代替案と利点・欠点 - 追加・変更・変更しないファイル - API、画面、DB、エラー、ログへの影響 - テスト方針 - 移行・ロールバック上の注意 - 未決事項 ファイル名とクラス名は、実在を確認したものだけを記載してください。 ``` ## タスク分解プロンプト ``` docs/requirements.md、docs/design.md、docs/test-plan.mdを読み、実装作業をdocs/tasks.md形式へ分解してください。 条件: - 1タスクを1つの責務またはレビュー可能な差分にする - 調査、実装、テスト、文書を分ける - DB、バックエンド、フロントエンドを必要以上に同じタスクへ混ぜない - 仕様変更とリファクタリングを分ける - 各タスクに対象ファイル、前提、完了条件、確認コマンドを付ける - 依存順に並べる コードは変更せず、過不足や未決事項も報告してください。 ``` ## 小さな実装依頼プロンプト ``` 次の1タスクだけを実装してください。 対象タスク: 参照: - docs/requirements.md - docs/design.md - docs/test-plan.md - docs/codex-instructions.md 変更してよい範囲: <ファイルまたはディレクトリ> 変更してはいけない範囲: <非対象> 完了条件: <観察可能な結果> 確認: <実在するコマンドと手動確認> 既存の類似実装、命名、例外処理、ログ、テスト方針へ合わせてください。不明点や設計変更が必要な場合は推測で進めず、理由と選択肢を報告してください。 完了後に、変更ファイル、変更内容、実行した確認と結果、未確認事項、残課題を出力してください。 ``` ## Java REST API追加プロンプト ``` Javaの既存アプリケーションへ、次のREST APIのうち<今回の対象レイヤー>だけを追加してください。 API: - Method: - Path: - Request: <項目とValidation> - Response: <項目> - Status: <正常・異常時> - 認証・権限: <条件> 今回の対象: 参照する既存実装: <実在する類似ファイル> 制約: - 既存のパッケージ、命名、DI、例外、ログ形式へ合わせる - Entityをそのまま外部レスポンスにしない - 公開APIの既存仕様を変更しない - 対象外のレイヤーを大規模に変更しない - Secretsや個人情報をログへ出さない 完了条件と確認コマンド: <条件とコマンド> 変更ファイル、API契約への対応、テスト結果、残課題を報告してください。 ``` ## DB変更を伴う実装プロンプト ``` 次のDB変更について、まず影響調査とmigration案を作成してください。承認するまで適用や本実装は行わないでください。 変更: <テーブル、カラム、型、NULL、既定値、制約、インデックス> 確認すること: - 使用しているmigration方式と命名規則 - 既存データ件数・値への影響を確認する方法 - Entity / Repository / DTO / API / 画面への影響 - 旧コードと新スキーマの展開順序 - ロック、処理時間、バックフィル - ロールバック方法と、戻せない変更 - 正常系、NULL、境界値、更新失敗のテスト 制約: - 本番データを推測しない - 破壊的ALTER、DROP、全件更新を勝手に実行しない - Secretsを表示しない - 既存データの意味を勝手に決めない 出力: - 根拠ファイル - migration案 - 適用手順 - リスク - テスト計画 - ロールバック案 - 人間が決める事項 ``` ## フロントエンド修正プロンプト ``` 次の画面変更だけを実装してください。 対象画面・コンポーネント: <実在するパス> 期待する表示と操作: <状態、入力、操作、結果> 確認する状態: - 通常 - ローディング - データなし - Validationエラー - APIエラー - 権限なし - 画面幅<必要な幅> 制約: - 既存のコンポーネント、CSS、状態管理、アクセシビリティ方針へ合わせる - API契約を勝手に変更しない - 関係ない画面や共通CSSを変更しない - 新しい依存関係を追加しない 実行するlint、test、buildと、人間が行う表示確認手順を示してください。変更ファイルと既存画面への影響も報告してください。 ``` ## テスト追加プロンプト ``` 確認済みの次の振る舞いを固定するテストを追加してください。 要件: <振る舞いと期待結果> 対象: <クラス、API、画面> 追加する観点: - 正常系: <ケース> - 異常系: <ケース> - 境界値: <ケース> - 権限・DB・外部連携: <必要なケース> 既存テストの命名、fixture、mock方針へ合わせてください。実装を追認するだけの期待値にせず、要件から期待値を定めてください。テストのためだけの不自然な本番コード変更は避けてください。 対象テストと関連する既存テストを実行し、コマンド、結果、未実行項目を報告してください。 ``` ## 不具合修正プロンプト ``` 次の不具合を調査してください。最初は原因候補と再現方法を報告し、承認するまで修正しないでください。 症状: <症状> 再現条件: <入力、データ、権限、環境、操作> 期待結果: <正しい振る舞い> 実際の結果: <誤った振る舞い> 依頼: 1. 関連処理を根拠ファイル付きで追跡する 2. 原因を特定する 3. 可能なら修正前に失敗する最小の再現テスト案を作る 4. 影響範囲と修正案を提示する 承認後は、再現テスト、最小修正、対象・既存テストの順で進めてください。関係ないリファクタリングは行わないでください。 ``` ## リファクタリングプロンプト ``` 次の範囲だけをリファクタリングしてください。 対象: <ファイルまたはクラス> 改善したい問題: <命名、重複、責務、可読性> 不変条件: - 既存仕様、公開API、DBの意味、画面の振る舞いを変えない - 新しい依存関係を追加しない - 対象外のファイルを変更しない - 仕様変更が必要なら実装せず報告する 変更前後で<テストコマンド>を実行してください。差分が大きくなる場合は、実装せず分割案を提示してください。 変更内容、改善理由、テスト結果、仕様を変えていない根拠を報告してください。 ``` ## 既存リポジトリから標準ドキュメントを生成するプロンプト ``` 既存リポジトリの内容を調査し、現在の実装・設定・運用に基づいて、開発に必要な標準ドキュメントを生成してください。 この依頼では、原則としてコードは変更せず、ドキュメント作成に必要な調査と文書生成だけを行ってください。 目的: 既存の実装内容、README、設定ファイル、API、画面、DB、テスト、運用手順を整理し、今後Codexで安全に開発を継続できるようにする。 生成・更新するドキュメント: - docs/requirements.md - docs/design.md - docs/test-plan.md - docs/codex-instructions.md - AGENTS.md - docs/api-spec.md - docs/screen-spec.md - docs/db-operations-rollback.md 調査対象: 1. AGENTS.md、README、既存docs、開発規約 2. package.json / pom.xml / build.gradle、Dockerfile、docker-compose、CI設定 3. src配下のController / Service / Repository / Entity / DTO / View / Component 4. DBマイグレーション、DDL、Entity、Repository、SQL 5. 既存テスト、テストデータ、fixture、mock 6. 環境変数、設定ファイル、外部API連携。ただしSecretsの値は表示しない 7. デプロイ、運用、ログ、障害対応、ロールバックに関係するファイル 作成方針: - 実装・設定・既存ドキュメントから確認できる事実を優先する - 推測で仕様を確定しない - 不明点は「未確認事項」「要確認事項」として分ける - 古いREADMEやコメントと現在の実装が矛盾する場合は、矛盾として明記する - 公開API、画面仕様、DB仕様、運用手順を混同しない - Secrets、パスワード、APIキー、個人情報を出力しない - ファイル名、クラス名、エンドポイント、コマンドは実在を確認したものだけを書く - ドキュメント作成のために必要な軽微なディレクトリ作成は行ってよい - コード、DBマイグレーション、依存関係、CI設定は変更しない 各ドキュメントに含める内容: 1. docs/requirements.md - システムの目的 - 対象ユーザー - 主な利用シナリオ - 機能要件 - 非機能要件 - 入力・出力 - 権限・認証 - 正常系、異常系、境界値 - 今回のドキュメント化で確認できた既存仕様 - 未確認事項 2. docs/design.md - 全体アーキテクチャ - 主要コンポーネント - Controller / Service / Repository / Entity / DTO / View の責務 - データの流れ - 外部連携 - エラー処理 - ログ方針 - 既存設計上の注意点 - 変更時に守るべき設計方針 3. docs/test-plan.md - 既存テスト構成 - テスト種別 - 実行コマンド - 主要機能ごとの確認観点 - 正常系、異常系、境界値 - DB、外部API、認証、権限の確認観点 - 手動確認が必要な項目 - テスト不足箇所 4. docs/codex-instructions.md - Codexに守らせる開発ルール - 変更してよい範囲、変更してはいけない範囲 - 実装前に読むべきファイル - 実装後に実行するコマンド - 既存パターンに合わせるべき事項 - 禁止事項 - Secrets、個人情報、外部APIキーの扱い - 人間に確認すべき判断 5. AGENTS.md - AIコーディングエージェント向けの共通指示 - Project Overview - Commands - Code Style - Testing - Git Workflow - Boundaries - Workflow - ツール固有ではなく、Codex / Cursor / Copilot などで共通利用できる内容 - AGENTS.md と docs/codex-instructions.md の役割分担 6. docs/api-spec.md - API一覧 - Method - Path - 概要 - Request parameter / Request body - Response - Status code - Validation - 認証・権限 - エラー仕様 - 関連するController / Service 7. docs/screen-spec.md - 画面一覧 - URL / route - 画面の目的 - 表示項目 - 入力項目 - 操作 - 状態別表示: 通常、ローディング、データなし、エラー、権限なし - 使用API - 関連するView / Component / Template 8. docs/db-operations-rollback.md - DB構成 - 主要テーブル - 主キー、外部キー、インデックス - 重要カラム - マイグレーション方式 - データ更新時の注意点 - バックアップ方針 - ロールバック手順 - 戻せない変更 - 本番作業前の確認事項 出力前の確認: - 生成・更新したファイル一覧を示す - 参照した主な根拠ファイルを示す - 実行したコマンドと結果を示す - 実行できなかったコマンドがあれば理由を示す - 推測で補った可能性がある箇所は明記する - 追加で人間が確認すべき事項を列挙する 作業の進め方: 1. まずリポジトリ全体を調査する 2. 既存ドキュメントと実装の差分・矛盾を整理する 3. ドキュメント構成案を作る 4. docs配下に各Markdownを生成・更新する 5. 可能であれば既存のlint、test、buildコマンドを確認する 6. 最後に変更内容、根拠、未確認事項、次に人間が確認することを報告する 不明点があっても作業を止めず、確認できる範囲で文書化してください。 ただし、仕様・運用判断・外部公開可否・本番作業手順を推測で確定しないでください。 ``` ## AGENTS.md作成・更新プロンプト `AGENTS.md` は、Codex、Cursor、GitHub Copilot など複数のAIコーディングエージェントが参照できる、リポジトリ共通の作業指示ファイルです。人間向けのREADMEを置き換えるものではなく、AIに守らせたい技術的な前提、実行コマンド、禁止事項、作業手順を簡潔にまとめます。 導入時は、ツール固有の機能や内部コマンドを書きすぎず、共通指示は `AGENTS.md` に集約します。Claude Code、Cursor、GitHub Copilot などの専用ファイルと併用する場合は、専用ファイル側にはそのツールでしか使えない指示だけを残します。 ``` 既存リポジトリを調査し、AIコーディングエージェント向けの共通指示ファイルとして、ルートのAGENTS.mdを作成または更新してください。 この依頼では、原則としてコードは変更せず、AGENTS.mdの作成・更新と、必要に応じた既存AI指示ファイルとの差分整理だけを行ってください。 目的: Codex、Cursor、GitHub Copilotなど複数のAIコーディングエージェントが、同じ開発ルール・コマンド・禁止事項を参照できるようにする。 調査対象: 1. README、既存docs、開発規約 2. リポジトリの親ディレクトリ、ルート、サブディレクトリにある既存のAGENTS.md 3. CLAUDE.md、.cursorrules、.cursor/rules、.github/copilot-instructions.md 4. package.json / pom.xml / build.gradle、Dockerfile、docker-compose、CI設定 5. src配下の主要構成、Controller / Service / Repository / Entity / DTO / View / Component 6. 既存テスト、lint、build、typecheck、formatコマンド 7. DBマイグレーション、DDL、Entity、Repository、SQL 8. 環境変数、外部API、Secretsの扱い。ただし値は表示しない 作成するAGENTS.mdの推奨構成: # AGENTS.md ## Project Overview - プロジェクトの目的 - 技術スタック - 主要な実行環境 - 主要ディレクトリ ## Commands - 依存関係のインストール - 開発サーバー起動 - lint - format - typecheck - test - build - DB migration確認 ## Code Style - 命名規則 - ディレクトリ構成 - レイヤーごとの責務 - 既存コードに合わせるべき実装パターン ## Testing - テストフレームワーク - テスト配置 - mock / fixture方針 - 実装後に実行すべき確認 - 手動確認が必要な項目 ## Git Workflow - ブランチ名 - コミットメッセージ - PR前の確認 - ドキュメント更新の扱い ## Boundaries - 変更してはいけないファイル - `.env*`、Secrets、APIキー、個人情報の扱い - 本番設定、DBマイグレーション、外部連携への注意 - 大規模リファクタリングや依存追加を勝手に行わないこと ## Workflow - 作業前に読むべきファイル - 変更前の調査 - 実装後の確認 - 不明点がある場合の扱い - 人間に確認すべき判断 作成方針: - 事実に基づいて簡潔に書く - ツール固有の機能はAGENTS.mdに書かない - 重要な指示を5から10個程度に絞り、長くなりすぎないようにする - コマンドは「テストを実行する」ではなく、実在するコマンドを具体的に書く - READMEの説明を丸ごと転記せず、AIが作業時に必要な指示へ要約する - 既存のCLAUDE.md、Cursor、Copilot向け指示と矛盾しないようにする - 矛盾がある場合は勝手に統合せず、矛盾点として報告する - 複数のAGENTS.mdがある場合は、各ファイルが適用されるディレクトリ範囲と、より対象に近い指示が優先されることを明記する - 親ディレクトリのAGENTS.mdはリポジトリ外にある場合も含めて確認し、勝手に変更しない - Secrets、パスワード、APIキー、個人情報は出力しない - 古い情報や未確認のコマンドは「要確認」として分ける 既存ファイルとの役割分担: - README: 人間向けの概要、導入、利用方法 - AGENTS.md: AIエージェント向けの共通作業指示 - docs/codex-instructions.md: Codexで開発を継続するための詳細ルール - CLAUDE.mdなど: 各ツール固有の機能や挙動だけ 出力前の確認: - 作成・更新したファイルを示す - AGENTS.mdに反映した根拠ファイルを示す - 既存AI指示ファイルとの重複・矛盾を示す - 実行可能と判断したコマンドと、未確認のコマンドを分ける - Secretsや個人情報を含めていないことを確認する - 人間が追加確認すべき事項を列挙する 不明点があっても作業を止めず、確認できる範囲でAGENTS.mdを作成・更新してください。 ただし、ツール対応状況、運用判断、本番作業、Secretsの扱いを推測で確定しないでください。 ``` ## ドキュメント更新プロンプト ``` 現在の実装差分を確認し、必要なドキュメント更新を行ってください。 対象候補: - README - docs/requirements.md - docs/design.md - docs/tasks.md - docs/test-plan.md - API仕様 - 画面仕様 - DB・運用・ロールバック手順 条件: - 既存の構成と文体へ合わせる - 実装から確認できる事実だけを書く - 外部仕様や運用判断を推測しない - コマンド、リンク、ファイル名を検証する - Secrets、実在の個人情報を含めない 変更した文書、実装差分との対応、要確認事項を報告してください。 ``` ## レビュー依頼プロンプト ``` 実装は変更せず、現在の差分をレビューしてください。 docs/requirements.md、docs/design.md、docs/test-plan.mdとリポジトリ内の規約を基準にしてください。 観点: - 要件を満たしているか - 既存仕様と公開APIを壊していないか - 変更範囲が適切か - 命名、例外、ログが既存ルールに合うか - 認証、権限、Validation、DB更新が安全か - テストが不足または誤った期待値になっていないか - 文書が更新されているか - Secretsや個人情報が含まれていないか - 不要な抽象化や大規模リファクタリングがないか 指摘は重大度順に、根拠ファイル、発生条件、影響、推奨対応を示してください。問題が見つからない場合も、残るリスクと未確認事項を報告してください。 ``` 同じ機能を繰り返し更新する場合の影響調査、現在仕様の更新、変更履歴の追記に使うプロンプトは「[29. 機能の継続更新](/engineering-handbook/codexwoshitana/29-continuous-feature-updates.md)」にまとめています。 ## 人間が確認すること * `<...>`を具体的な事実へ置き換えたか * 変更可能範囲と禁止範囲が明確か * 完了条件と確認方法が観察可能か * 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/27-prompt-templates.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.