日本語DSLを SSoT (Single Source of Truth) として、AI生成コードを型・テスト・CIで検証しながら育てる、仕様駆動開発 (SDD: Specification-Driven Development) の実践チュートリアルです。
題材は、在庫ロット・販売案件・価格査定・販売契約を含む販売管理ドメインです。同じドメインDSLから F# と Kotlin の実装を作り、型安全性・ビルド速度・品質ゲート・AIエージェント適性を比較します。
Status: このリポジトリは、SDDチュートリアルとAIエージェントハーネス構築のための教材です。実装トラックやCIスクリプトが未配置の場合は、まずドメインDSLとステップガイドを読んで全体像を把握してください。
このチュートリアルでは、業務仕様を日本語DSLとして記述し、それを実装・テスト・CIの起点にします。
目指す状態は、単にAIにコードを書かせることではありません。AIが生成したコードを、型、プロパティベーステスト、CI、SAST、DASTなどの品質ゲートで検証し、継続的に改善できる構造を作ることです。
最終的には、CI結果をAIエージェントが読み取り、失敗から学習しながら修正を繰り返すハーネス構築まで扱います。
- AIを使った開発を、単なるコード生成ではなく開発プロセスとして設計したい人
- 仕様駆動開発、型駆動設計、関数型ドメインモデリングに関心がある人
- 業務ドメインの状態遷移を、型で安全に表現したい人
- AIエージェントが自走できるCI / 品質ゲート / ハーネスを作りたい人
- 日本語DSLで業務仕様を表現する方法
- DSLをSSoTとして、実装・テスト・CIへ展開する考え方
- 状態遷移を型で表現し、不正な操作をコンパイル時に防ぐ設計
- プロパティベーステストで業務ルールを検証する方法
- AIが生成したコードをCIで検証する構成
- CI結果をAIエージェントが読める形に整備するハーネス設計
このチュートリアルでは、以下の業務ドメインを扱います。
- 在庫ロット
- 直接販売案件
- 価格査定
- 販売契約
- 予約販売案件
- 委託販売案件
- 品目変換
ドメインモデルは、以下のような日本語DSLで表現します。
data 在庫ロット = 製造中ロット OR 製造完了ロット OR 出荷指示済みロット OR 出荷完了ロット
behavior 製造完了を指示する = 製造中ロット AND 製造完了日 -> 製造完了ロット OR 製造完了指示エラー
behavior 出荷を指示する = 製造完了ロット AND 出荷期限日 -> 出荷指示済みロット OR 出荷指示エラー
behavior 出荷完了を指示する = 出荷指示済みロット AND 出荷日 -> 出荷完了ロット OR 出荷完了指示エラー
状態をフラグではなく型として分けることで、業務上ありえない操作を実装前に排除しやすくします。
初めて見る場合は、次の順番で読むのがおすすめです。
- domain-model-section1.md 在庫ロットのライフサイクルを扱う最小のドメインモデルです。
- domain-model-section2.md 直接販売案件、価格査定、販売契約を追加します。
- domain-model-section3.md 予約販売案件、委託販売案件、品目変換を追加します。
- domain-model-sales-management.md Section 1〜3を統合した完全版のドメインモデルです。
- 01-steps/README.md Step 0〜30 の実装・CI・ハーネス構築ルートです。
読むもの:
- domain-model-section1.md
- docs/01-sdd-concepts.md
- READMEの「題材」「全体像」「F# / Kotlin の選び方」
ゴール:
- 日本語DSLが何を表しているか説明できる
- 状態をフラグではなく型で分けるメリットを説明できる
進める範囲:
ゴール:
- 在庫ロット、販売案件、価格査定、契約のAPIを実装する
- PBTとCIで業務ルールを検証する
- 品質ゲートを通過する状態を作る
進める範囲:
ゴール:
- CI結果をエージェント可読な形式に統一する
- 失敗から学習する仕組みを作る
- PRD完了まで自律的に反復するハーネスを構築する
日本語DSLを起点に、F# / Kotlin でAPIを実装し、CIで品質を担保する段階です。
扱う内容:
- DSLから型定義を作る
- 業務APIを実装する
- PostgreSQLとマイグレーションを導入する
- フォーマッター、リンター、PBT、カバレッジを導入する
- gitleaks、Trivy、SonarQube、OWASP ZAPなどの品質ゲートを追加する
Phase 1で作ったCIを、AIエージェントが自走するためのハーネスに拡張する段階です。
扱う内容:
- CI結果をSARIFに統一する
- ミューテーションテストを導入する
- アーキテクチャルールを検査する
- APIコントラクトを検証する
- SBOMを生成する
- エージェントの実行をOpenTelemetryで観測する
- CI失敗から学習し、AGENTS.mdへ知見を蓄積する
- PRD完了まで反復するRALPHループを構築する
| 重視するもの | おすすめ |
|---|---|
| DSLとの一致、型安全性、不正状態の排除 | F# |
| 組織導入、品質可視化、JVMエコシステム | Kotlin |
| AI生成コードの検証基盤を作りたい | どちらでも可。比較目的なら両方 |
詳細は docs/04-fsharp-vs-kotlin.md を参照してください。
| ドキュメント | 内容 |
|---|---|
| docs/00-overview.md | 背景、目的、PoCの前提、Exit Criteria |
| docs/01-sdd-concepts.md | SDD、DSL、SSoT、型で状態遷移を表す考え方 |
| docs/02-roadmap.md | Step 0〜30 の概要と既存stepファイルへのリンク |
| docs/03-ci-quality-gates.md | CI、PBT、verify、品質ゲート、ツール一覧 |
| docs/04-fsharp-vs-kotlin.md | F# / Kotlin の比較 |
| docs/05-agent-harness.md | Phase 2、SARIF、AGENTS.md、OpenTelemetry、RALPHループ |
| 01-steps/README.md | メインステップの索引 |
| 02-advanced-steps/README.md | Spring Boot 機能の代替実装 |
| 02-batch-steps/README.md | Spring Batch 機能の代替実装 |
- dsl-conversion-rules.md: DSLをコードへ変換するルール
- domain-model-section1.md: 在庫ロット
- domain-model-section2.md: 直接販売案件、価格査定、販売契約
- domain-model-section3.md: 予約、委託、品目変換
- domain-model-sales-management.md: 統合版ドメインモデル