AI-DLCを完全理解する 第12回: Operationsと拡張レイヤーについて

AI-DLC AWS

吉田真吾 (@yoshidashingo) です。

これだけは覚えて帰ってね💡

  • operations.mdはわずか20行のプレースホルダー。「未完成であること」が将来への拡張余地を示す
  • AI-DLCはベースレイヤー (標準ルール) ＋拡張レイヤー (独自カスタマイズ) の二層構造で運用できる
  • ルール適用の優先度は core-workflow.md > 拡張レイヤー > ベースレイヤー
  • AI-DLCは「完成品」ではなく「拡張可能なプラットフォーム」として設計されている

https://extravaganzarr.s3.ap-northeast-1.amazonaws.com/aidlc-image03.png

引用元：AI 駆動開発ライフサイクル:ソフトウェアエンジニアリングの再構築 | Amazon Web Services ブログ

operations.md: 未実装

全文

operationsディレクトリにはファイルが1つだけ。operations.mdの全文は以下のとおり本日現在では未実装です。

# Operations

**Purpose**: Placeholder for future operational phases (deployment, monitoring, maintenance)

**Status**: This phase is currently a placeholder and will be expanded in future versions.

## Future Scope

The Operations phase will eventually include:
- Deployment planning and execution
- Monitoring and observability setup
- Incident response procedures
- Maintenance and support workflows
- Production readiness checklists

## Current State

All build and test activities have been moved to the CONSTRUCTION phase.
The AI-DLC workflow currently ends after the Build and Test phase in CONSTRUCTION.

将来実装される予定の機能性

operations.mdで列挙されている将来機能は5つです。

# 機能 想定される内容
1 Deployment planning and execution デプロイ計画と実行手順
2 Monitoring and observability setup モニタリングと可観測性の構築
3 Incident response procedures インシデント対応手順
4 Maintenance and support workflows 保守・サポートのワークフロー
5 Production readiness checklists 本番準備チェックリスト

第1回で「DevOpsが導入した『開発から運用まで一気通貫で面倒を見る』という考え方は、AI-DLCの3フェーズ構成にも共通している」と解説しましたが、現時点でその「運用」部分はoperations.mdで「Status: This phase is currently a placeholder」と明記している通りです。

第1回で解説した通り、AI-DLCは2025年にオープンソースとして公開されたフレームワークです。INCEPTIONとCONSTRUCTIONが先に充実し、OPERATIONSは将来の拡張に委ねられています。

AI-DLCのカスタマイズ: 二層構造

ベースレイヤーと拡張レイヤー

AI-DLCのルールファイル群は、そのまま使うこともできますが、組織やプロジェクトに合わせてカスタマイズすることも可能です。core-workflow.mdが規定するのはベースレイヤー (aws-aidlc-rule-details/) の読み込みのみですが、利用者側でこれに拡張レイヤーを追加する二層構造の運用パターンが考えられます。

.steering/
  aws-aidlc-rules/
    core-workflow.md           # マスターワークフロー (変更不可) 
  aws-aidlc-rule-details/      # ベースレイヤー (変更不可) 
    common/
    inception/
    construction/
    operations/
  [organization]-aidlc-rule-details/  # 拡張レイヤー (自由にカスタマイズ) 
    ...
  • ベースレイヤー (aws-aidlc-rule-details/) : AI-DLC標準のルール詳細。変更不可
  • 拡張レイヤー ([organization]-aidlc-rule-details/) : 組織独自の知見・ノウハウを格納。自由にカスタマイズ可能

ベースレイヤーを変更しない理由は明確です。AI-DLCが公式にアップデートされたとき、ベースレイヤーを差し替えるだけで最新のルールを取り込めます。拡張レイヤーには手を入れていないため、アップデートの影響を受けません。ライブラリ本体に手を入れずに、拡張ポイントを通じて機能を追加する発想と同じです。

ルール読み込みの優先順位

二層構造を運用する際のルール読み込み手順は以下の通りです:

  1. aws-aidlc-rule-details から該当ステージのルールファイルを読み込む
  2. 拡張レイヤー に同名または関連するファイルが存在する場合、追加で読み込む
  3. 両方のルールを統合して適用する

競合がある場合の優先順位:

優先度 ソース 役割
最優先 core-workflow.md プロセスフロー (変更不可)
高 拡張レイヤー 業界・業務固有のルール
ベース aws-aidlc-rule-details 標準ルール

拡張レイヤーはベースレイヤーを「上書き」するのではなく「補完・拡張」します。たとえば、ベースレイヤーのrequirements-analysis.mdが複数の質問カテゴリを定義している場合、拡張レイヤーで「金融業界固有の質問カテゴリ」を追加できます。元のカテゴリは残したまま、業界固有の観点を加える形です。

拡張レイヤーで何をカスタマイズするか

拡張レイヤーに格納する典型的な内容は以下の通りです:

  • 業界コンテキスト: 顧客業界に固有の規制、基準、考慮事項
  • 品質基準: 組織独自のレビュー観点、品質チェックリスト
  • 成果物テンプレート: 組織流のドキュメントフォーマット
  • サービスマッピング: 自社のサービスメニューとAI-DLCのステージの対応付け
  • 用語定義: 業界用語や組織固有の用語の統一

AI-DLCは特定の業界や組織に最適化されていない汎用フレームワークですが、拡張レイヤーの仕組みにより、さまざまな業界・組織の要件に合わせたカスタマイズが可能です。

ワークフロー定義ファイル群の全体像

第8回〜第11回で解説してきたすべてのファイルを、1つの表にまとめましょう。

core-workflow.md (1ファイル)

AI-DLC全体の「憲法」。4つのMANDATORYルール、3フェーズ定義、8つのKey Principles、チェックボックス追跡、監査ログルールを含みます。

common/ (11ファイル)

ファイル 説明
process-overview.md AIモデル向け全体図 (Mermaid)
welcome-message.md ユーザー向けウェルカムメッセージ
session-continuity.md セッション再開テンプレート
question-format-guide.md 質問ファイル方式のルール
depth-levels.md 適応的深度の定義
terminology.md 用語集
overconfidence-prevention.md 過信防止ガイド
content-validation.md コンテンツ検証ルール
ascii-diagram-standards.md ASCII図表の標準規格
workflow-changes.md ワークフロー変更管理
error-handling.md エラー処理と復旧手順

inception/ (7ファイル)

ファイル ステップ数 成果物数 分類
workspace-detection.md 6 1 ALWAYS
reverse-engineering.md 12 8+1 CONDITIONAL
requirements-analysis.md 9 1-2 ALWAYS
user-stories.md 23 2 CONDITIONAL
workflow-planning.md 11 1 ALWAYS
application-design.md 15 4 CONDITIONAL
units-generation.md 19 3 CONDITIONAL

construction/ (6ファイル)

ファイル ステップ数 成果物数 分類
functional-design.md 9 3 CONDITIONAL
nfr-requirements.md 9 2 CONDITIONAL
nfr-design.md 9 2 CONDITIONAL
infrastructure-design.md 9 2-3 CONDITIONAL
code-generation.md 16 多数 ALWAYS
build-and-test.md 10 5+ ALWAYS

operations/ (1ファイル)

ファイル 説明
operations.md プレースホルダー

合計: 1 + 11 + 7 + 6 + 1 = 26ファイル。これがAI-DLCのワークフロー定義の全体です。

シリーズ総括: AI-DLCが変える開発の風景

12回で見えてきたもの

第1回から第12回まで、AI-DLCの全体像を見てきました。ここで、シリーズ全体を通じて見えてきたAI-DLCの本質をまとめます。

AI-DLCは「AIにどうコーディングさせるか」のフレームワークではありません。「AIにどう開発プロセスを回させるか」のフレームワークです。

従来の開発手法では、プロセスの設計と運用は人間の仕事でした。ウォーターフォールのプロジェクトマネージャーも、アジャイルのスクラムマスターも、DevOpsのプラットフォームチームも、「次に何をすべきか」を決めるのは人間でした。AI-DLCはこの前提を変え、ルールファイル群の指示に基づいてAIがプロセスを進行します。

ただし「AIに丸投げ」ではありません。12回を通じて繰り返し見てきた通り、AI-DLCには以下の仕組みが組み込まれています:

  • 承認ゲート: ほぼすべてのステージで人間の承認が必要
  • 質問ファイル方式: AIが「分かったつもり」で進まないための構造化された対話
  • 過信防止: 「聞きすぎるくらい聞け」という設計思想
  • 監査証跡: すべてのやり取りがタイムスタンプ付きで記録される
  • NO EMERGENT BEHAVIOR: AIが独自の判断で新しいパターンを生み出すことは認められていない
  • 適応型ワークフロー: タスクの複雑さに応じてプロセスが自動で伸び縮みする

これらは、AIの出力を適切に検証しながら活用するための設計です。

必要なルールだけ必要なときに読み込む構造

core-workflow.md          ← 全体を規定する「憲法」
  ├── common/             ← すべてのステージに適用されるメタルール
  ├── inception/          ← Inceptionの各ステージのルール
  ├── construction/       ← CONSTRUCTIONの各ステージのルール
  └── operations/         ← 将来拡張用のプレースホルダー

この構造には、ソフトウェアアーキテクチャの基本原則が見て取れます:

  • 関心の分離: フェーズ別、ステージ別にファイルを分離
  • DRY原則: commonディレクトリで共通ルールを一元管理
  • 開放閉鎖原則: ベースレイヤーを変更せずに拡張レイヤーで拡張
  • 段階的具体化: core-workflow.md (抽象) → 個別ファイル (具体)

AI-DLCのワークフロー定義ファイル群は、それ自体がこれらのソフトウェア設計原則を反映した構造になっています。

AI-DLCの未来

OPERATIONSフェーズの空白は、AI-DLCの現在地を正直に示しています。コードの生成とテストまではAIが主導できますが、AI-DLCの現バージョンでは、デプロイ・モニタリング・インシデント対応はまだ対象範囲外です。

しかし、INCEPTIONとCONSTRUCTIONの仕組みを見れば、OPERATIONSが充実したときの姿は想像できます。デプロイ計画の策定、モニタリングの設定、インシデント対応手順の生成 ― これらもALWAYS/CONDITIONALの適応型ワークフローで実行され、承認ゲートと監査証跡により品質を高める設計が適用されると推測されます。

AI-DLCは「完成品」ではありません。拡張レイヤーによるカスタマイズとOPERATIONSフェーズの将来実装を前提とした「拡張可能なプラットフォーム」です。

まとめ

第12回はOPERATIONSフェーズの現状と、AI-DLCのカスタマイズの仕組みについて説明しました。今回学んだことは以下です。

  • operations.mdは20行のプレースホルダーで、5つの将来機能 (デプロイ、モニタリング、インシデント対応、保守、本番準備) を予告します
  • AI-DLCはベースレイヤー＋拡張レイヤーの二層構造でカスタマイズ可能です。ベースレイヤーは変更不可、拡張レイヤーで組織固有のルールを追加します
  • ワークフロー定義の全体は26ファイルで構成されます (core-workflow 1 + common 11 + inception 7 + construction 6 + operations 1)
  • 本シリーズで述べた通り、AI-DLCの本質は「ルールファイル群に基づくAI主導の開発プロセス」にあります
  • 26ファイルの構造自体が、関心の分離、DRY原則、開放閉鎖原則、段階的具体化というソフトウェア設計の原則を反映しています
  • AI-DLCは「完成品」ではなく「拡張可能なプラットフォーム」として設計され、拡張レイヤーとOPERATIONSフェーズの将来実装を前提としています

AI-DLCを完全理解する 第11回: CONSTRUCTION(実装)フェーズ徹底解説

AI-DLC AWS

吉田真吾 (@yoshidashingo) です。

これだけは覚えて帰ってね💡

  • constructionの最初の5ファイルは「per-unit」で実行され、Per-Unit Loopの骨格を形成する
  • code-generation.mdは「Brownfieldではコピーファイル禁止」という明確なルールを持つ
  • build-and-test.mdは6種類のテスト (unit / integration / performance / e2e / contract / security) を定義する
  • Per-Unit Loopの5ファイルに「標準化された2択メッセージ」が規定されている

https://extravaganzarr.s3.ap-northeast-1.amazonaws.com/aidlc-image03.png

引用元：AI 駆動開発ライフサイクル:ソフトウェアエンジニアリングの再構築 | Amazon Web Services ブログ

constructionディレクトリの概観

constructionディレクトリには、CONSTRUCTIONフェーズの6つのステージに対応する6つのルールファイルが格納されています。

# ファイル 行数 ステップ数 分類
1 functional-design.md 113 9 CONDITIONAL
2 nfr-requirements.md 100 9 CONDITIONAL
3 nfr-design.md 91 9 CONDITIONAL
4 infrastructure-design.md 95 9 CONDITIONAL
5 code-generation.md 208 16 ALWAYS
6 build-and-test.md 355 10 ALWAYS

inceptionディレクトリと比べて2つの特徴があります。1つ目はファイルサイズの均一性です。inceptionが94行〜480行と大きな幅があったのに対し、constructionは91行〜355行と差が小さくなっています。2つ目はステップ数の9ステップ収束です。最初の4ファイルはすべて9ステップで構成されています。この均一性は、Per-Unit Loop内で同じリズムが繰り返される設計を反映していると考えられます。

Per-Unit Loopの内側

第5回と第8回で解説したPer-Unit Loopの構造を、ルールファイルの視点から見直してみましょう。

ユニットA → [functional-design → nfr-requirements → nfr-design → infrastructure-design → code-generation]
ユニットB → [functional-design → nfr-requirements → nfr-design → infrastructure-design → code-generation]
全ユニット完了 → build-and-test

最初の4ファイル (functional-design〜infrastructure-design) は、すべてCONDITIONALでありper-unitで実行されます。code-generationはALWAYSかつper-unit。build-and-testはALWAYSですがper-unitではなく、全ユニットの完了後に1回だけ実行されます。

1. functional-design.md: 技術非依存のビジネスロジック

9ステップの構造

functional-design.mdは9ステップで構成されます:

  1. ユニットコンテキストの分析
  2. Functional Design計画の作成
  3. コンテキスト適応型の質問生成
  4. 計画の保存
  5. 回答の収集と分析
  6. 成果物の生成
  7. 完了メッセージの提示
  8. 明示的承認の待機
  9. 承認記録と進捗更新

この9ステップはnfr-requirements.md、nfr-design.md、infrastructure-design.mdでもほぼ同一です。

3つの成果物

第5回で概念的に解説した3つの成果物が、ここでファイルパス付きで定義されています:

  • {unit-name}/functional-design/business-logic-model.md
  • {unit-name}/functional-design/business-rules.md
  • {unit-name}/functional-design/domain-entities.md

7つの質問カテゴリ

質問カテゴリは7つ定義されています:

  1. Business Logic Modeling ― コアエンティティ、ワークフロー、データ変換
  2. Domain Model ― ドメイン概念、エンティティ関係、データ構造
  3. Business Rules ― 決定ルール、バリデーションロジック、制約
  4. Data Flow ― データの入出力、変換、永続化
  5. Integration Points ― 外部システムとの連携
  6. Error Handling ― エラーシナリオ、バリデーション失敗、例外処理
  7. Business Scenarios ― エッジケース、代替フロー、複雑な状況

各カテゴリには「evaluate ALL categories」と指示されています。第9回で解説したoverconfidence-prevention.mdと同様の「すべてのカテゴリを評価せよ」という方針が、functional-design.md自身にも記述されています。

2-3. nfr-requirements.md と nfr-design.md: 品質の2段階設計

NFR Requirements (9ステップ)

第5回で解説した8つの質問カテゴリが、ルールファイルでは以下のように定義されています:

  1. Scalability Requirements
  2. Performance Requirements
  3. Availability Requirements
  4. Security Requirements
  5. Tech Stack Selection
  6. Reliability Requirements
  7. Maintainability Requirements
  8. Usability Requirements

成果物は2つ: - {unit-name}/nfr-requirements/nfr-requirements.md - {unit-name}/nfr-requirements/tech-stack-decisions.md

NFR Design (9ステップ)

NFR Designの質問カテゴリは5つ:

  1. Resilience Patterns
  2. Scalability Patterns
  3. Performance Patterns
  4. Security Patterns
  5. Logical Components

ここで興味深い違いがあります。NFR RequirementsではALL categoriesの評価が求められますが、NFR Designでは「Use the categories below as inspiration, NOT as a mandatory checklist. Skip entire categories if not applicable」と書かれています。要件段階ではすべてのカテゴリについて体系的に聞き、設計段階では必要なパターンだけを選びます。この非対称性は、要件段階ではすべてのカテゴリを評価し、設計段階では該当するものだけを選ぶという使い分けによるものです。

成果物は2つ: - {unit-name}/nfr-design/nfr-design-patterns.md - {unit-name}/nfr-design/logical-components.md

4. infrastructure-design.md: 論理から物理へ

「推奨」という前提条件

infrastructure-design.mdの前提条件に注目してください:

- Functional Design must be complete for the unit
- NFR Design recommended (provides logical components to map)

Functional Designは「must be complete」ですが、NFR Designは「recommended」です。つまり、NFR DesignをスキップしてもInfrastructure Designは実行できます。この違いは、機能設計がインフラ設計の論理的な前提であるのに対し、NFR設計は品質面の補強であり必須ではないことを意味します。Per-Unit Loop内のステージは固定順序ですが、CONDITIONALステージのスキップにより実際の経路は変わりえます。

成果物

成果物は2〜3つ: - {unit-name}/infrastructure-design/infrastructure-design.md - {unit-name}/infrastructure-design/deployment-architecture.md - shared-infrastructure.md (共有インフラがある場合のみ)

3つ目のshared-infrastructure.mdはユニット固有ではなくconstruction/直下に配置されます。複数ユニットが共通のインフラ (VPC、ロードバランサーなど) を使う場合の設計を一元管理するためです。

5. code-generation.md: 計画→承認→生成

2部構成

code-generation.mdもuser-stories.md、units-generation.mdと同じくPart 1 (Planning: Step 1〜9) とPart 2 (Generation: Step 10〜16) の2部構成です。

計画の具体性

Step 2の計画作成では、生成するコードの種類が具体的に列挙されています:

  1. Project Structure Setup (Greenfieldのみ)
  2. Business Logic Generation
  3. Business Logic Unit Testing
  4. Business Logic Summary
  5. API Layer Generation
  6. API Layer Unit Testing
  7. API Layer Summary
  8. Repository Layer Generation
  9. Repository Layer Unit Testing
  10. Repository Layer Summary
  11. Database Migration Scripts
  12. Documentation Generation
  13. Deployment Artifacts Generation

各層 (Business Logic / API Layer / Repository Layer) が「生成→テスト→サマリー」の3点セットで構成されています。

テストはCode Generationの段階で生成され、Build and Testの段階で実行されます。「テストを書く」と「テストを走らせる」が分離されている設計です。

Brownfieldの「コピーファイル禁止」ルール

code-generation.mdで最も注目すべきルールがこれです:

- **If file exists**: Modify it in-place
  (never create `ClassName_modified.java`, `ClassName_new.java`, etc.)
- **If file doesn't exist**: Create new file

Brownfieldプロジェクトで既存ファイルを変更する場合、ファイルを「その場で修正」します。ClassName_modified.javaやClassName_new.javaのようなコピーファイルを作ってはなりません。

なぜこのルールが必要なのか。AIによるコード生成では、既存ファイルの変更を避けて新しいファイルにコピーを作り、そこで変更を加えるという「安全な」パターンに陥りがちです。しかしこのパターンは、元のファイルとコピーの二重管理を生み、ビルドの混乱やテストの不整合を引き起こします。「その場で修正」をルールとして規定することで、これらの問題を抑制する設計になっています (ただしプロンプト指示であるため、AIの振る舞いを技術的に保証するものではありません) 。

Step 12にも検証ルールがあります: 「Brownfield only: Verify no duplicate files created (Brownfieldのみ: 重複ファイルが作成されていないことを検証せよ) 」。生成後のチェックまで含めた2段階のルールです。

コード配置のルール

Code Location Rulesとして、プロジェクトタイプ別のディレクトリ構造が定義されています:

プロジェクトタイプ コード配置
Brownfield 既存構造をそのまま使用
Greenfield単一ユニット src/, tests/, config/
Greenfieldマイクロサービス {unit-name}/src/, {unit-name}/tests/
Greenfieldモノリス src/{unit-name}/, tests/{unit-name}/

マイクロサービスとモノリスでディレクトリの階層が逆になる点に注意してください。マイクロサービスはユニットがトップレベルで、その下にsrc/tests。モノリスはsrc/testsがトップレベルで、その下にユニット。

6. build-and-test.md: 6種類のテスト戦略

ループの外側

build-and-test.mdはPer-Unit Loopの外側に位置する唯一のステージです。全ユニットのCode Generationが完了した後、1回だけ実行されます。

6種類のテスト

build-and-test.mdが定義するテストは6種類です:

# テスト種別 成果物 備考
1 Unit Tests unit-test-instructions.md Code Generation段階で生成済み
2 Integration Tests integration-test-instructions.md ユニット間の連携テスト
3 Performance Tests performance-test-instructions.md 負荷・ストレステスト
4 End-to-End Tests e2e-test-instructions.md 完全なユーザーワークフロー
5 Contract Tests contract-test-instructions.md マイクロサービス向け
6 Security Tests security-test-instructions.md 脆弱性スキャン、認証テスト

1〜3はbuild-and-test.mdの個別ステップ (Steps 2〜5) として定義されており、4〜6はStep 6で「Based on project requirements」として要件に応じて生成されます。

5つの成果物

最終的に生成される成果物は5つ (＋要件に応じた追加テスト手順書) :

  1. build-instructions.md ― ビルド手順 (依存関係インストール〜ビルド実行〜検証)
  2. unit-test-instructions.md ― ユニットテスト実行手順
  3. integration-test-instructions.md ― 結合テスト手順
  4. performance-test-instructions.md ― パフォーマンステスト手順
  5. build-and-test-summary.md ― ビルド・テスト結果の総合サマリー

build-and-test-summary.mdの末尾には「Ready for Operations: [Yes/No]」という判定項目があります。すべてのテストが通過すればOPERATIONSフェーズへの準備完了、失敗があれば修正してリビルドします。

constructionディレクトリに共通するパターン

統一された完了メッセージ

第8回で解説した「MANDATORY: Present standardized 2-option completion message」が、Per-Unit Loop内の5ファイル (functional-design〜code-generation) に定義されています。完了メッセージの構造は以下の通りです:

  1. Completion Announcement: # [emoji] [Stage Name] Complete - [unit-name]
  2. AI Summary: 成果物の要約 (箇条書き)
  3. Formatted Workflow Message: 2択の選択肢

2択は常に「Request Changes (変更を依頼する) 」と「Continue to Next Stage (次のステージに進む) 」です。第8回で述べた通り、core-workflow.mdの「NO EMERGENT BEHAVIOR」原則と各ステージの実行ステップにより、AIが独自に3択目を作り出すことは認められていません。

なお、build-and-test.mdはPer-Unit Loopの外側にあるため、この2択形式ではなく「Ready to proceed to Operations stage?」という形式の完了メッセージを使用します。

前提条件の段階的依存

各ステージの前提条件を追うと、段階的な依存関係が見えます:

functional-design    → Units Generation complete, Application Design recommended
nfr-requirements     → Functional Design complete
nfr-design           → NFR Requirements complete
infrastructure-design → Functional Design complete, NFR Design recommended
code-generation      → Unit Design Generation complete, NFR Implementation complete (if executed)
build-and-test       → Code Generation complete for ALL units

NFR DesignやInfrastructure Designをスキップしても、Code Generationには到達できる設計になっています。これは「must be complete」と「recommended」の使い分けによるものです。

まとめ

第11回はCONSTRUCTIONフェーズの6つのルールファイルについて説明しました。今回学んだことは以下です。

  • constructionディレクトリの6ファイルは、inceptionに比べてサイズが均一で、最初の4つは9ステップに収束しています
  • functional-design.mdは技術非依存で7つの質問カテゴリを体系的に評価します
  • nfr-requirements.mdとnfr-design.mdは、要件段階では全カテゴリを評価し設計段階では該当するものだけを選ぶ非対称の構造を持ちます
  • infrastructure-design.mdのshared-infrastructure.mdは、ユニット横断の共有インフラを一元管理します
  • code-generation.mdの「コピーファイル禁止」ルールと生成後の重複検証は、Brownfieldプロジェクト特有のリスクに対する2段階のルールです
  • build-and-test.mdは6種類のテストを定義し、Per-Unit Loopの外側で全ユニットを横断的に検証します
  • Per-Unit Loop内の5ファイルに「標準化された2択メッセージ」が規定されており、build-and-test.mdは別の完了メッセージ形式を使用します

次回予告

最終回 (第12回) では、OPERATIONSフェーズのプレースホルダーが示す将来ビジョン、AI-DLCのカスタマイズ方法 (ベースレイヤー＋拡張レイヤーの二層構造) 、そしてシリーズ全体の総括を行います。AI-DLCはフレームワークの完成品ではなく、拡張可能なプラットフォームです。

AI-DLCを完全理解する 第10回: INCEPTION(計画フェーズ)徹底解説

AI-DLC AWS

吉田真吾 (@yoshidashingo) です。

これだけは覚えて帰ってね💡

  • workspace-detection.mdは唯一「承認不要」かつ最短 (94行) のステージ。6ステップでBrownfield/Greenfieldを判定する
  • reverse-engineering.mdはBrownfieldプロジェクトで「常に再実行」 (Always rerun) のポリシーを持ち、8種の成果物テンプレートを定義する
  • user-stories.mdは最多ステップ (328行・23ステップ) で、Planning→Generationの2部構成を持つ
  • workflow-planning.mdはMermaidフローチャートの生成指示とBrownfield向けのモジュール連携分析を含む

https://extravaganzarr.s3.ap-northeast-1.amazonaws.com/aidlc-image03.png

引用元：AI 駆動開発ライフサイクル:ソフトウェアエンジニアリングの再構築 | Amazon Web Services ブログ

inceptionディレクトリの概観

inceptionディレクトリには、Inceptionフェーズの7つのステージに対応する7つのルールファイルが格納されています。

# ファイル 行数 ステップ数 分類
1 workspace-detection.md 94 6 ALWAYS
2 reverse-engineering.md 312 12※ CONDITIONAL
3 requirements-analysis.md 169 9 ALWAYS
4 user-stories.md 328 23 CONDITIONAL
5 workflow-planning.md 480 11 ALWAYS
6 application-design.md 146 15 CONDITIONAL
7 units-generation.md 184 19 CONDITIONAL

※reverse-engineering.mdはStep 1の見出しが2つあるため、ステップ見出しの総数は13個。詳細は後述。

ファイルのボリュームには大きな差があります。最短のworkspace-detection.md (94行) から最長のworkflow-planning.md (480行) まで、5倍以上の開きがあります。この差はステージの複雑さやBrownfield向け分析の有無を反映していると考えられます。

1. workspace-detection.md: ワークスペース内の調査

6ステップの全容

Step 内容
1 aidlc-state.mdの存在チェック (既存プロジェクトの検出)
2 ワークスペースの既存コードスキャン
3 Brownfield/Greenfieldの判定と次ステージの決定
4 aidlc-state.mdの初期作成
5 完了メッセージの提示
6 自動的に次ステージへ進行

Step 2のスキャン対象は具体的です。ソースファイルには.java, .py, .js, .ts, .jsx, .tsx, .kt, .kts, .scala, .groovy, .go, .rs, .rb, .php, .c, .h, .cpp, .hpp, .cc, .cs, .fsなど主要言語の拡張子と、pom.xml, package.json, build.gradleなどのビルドファイルが列挙されています。さらに「Workspace Root」を特定し、「NOT aidlc-docs/」と明記してドキュメントディレクトリとアプリケーションコードの混同を防ぐ意図です。

Step 4で作成されるaidlc-state.mdの初期テンプレートには「Code Location Rules」が含まれています:

## Code Location Rules
- **Application Code**: Workspace root (NEVER in aidlc-docs/)
- **Documentation**: aidlc-docs/ only
- **Structure patterns**: See code-generation.md Critical Rules

このルールは第8回で解説したディレクトリ構造の「分離原則」を、プロジェクトの最初期から適用するものです。

2. reverse-engineering.md: 8種の成果物テンプレート

「常に再実行」ポリシー

冒頭に注目すべき一文があります:

**Rerun behavior**: Always rerun when brownfield project detected,
even if artifacts exist. This ensures artifacts reflect current code state

「成果物が既に存在していても、Brownfieldプロジェクトが検出されたら常に再実行する。これにより成果物が現在のコードの状態を反映することを意図している (原文: ensures) 。」

一方、core-workflow.md上のSkip条件は「Greenfieldプロジェクト、または既存のリバースエンジニアリング成果物がある場合にスキップ」と定めています。reverse-engineering.md自身の「常に再実行」ポリシーとは方向性が異なります。これはcore-workflow.mdがステージ全体のスキップ判断を扱い、個別のルールファイルがステージ内の振る舞いを詳細に定義するという「二層構造の粒度の違い」として読み取れますが、両ルール間に潜在的な矛盾がある可能性にも留意が必要です。

8つの成果物

reverse-engineering.mdが生成する成果物は以下の8つです:

# 成果物 内容
1 business-overview.md ビジネスコンテキスト図、ビジネス説明、ビジネストランザクション
2 architecture.md システム概要、アーキテクチャ図、コンポーネント説明、データフロー
3 code-structure.md ビルドシステム、クラス/モジュール階層、既存ファイルの一覧
4 api-documentation.md REST API、内部API、データモデル
5 component-inventory.md パッケージの種類別インベントリ
6 technology-stack.md プログラミング言語、フレームワーク、インフラ、ビルドツール
7 dependencies.md 内部依存関係図、外部依存関係
8 code-quality-assessment.md テストカバレッジ、コード品質指標、技術的負債

これらに加えて、分析のメタデータを記録するreverse-engineering-timestamp.mdも生成されます。

第2回でTOGAFのArchitecture Visionと対比した内容が、ここで8つの具体的な成果物テンプレートとして定義されています。特にbusiness-overview.mdはBusiness Dictionary (DDDのユビキタス言語と同様に、ビジネスドメインの用語を統一定義するものです。第3回で詳述しました) を含みます。

Step 1の二重性

実はreverse-engineering.mdには「Step 1」の見出しが2つあります。最初のStep 1は「Multi-Package Discovery」で、6つのサブステップでワークスペースをスキャンします。2番目のStep 1 (実質的にはStep 2に相当) は「Generate Business Overview Documentation」です。これはルールファイル自体の構造的な問題です。AIモデルがステップ番号の重複をどのように処理するかはモデルの実装に依存するため、影響について断定的なことは言えませんが、ソースの記述順に処理が進む場合はMulti-Package Discoveryが先に実行されることが期待されます。

3. requirements-analysis.md: 「プロダクトオーナーの役割を担え」

ロールの指定

冒頭にある「Assume the role of a product owner (プロダクトオーナーの役割を担え) 」という指示は、AI-DLCの中でも特徴的です。AIモデルにプロダクトオーナーの視点を持たせることで、要件の体系的な分析と整合性の向上を意図しています。

4段階のインテント分析

Step 2でユーザーのリクエストを4つの観点から分析します:

  1. Request Clarity (明確さ) : Clear / Vague / Incomplete
  2. Request Type (種類) : New Feature / Bug Fix / Refactoring / Upgrade / Migration / Enhancement / New Project
  3. Initial Scope Estimate (スコープ) : Single File → Cross-system の5段階
  4. Initial Complexity Estimate (複雑さ) : Trivial / Simple / Moderate / Complex

この分析結果がStep 3の「Requirements Depth」の決定に用いられます。第7回で解説したAdaptive Depthの3段階 (Minimal / Standard / Comprehensive) がここで具体的に適用されます。

完了メッセージのパターン

requirements-analysis.mdの完了メッセージには、他のステージにはないオプションが含まれています:

> 📝 **Add User Stories** - Choose to Include **User Stories** stage
>   (currently skipped based on project simplicity)

User Storiesがスキップ予定の場合に限り、「User Storiesを追加する」という選択肢が提示されます。第8回で解説した「User Control」原則の具体的な適用例です。AIがスキップと判断したステージについて、ユーザーがその判断を覆して含めることができるオプションを提示しています。

4. user-stories.md: 最多ステップの23ステップ

2部構成: PlanningとGeneration

user-stories.mdは328行、23ステップで構成されます。行数ではworkflow-planning.md (480行) が最大ですが、ステップ数ではuser-stories.mdがInceptionフェーズ最多です。

構造はPart 1 (Planning: Step 1〜14) とPart 2 (Generation: Step 15〜23) の2部構成になっています。この2部構成は、第9回で解説したterminology.mdの「Planning vs Generation」の区別そのものです。計画を立ててから承認を得て、その後に成果物を生成します。

インテリジェント・アセスメント

Step 1の前に、user-stories.mdには「Intelligent Assessment Guidelines」という独自のセクションがあります。User Storiesの実行が必要かどうかを、3段階の優先度で判断するためのガイドラインです:

優先度 判断 例
High Priority 常に実行 新しいユーザー機能、UX変更、マルチペルソナ
Medium Priority 複雑さに応じて判断 バックエンドのユーザー影響、パフォーマンス改善
Skip 単純なケースのみスキップ 純粋なリファクタリング、孤立したバグ修正

なお、ソースにはMedium Priorityの判断に使う「Complexity Assessment Factors」(6項目) も別途定義されています。

そしてデフォルトのルールとして「When in doubt, include user stories AND ask clarifying questions (迷ったら、ユーザーストーリーを含めて明確化質問もする) 」があります。第9回で解説したoverconfidence-prevention.mdの「聞きすぎるくらい聞け」という方針と同じ考え方が見られます。

INVEST基準の明示

Step 4では、生成するユーザーストーリーがINVEST基準に従うことが明示されています:

  • Independent (独立している)
  • Negotiable (交渉可能)
  • Valuable (価値がある)
  • Estimable (見積もり可能)
  • Small (小さい)
  • Testable (テスト可能)

第3回で「アジャイルのユーザーストーリーの適用」として触れた内容が、ルールファイルで明示的に指示されています。ただし、これはプロンプト指示であり、AIモデルがINVEST基準に完全に準拠したストーリーを生成する技術的保証ではありません。

5. workflow-planning.md: ワークフローの計画

ファイルの巨大さの理由

workflow-planning.mdは480行で、inceptionディレクトリ最大のファイルです。その理由は、このステージが「CONSTRUCTIONフェーズを含む後続すべてのステージの実行/スキップを決定する」要 (かなめ) だからです。

Brownfield向けの詳細分析

workflow-planning.mdの約半分はBrownfield (既存コードベースがある) プロジェクト向けの分析に費やされています。Step 2のサブセクションとして以下の4項目が定義されています:

  • Step 2.1 Transformation Scope Detection (Brownfield Only): 単一コンポーネントの変更か、アーキテクチャ変革か
  • Step 2.2 Change Impact Assessment: ユーザー影響、構造変更、データモデル変更、API変更、NFR影響の5領域（※Brownfield限定の指定なし）
  • Step 2.3 Component Relationship Mapping (Brownfield Only): 依存関係グラフの作成
  • Step 2.4 Risk Assessment: リスクの評価

さらに独立したステップとして:

  • Step 5 Multi-Module Coordination Analysis (Brownfield Only): 複数モジュールの更新順序、並列化可能性、テスト戦略

Greenfieldプロジェクトでは「Brownfield Only」と指定された分析がスキップされるため、同じステージでもBrownfieldとGreenfieldで実行時間が大きく異なります。

Mermaidフローチャートの生成

Step 6では、実行計画をMermaidフローチャートとして視覚化します。スタイルルールも具体的に定義されています:

スタイル 色 用途
Material Green (#4CAF50) 緑 常に実行 / 完了済み
Material Orange (#FFA726) 橙 CONDITIONALで実行
Material Gray (#BDBDBD) 灰 CONDITIONALでスキップ
Material Purple (#CE93D8) 紫 開始/終了

第9回で解説したcontent-validation.mdの「Mermaidバリデーション」が、ここで生成されるフローチャートに適用されます。

6. application-design.md: 4つの設計成果物

「詳細なビジネスロジックは後で」

application-design.mdの冒頭に重要な注記があります:

**Note**: Detailed business logic design happens later
in Functional Design (per-unit, CONSTRUCTION phase)

Application Designは「高レベルのコンポーネント識別とサービス層の設計」に焦点を当て、詳細なビジネスロジックはCONSTRUCTIONフェーズのFunctional Designに委ねます。第5回で解説した段階的な具体化の考え方と一致する構造です。

4つの成果物

# 成果物 内容
1 components.md コンポーネント定義、責務、インターフェース
2 component-methods.md メソッドシグネチャ、高レベルの目的、入出力型
3 services.md サービス定義、責務、オーケストレーション
4 component-dependency.md 依存関係マトリクス、通信パターン、データフロー

component-methods.mdには「Note: Detailed business rules will be defined in Functional Design (per-unit, CONSTRUCTION phase)」という注記が付いています。メソッドシグネチャ (メソッドの名前・引数・戻り値の型の定義) は決めるが「中身」は決めません。Inceptionフェーズの役割が「何を作るか」であり「どう作るか」ではないことが、成果物のレベルにも反映されています。

7. units-generation.md: 分割のルール

2部構成

units-generation.mdもuser-stories.mdと同じく、Part 1 (Planning: Step 1〜11) とPart 2 (Generation: Step 12〜19) の2部構成です。

Unit of Workの定義

冒頭でUnit of Workが厳密に定義されています:

**DEFINITION**: A unit of work is a logical grouping of stories
for development purposes. For microservices, each unit becomes
an independently deployable service. For monoliths, the single unit
represents the entire application with logical modules.

第9回で解説したterminology.mdの用語定義がここで実践されています。マイクロサービスではUnit = Service、モノリスではUnit = アプリケーション全体 (内部にModuleを持つ) 。

3つの成果物

# 成果物 内容
1 unit-of-work.md ユニット定義、責務
2 unit-of-work-dependency.md 依存関係マトリクス
3 unit-of-work-story-map.md ストーリーとユニットの対応表

unit-of-work-story-map.mdは、第3回で生成されたユーザーストーリーと、ここで分割されたユニットを紐づける成果物です。この対応表により「どのストーリーがどのユニットで実装されるか」のトレーサビリティが確保されます。

7ファイルに共通するパターン

inceptionディレクトリの7ファイルを俯瞰すると、以下の共通パターンが見えます:

  1. コンテキストのロード: 前ステージの成果物を読み込む
  2. 分析: ユーザーのリクエストや既存コードを分析する
  3. 質問の生成: 曖昧な点について質問ファイルを作成する
  4. 回答の分析: 回答の矛盾や曖昧さをチェックする
  5. 成果物の生成: テンプレートに従って成果物を生成する
  6. 承認待ち: ユーザーの明示的な承認を待つ (workspace-detection以外)
  7. 進捗更新: aidlc-state.mdとaudit.mdを更新する

この共通パターンにより、多くのステージは一貫した構造を持っています。

まとめ

第10回はINCEPTIONフェーズの7つのルールファイルについて説明しました。今回学んだことは以下です。

  • workspace-detection.mdは6ステップで完結する最短のステージで、承認なしの自動進行が特徴です
  • reverse-engineering.mdはBrownfieldプロジェクトで「常に再実行」のポリシーを持ち、8つの成果物テンプレートで既存コードベースを体系的にドキュメント化します
  • requirements-analysis.mdは「プロダクトオーナーの役割を担え」というロール指定と4段階のインテント分析が特徴です
  • user-stories.mdは最多の23ステップで、INVEST基準の明示的な指示とインテリジェント・アセスメントを含みます
  • workflow-planning.mdは最長の480行で、Brownfield向けの詳細分析とMermaidフローチャート生成を含みます
  • application-design.mdとunits-generation.mdは「INCEPTIONでは何を決め、何をCONSTRUCTIONに残すか」の境界を明確にしています

次回予告

第11回では、constructionディレクトリの6つのルールファイルを解説します。functional-design.md (ドメインエンティティとビジネスルールの設計) 、nfr-requirements.md / nfr-design.md (非機能要件の2段階設計) 、infrastructure-design.md (論理→物理のマッピング) 、code-generation.md (Brownfieldの「コピーファイル禁止」ルール) 、build-and-test.md (6種のテスト戦略) を読み解いていきます。