はじめに
- AIが賢くなり、多くの実装タスクをそのままこなせるようになってきました。すでに能力は人間を超えています。
- 一方で、AIに「何を、どう指示するか」（プロンプトやinstructionsの設計）は、依然として人が手作業で組み上げる領域でした。
- 今回はその一歩先、AIへの指示書そのものをAIに書かせる を行った結果を記事にします。
- 対象は実装フェーズ（UT含む）。いわば「AIの、AIによる、人間のためのAI駆動開発」です。
用語メモ: 本記事では「実装」という言葉が2つの意味で登場します。混同しやすいので先に整理しておきます。
- コード実装 — AIに書かせる Java コードなど、AI駆動開発の最終成果物。
- AI指示資産の構築 — prompts / instructions ファイル一式の整備。今回AIに設計・構築してもらった対象。
以下、区別が必要な場面では「コード実装」「AI指示資産」と書き分けます。
やったこと
- 実装フェーズのプロンプト類設計を、AIと壁打ちしながらmarkdown設計書として作成。
- 要件や方針を言葉で与え、具体的なファイル構成・ファイル内容はAIに考えてもらった上で、そのまま prompts / instructions ファイルの構築まで依頼。
- 開発者向け・運用者向けのユーザガイドドキュメントもAIが作成。
- 生成処理の計画書と結果レポートもAIが出力する運用にした。
- その他細かい指示は実際の設計書を確認してみて。
こだわった設計ポイント
- コード実装の結果から設計書・プロンプトにフィードバックするプロセス を組み込んだ（作りっぱなしにしない）。
- コード実装をひと塊で任せず、手順を分割（事前準備 → 仕様確認 → 実装 → 単体テスト → 品質確認 → 全体見直し）。
- 汎用部分とカスタマイズ部分をファイルで分離し、プロジェクト固有の追記をしやすくした。
- 要件・方針だけ先に書いて、ファイル構成や内容はAIに考えさせる流れ（人が細部まで決め打ちしない）。
Before / After
| 観点 | Before | After |
|---|---|---|
| プロンプト設計 | 人が毎回手で書く | 要件・方針を書けばAIが設計書＋ファイル一式を生成 |
| 拡張・改善 | 気づくたびに個別ルールを追記 | フィードバックプロセスで設計書ごと更新、実装にも反映 |
| 新案件への流用 | 案件ごとに書き直し | 汎用ルールは固定、カスタマイズ部分だけ差し替え |
| AIへの細かな指示 | 人が分割・指示出し | 手順分割・TODO解消・観点ID付与まで指示書側で標準化 |
効果と学び
良かったこと
- 非常に汎用性が高い運用ができるようになった。AIに任せることで、高い保守性を得られた。
- プロンプト類の設計書自体をAIに修正させ、そこから prompts / instructions ファイルへの反映まで任せられる。
- 「こういうプロセスを作りたい／追加したい」と伝えれば、設計書の更新と AI指示資産の反映をまとめて行ってくれる。
- 基本的なプロセスから書いてあるので、「フロントエンド特化で」などと指示するだけで他領域にも展開可能。
感想
- やりたいことをmdにAIと壁打ちしながら作成し、それを基にコード実装してもらう、というフローが定着してきた。
- 設計書を公開すれば、動くものが共有できる時代になった。もはやコードは関係ない。設計書からコード実装へのコンパイルをAIが行ってくれる。
- AIで「いろいろできるようになった」からこそ、それを統制するルールや方針の設計 が重要になってきたと感じる。
- 「AIで生成できてよかった」で終わりではなく、その先のより高い品質が求められる時代に入った。
- skillも使うのかと思いきや、AI本人は
skillよりもinstructionsを好むようだった（「instructionsで十分」とのこと）。 - 逆に記述された、
instructionsなどから設計書にフィードバックすることもできます。 - 今回は実装フェーズのみを話題にしましたが、その他のフェーズでも応用してみてください。
使い方
- 今回の設計書で、実装フェーズの方針と工程を書いたところから、「ファイル構成と内容の具体的な設計をして」と依頼すれば、設計書の後半（AI指示資産のファイル構成）はほぼ生成しなおせます。AI指示体系を大きく作り変えたい場合に。
- コード実装や単体テストを進める中で気づきがあれば、promptファイルやinstructionsに追記してルールを拡充させてください。AIは追加されたものも加味しながら保守してくれます。
- 全体的な方針変更は、目的と方針に追記した上で、設計書の更新とファイルの修正を行えばOKです。
- GitHub Copilot用に書きましたが、Claude Codeでも簡単に書き直せると思います。
実際の設計書
- 下記で基盤ができあがるので、実際のプロジェクトに合わせてファイルをカスタマイズしていけばうまくいきます。
# 実装フェーズ AI指示 設計
## 目的と方針
- 本書は、AIに実装を依頼するため、指示の書き方の設計ドキュメントです。
- github copilotで実装を行います。skill、instruction、promptなどなど、構成で実装するための設計です。
- メンテナンス性が高い構造、構成が望ましいです。
- AIへの指示は、汎用的な部分と、カスタマイズ部分を分けられることが望ましいです。
- ファイルで分けられる構造にすることが望ましいです。
- ライブラリやフレームワークによってカスタマイズしやすい構造にすることが望ましいです。
- 汎用的な部分には、一般的なことのみを記載し、カスタマイズ部分には、プロジェクト固有のことを記載することが望ましいです。
- 今後、実装以外のフェーズ、テストや設計なども加味した構成にすることが望ましいです。
- 可能な限り、構成はシンプルであることが望ましいです。
- AIに指示を出すため、細かい単位で、指示とその結果の確認を行うことが望ましいです。
- 実装フェーズでは、実装着手前にテストケースを先に作成し、受入観点を先に確定させる方針とします。
- テストケースは、コメント等で観点IDや目的などを付与し、観点の追跡やレビューを容易にすることが望ましいです。
- 実装が修正された場合も、このファイルを最新に保ち、実装と指示の乖離がないようにすることが望ましいです。
---
## 実装フェーズでAIが行うタスク一覧
### 実施順序（指定）
1. 事前準備
2. 仕様確認（テスト観点・受入条件の確定）
3. 実装
4. 単体テスト（テストケース作成・テストコード実装・実行）
5. 品質確認
6. 全体見直し（機能単位、ユーザー判断で発動）
### 1. 事前準備
1. 設計書、仕様書の場所の確認
2. 既存コードの場所の確認
3. 実装機能の確認（スコープ）
### 2. 仕様確認（テスト観点・受入条件の確定）
1. 対象機能の仕様確認
API定義、画面設計書、DBスキーマから仕様を確認
2. テスト観点の洗い出し
正常系、異常系、境界値、0件/NULL/空文字などの観点で作成、処理の記述を確認して観点を追加する
3. 受入条件の確定
4. 全体でのテスト観点の抜け漏れ確認
### 3. 実装
1. クラス、ファイル構成
2. メソッド構成、ファイル内容の構成
3. クラス、ファイル間の関係の調整と確認
4. メソッドの実装
5. 例外処理の実装
6. メソッドコメントの実装
7. 共通部品の検討
8. 定数定義の実装
9. 権限制御の実装
10. ログ出力の実装
11. 既存コードとの整合性の確認
12. 全体の整合性の確認
13. セキュリティ観点の確認
14. 静的解析結果の確認（警告・重大度）
15. 命名規約・コーディング規約準拠の確認
### 4. 単体テスト（テストケース作成・テストコード実装・実行）
1. テストケースの作成（仕様確認で確定した観点 + 実装コードの分岐を反映）
2. テストデータの作成
3. テストクラス、テストファイルの作成
4. テスト構成の実装（モック、スタブ、テストダブルの設定）
5. テストの実装
6. テストの実行
7. テスト結果の確認
### 5. 品質確認
1. テスト結果の確認（全件/対象）
2. **関連テスト全件実行（リグレッション防止）** — 変更ファイルを `import` している既存クラスのテストを全件実行し、変更によって既存機能が壊れていないか確認
3. **受入確認チェックリストの確認** — タスクプランに記載された実装側の観点（仕様準拠/権限/例外/ログ/テスト/コード品質）を人がレビューで確認
4. 全体での品質観点の抜け漏れ確認
5. レポートの作成
### 6. 全体見直し（機能単位）
機能を構成する複数タスクの実装が完了した段階で、タスク単位の品質確認では見つからない **機能全体の不整合** と **AI指示資産（instructions/prompts）の肥大化** を総合的にチェックする。発動は **ユーザー判断**（機能完成時が基本、マイルストーン前の総点検でも可）。
1. **コード横断レビュー** — Controller/Service/Mapper 間の一貫性、アンチパターン横断照合、重複・共通化機会、観点IDカバー率マトリクス、ドキュメント整合
2. **AI指示資産メンテナンス** — 重複検出と **方針格上げ**（3箇所以上で繰り返される記述は `common` / `copilot-instructions` へ）、**陳腐化・不要セクションの削除**、**肥大化の検出**（1ファイル150行超を目安）、未使用・孤立 prompt の洗い出し、新規追加候補の検討（既存で対応可能か必ず先にチェック）
3. **修正提案と UI選択による適用** — 提案は `案 A/B/C` 形式で優先度★付き、ユーザーが Copilot Chat で選択して適用
4. **総合レポート** — `_log/{YYYY-MM-DD}_機能見直し_{機能名}.md` に記録
### タスク ↔ instructions / prompt 対応表
| タスク | 適用 instructions | 使用 prompt |
|---|---|---|
| 1. 事前準備 | `common` | `coding-create-task-plan` |
| 2. 仕様確認 - 仕様把握 | `common` | `coding-clarify-requirements` |
| 2. 仕様確認 - テスト観点洗い出し | `unittest-common`, `unittest-test-{controller,service,mapper}` | `unittest-create-test-cases` |
| 3. 実装 - クラス/メソッド構成 | `common`, `coding-java-spring` | `coding-implement-from-tests` |
| 3. 実装 - API実装 | `coding-java-spring`, `coding-api-openapi` | `coding-implement-from-tests` |
| 3. 実装 - DB/SQL実装 | `coding-database-mybatis` | `coding-implement-from-tests` |
| 3. 実装 - 権限/セキュリティ | `coding-java-spring`, `quality-security-check` | — |
| 3. 実装 - 不明点（TODO）解消 | `common`, `coding-java-spring` | `coding-resolve-todos` |
| 4. 単体テスト - テストケース作成 | `unittest-common`, `unittest-test-{controller,service,mapper}` | `unittest-implement-tests` |
| 4. 単体テスト - テストデータ作成 | `unittest-testdata-sql` | `unittest-generate-testdata-sql` |
| 4. 単体テスト - テスト実装・実行 | `unittest-common`, `unittest-test-*` | `unittest-implement-tests` |
| 5. 品質確認 | `quality-gate`, `quality-static-analysis`, `quality-security-check` | `coding-run-quality-check` |
| 6. 全体見直し | `common`, `quality-gate`, `project-antipatterns`（整備後） | `review-feature` |
---
## GitHub Copilot 構成（実装フェーズ向け）
### 1. 構成方針
- 汎用ルール（全案件共通）と、プロジェクト固有ルールを分離する。
- 実装フェーズでは「仕様確認先行」を標準フローとする。
- 仕様確認でテスト観点・受入条件を確定し、実装後にテストコードを作成する。
- 指示の責務を分け、変更時の影響範囲を最小化する。
- 1ファイル1責務とし、長文化しすぎない。
- テストの実記述ルールは、テスト専用instructionsに集約する（実装系instructionsには詳細を書きすぎない）。
- **instructions と prompt の責務境界**:
- **instructions** = 「常に適用されるルール」。applyTo で対象ファイルに自動適用される。観点・規約・制約を記載する。
- **prompt** = 「手動で呼び出す手順書」。入力・出力・実行ステップを記載する。prompt 内では instructions のルールを重複記載せず、「instructions に従う」と参照する。
- **templates** = 「出力フォーマットの雛形」。prompt から参照され、成果物の構造を統一する。
### 2. ディレクトリ構成
```text
.github/
copilot-instructions.md # 全体方針（最上位）
instructions/ # ※ GitHub Copilot は直下ファイルのみを対象とするため、サブディレクトリは使わず「フェーズ名-内容」の prefix で分類する
common.instructions.md # 汎用ルール（実装全般）
ScreenDesign.instructions.md # 画面設計ルール
coding-java-spring.instructions.md # Java/Spring実装ルール
coding-api-openapi.instructions.md # API/OpenAPI実装ルール
coding-database-mybatis.instructions.md # MyBatis/SQLルール
coding-database.instructions.md # DB実装ルール
unittest-common.instructions.md # テスト共通ルール（フレームワーク+実記述統合）
unittest-test-controller.instructions.md # Controller単体テストルール（+ テストケース観点）
unittest-test-service.instructions.md # Service単体テストルール（+ テストケース観点）
unittest-test-mapper.instructions.md # Mapper/DBテストルール（+ テストケース観点）
unittest-testdata-sql.instructions.md # テストデータSQLルール
quality-gate.instructions.md # 品質確認ルール
quality-static-analysis.instructions.md # 静的解析ルール
quality-security-check.instructions.md # セキュリティ簡易チェック
prompts/ # ※ スラッシュコマンドとして確実に登録するため、サブディレクトリは使わず prefix で分類する
coding-create-task-plan.prompt.md # タスクプラン作成
coding-clarify-requirements.prompt.md # 仕様確認レポート生成（フェーズ2 先頭）
coding-implement-from-tests.prompt.md # テストケースに基づく実装
coding-resolve-todos.prompt.md # 実装内の不明点（TODO）解消（修正案を複数提示・選択）
coding-run-quality-check.prompt.md # 品質確認
unittest-create-test-cases.prompt.md # テスト観点洗い出し（レイヤ固有観点は instructions で自動適用）
unittest-implement-tests.prompt.md # テストコード実装・実行
unittest-generate-testdata-sql.prompt.md # テストデータSQL作成
review-feature.prompt.md # 機能単位の全体見直し（コード + AI指示資産メンテ）
templates-coding-quality-report-template.prompt.md # 品質確認レポートテンプレート
templates-unittest-testcase-template.prompt.md # テストケーステンプレート
_tasks/
2026-04-17_実装指示.md # 本設計ドキュメント
docs/
ai-usage-guide.md # 使い方ガイド（開発者向け）
ai-maintenance-guide.md # メンテナンスガイド（管理者向け）
```
**命名規約（prefix方式）:**
- `{フェーズ}-{内容}.instructions.md` / `{フェーズ}-{内容}.prompt.md` の形式で命名する。
- フェーズ prefix: `coding-`（実装）、`unittest-`（単体テスト）、`quality-`（品質確認）、`review-`（全体見直し）、`templates-{フェーズ}-`（テンプレート）。
- 汎用ルールは prefix を付けず、内容名のみ（例: `common`）で配置する。
- 数字連番は付けない。順序・重要度はファイル名でなく、本ドキュメントのタスク↔instructions対応表・applyTo定義で表現する。
- サブディレクトリを使わない理由: GitHub Copilot の prompt ファイルはスラッシュコマンドとして登録される際、`.github/prompts/` 直下のみが確実に認識される（サブディレクトリ内はセマンティック検索の補助止まり）。instructions 側はサブディレクトリが再帰的にスキャンされるが、prompts と運用を揃えるため同じ prefix 方式に統一する。
### 3. 各ファイルの責務
#### 3.1 `.github/copilot-instructions.md`
- 最上位ルールのみ記載する。
- 日本語で記述する
- JavaDocを必須とする
- 実装前に仕様確認としてテスト観点を確定する
- 実装後にテストコードを作成する
- 不明点は推測実装しない
#### 3.2 `.github/instructions/common.instructions.md`
- 実装フェーズ共通の進め方を記載する。
- 実施順序（事前準備 → 仕様確認 → 実装 → 単体テスト → 品質確認）
- 変更は最小差分
- 影響範囲の明示
#### 3.3 `.github/instructions/coding-java-spring.instructions.md`
- Java 21 / Spring の実装規約を記載する。
- クラス構成、命名、例外設計、ログ方針
- テストに関する記述はしない（テスト用は `unittest-common.instructions.md` へ分離）
#### 3.4 `.github/instructions/coding-api-openapi.instructions.md`
- OpenAPI準拠の実装ルールを記載する。
- API仕様差分の扱い
- DTO/レスポンス整合
#### 3.5 `.github/instructions/coding-database-mybatis.instructions.md`
- MyBatis/SQL実装ルールを記載する。
- スキーマ変数利用
- 動的SQL
- DB実装観点（テスト詳細は `unittest-*` へ分離）
#### 3.6 `.github/instructions/unittest-common.instructions.md`（統合ファイル）
単体テスト共通のフレームワーク設定と実記述ルールを統合。旧 `unittest-java-spring` + `unittest-test-common` の統合版（applyTo が同一で常時重複 apply されていたため）。
- フレームワーク（JUnit 5 / Mockito / assertj）
- テストクラスの基本構成（`@ExtendWith(MockitoExtension.class)`、命名、標準import）
- テストメソッド構造・日付の扱い
- テスト観点（正常/異常/境界/NULL/空文字/権限）
- Mockito 方針・検証方針
- 観点IDとの対応付け（必須）
- コメント記述ルール（JavaDoc、Arrange/Act/Assert）
#### 3.7 `.github/instructions/unittest-test-controller.instructions.md`
- Controller 単体テストのレイヤ固有ルール。
- Service モック化、Web 呼び出し非使用、`TestControllerUtil` 活用
- 権限制御検証時の AccessInfo 方針
- **テストケース作成観点**（正常系 / 引数マッピング / 権限チェック / 異常系）— `unittest-create-test-cases` から自動参照される
#### 3.8 `.github/instructions/unittest-test-service.instructions.md`
- Service 単体テストのレイヤ固有ルール。
- Dao/Mapper モック化
- 例外分岐、業務分岐の検証
- **テストケース作成観点**（正常系 / 業務分岐 / Mapper呼び出し検証 / 例外パターン / NULL・空データ）
#### 3.9 `.github/instructions/unittest-test-mapper.instructions.md`
- Mapper/DB テストのレイヤ固有ルール。
- `@MybatisTest` 利用、実 DB 接続テスト
- **テストケース作成観点**（CRUD / WHERE条件 / 境界値 / ORDER BY / ページング / JOIN）
#### 3.10 `.github/instructions/unittest-testdata-sql.instructions.md`
- テストデータSQL作成ルールを記載する。
- SQL配置先
- 命名規約
- テスト観点との対応付け
#### 3.11 テスト記述の配置ルール
- テスト観点、テストケース構成、Mockito利用、期待値検証などの「実記述ルール」は `unittest-common.instructions.md` に集約する。
- DBアクセスを伴うテスト（Mapper/SQL検証）の固有ルールは `unittest-test-mapper.instructions.md` に記載する。
- `coding-java-spring.instructions.md`（実装用）にはテスト記述をしない。テスト用は `unittest-common.instructions.md` に分離する。
- 同一ルールを複数ファイルに重複記載しない（参照リンクで接続する）。
- レイヤ固有テストケース観点は `unittest-test-{controller,service,mapper}.instructions.md` の「テストケース作成観点」セクションに集約する（`unittest-create-test-cases` プロンプトから自動参照される）。
#### 3.11.1 観点IDトレーサビリティ（レビュー効率化）
AI生成テストを後から人がレビューする際、「どの観点がどのテストでカバーされているか」を即座に追跡できるよう、テストケース一覧とテストコードを **観点ID** で紐付ける。
- **観点IDの形式**: `TC{3桁連番}`（例: `TC001`）。対象クラス単位でユニークに採番する。
- **採番タイミング**: `unittest-create-test-cases` 等でテストケース一覧を作成する時点で採番する。
- **テンプレート**: `templates-unittest-testcase-template.prompt.md` の観点一覧テーブル1列目が観点ID。
- **テストコードへの反映**:
- テストメソッド名: `test{対象メソッド名}_TC{NNN}_{条件}`（例: `testGetRisks_TC001_全件取得`）
- JavaDoc 先頭行: `観点ID: TC{NNN}` を必ず記載
- 複数観点をまとめる場合はカンマ区切り（例: `観点ID: TC002, TC003`）
- **採番の維持**: 一度採番した観点IDは変更しない。ケース追加は末尾連番、削除は欠番のまま残す（テストコードからの参照整合を保つため）。
- **記述ルール本体**: `unittest-common.instructions.md` の「観点IDとの対応付け」セクションを参照。
#### 3.11.2 受入確認チェックリスト（実装側のカバー観点）
観点ID（テスト側）は「何を検証したか」を追跡するのに対し、受入確認チェックリスト（実装側）は「何を実装としてカバーしたか」を追跡する。両者がペアになってレビューの網羅性を担保する。
- **格納場所**: `_tasks/{TASK_ID}_{日付}_{機能名}.md` の「受入確認チェックリスト」セクション
- **生成タイミング**: `coding-create-task-plan` がタスクプラン生成時にベースラインを埋め込む
- **項目カテゴリ**: 仕様準拠 / 権限・セキュリティ / エラー・例外処理 / ログ出力 / テスト / コード品質 / プロジェクト固有
- **確認タイミング**: 品質確認フェーズ（`coding-run-quality-check`）で人がレビューして確認 → 品質ゲートの合格条件にも含まれる
- **拡張方法**: プロジェクト固有項目はタスクごとに追加する（例: 特定画面の表示条件、特殊な権限パターン等）
- **未該当項目**: 対象外の項目は `N/A` と記載する（削除しない。対象外であることを明示するため）
#### 3.11.3 関連テスト全件実行（リグレッション防止）
変更が既存機能を壊していないか、品質確認フェーズで確認する。
- **対象特定方法**: 変更ファイル（クラス・DTO・共通部品）を `import` している既存クラスを grep で洗い出し、それらのテストクラスを抽出
- **実行タイミング**: `coding-run-quality-check` 実行時。ステップ2「影響範囲の特定」→ ステップ4「関連テスト全件実行」として明示的に実施
- **広範囲変更時**: 共通クラス（DTO、定数、Util）変更時は影響範囲が広いため、原則 `./gradlew test` で全テスト実行
- **判断基準**: 判断に迷う場合は広めに実行する（時間よりリグレッション検出を優先）
- **ルール本体**: `quality-gate.instructions.md` の「影響範囲の特定方法」セクションを参照。
#### 3.12 `.github/instructions/quality-gate.instructions.md`
- 品質確認の合格条件を記載する。
- コンパイル成功
- 対象テスト成功
- **関連テスト（影響範囲）全件成功**（リグレッション防止）
- 重大警告0
- 変更サマリ作成
- **受入確認チェックリスト全項目確認済み**
- 影響範囲の特定方法（grep による import 逆引き、共通クラス変更時の全件実行）を定義する。
#### 3.13 `.github/instructions/quality-static-analysis.instructions.md`
- 静的解析の確認ルールを記載する。
- SpotBugs等の重大度基準
- 警告対応方針
#### 3.14 `.github/instructions/quality-security-check.instructions.md`
- セキュリティ簡易チェックルールを記載する。
- 入力値検証
- 例外情報の露出防止
- ログ出力の秘匿情報確認
#### 3.15 `.github/prompts/templates-unittest-testcase-template.prompt.md`
- テストケース一覧の出力フォーマット。
- 観点ID（`TC{3桁連番}`）、観点、テストケース、入力値、期待結果、備考の構造を定義する。
- 観点IDはテストコード側（テストメソッド名・JavaDoc）と必ず対応させる（詳細は 3.11.1 参照）。
#### 3.16 `.github/prompts/templates-coding-quality-report-template.prompt.md`
- 品質確認レポートの出力フォーマット。
- 合否、テスト結果概要、課題一覧、TODO一覧、次アクションの構造を定義する。
#### 3.17 `.github/prompts/coding-resolve-todos.prompt.md`
実装コード内に残った `// TODO: [要確認]` を解消する対話型プロンプト。AIが自動で決定せず、**修正案を複数提示して人が UI で選択する**形式とする。
- **入力**: 対象ファイル（未指定時は直近変更ファイル全体を自動スキャン）
- **動作**:
1. `// TODO: [要確認]` を検出し、番号付き一覧化（TODO#1, TODO#2, …）
2. 各TODOについて OAS / DBスキーマ / 画面設計書 / 既存パターンを根拠に **修正案 2〜3件** を作成
3. 各案に **概要・実装内容・想定動作・根拠・トレードオフ・推奨度（★1〜3）** を付けて提示
4. ユーザーは `TODO#1: A` / `TODO#1: skip` / `TODO#1: 独自案` の形式で選択
5. 選択された案を適用し、TODO コメントを削除
6. 関連テストへの影響・残存TODO・仕様確認事項をサマリ出力
- **UI選択**: Copilot Chat 内で番号・ラベルで回答できる形式で提示する
- **決定の原則**: 根拠が明確でも AI が単独で採用しない。必ず人の選択を挟む
- **テストへの影響報告**: 期待値・分岐が変わる場合は `unittest-implement-tests` 再実行を促す
#### 3.18 `.github/prompts/review-feature.prompt.md`
機能単位の全体見直しプロンプト。**コード横断レビュー** と **AI指示資産(instructions/prompts)のメンテナンス** を同時に実施する。
- **位置づけ**: 新フェーズ「6. 全体見直し」に対応する。タスク単位の `coding-run-quality-check` とは別物で、複数タスクが完了して **1機能が完成** した段階で発動する
- **発動**: ユーザー判断（機能完成時が基本、マイルストーン前の総点検でも可）
- **入力**: 対象機能、関連タスクID一覧、スコープ指定（`full` / `code` / `artifacts`）
- **動作**:
- **Section A（コード見直し）**: 一貫性、アンチパターン横断、重複・共通化、観点IDカバー率マトリクス、受入条件統合確認、ドキュメント整合
- **Section B（AI指示資産メンテナンス）**:
- 重複検出 → **3箇所以上で繰り返される記述は `common` / `copilot-instructions` への方針格上げを提案**
- 陳腐化・不要セクションの削除提案（必ず理由付き）
- **肥大化の検出**（1ファイル150行超を目安）→ 責務分割 or 冗長削減を提案
- 未使用・孤立 prompt の削除候補抽出
- 新規追加候補は既存で対応可能か必ず検証の上で提案
- 本 prompt 自身のメンテナンスも対象
- **Section C（レポート）**: `_log/{YYYY-MM-DD}_機能見直し_{機能名}.md` に出力
- **Section D（適用）**: UI選択で採用案を決定 → 自動適用 → 変更差分と次回引き継ぎ観点を報告
- **重要原則**:
- 単純追加を避ける（必ず既存で対応可能か先にチェック）
- 削除・格上げは勝手に実施せず、必ずユーザー選択を挟む
- 全提案に優先度（★1〜3）を付与
#### 3.19 `.github/prompts/coding-clarify-requirements.prompt.md`
フェーズ2（仕様確認）の先頭で使用する仕様確認プロンプト。タスクプラン作成後、テスト観点洗い出し前に、対象機能の **仕様を詳細把握** して **仕様確認レポート** を成果物として残す。
- **位置づけ**: フェーズ2の第1ステップ（「対象機能の仕様確認」）の実行者
- **入力**: タスクID（`_tasks/` 配下ファイル指定）、追加情報（任意）
- **動作**:
1. タスクプランを読み込み、対象機能・対象レイヤ・受入条件を把握
2. API 仕様（OAS）、画面設計書、DB スキーマの **詳細** を抽出・突合
3. 既存コードの類似パターンを探索
4. 情報源間の矛盾・不足を **要確認事項** として優先度付きで列挙
5. 調査結果をもとに受入条件をリファインメント
- **出力**: タスクプラン末尾に追記する **仕様確認レポート**（API仕様詳細表・画面仕様詳細・DBスキーマ詳細・既存パターン・要確認事項・リファイン後の受入条件）
- **原則**:
- コードは書かない（仕様確認のみ）
- 不明点は勝手に決定せず「要確認事項」として残す
- 情報源の不足箇所と問い合わせ先の想定を明示
> **補足**: タスク入力の構造は `coding-create-task-plan.prompt.md` にインラインで定義し、独立したテンプレートファイルは設けない（ファイル数を最小化するため）。
### 4. プロンプト運用
フェーズ順に並べる（1機能の標準フロー）。
1. `coding-create-task-plan.prompt.md`
- 入力: 対象機能、対象レイヤ、優先度
- 出力: タスクプラン（`_tasks/{TASK_ID}_*.md`、受入条件・受入確認チェックリスト含む）
2. `coding-clarify-requirements.prompt.md` ★**新規**
- 入力: タスクID、追加情報（任意）
- 出力: タスクプランに追記する **仕様確認レポート**（API仕様詳細・画面仕様詳細・DBスキーマ詳細・既存パターン・要確認事項・リファイン後の受入条件）
3. `unittest-create-test-cases.prompt.md`
- 入力: タスクID、対象機能、対象レイヤ、受入条件、関連ファイル
- 出力: レイヤ別テスト観点一覧（観点ID付き）— コードは書かない
- レイヤ固有観点は `unittest-test-{controller,service,mapper}.instructions.md` が自動適用される
4. `coding-implement-from-tests.prompt.md`
- 入力: テスト観点一覧、対象ファイル
- 出力: 実装差分案（Controller/Service/Mapper）
5. `coding-resolve-todos.prompt.md`
- 入力: 対象ファイル（実装済みで `// TODO: [要確認]` を含む）
- 出力: TODO一覧、各TODOごとに修正案2〜3件（推奨度付き）、ユーザー選択後の変更差分、残存TODO・仕様確認事項サマリ
- 特徴: ユーザーは UI（Copilot Chat）で `TODO#1: A` 形式で選択可能
6. `unittest-implement-tests.prompt.md`
- 入力: 実装済みコード、テスト観点一覧
- 出力: テストコード実装・テスト実行結果
7. `unittest-generate-testdata-sql.prompt.md`
- 入力: テストケース一覧
- 出力: テストデータSQL案（Mapper テストで DB アクセスを伴う場合に使用）
8. `coding-run-quality-check.prompt.md`
- 入力: 変更差分、テスト結果
- 出力: 品質確認レポート（影響範囲特定 + 関連テスト全件実行 + 静的解析 + セキュリティチェック）
9. `review-feature.prompt.md`
- 入力: 対象機能、関連タスクID一覧、スコープ指定（`full`/`code`/`artifacts`）
- 出力: 機能見直しレポート（`_log/` 配下）、コード修正提案、AI指示資産の改善提案（格上げ/削除/肥大化警告/新規候補）、観点IDカバー率マトリクス、UI選択による適用差分
- 発動: ユーザー判断（機能完成時・マイルストーン前等）
### 5. applyTo 定義
| instructions | applyTo |
|---|---|
| `common` | `src/main/java/**/*.java, src/main/resources/**/*.xml, src/main/resources/**/*.yaml, src/test/java/**/*.java` |
| `coding-java-spring` | `src/main/java/**/*.java` |
| `coding-api-openapi` | `src/main/resources/openapi.yaml, gen/src/main/java/**/oas/**/*.java` |
| `coding-database-mybatis` | `src/main/resources/**/mapper/*.xml, src/main/java/**/mapper/*.java, src/main/java/**/dao/*.java` |
| `unittest-common` | `src/test/java/**/*.java` |
| `unittest-test-controller` | `src/test/java/**/controller/*.java` |
| `unittest-test-service` | `src/test/java/**/service/*.java` |
| `unittest-test-mapper` | `src/test/java/**/mapper/*.java` |
| `unittest-testdata-sql` | `tests/00DB/sql/*.sql, src/test/**/sql/*.sql` |
| `quality-gate` | （auto-apply なし — `coding-run-quality-check` から明示的に参照） |
| `quality-static-analysis` | （auto-apply なし — `coding-run-quality-check` から明示的に参照） |
| `quality-security-check` | `src/main/java/**/*.java` |
**applyTo 重複時のルール:**
- 同一ファイルに複数の instructions が適用されるのは意図した設計である（例: Controller テストファイルには `common` + `unittest-common` + `unittest-test-controller` が適用される）。
- 各ファイルはそれぞれ異なる責務を担うため、内容が矛盾しないように記載する。
- 万一矛盾が発生した場合は、汎用ルール（`common`）を優先し、フェーズ別 instructions はそれを補完する扱いとする。
**コンテキストコスト配慮:**
- `quality-gate` / `quality-static-analysis` は実装フェーズで常時必要ではないため、auto-apply しない。`coding-run-quality-check` プロンプトから明示的に参照する。
- `quality-security-check` は cross-cutting な観点（権限・入力検証・ログ秘匿）のため main コードに auto-apply を維持。
- `common` は実装・テスト両方の進め方ルール（実施順序、不明点対応）を含むため両方に適用拡張。
- `unittest-common` は旧 `unittest-java-spring` + `unittest-test-common` を統合したもの（両者とも test/**/*.java に重複 apply していたため）。
### 6. タスク粒度ルール
- **全体粒度**: 1機能単位でタスクを定義する。
- **実行粒度**: 1機能を複数ステップ（仕様確認 → 実装 → テスト → 品質確認）に分解する。
- **停止・再開**: 各ステップ完了時に中間成果物（テスト観点一覧、実装差分、品質レポート）を出力し、任意のタイミングで停止・再開できるようにする。
- **個別対応**: 特定のクラスやメソッド単位での個別指示にも対応する。その場合、対象ファイルとスコープを明示する。
- **prompt選択**: 全体フロー時は `coding-create-task-plan` → `coding-clarify-requirements` → `unittest-create-test-cases` → `coding-implement-from-tests` → `coding-resolve-todos`（TODO解消）→ `unittest-implement-tests` → `coding-run-quality-check` を順に使用する。テストデータSQLが必要な場合は `unittest-generate-testdata-sql` を `unittest-implement-tests` の前後で使用する。
- **機能完成時**: 複数タスクで構成される 1 機能が完成したら、ユーザー判断で `review-feature` を発動して全体見直しを行う（コード横断チェック + AI指示資産のメンテナンス）。
### 7. AI判断ルール
- **不明点、疑問点がある場合**: 仮実装し、`// TODO: [要確認] 〜の仕様が不明なため仮実装` 積極的にコメントを残す。
- **TODO形式**: `// TODO: [要確認] {内容}` で統一する。
- **仮実装の範囲**: 動作する最小実装とし、分岐やエラー処理は安全側（例外スロー）で仮置きする。
- **タスク完了時**: TODO一覧を変更サマリに含め、人が確認できるようにする。
- **TODOの解消**: 実装後に人がレビューする際、`coding-resolve-todos` プロンプトを使って TODO ごとに修正案を提示させ、UI で選択して確定する。AIが勝手に決定せず、人の選択を経ることで実装と仕様のズレを防ぐ。
### 8. 既存コードとの矛盾時ルール
- **instructions を優先する**。既存コードのパターンは無視する。
- 既存コードと instructions が矛盾する場合、instructions に従って実装する。
- 矛盾が発生した箇所は変更サマリに記録し、人がレビュー時に把握できるようにする。
### 9. 運用ルール（最小）
- 1タスク1ドキュメントで管理する。
- 1回の指示で求める作業は1目的に絞る。
- 各工程終了時に、結果をチェックリストで確認する。
- 指示テンプレートの項目不足時は、AIが補完候補を提示する。
### 10. 既存 instructions との統合方針
- 既存の `coding-database.instructions.md` および `ScreenDesign.instructions.md` は**そのまま併存**する。
- 既存の `copilot-instructions.md` は現在詳細な規約を含むが、最終的には最上位方針のみに縮小し、詳細は prefix 付き instructions に移行する。
- **移行手順**: ① 新規 instructions の初版作成 → ② 動作確認 → ③ `copilot-instructions.md` から該当記載を削除し参照に置換 → ④ 再度動作確認
- **移行完了まで**: 既存 `copilot-instructions.md` の記載をそのまま維持する。新規 instructions と重複する場合、新規側を優先する。
- 新規 instructions は prefix 付き命名（`{フェーズ}-{内容}.instructions.md`）で追加する。
- 既存ファイルの削除・統合は、新構成が安定した後に判断する。
### 11. 参照ドキュメント一覧
AIが実装時に参照すべきドキュメントの優先順位：
1. `copilot-instructions.md`（全体方針）
2. 対象の `instructions/*.instructions.md`（レイヤ別ルール）
3. `dictionary.md`（命名・用語）
4. API仕様
5. DBスキーマ
7. 対象の画面設計書（`docs/開発/02画面設計/`）
### 12. ドキュメント
instructions / prompts の構成完了後、以下の2つのドキュメントを作成する。
#### 12.1 使い方ガイド（開発者向け）`docs/ai-usage-guide.md`
日常的にAI実装を利用する開発者が対象。操作手順と具体例を中心に記載する。
1. **前提条件** — VS Code + GitHub Copilot の必要な設定、拡張機能
2. **基本フロー** — 1機能を実装する際の手順（テストケース先行 → 実装 → 品質確認）
3. **prompt の使い方** — 各 prompt ファイルの呼び出し方、入力パラメータの埋め方
4. **よくある操作例** — Controller追加、Mapper追加、テストデータ作成などの具体例
5. **停止・再開の方法** — 途中で中断した場合の再開手順
6. **トラブルシューティング** — instructions が適用されない場合の確認方法
7. **FAQ** — よくある質問と回答
#### 12.2 メンテナンスガイド（管理者向け）`docs/ai-maintenance-guide.md`
instructions / prompts の追加・変更・管理を行う担当者が対象。構造理解と変更手順を中心に記載する。
1. **ディレクトリ構成と設計意図** — instructions / prompts / templates 各フォルダの役割と分割方針
2. **applyTo の設定方法** — glob パターンの書き方、対象ファイルの確認方法
3. **instructions の追加手順** — 新規 instructions ファイルの作成手順、命名規約、番号付けルール
4. **instructions の変更手順** — 既存ファイル修正時の影響範囲の確認方法、テスト方法
5. **prompt の追加・変更手順** — prompt ファイルの構成ルール、テンプレート変数の定義
6. **既存 instructions との整合性確認** — 重複チェック、矛盾検出の方法
7. **バージョン管理方針** — 変更履歴の記録、レビュー手順
8. **トラブルシューティング** — applyTo が効かない、instructions が競合する場合の対処
#### 作成タイミング
- instructions / prompts の初版作成完了後に作成する。
- instructions の変更時は、使い方ガイド・メンテナンスガイドの両方を同期更新する。
### 13. 将来拡張（実装以外フェーズ）
- `design-*` 向け instructions 追加
- `integration-test-*` 向け instructions 追加
- `release-*` 向け instructions 追加
- フェーズ共通の品質ゲート統合