--- type: Reference title: "コーディングとテストガイド（AI-DLC 版）" description: "AI-DLC（AI-Driven Development Lifecycle）の Construction フェーズにおけるコーディングとテストの手法。TDD の三原則を AI が実行し人が承認ゲートで検証する Bolt 実装フロー、ステップ計画、AI 生成コードとテストのレビュー観点、ソース束縛レビュー、テスト戦略の水準、リファクタリングとガードレール、技術的負債（quick-cement）の管理、本プロジェクトの開発スキルへの適用方法をまとめる。" tags: [reference] status: stable generated: { by: claude-code/claude-fable-5-1, at: 2026-09-12T05:50:00Z } sources: - id: coding-testing-guide resource: ./コーディングとテストガイド.md title: コーディングとテストガイド（XP 版） author: human:kakimomokuri - id: aidlc-guide resource: ./AI-DLC導入ガイド.md title: AI-DLC 導入ガイド author: claude-code/claude-fable-5-1 - id: aidlc-paper resource: https://prod.d13rzhkk8cj2z0.amplifyapp.com/aidlc.pdf title: AI-Driven Development Lifecycle (AI-DLC) Method Definition author: human:raja-sp - id: aidlc-workflows resource: https://github.com/awslabs/aidlc-workflows title: awslabs/aidlc-workflows（User Guide） author: org:awslabs verified: - { by: human:kakimomokuri, at: 2026-09-12T06:25:42Z } --- # コーディングとテストガイド（AI-DLC 版） ## 概要 このガイドは、[コーディングとテストガイド](コーディングとテストガイド.md)（XP 版）を AI-DLC の原則で読み替えたものです。AI-DLC の背景と用語は [AI-DLC 導入ガイド](AI-DLC導入ガイド.md) を、Bolt の計画は [リリース・イテレーション計画ガイド（AI-DLC 版）](リリース・イテレーション計画ガイド_AI-DLC版.md) を、実装の契約となるストーリーは [ユースケース作成ガイド（AI-DLC 版）](ユースケース作成ガイド_AI-DLC版.md) を参照してください。 XP 版との最大の違いは、**Red-Green-Refactor を回すのが AI で、各サイクルの成果物を検証するのが人** になることです。AI-DLC の論文は、設計技法を方法論の中核に置くと述べ、DDD・BDD・TDD それぞれのフレーバーがあると明記しています。本ガイドは **TDD フレーバー** の AI-DLC です。TDD の三原則・テストピラミッド・リファクタリングの規律は XP 版から変えません。変わるのは、誰がコードを書き、誰が何を検証するかです。 | 観点 | XP 版 | AI-DLC 版 | | :--- | :--- | :--- | | コードを書く | 開発者（ペア） | AI が生成し、開発者が全行を理解して検証する | | TODO リスト | 開発者が作る | AI がチェックボックス付きのステップ計画として書き、人が承認する | | Red-Green-Refactor | 開発者が回す | AI が回し、サイクルごと（または Bolt ごと）に人が承認ゲートで検証する | | 単位 | イテレーション（1〜4 週間） | Bolt（時間〜日） | | コードレビュー | ペア・プルリクエスト | 承認ゲート。レビュアーエージェントの指摘を材料に人が判断する | | 品質チェック | コミット前に開発者が実行 | AI が実行し結果を分析、人が確認する | | コミット | 開発者 | 承認ゲート通過後に人が行う（または人の承認のもとで AI が行う） | | ふりかえり | イテレーション末 | Bolt 末。判断と学びをガードレールにする | | 儀式 | ペアプログラミング | Mob Construction（同じ部屋・共有画面で技術判断） | --- ## 基本原則 ### TDD の三原則（変えない） 1. **失敗するテストを書くまで、プロダクションコードを書いてはならない** 2. **失敗するテストは、失敗するのに十分なだけ書く** 3. **現在失敗しているテストを成功させる以上のプロダクションコードを書いてはならない** AI は「一度にたくさん書く」ことが得意なため、放っておくと三原則を破ります。テストを書かずに実装を生成する、失敗を確認せずに次へ進む、テストが要求する以上の機能を先回りして実装する、といった振る舞いです。AI-DLC 版では、三原則を **AI への指示（ガードレール）** として明示し、承認ゲートで守られているかを検証します。 ### AI-DLC における追加原則 | 原則 | 内容 | | :--- | :--- | | AI が実行し、人が検証する | AI がサイクルを回し、人は各ゲートで成果物を検証・承認する | | コードは全行理解する | AI が書いたコードでも、理解していないコードはマージしない | | 検証は損失関数 | 早い段階のゲートで誤りを刈り取る。ウォーキングスケルトンで AI の出力品質を確かめてからゲート密度を決める | | 品質基準を引き上げる | 生成コストが下がった分、テスト・静的解析・ドキュメントの水準を上げる | | 修正はガードレールにする | 人が AI の振る舞いを修正した内容は `CLAUDE.md`・`PROJECT.md`・スキルに反映し、同じ修正を繰り返さない | ### Red-Green-Refactor サイクル（AI-DLC 版） ```plantuml @startuml title Red-Green-Refactor サイクル（AI が回し、人が検証する） [*] --> Red state Red { [*] --> テストを書く テストを書く : AI が失敗するテストを書き テストを書く : 失敗を確認して報告する } Red --> Green : 最小限の実装 state Green { [*] --> テストが通る テストが通る : AI が最小限のコードを書き テストが通る : テストが通ることを確認する } Green --> Refactor : テスト成功 state Refactor { [*] --> リファクタリング リファクタリング : AI が重複を除去し設計を改善 リファクタリング : テストが通り続けることを確認 } Refactor --> Gate : サイクル完了 state Gate { [*] --> 人が検証 人が検証 : コードを全行理解する 人が検証 : テストが契約（受入条件）を表すか確認 } Gate --> Red : 承認・次のテスト Gate --> Refactor : 変更依頼 Gate --> [*] : ステップ完了 note right of Red テストが本当に失敗したか AI に報告させる end note note right of Gate ゲート密度は ウォーキングスケルトンの 結果で決める end note @enduml ``` --- ## Bolt 開発フロー ### 全体プロセス XP 版のイテレーション開発フローを Bolt に置き換えます。TODO リストは AI が書くステップ計画、コードレビューは承認ゲート、受け入れは Deployment Unit の検証になります。 ```plantuml @startuml title Bolt 開発プロセス start partition "Bolt 開始" { :Unit のストーリーと受入条件を AI に渡す; :AI がステップ計画を書く; :人が計画を承認する（承認ゲート）; } repeat partition "TDD 実装サイクル（AI）" { :ステップを 1 つ選ぶ; repeat :失敗テスト作成（Red）; :最小実装（Green）; :リファクタリング（Refactor）; :品質チェック（テスト・Lint・静的解析）; if (品質 OK?) then (yes) else (no) :AI が修正案を提示; endif repeat while (ステップ内のテスト完了?) } partition "承認ゲート（人）" { :コードを全行理解する; :レビュアーの指摘を確認する; if (承認?) then (yes) :コミット; :チェックボックスを完了にする; else (no) :変更依頼（AI が修正して再提示）; endif } repeat while (全ステップ完了?) partition "Bolt 完了" { :Deployment Unit として検証; :Bolt 終了報告; :判断と学びをガードレールに反映; } stop @enduml ``` ### 承認ゲートの密度 Bolt の最初のステップ（ウォーキングスケルトン）のゲートを通過した時点で、残りのステップをどう進めるかを 1 回だけ決めます。 | 選択 | 内容 | 向いている場合 | | :--- | :--- | :--- | | 各サイクルでゲート | Red-Green-Refactor ごとに人が検証する | 初めてのコードベース、AI の出力品質が未知、規制対象 | | 各ステップでゲート | ステップ（複数サイクル）ごとに人が検証する | 通常の Bolt。既定の密度 | | 自律実行 | 失敗時と Bolt 完了時だけ人が検証する | ウォーキングスケルトンの品質が十分、確認必須の操作を含まない | 自律実行を選んでも、次の場合は必ず停止して人に判断を求めます。 - テストが失敗し、AI の修正案でも通らない - 新規ファイル作成・スキーマ変更・外部ライブラリ導入・セキュリティ・本番環境に関わる操作 - AI が置いた仮定が未確認 - 計画に無いステップが必要になった --- ## アプローチ戦略 ### インサイドアウト vs アウトサイドイン XP 版の選択フローはそのまま有効です。AI-DLC 版では、選択の結果を **AI に明示的に指示** します。AI は指示がなければ全層を一度に生成しようとするためです。 ```plantuml @startuml title 実装アプローチ選択フロー（AI-DLC 版） start :ユーザーストーリーと Unit を分析; if (ブラウンフィールド?) then (はい) :AI にコードを静的・動的モデルへ昇格させる; :人がモデルを検証; endif if (基本 CRUD 実装済み?) then (はい) if (ドメインロジックが複雑?) then (はい) :ドメインモデル中心; #lightgreen:アウトサイドイン推奨; note right 受入テストからスタート AI にモックで層を降りさせる end note else (いいえ) :シンプルな機能追加; #lightblue:どちらでも可; endif else (いいえ) :貧血ドメインモデル; #yellow:インサイドアウト推奨; note right データ層から開始 AI に層ごとにゲートを置く end note endif :アプローチを Bolt 計画に明記し AI に指示; stop @enduml ``` ### インサイドアウトアプローチ データベース層から順に上位層へ進めます。AI には **層ごとに 1 ステップ** として計画させ、層の境界を承認ゲートにします。 ```plantuml @startuml title インサイドアウトアプローチ（AI-DLC 版） participant "人（ゲート）" as human participant "AI" as ai participant "データベース層" as db participant "インフラ層" as infra participant "ドメイン層" as domain participant "サービス層" as service participant "プレゼンテーション層" as ui == ステップ 1: データベース == ai -> db: テーブル定義テスト → 実装 ai -> human: スキーマを提示（確認必須） human --> ai: 承認 == ステップ 2: インフラストラクチャ == ai -> infra: リポジトリテスト → 実装 ai -> human: 永続化の方式を提示 human --> ai: 承認 == ステップ 3: ドメイン == ai -> domain: ビジネスロジックテスト → 実装 ai -> human: ドメインモデルとの整合を提示 human --> ai: 承認 == ステップ 4: サービス == ai -> service: ユースケーステスト → 実装 ai -> human: トランザクション境界を提示 human --> ai: 承認 == ステップ 5: プレゼンテーション == ai -> ui: UI テスト → 実装 ai -> human: 受入条件との対応を提示 human --> ai: 承認 @enduml ``` ### アウトサイドインアプローチ 受入テストから始めて内側へ進めます。AI にはモックで外側から降りさせ、**モックを実装に置き換えるタイミング** を承認ゲートにします。 ```plantuml @startuml title アウトサイドインアプローチ（AI-DLC 版） participant "人（ゲート）" as human participant "AI" as ai participant "受け入れテスト" as at participant "プレゼンテーション層" as ui participant "サービス層" as service participant "ドメイン層" as domain participant "インフラ層" as infra == ステップ 1: 受け入れテスト == ai -> at: 受入条件から受け入れテストを生成 ai -> human: 受入条件との対応を提示 human --> ai: 承認（契約の確定） == ステップ 2: UI 実装 == ai -> ui: UI テスト → 実装（サービスはモック） ai -> human: 画面動作を提示 == ステップ 3: サービス実装 == ai -> service: 統合テスト → 実装（ドメインはモック） ai -> human: モックを実装に置き換える境界を提示 human --> ai: 承認 == ステップ 4: ドメイン実装 == ai -> domain: ドメインテスト → 実装（インフラはモック） ai -> human: ドメインモデルとの整合を提示 human --> ai: 承認 == ステップ 5: インフラ実装 == ai -> infra: 永続化テスト → 実装 ai -> human: 受け入れテストが実データで通ることを提示 human --> ai: 承認（Deployment Unit へ） @enduml ``` ### ブラウンフィールドでの前処理 既存コードに手を入れる場合、AI に直接コードを渡すのではなく、まず **静的モデル（コンポーネント・責務・関係）と動的モデル（主要ユースケースの相互作用）に昇格** させ、人が検証してから変更に入ります。変更対象を「既存の ○○ と同じ方式で」と参照させることで、コードベースの規約から外れた生成を防ぎます。 --- ## TDD 実装の詳細手順 ### 1. ステップ計画（TODO リストの AI-DLC 版） XP 版の TODO リストは、AI が書く **チェックボックス付きのステップ計画** になります。[AI-DLC 導入ガイド](AI-DLC導入ガイド.md#7-プロンプトパターン) のプロンプト骨格で書かせます。 ```markdown あなたは経験豊富なソフトウェアエンジニアです。 docs/requirements//stories.md のストーリー「ユーザー登録」と受入条件を参照し、 実装のステップをチェックボックス付きの Markdown 計画として docs/development//bolt__plan.md に書いてください。 規約: - テスト駆動開発の三原則に従う。テストを書き、失敗を確認してから実装する - アプローチはインサイドアウト。層ごとに 1 ステップにする - 各ステップは 1 回のやり取りで完結する粒度にする - 人の確認が必要なステップ（新規ファイル、スキーマ変更、ライブラリ追加、 セキュリティ）にはその旨を注記する - 既存の apps//src/.../Order.java と同じ規約で書く - 置いた仮定は計画の末尾に列挙する 計画ができたらレビューと承認を求め、承認後に 1 ステップずつ実行し、 完了したステップのチェックボックスを更新してください。 ``` ```markdown ## Bolt 3 計画：ユーザー登録（AI が作成、人が承認） - [ ] 1. User エンティティ - [ ] 1.1 必須フィールドの検証（Red → Green → Refactor） - [ ] 1.2 メールアドレスの形式検証 - [ ] 1.3 パスワードの強度チェック ※ハッシュ方式は要確認 - [ ] 2. UserRepository - [ ] 2.1 save() ※テーブル追加（スキーマ変更）のため要確認 - [ ] 2.2 findByEmail() - [ ] 2.3 existsByEmail() - [ ] 3. UserService - [ ] 3.1 register() - [ ] 3.2 重複チェック - [ ] 4. UserController - [ ] 4.1 POST /users ※既存の OrderController と同じ規約 - [ ] 4.2 バリデーションとエラーハンドリング ### AI の仮定 - パスワードのハッシュには既存の依存関係にある BCrypt を使う（要確認） - メールアドレスの一意性は DB 制約とアプリ側の両方で担保する（要確認） ``` 計画の検証観点は次のとおりです。 | 観点 | 確認内容 | | :--- | :--- | | 三原則 | 各ステップがテストから始まる順序になっているか | | 粒度 | 1 ステップが 1 回のやり取りで完結するか。大きすぎるステップはないか | | 確認ポイント | 確認必須の操作に注記があるか | | 参照 | 既存実装・規約・ドメイン用語を参照しているか | | 仮定 | 列挙された仮定に答えたか。答えていない仮定で AI が進んでいないか | | スコープ | ストーリーに無い機能を先回りしていないか | ### 2. Red フェーズ（AI が失敗するテストを書く） AI にテストを書かせ、**実行して失敗したことを報告させます**。「テストを書きました」だけで進ませません。 ```java // UserTest.java（AI が生成） @Test void ユーザー作成時に必須フィールドが検証される() { // Given String email = "test@example.com"; String password = "SecurePass123!"; String name = "山田太郎"; // When User user = new User(email, password, name); // Then assertThat(user.getEmail()).isEqualTo(email); assertThat(user.getName()).isEqualTo(name); // パスワードはハッシュ化されている assertThat(user.getPassword()).isNotEqualTo(password); } @Test void 無効なメールアドレスで例外が発生する() { // Given String invalidEmail = "invalid-email"; // When/Then assertThrows(IllegalArgumentException.class, () -> { new User(invalidEmail, "password", "name"); }); } ``` ```text AI の報告例: テストを 2 件追加し実行しました。結果: 2 件失敗（User クラスが存在しないためコンパイルエラー）。 次のステップで最小限の実装に進みます。 ``` 人の検証観点は次のとおりです。 - テストは **受入条件を表しているか**。実装の都合ではなく振る舞いを検証しているか - 本当に失敗したか。失敗の理由は想定どおりか - 1 つのテストが 1 つのことを検証しているか - テスト名がドメイン用語で振る舞いを説明しているか ### 3. Green フェーズ（AI が最小限の実装を書く） AI は「先回りして完成形を書く」傾向があります。**現在失敗しているテストを通す以上のコードを書かない** ことを指示し、検証します。 ```java // User.java（AI が生成した最小実装） public class User { private String email; private String password; private String name; public User(String email, String password, String name) { if (!isValidEmail(email)) { throw new IllegalArgumentException("無効なメールアドレス"); } this.email = email; this.password = hashPassword(password); this.name = name; } private boolean isValidEmail(String email) { return email != null && email.contains("@"); } private String hashPassword(String password) { // 最小実装。ハッシュ方式は Refactor で確定（要確認の仮定） return "hashed_" + password; } // getters... } ``` 人の検証観点は次のとおりです。 - テストが要求する以上の機能（未テストの分岐・将来用のフィールド・汎用化）が入っていないか - 「仮の実装」に印が付いているか。AI が仮の実装を本実装として扱っていないか - 全テストが通ったことを AI が報告しているか（新しいテストだけでなく既存テストも） ### 4. Refactor フェーズ（AI が設計を改善する） AI に重複の除去と設計改善をさせ、**テストが通り続けること** を確認させます。設計判断（値オブジェクトの抽出・ライブラリの採用）は承認ゲートで人が決めます。 ```java // User.java（リファクタリング後。値オブジェクトへの分割は人が承認） public class User { private final Email email; private final Password password; private final Name name; public User(String email, String password, String name) { this.email = new Email(email); this.password = new Password(password); this.name = new Name(name); } // getters... } // Email.java（値オブジェクト） public class Email { private static final Pattern VALID_EMAIL_PATTERN = Pattern.compile("^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$"); private final String value; public Email(String value) { if (value == null || !VALID_EMAIL_PATTERN.matcher(value).matches()) { throw new IllegalArgumentException("無効なメールアドレス: " + value); } this.value = value; } public String getValue() { return value; } } // Password.java（値オブジェクト。BCrypt の採用は仮定を確認して承認） public class Password { private static final int MIN_LENGTH = 8; private final String hashedValue; public Password(String rawPassword) { validate(rawPassword); this.hashedValue = BCrypt.hashpw(rawPassword, BCrypt.gensalt()); } private void validate(String password) { if (password == null || password.length() < MIN_LENGTH) { throw new IllegalArgumentException( "パスワードは" + MIN_LENGTH + "文字以上必要です" ); } } public boolean matches(String rawPassword) { return BCrypt.checkpw(rawPassword, hashedValue); } } ``` 人の検証観点は次のとおりです。 - リファクタリングで振る舞いが変わっていないか（テストが同じまま通っているか） - ドメインモデル設計（`docs/design/`）と整合しているか。AI が独自のモデルを作っていないか - 抽出した値オブジェクト・クラスの名前がドメイン用語集と一致しているか - コードベースの既存規約（パッケージ構成・命名・例外の扱い）に従っているか ### 5. 承認ゲートでの検証 サイクル（またはステップ）が終わったら、人が承認ゲートで検証します。「コードを全行理解する」がここの規律です。 ```plantuml @startuml title 承認ゲートでの検証手順 start :AI の完了報告を読む （追加したテスト・実装・実行結果・仮定）; :差分を全行読む; if (理解できない箇所がある?) then (yes) :AI に説明させる; if (説明で納得できる?) then (yes) else (no) :変更依頼（簡潔に書き直す）; stop endif endif :テストが受入条件を表しているか確認; :三原則が守られたか確認 （テストが先か、最小実装か、先回りがないか）; :レビュアーエージェントの指摘を確認; if (承認できる?) then (yes) :承認・コミット; else (no) :変更依頼（理由を明記）; :修正内容をガードレール候補として記録; endif stop @enduml ``` --- ## 品質チェックリスト ### 承認ゲート前の必須確認事項 XP 版の「コミット前の必須確認事項」は、AI-DLC 版では **AI が実行し、結果を報告** します。人は報告を確認し、必要に応じて自分でも実行します。 ```bash # AI が実行し、結果を承認ゲートで報告する # 1. テスト実行 ./gradlew test # または npm test # 2. コードフォーマット ./gradlew spotlessApply # または npm run format # 3. 静的解析 ./gradlew check # または npm run lint # 4. ビルド確認 ./gradlew build # または npm run build # 5. カバレッジ確認 ./gradlew jacocoTestReport # または npm run test:coverage ``` AI の報告には、実行したコマンド・結果・失敗があればその分析と修正案を含めさせます。「テストは通っています」という要約だけの報告は受け付けません。 ### 品質基準 XP 版の基準はそのまま使い、AI-DLC 版では **引き上げる** 方向で運用します。生成コストが下がった分、基準を緩める理由はなくなります。 | 項目 | 基準 | 必須/推奨 | AI-DLC での補足 | | :--- | :--- | :--- | :--- | | テストカバレッジ | 80% 以上 | 必須 | テスト戦略の水準に応じて 90% 以上も検討 | | 循環的複雑度 | 10 以下 | 必須 | AI は分岐を増やしやすい。超えたら分割を指示 | | メソッドの行数 | 20 行以下 | 推奨 | | | クラスの行数 | 200 行以下 | 推奨 | AI は 1 クラスに詰め込みやすい | | 重複コード | 0% | 必須 | AI は既存コードを探さず似た実装を生成しやすい。既存実装の参照を指示 | | コンパイラ警告 | 0 個 | 必須 | | | Linter 警告 | 0 個 | 必須 | | | 未使用コード | 0 個 | 必須 | AI が先回りで書いた未使用のメソッド・フィールドは削除 | ### AI 生成コードに固有の検証観点 | 観点 | 症状 | 対処 | | :--- | :--- | :--- | | 先回り実装 | テストされていない分岐・将来用のオプション引数・汎用化 | 削除。三原則をガードレールに追加 | | 同型テスト | 実装をなぞるだけで振る舞いを検証しないテスト（実装をコピーした期待値） | 受入条件から期待値を書き直す | | 過剰なモック | 検証対象までモックにして何も検証していない | モックは境界だけに限定する | | 既存の無視 | 既存のユーティリティ・値オブジェクト・規約を使わず新規に作る | 既存実装を参照させる。ブラウンフィールドは静的モデルを先に渡す | | 幻覚 API | 存在しないライブラリのメソッドや設定を使う | ビルド・型チェックで検出。依存関係の追加は確認必須 | | 例外の握りつぶし | catch して何もしない、汎用例外で包む | エラーハンドリング方針をガードレールにする | | 秘密情報の混入 | テストデータに本物らしい鍵・個人情報 | AI に渡す範囲を In/Out リストで制限する | ### ソース束縛レビュー 参照実装は、コード生成のレビューを **変更したソースファイルの一覧** に束縛します。レビュー後に未申告の変更があれば完了を拒否します。本プロジェクトでは次で代替します。 - AI に、ステップで作成・変更・削除したファイルの一覧を完了報告に含めさせる - 人は `git diff --stat` と突き合わせ、報告に無い変更があれば理由を問う - 承認後に AI が追加の変更をした場合は、再度ゲートを通す --- ## コミット規約 ### コミットメッセージフォーマット XP 版の Conventional Commits 形式はそのまま使います。 ```text ():