> 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/aineitibu/17-overview.md).

# 17. AIネイティブ開発の基本方針

## 目的

この章では、AIを開発プロセスに組み込み、安全かつ継続的に開発するための基本姿勢を定めます。

初回の着手手順は[初回の開発を始める](/engineering-handbook/aineitibu/19-development-flow/first-development.md)、工程全体は[AIネイティブ開発の全体フロー](/engineering-handbook/aineitibu/19-development-flow.md)、依頼文の選び方は[AI依頼プロンプト集](/engineering-handbook/aineitibu/27-prompt-templates.md)を参照してください。この章は、各工程で共通して守る判断と責任範囲を扱います。

AIは、調査、設計案、実装案、レビュー案、テスト案、文書化を高速化する共同開発者です。開発者の代替でも、要件や設計を自動的に正しく決める存在でもありません。最終的な判断、確認、承認、リリース責任は人間が持ちます。

## リブログの開発思想との関係

AIを使う場合も、リブログの基本方針は変わりません。

* 小さく作る
* まず動かす
* 人間が動作と業務上の妥当性を確認する
* 採用した振る舞いをテストで固定する
* 使いながら改善する
* AIを使うが、AI任せにしない

要件、設計、完了条件、テスト計画を実装前に整理したうえで、実装中は次の短いサイクルを回します。

```
最小実装 → 動作・業務確認 → テスト追加 → リファクタリング
```

これはテスト計画を実装後まで作らないという意味でも、TDDを否定するものでもありません。仕様が探索中の機能では実装前に暫定の確認観点を定め、進化型プロトタイピングで正しいと確認した重要な振る舞いをテストで固定します。一方、不具合の再現条件や金額計算のように期待結果が明確な場合は、先にテストを書く方法を選びます。

## AIに渡す情報

AIへの依頼には、少なくとも次の情報を含めます。

| 項目   | 内容                          |
| ---- | --------------------------- |
| 前提   | 対象リポジトリ、技術構成、既存仕様、参照ファイル    |
| 目的   | 何を、誰のために、なぜ変更するのか           |
| 制約   | 変更可能な範囲、互換性、禁止事項、採用する実装パターン |
| 完了条件 | 動作、テスト、文書、報告内容を含む確認可能な条件    |

「適切に実装してください」のような抽象的な依頼だけでは、AIが不足情報を推測し、不要な変更を加える可能性があります。不明点は推測で埋めさせず、質問または未決事項として報告させます。

## 人間が判断すること

人間は、次の事項を決定します。

* 機能の目的、優先順位、対象利用者
* 業務上正しい振る舞いと、今回は実現しない範囲
* アーキテクチャ、データモデル、公開APIの契約
* セキュリティ、個人情報、法務、運用上の許容範囲
* AIが提示した選択肢の採否
* 差分の承認、マージ、デプロイ、ロールバック

特に、複数の正解があり得る設計判断を、AIの最初の提案だけで確定してはいけません。

## AIと人間の責任範囲

AIと人間の役割は、次のように分けます。

| 領域   | AIの役割                              | 人間の責任                       |
| ---- | ---------------------------------- | --------------------------- |
| 調査   | 既存実装、DB、API、画面、業務フロー、関連機能を調べ、根拠を示す | 調査範囲が十分か判断する                |
| 要件   | 曖昧さ、矛盾、抜け漏れ、受け入れ条件案を提示する           | 要件、非対象、優先順位を決める             |
| 設計   | 設計案、代替案、影響範囲、リスクを提示する              | アーキテクチャ、DB、API、権限、業務ルールを決める |
| 実装   | 承認済みの設計に沿って小さな差分を作る                | 差分を読み、採用可否を判断する             |
| テスト  | テスト観点やテストコード案を作る                   | 期待値が正しいか、確認範囲が十分か判断する       |
| レビュー | 問題候補、理由、改善案、影響範囲を提示する              | 指摘の採否、優先度、公開可否を決める          |
| 文書   | 実装差分に基づく更新案を作る                     | 外部仕様、運用判断、公開範囲を決める          |

AIは共同開発者ですが、最終責任者ではありません。設計責任、品質責任、公開責任は人間が持ちます。

## AIに任せてよいこと

前提と変更範囲を明示したうえで、次の作業を依頼できます。

* リポジトリ内の関連ファイルや既存パターンの調査
* 要件、設計、タスク、テスト観点の整理と抜け漏れ確認
* 小さく限定された実装
* 既存パターンに沿ったテストの追加
* コマンド実行と結果の要約
* 実装差分に基づくドキュメント更新案
* 差分レビューとリスク候補の列挙

出力は候補または作業結果であり、人間による確認を省略する根拠にはなりません。

## AIが推測してはいけないこと

次の事項は、AIが推測で補ってはいけません。不明な場合は、質問または未決事項として返します。

* 仕様の推測
* DBの推測
* API契約の推測
* 権限仕様の推測
* 業務ルールの推測
* 例外処理の推測
* 金額計算の推測

仮定を置く必要がある場合は、仮定、影響範囲、差し替え箇所、採用しない可能性を明記し、人間の承認を得てから進めます。

## 小さな単位で進める

一度に「API、DB、画面、テスト、リファクタリングをすべて実装する」と依頼すると、差分が大きくなり、誤りの原因も追いにくくなります。変更は責務ごとに分け、各段階で確認します。

例えばJavaのREST APIでは、DTO、Validation、Service、Repository、Controller、テスト、文書を分けます。各依頼で、変更対象、実行する確認、完了後の報告内容を指定します。

AIネイティブ開発では、次を標準とします。

* Small PR: 1つの目的に閉じたレビュー可能な差分にする
* Small Commit: 変更理由が説明できる単位で履歴を残す
* Small Refactoring: 仕様変更と整理を混ぜない
* Small Prompt: 1回の依頼を確認可能な成果へ絞る。小さな変更では、関連する調査、実装、確認、文書更新をまとめてよい

## 慎重に進める変更

次の変更は、通常の画面文言修正より影響が大きいため、要件、設計、テスト計画、人間の承認を厚くします。

* 金額、税、請求、ポイントなどの計算
* 認証、認可、権限判定
* 外部公開APIと後方互換性
* DBスキーマ変更、既存データ更新、削除処理
* 日付、時刻、タイムゾーン、締め処理
* 外部API、決済、通知などの連携
* Secrets、個人情報、機密情報を扱う処理

privateリポジトリであっても、APIキー、パスワード、トークンなどのSecretsはコミットしません。AIへの指示、サンプル、ログ、テストデータにも実値を含めません。

## 基本手順

初期開発を含むすべての変更はIssueから始めます。Issueには目的、変更範囲、完了条件を置き、必要に応じてRequirements、Design、TasksをIssue単位のSpecへ分けます。Issue完了時には、採用した結果をREADME、現在仕様、ADR、運用手順などの全体ドキュメントへ同期します。

1. 人間がIssueを作成し、目的、制約、完了条件を決める
2. AIに既存実装を調査させる
3. 人間が調査結果と設計案を確認する
4. 小さな単位で実装を依頼する
5. 人間が動作と業務上の妥当性を確認する
6. 重要な振る舞いをテストで固定する
7. 仕様を変えずにリファクタリングする
8. 文書と差分を確認し、人間が取り込む
9. 採用した結果を全体ドキュメントへ同期してIssueを閉じる

## AIに依頼すること

* 関連ファイルと既存パターンを、根拠となるパスとともに報告する
* 不明点、仮定、リスクを実装前に列挙する
* 指定範囲だけを変更する
* 実装後に変更ファイル、変更内容、実行した確認、残課題、仕様・変更履歴・テスト観点の更新要否を報告する

## 人間が確認すること

* 依頼内容が小さく、完了条件が確認可能か
* AIの前提や仮定が正しいか
* 重要な判断をAI任せにしていないか
* 差分が目的に対して必要最小限か
* テストだけでなく、実際の利用方法でも正しいか