変化を抱擁するドキュメントの作り方 - ビジネスルール駆動開発がもたらす、コードとの新しい関係

Transcript

1. 変化を抱擁する ドキュメントの作り方 ビジネスルール駆動開発がもたらす、コードとの新しい関係 スタディプラス株式会社 伊尾木将之
2. 今日話すこと 1 ドキュメントとコードの関係 25 2 年、何が試されてきたか。どこで詰まってきたか ビジネスルール駆動開発（BRDD） 「何が真か」を正にする。私たちの提案 3 miko BRDD のフレームワーク。全チームで約半年、動かしてきた実際 2
3. ドキュメントとコードの関係 Par t 1 / 3
4. 包括的なドキュメントよりも 動くソフトウェアを アジャイルソフトウェア開発宣言（2001） 4
5. なぜドキュメントよりもコードを重視したのか コードを重視した理由は 2 つ。 大量のドキュメント問題 —— 動かないものに工数をかけることへの反論 腐っていく問題 —— 更新しなくても、システムは止まらない 前者は、アジャイルな開発が広がって解決されつつある（ようにみえる）。一方で、ドキュメント を捨てることはできません。 合意や整理のためには依然として必須 コードは「どう動くか」は明確だが、「なぜそうなのか」は表現が難しい エンジニアでなくても読める 5
6. ドキュメントが腐っていく問題 ドキュメントとコードが重複するため、２重管理になる 更新しなくても「すぐには」困らない。気づいた頃には、実態と乖離している コード 書いてある通りにしか動かない ズレない なぜそうなのかは残らない 意図が読めない ドキュメント エンジニア以外にも通じる 読める 更新されたか分からない 今もズレていないか分からない 得意なことが、逆になっています。 6
7. 腐っていく問題をどのように解こうとしたか 大きく 3 つの方向が試されてきました。どれも実際に効いていて、今も現役です。 01 02 ドキュメントを、実行されるコードその ものにする 残す場所を決め、更新を規律で守る コードで 代替する テスト・BDD DDD 命名 03 人手で 頑張る ADR / Wiki プロセスで縛る ドキュメントから コードを生成する ドキュメントを正にして、実装を導出 する MDA ローコード SDD 7
8. DDD や宣言的プログラミング 問題の捉え方 コードから離れているからズレる。言語の機能で what を表現すればいい 効いていること 残る限界 ドキュメントがコードそのものなので、乖離しようがない scattering / tangling ズレない how ではなく what を書ける モジュール機能・ユビキタス言語・命名で意図に寄せる 言語の制約に当たる 意図かどうかを区別できない 下の 31 は、バグ？ ビジネスの意図？ def cancellable?(order) !order.shipped? && order.confirmed_at > 31.days.ago end 8
9. BDD 問題の捉え方 実行されるテストコードを、仕様書として捉える 効いていること 残る限界 実行されるので、外れれば落ちる 「何が真か」ではなく「この場合はこうなる」の列挙になる ズレない保証 ツールが普及した rspec などで、書く習慣まで定着している 書けるのは、個々の具体例 ケース数が膨大になる 決めごと 1 つに対して、境界の数だけケースが生える 実際、弊社の 1 リポジトリは 9,562 ケース。リビングドキュメント（ --format documentation の出力） は 2万行を超える。 9
10. 人手で頑張る 問題の捉え方 コードは実装の詳細にしか答えない。残す場所と、守る規律が要る 効いていること 残る限界 ADR / Wiki / docs as code 実装完了の条件に入れる、レビューで見る、量を減らす 人にとって自然な形で書ける なぜ決めたかを残せる ADR は今も現役 維持が人に残る 続かない 更新しなくてもシステムは動く 人手でメンテは現実解ではない。 10
11. ドキュメントからコードを生成する 問題の捉え方 どちらかを諦める必要はない。ドキュメントを正にすれば、両方取れる 効いていること ドキュメントが正 MDA / CASE ズレない SDD —— AI ツール、ローコード・ノーコード に詳細な仕様を書かせて、AI に実装させる 残る限界 生成できるだけの詳細さが要る 結局、仕様レベルまで書き込む 人間が読めない 量が多く、レビューが追いつかない 道具は変わったが、詰まる場所は同じ。 11
12. どれも、片側しか取れていない コードで代替する 人手で頑張る ドキュメントからコードを生成する ズレない 維持は人任せ ズレない保証と、読める形。25 年、どちらか片側の話でした。 読める形 区別できない／ケース膨大 仕様レベルまで書かされる 12
13. ビジネスルール駆動開発 Par t 2 / 3
14. 提案 ビジネスルールを AI にメンテさせ、そのビジネスルールから AI に実装させる —— ビ ジネスルール駆動開発（BRDD） 読める形 ズレない Studyplus ビジネスルールという抽象度 BR が正、 コードが従 社で実践している開発手法です。 14
15. ビジネスルール 「このビジネスで何が真か」の宣言。 BR・仕様・ビジネスロジックは層構造で、下にいくほど 「どう実現するか（how）」になります。 出荷前かつ 24 時間以内であれば、キャンセルできる what 仕様 キャンセル実行時、出荷済みならエラーを表示 how ビジネスロジ ック order.cancellable? && !order.shipped? how BR BR の宣言 ↓ （挙動） ↓ （コード） はビジネスの判断が変わらない限り不変。 15
16. ビジネスルール例 #### 注文ライフサイクル（ORD） - ORD-01 バックオーダー（在庫なし受注）は受け付けない - ORD-02 出荷済みの注文は、ユーザー操作ではキャンセルできない - ORD-03 キャンセル猶予期間は、注文確定から 24 時間とする - ORD-04 猶予期間経過後のキャンセルは、管理者操作でのみ可能とする 汎用性のない、かつ、コードを読めばわかる情報は書かない 仕様に相当する情報は書かない 16
17. BR 高 の抽象度 高すぎる 「ユーザー体験を大切にする」—— 客観的に判定できない。方針であって、ルールではない 抽 象 度 出荷前かつ 24 時間以内であれば、キャンセルできる —— 誰かが選んだ、判定できる決めごと 低 低すぎる 実装の詳細、エラー文言の文面 —— コードや仕様書の二番煎じ。書かなくてもコードにある BR BR の抽象度は、この中間。 17
18. 合理的な代替案テスト 「合理的な代替案はあったか？」を問う 記述 AI 合理的な 代替案はあったか？ あった 選んだ主体がいる ＝ BR 無かった 選びようがない ＝ BR ではない は抽象度が低いルールを生成しがちなので、このテストでふるいにかける 18
19. 合理的な代替案テストの例 出荷前かつ24時間以内であればキャンセルできる。キャンセルするとステータスが cancelled になる。 記述 出荷前 24時間以内 ステータスが cancelled になる 代替案は？ 出荷後も可にできた 48時間でもよかった 判定 BR 候補 BR 候補 —— not BR 問うているのは理由ではなく、選択の余地があったかどうか。 19
20. BR BR を正として実装 で「読める形」は取れた。残るは「ズレない」。 これまで BRDD コード ビジネスルール ↓ 後追いで、気が向いたら ↓ その帰結として ドキュメント コード 更新しなくても動く → 腐る BR を変えないと、コードが変わらない → 腐りようがない 20
21. SDD と何が違うのか 同じ AI を使っている。違うのは、何を書かないと決めているか。 SDD —— 仕様レベルの記述なので、how まで書き込むことになる 生成できるだけの詳細さが要る。量が増え、レビューが追いつかない BRDD —— 仕様よりも高い抽象度。how を書かない 書くのは「何が真か」だけ。how は AI がその場で導く how を書かないから、人間が読める量に収まる。 21
22. ビジネスルール駆動開発（BRDD）Flow から始まって、BR を更新して終わる 提案 BR BR 検証 への変更を proposal ファイルとして定義 proposal の BR に攻撃的検証 proposal を元に実装 実装 BR 更新 22
23. 提案（proposal） 「やりたいこと」を、BR への変更提案（proposal）にする # ## 既存の有料契約アカウントに、初期のトライアルデータを付与する 背景・動機 トライアル機能のリリース前から有料契約のアカウントには... ## ビジネスルールの変更 （どの BR がどのように変更されるか） ## 機能仕様 ... ユーザーとの対話から得た背景などが記載される 仕様などの詳細な情報も、ここに記載される 23
24. 検証（攻撃的検証） 書いた BR を、6 軸で AI に攻撃させる 検証軸 内部矛盾 不完全性 境界の曖昧さ 時間軸の破綻 ビジネス毀損 悪用耐性 例 ルール A と B が同時に成り立たないケース 決まっていない境界条件 「出荷準備開始」の正確な定義は？ 日付変更線をまたぐとどうなる？ このルールで売上が減るシナリオは？ ルールの抜け穴を突く行動パターン 24
25. 実装 を入力にして、コードを書く 実装の入力は proposal と、対象ケイパビリティの BR proposal 何を作るかは決まっている。how だけを起こす BR の更新も同じ PR でマージ コードだけ進んで BR が置いていかれる、が構造上できない 次のタスクは、その更新された BR を読むところから始まる 「読んで始め、残して終わる」 25
26. 両方を満たす ズレない 読める形 コードで代替する 人手で頑張る ドキュメントからコードを生成する BRDD 26
27. Par t 3 / 3 miko
28. miko ビジネスルール駆動開発のためのフレームワーク AI エージェント用スキル群 28
29. miko の世界観を動かす仕組みが miko。 ビジネスルール駆動開発（BRDD）のためのフレームワークで、AI エ ージェント用のスキル群として提供しています。 BRDD フローに対応するスキルを提供 BRDD 提案: /miko-propose 検証: /miko-harae 実装: /miko-quick-impl OSS として公開中 https://github.com/studyplus/miko 29
30. BRDD Flow と miko のスキル から始まって、BR を更新して終わる 提案: /miko-propose BR BR への変更を proposal ファイルとして定義 検証: /miko-harae proposal の BR に攻撃的検証 proposal を元に実装 実装: /miko-quick-impl BR 更新 30
31. ケイパビリティ ではシステム全体を、ケイパビリティ単位で分割して管理します。 miko システム全体 注文管理 在庫管理 契約管理 22 rules 18 rules 31 rules … や proposal の管理単位。miko のスキルはケイパビリティ単位で実施 1 つの変更に必要な情報が、過不足なく収まる大きさ BR 大きすぎると関係ないルールまで読み込む。小さすぎると関連ルールが分散する 31
32. ディレクトリ構成 miko/ glossary.md system_high_level_design.md order/ business_rules.md high_level_design.md harae.md proposals/ ← ケイパビリティ ← ビジネスルール ← ハイレベルデザイン ← 祓えの指摘の記録 ← 変更履歴 2026-02-02-cancel-window-extension.md 2026-05-09-guest-checkout.md inventory/ business_rules.md high_level_design.md harae.md proposals/ ← ケイパビリティ 32
33. business_rules.md 注文管理 ビジネスルール ## 背景 # EC の注文受付から出荷指示までを担う... 操作の定義 ## 1. 注文確定 / キャンセル / 返品受付 / 支払期限切れ ... ビジネスルール・カタログ 注文ライフサイクル（ORD） ## 2. ### ORD-01 〜 ORD-04 実装マッピング ORD-02 → Ec::Order#cancellable? ... 決済タイミング（ ） ### PAY PAY-01 〜 PAY-02 実装マッピング ... 33
34. 実装マッピング BR がコードのどこで実現されているか、miko が持っておく ORD-02 出荷済みは キャンセル不可 1 Ec::Order#cancellable? Ec::CancelOrderService admin/orders_controller.rb つの BR の実現箇所は、4 割が複数箇所にまたがる（最大 13 箇所） AI がその全部を知らないと、読む範囲が定まらない 一部だけ読んで、誤解したまま実装する／実現箇所を見落とす 読むべき場所を確定させるために、実装マッピングを持ちます。 34
35. ハイレベルデザイン から実装する際の、モジュール構造などの情報。 ケイパビリティ単位に high_level_design.md が生成される 主要モジュール・テーブル、独特な構成（特定クラスを継承など）を記述 BR が「何が真か」 なら、こちらは「どこに何があるか」 BR だけでは、AI は独自の書き方は分からない。実装マッピングが行き先を、 ハイレベルデザイ ンが周辺の地形を渡します。 BR 35
36. high_level_design.md # 注文管理 ハイレベルデザイン ## この機能は何か EC の注文受付から出荷指示までを担う... ## 概念モデル 注文 / 注文明細 / 支払 ... 外部システムとの関係 決済プロバイダ / 在庫管理 / 配送管理 ## 処理の全体像 ## 注文確定 → 在庫引当 → 決済 → 出荷指示 ... ## 設計上の特徴 非同期決済による結果整合性 / 単価スナップショット 36
37. 実践している規模 バックエンドの全チームが、このワークフローで開発しています 以下は、そのうち 1 リポジトリの数字です（運用 約半年）。 26 ケイパビリティ 581 ルール ビジネスルール 6,100 124 本 （＝変更履歴） proposal NOTE: 行 3,628 行 ハイレベルデザイン 22 ルール 1 ケイパビリティあたり 中央値 69,865 行 242 テーブル アプリケーションコード ケイパビリティの分割・統合は、これから起きると思っています。 37
38. BRDD Flow と miko のスキル から始まって、BR を更新して終わる 提案: /miko-propose BR BR への変更を proposal ファイルとして定義 検証: /miko-harae proposal の BR に攻撃的検証 proposal を元に実装 実装: /miko-quick-impl BR 更新 38
39. 提案（propose） 「やりたいこと」を、BR の改訂案にする ❯ /miko-propose contract 有料契約に初期データをつくって /miko-propose [ケイパビリティ名] [やりたいこと] 人は、変えたいことを話すだけ。miko が質問してくれる miko は関係する BR を読み、 どのルールがどう変わるか を proposal にまとめる 変更の背景・動機・ルールの差分が、そのまま変更履歴として残る ここではまだ実装しない —— 判断を固め、合意してから実装へ 39
40. 提案（propose）: よかったこと 「有料アカウント向けに初期データを作って」と依頼。miko は BR を読んで、こう指摘しました。 「永久無料アカウントと検証用アカウントも必要ですか？」 アカウント種別ごとの扱いが、BR に決めごととして書いてあった コードにあるのは「現在の実装」だけ —— そこには「他にも種別がある」は書かれていない 人が思い出す前に、miko が先に聞いてきた 抜けに気づくのが、実装より前になりました。 40
41. 検証 祓え（harae） ❯ /miko-harae contract/proposals/2026-06-09-init-data-for-paid-contracts.md 検証軸 内部矛盾 不完全性 境界の曖昧さ 時間軸の破綻 ビジネス毀損 悪用耐性 例 ルール A と B が同時に成り立たないケース 決まっていない境界条件 「出荷準備開始」の正確な定義は？ 日付変更線をまたぐとどうなる？ このルールで売上が減るシナリオは？ ルールの抜け穴を突く行動パターン 41
42. 検証 祓え（harae）: よかったこと 既存のメール送信機能で、予期しない問題が起きました。その機能の BR を miko で書き起こ し、祓えにかけると—— 指摘の中に、その問題の再現フロー が出てきた 実装の誤りではなく、決めごとの考慮漏れ —— コードを読んでも「仕様どおり」にしか見え ない BR と祓えが先にあれば、実装の前に 潰れていた 42
43. 実装（quick-impl） proposal を入力にして、コードを書く ❯ /miko-quick-impl contract/proposals/2026-06-09-init-data-forpaid-contracts.md BR の更新も同じ PR でマージ 次のタスクは、その更新された BR を読むところから始まる 「読んで始め、残して終わる」 43
44. エンジニア以外にも広がっている が BR を読み、miko に聞いている 挙動の確認 PdM これまではエンジニアに聞いていた。それが miko に聞くようになった 新規開発の検討 既存のルールを壊さないか、新しい穴を作らないか 調査用クエリの組み立て BR CS を見ながらクエリを書いてくれるスキルを用意 もたまに使う —— ユーザー対応で、バグか仕様かを確認するために 44
45. 人と AI の協働 決めるのは人、書くのは AI。指示を出す相手から、相談しながら実装する相手になりました。 miko は、判断が要る箇所を抽出して、人の確認をフローに入れている。 全部を読み直させない。判断が要るものだけを出す 実際に人が直すのは、2 つだけ 仕様レベルの記述の混入 —— 抽象度が下がっている。代替案テストで落とす BR の意図のズレ —— 書かれていることは正しいが、決めたかったことと違う どちらも、コードを読んでも分からない種類の誤りです。 45
46. 「変化を抱擁せよ」を、ドキュメントに が変化を抱擁するために積み上げてきたのは、コード側の仕組みでした。 テスト、リファクタリング、継続的インテグレーション 変化に耐えるコードは、これで手に入った 同じことをドキュメントでやるには、粒度とコストが壁だった。 粒度は BR が決める。コストは AI が引き受ける ドキュメントも、変化を抱擁する側に回れる。 XP 46
47. まとめ ビジネスルール駆動開発 ビジネスルールを中心に、人と AI が協働していくプロセス miko BRDD のためのフレームワーク。OSS として公開中 miko github.com/studyplus/miko
48. 付録 Appendix
49. どう始めるか いきなり全システムの BR を抽出する必要はない 必要なケイパビリティだけ、既存コードから逆算して始められる が既存コードを読み、BR の初版を起こす なので、既存システムでもすぐに始めることが可能 /miko-new-cap ケイパビリティ動かせば、次のタスクはその BR を読むところから始まる 関心のあるところから、1 ケイパビリティずつ増やせます。 1 49
50. BRDD フローから外れたら？ 緊急対応など、フローに乗らないこともあります。 後から BR を合わせる /miko.catchup がコードを読み直し、 BR との差分を出す 採否は人間が決める。結果は proposal として残る スキルを使わず、手で直してもよい どの経路で直しても、最新の BR が次のタスクの出発点になる。 50
51. BR が変わらない変更は？ リファクタリング、性能改善、バグ修正など。 BR の変更を伴わない proposal も、同じフローに乗る 変更の背景と内容は、proposal に書く BR は変わらない —— ビジネスの判断が変わっていないから 更新されるのは実装マッピング（実現箇所が動くため） 実装が動いても BR が動かないのは、BR が実装から独立しているから。 51