> 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/22-implementation.md).

# 22. AIによる実装

## 目的

承認した要件と設計を、レビュー可能な小さな差分として実装します。AIには作業範囲と完了条件を明確にし、関係のない目的を1回の依頼へ混ぜません。

## 小さな単位で依頼する

1回の依頼は、結果と差分を確認できる単位に絞ります。

* 1つの目的または責務
* 限定した変更対象
* 具体的な期待結果
* 実行する確認
* 変更後の報告形式

例えば、「検索機能を完成させる」ではなく、「既存のResponse形式に合わせ、検索条件を受け取るRequest DTOとValidationを追加する」と依頼します。

小さく低リスクな変更では、関連する調査、実装、確認、必要な文書更新を一つの依頼にまとめられます。DTO、Service、Controllerなどを常に別々の依頼にする必要はありません。仕様判断、影響範囲、差分の大きさから個別に確認する必要がある場合は、工程や責務ごとに分けます。

## Java REST APIの推奨分割

JavaのAPI開発では、次の単位を目安にします。

```
1. DTO / Request / Response
2. Validation
3. Service
4. Repository / DAO
5. Controller / Handler
6. Error handling
7. Unit test
8. Integration test
9. docs更新
```

依存関係に応じて順序は調整できます。ただし、DB変更、API契約、画面変更を一度に生成させるより、各段階でコンパイルやテストを行う方が問題を特定しやすくなります。

## 実装依頼に含める情報

```markdown
## 対象タスク

## 参照ファイル

## 変更してよいファイル

## 変更してはいけない範囲

## 実装する振る舞い

## 既存パターン

## 完了条件

## 実行する確認

## 完了後の報告
```

実在するファイル、クラス、コマンドだけを指定します。不明な場合は、先に調査を依頼します。

## 既存パターンに合わせる

実装前に、新規採用または変更する開発・ビルド・配布基盤の成立条件と、確認済みの証跡を確認します。基盤が未確認の場合は、[開発基盤の成立を先に確認する](https://livlog-llc.gitbook.io/engineering-handbook/aineitibu/pages/DM9HJUSOGzqxo9TAmoaH#開発基盤の成立を先に確認する)に従って最小構成の確認を先に行い、依存する業務機能を作り込みません。基盤確認に必要な最小実装と、本体の実装を分けて扱います。

AIが一般的に好む構成より、リポジトリで運用されている構成を優先します。

* 既存の命名、パッケージ、例外、ログ形式を踏襲する
* 類似機能を参照し、独自の新レイヤーを安易に増やさない
* 既存ライブラリで実現できる場合、新しい依存関係を追加しない
* formatや生成手順がある場合は、それに従う
* 既存の互換性を維持する

既存パターン自体に問題がある場合は、今回の実装と改善提案を分けます。

## 自動生成コードを確認する

大量のコードを短時間で生成できることは、採用理由にはなりません。次を確認します。

* 使用されないクラス、設定、依存関係がないか
* 不必要な抽象化や汎用化がないか
* Entityをそのまま外部へ返していないか
* 例外を握りつぶしていないか
* ログへSecretsや個人情報を出していないか
* DBクエリ、ループ、画面描画に明らかな性能問題がないか
* コメントがコードと一致し、当然の処理を冗長に説明していないか

## 実装中の判断変更

設計どおりに実装できないことが分かった場合、AIには勝手な迂回実装をさせません。次を報告させ、作業を止めます。

1. 問題が見つかった箇所
2. 設計どおりにできない理由
3. 影響する要件とファイル
4. 選択肢と利点・欠点
5. 人間に必要な判断

人間が依頼文または存在するDesignを更新し、変更後の方針を再度指示します。そのIssueで必要な設計判断は、会話だけに残さずIssue単位のSpecへ反映します。Issue完了後も有効な判断は、現在仕様やADRなどの継続的なAssetへ反映します。

## 実装後の報告

AIには、少なくとも次を出力させます。

* 変更したファイル
* ファイルごとの変更内容
* 要件と完了条件への対応
* 実行したコマンドと結果
* 実行できなかった確認と理由
* 仮定、制約、残課題
* 人間が行う手動確認手順
* `current-spec.md`、`change-log.md`、テスト観点を含む文書の更新要否と理由

「実装しました」だけでは、レビューに必要な情報が不足します。

## 手順

1. 依頼文または存在するTasksから、レビュー可能な1つのタスクを選ぶ
2. 対象、参照、禁止範囲、完了条件を依頼へ含める
3. AIに実装と局所的な確認を行わせる
4. 人間が差分を読む
5. コンパイル、テスト、画面またはAPIを確認する
6. 問題がなければタスクを完了にする
7. 次の責務へ進む

## AIに依頼すること

* 指定した範囲だけを変更する
* 既存の類似実装を参照して合わせる
* 不明点を推測せず、実装前または途中で報告する
* 変更、確認結果、残課題を構造化して出力する

## 人間が確認すること

* 差分が1つの責務に収まっているか
* 実装が要件ではなくAIの都合で拡大していないか
* 既存パターン、互換性、セキュリティを守っているか
* 自動テストだけでなく、実際の動作を確認できるか