命名から始めるSpec Driven

by Kurowi

Slide 1

Slide 1 text

Slide 2

Slide 2 text

Slide 3

Slide 3 text

Slide 4

Slide 4 text

Slide 5

Slide 5 text

Slide 6

Slide 6 text

Slide 7

Slide 7 text

Slide 8

Slide 8 text

©2025 Kyash Inc. 進め方アイデアを書き出す CONCEPT.md 煮詰まっていなくていいのでまずは設計方針を立てる定義を生成し、曖昧さを炙り出すアイデアから定義となるコードを生成してもらうテーブル定義、構造体、オブジェクトなどやりやすい形式。「この型でいい？」「この制約で足りる？」を考える重要なのは各要素が何を表すかをコメントまで書くこと違和感を見つける一貫性のない命名, 曖昧な表現, 増えすぎたENUMなど AIとの対話で違和感を解消「この単語は適切？」「別の事象と混同しない？」「増えすぎているので分けるべきでは？」アイデアがなくても「〜すべきでは？」と投げかける設計の軸は自分で持ち、AIの引き出しを活用する 1 2 3 4 何度も往復する

Slide 9

Slide 9 text

Slide 10

Slide 10 text

©2025 Kyash Inc. 違和感の見つけ方(一例) 一貫性のある用語を使用しているか？文脈が揃っていない用語はロジックも歪む例: billing ↔ refund … 一見対称に見えるが文脈が違う増えすぎていないか？登場人物が増えるときはまず疑ってみるカラムが増える … 別のエンティティの責務ではないか？区分値が増える … 別の概念を混ぜていないか？テーブルが増える … ドメイン境界を誤っていないか？ひとことで説明できるか？説明が長くなったらブラッシュアップの余地がないか考える定義にコメントを付けておくとコメントの肥大化で気づきやすい

Slide 11

Slide 11 text

Slide 12

Slide 12 text

Slide 13

Slide 13 text

©2025 Kyash Inc. 例1: 同じ文脈の言葉を使っているか？初期設計の用語ユーザーが支払うべき額 … billing_amount ユーザーに支払うべき額 … refund_amount ユーザーが支払った額 … paid_amount ユーザーに返金した額 … refunded_amount 初期設計の違和感違和感 billing ↔ refund: 対称的でない refund ↔ refunded: 違いが分かりづらい refund: お金が動いていないことが表現できていない paid: ユーザー, 会社, 誰が払った？

Slide 14

Slide 14 text

©2025 Kyash Inc. 例1: 同じ文脈の言葉を使っているか？ AIとの対話 billing ↔ refund が対称的でなくて気持ち悪い。何か良い単語はない？いいですね。テーブル定義に落とし込んでください会計用語で debit / credit があります。 debit は借方、credit は貸方で完全に対称です debited_amount: 請求権の発生額 credited_amount: 返金義務の発生額 collected_amount: 実際に回収した額 refunded_amount: 実際に返金した額

Slide 15

Slide 15 text

Slide 16

Slide 16 text

©2025 Kyash Inc. 例2: 増えすぎていないか問題の発生初期設計の決済集約がもつステータス REQUIRES_REFUND REQUIRES_COLLECTION COMPLETED 新たな要件「要対応の取引」を抽出するクエリが複雑化 Before : WHERE status <> 'COMPLETED' After : WHERE status NOT IN ('COMPLETED', 'REFUNDED', ...) COMPLETEDのうち「返金取引」を区別したい statusにREFUNDEDを追加します

Slide 17

Slide 17 text

©2025 Kyash Inc. 例2: 増えすぎていないか AIとの対話 COMPLETEDでない取引を抽出するケースが複雑化しています。Statusに追加すべきでない可能性はありませんか？おっしゃるとおり運用状態と最終結果は別の関心事です (言語化) final_statusの追加を提案します _statusが増えていく未来が見えてイケていないです。適切な一単語はありませんか？ outcome, conclusion, verdict... outcomeにしましょう

Slide 18

Slide 18 text

©2025 Kyash Inc. 例2: 増えすぎていないか結果 statusとoutcomeの分離 status … 現在の状態 collection_due ↔ ↔ refund_due balanced requires_action outcome … 最終的にどうなったか collected / refunded reversed / voided written_off / escheated → 要対応 … status <> ‘balanced’ だけでシンプル → statusがbalancedになったときに確定 ✓ 関心事が分離されシンプルに

Slide 19

Slide 19 text

©2025 Kyash Inc. いろいろつきつめた結果全usecaseがこれだけ func(uc *HandleEventUseCase) Execute( ctx context.Context, event PaymentEvent, ) error { nexus := repository.FindByOrigin(...) nexus.Apply(event) repository.Save(nexus) return nil } 10種類のイベントすべてがこのパターンに収束言葉を詰めた結果、スペック駆動ツールが不要なほどシンプルに

Slide 20

Slide 20 text

Slide 21

Slide 21 text

Slide 22

Slide 22 text

©2025 Kyash Inc. 既存システムへの適用一見具体的な指示で始めても記事にいいね機能を追加してください。 - likesテーブルを作成 (user_id, article_id, created_at) - POST /articles/:id/likes でいいね - DELETE /articles/:id/likes で取消 - いいね数はarticles.likes_countで管理

Slide 23

Slide 23 text

©2025 Kyash Inc. 既存システムへの適用指示は具体的でも、用語と責務が曖昧なまま進むと継ぎ足しの設計に追加要件でテーブルが増殖自分：コメントにもいいねしたい AI：comment_likesテーブルを作成します（article_likesと別になった…） → 抽象化（Likeable）を検討しなかった振る舞いの置き場所がバラバラ自分：いいねのロジックを共通化して AI：LikeService.execute(user, article)を作成します（さっきはUser.like(article)だったのに…） → 「誰がいいねする責務を持つか」を決めなかった用語の衝突自分：ブックマーク機能も追加して AI：Favoriteモデルを作成します（LikeとFavorite、何が違うの…？） → 「Likeとは何か」を定義しなかった

Slide 24

Slide 24 text

©2025 Kyash Inc. 命名から始めるアプローチ Step 1：用語を決めるいいねする → like いいね取り消し → unlike (cancel? remove?) いいね済み → liked Step 2：ドメイン層の責務を考える Like（Entity） user_id, target_type, target_id Likeable（Interface）いいねされる対象が実装 Article, Comment などさまざまなものが対象になる LikeService 重複いいね防止いいね数の集計ロジック Step 3：ここでスペック駆動「LikeServiceを実装して。 Likeエンティティを作成し、対象のlikesCountをインクリメントする」用語と責務が決まっているので AIの実装が一貫する

Slide 25

Slide 25 text

©2025 Kyash Inc. DDDっぽいけどDDDではないやったことを振り返ると・使う用語を統一した・曖昧な概念を明確にした（statusとoutcomeの分離）・モデルに振る舞いを持たせた DDDで言う「ユビキタス言語」と「ドメインモデル」に近いただし、本来の DDDとは違う DDDは「ドメインエキスパートと開発者の協働」が核心 AIはドメインエキスパートではない AIは広く浅い知識を持っているだけビジネス上の正解はAIにはわからないそれを決めるのは人間