ソフトウェアファクトリーとコード設計と顧客価値

kosui
岩佐 幸翠 / kosui

テックリード @ 株式会社カケハシ

背景

私の近況

最近、業務でコードを読むことはほとんどなくなりました。

私は、認証基盤、ID基盤、端末・証明書基盤など、5つ以上の医療系プロダクトから使われるプラットフォームシステムをテックリードとして牽引しています。しかし、最近の私はエンジニアというよりもPdMに近い振る舞いを取っており、想像以上に複雑な医療機関の様々な制約、要求される高度なセキュリティ、そして医療機関に存在する多様なステークホルダーの顧客体験を成立させるために悪戦苦闘しています。

厳しく制限されたネットワーク環境、一つの端末を複数ユーザーが共用する環境、頻繁に操作者が交代する業務フローなど、認証基盤屋を悩ませる要素がたくさんあります。

ソフトウェアファクトリーはコード設計を無意味にする?

そんな状況にあって、最近はソフトウェアファクトリーに設計・実装・レビューを任せることが増えました。あらかじめ顧客の置かれている環境やその制約、法令やガイドラインなどの情報をナレッジベースへ蓄積した上で、私がPRDやサービスブループリントで意図を記述すると、その意図とナレッジベースから、バックログと論点が生成されます。

私は論点に回答していき、回答に応じて実装とテストが生成され、レビューおよびそれを踏まえた修正すら自動で完結します。

人の関与箇所の比較
ターミナルで指示する開発の時間軸 横軸を時間とし、上段に人、下段にエージェントを置いた図です。人の指示、エージェントの実行、人の確認が交互に3回続きます。2回目と3回目の間に、人が離席している区間があります。この区間では、エージェントも停止しています。課題ごとに人の入力が必要です。 離席 人 課題ごとに人の入力が必要 エージェント 時間 停止 指示 実行 確認 指示 実行 確認 指示 実行 確認
ソフトウェアファクトリーの時間軸 横軸を時間とし、上段に人、下段にエージェントを置いた図です。人は、左端で意図を作成し、中ほどで論点に回答し、右端でマージを判断します。エージェントは、左端でバックログと論点を生成し、そこから分岐して、複数の課題を3本のレーンで並列に実装とレビューします。3本のレーンは、開始と終了の時刻がずれながら重なり合って進みます。人が離席している区間でも、レーンは止まりません。各レーンの出力は、右端のレビュー待ちにたまり、そこから人のマージの判断へ線が伸びます。人の関与は3点に限定されます。 離席 人 人の関与は3点に限定 エージェント 時間 意図を作成 論点に回答 マージを判断 並列に実行 バックログと 論点を生成 実装⇄レビュー 実装⇄レビュー 実装⇄レビュー レビュー待ち
ループの構造 上段の左に、人が記述する意図と、ナレッジベースが並ぶ図です。この2つから、エージェントがバックログと論点を生成します。バックログからは、課題を取得する線が worker と reviewer の循環へ向かいます。論点からは、人が回答する線が人へ向かい、仮の案で実装を継続する破線が worker と reviewer の循環へ向かいます。worker と reviewer の循環は、指摘が解消されるまで自動で反復されます。worker と reviewer の組は複数が並列に動きます。循環の出力は PR になり、PR の上には、PR ごとに作成する解説ページがあります。人が解説ページを読んで判断する線は、判断・マージに向かいます。PR と判断・マージの間には、上限のあるレビュー待ちの列があります。上限に達すると、新しい課題を取得しない経路が worker に戻ります。下部では、retro がスキル改善の PR を作成し、その PR が判断・マージに届きます。アニメーションでは、意図から課題が生まれ、worker と reviewer が PR を作り、レビュー待ちが上限に達すると止まり、人が判断・マージすると再び流れる様子を、16秒周期でくり返し示します。 意図 ナレッジベース 生成 バックログ 論点 課題を取得 人 人が回答 仮の案で実装を継続 ×N worker ⇄ reviewer 指摘が解消されるまで 自動で反復 PR PR ごとに作成 解説ページ 人が読んで判断する レビュー待ち (上限あり) 判断・マージ 上限に達すると新しい課題を取得しない retro スキル改善の PR 待機中
ターミナルで指示する開発では、課題ごとに人の入力が必要です。ソフトウェアファクトリーでは、人の関与は意図の作成、論点への回答、マージの判断の3点に限定されます。

一方、従来もgrill-meスキルなどを利用して論点を整理していくことはありましたが、それらにおける「論点」とはせいぜい1-2行の質問でした。ターミナルに張り付きながら一つ一つの質問に回答していくため、私が回答をやめれば当然ながら開発も止まっていました。

ソフトウェアファクトリーにおける「論点」とはそれとは粒度が異なっていて、ややサイズの小さいADRぐらいのものが中心です。それに、論点が未決の状態でも、エージェントが仮説を立てて実装を次々と進めていきます。結果として、私がレビューする単位もプルリクエストではなく、そうした小粒のADRが中心になりつつあります。

そうした中で、カンファレンスや勉強会においてコード設計に関する話題は、以前よりも少し減っているように感じます。私自身が主催するハンズオン形式の勉強会でも、参加者から「AI がこれだけコードを書くなら、コード設計のビジネス価値とは何か?コード設計は不要ではないか?」という疑問が提示されました。

結論

実は、コードを読まなくなった現在のほうが、コード設計の重要性は高いのでは?と考えています。

開発速度を上げても、顧客が認知できる機能の量には上限があります。いくらたくさん機能を作っても、正しく認知して使ってもらえなければ意味がありません。

そのため、これからのソフトウェア事業における差別化要因は品質、とくに機能適合性になるのではないでしょうか。そして、機能適合性を維持するには、PRDに記述したビジネスの関心とコードの構造が十分に近づいていて、人もエージェントもビジネスロジックを把握しやすい設計になっている方が嬉しい、と私は考えます。

開発速度は顧客の認知負荷で律速される

すでに述べたとおり、機能を多く開発しても、顧客がその機能を正しく認知しなければ、機能は利用されません。私たちも生成AIが狂ったように吐き出した”Design Doc”を大量に読んでうんざりしましたよね?顧客だってそれは同じで、その機能が期待通りに動作しなかったり、自分の課題を解決してくれなかったりしたら、利用を継続してくれません。

みなさんもご存知の通り、エージェントの導入によって、開発できる量は増えました。一方で、顧客が新しい機能を理解して業務に組み込む速度は、開発チームのリリース頻度とは無関係に決まります。

🤖 Claude Code より

DORA の AI Capabilities Model も、ユーザー中心の視点を欠いたまま AI を導入すると、誤った方向に速く進むだけになりうると指摘しています。

私が担当している薬局の業務は、この認知負荷の制約がとくに強い領域です。1台の端末を複数のユーザーが共有し、執務室には複数台の端末があり、ユーザーは複数の店舗を移動します。

端末・ユーザー・店舗の組み合わせによるシナリオ
薬局のシナリオの組み合わせ 行は「1台の端末を複数のユーザーで共有」「1人のユーザーが複数の端末を使う」「1人のユーザーが店舗を移動する」の3つ、列は「順番に使う」「並行して使う」の2つの表です。「1人のユーザーが複数の端末を使う」の「並行して使う」のセル、「2台で同時にセットアップする」が、次の不具合の場面です。 順番に使う 並行して使う 1台の端末を 複数のユーザーで共有 交代でログインする 別ユーザーの作業が 残った端末を使う 1人のユーザーが 複数の端末を使う 別の端末で 作業を続ける 2台で同時に セットアップする 1人のユーザーが 店舗を移動する 移動先の店舗で 作業を続ける 2店舗で同時に 作業する 次の不具合の場面
端末の共有、複数台の端末、店舗間の移動の組み合わせにより、PRD で検討すべきシナリオが増加します。

このような環境で想定外の挙動が発生すると、問い合わせにつながります。そして、問い合わせの対応には人件費がかかるため、想定外の挙動は単に顧客の時間を奪い満足度を低下させるだけでなく、サービス提供者の運用コストにも跳ねるわけです。特に顧客シナリオがこれだけ複雑な場合、ユーザーストーリーを網羅的に検討した上で、その内容が設計や実装に正しく反映されている必要があります。

開発速度で差別化できないのであれば、差別化要因は品質です。品質特性にはさまざまなものがありますが、この記事では、そのうち機能適合性を扱います。

PRDを起点にした検証の限界

ソフトウェアファクトリーの運用を開始した当初、私は「PRDやDesign Doc、ADR、仕様書を十分にレビューすれば、ある程度のプロダクトの品質は担保されるだろう。後は実機デモを見ながらフィードバックしよう。」と考えていました。

今回提供する機能の顧客価値、スコープを十分に吟味し、想定される様々な業務フローとその場合の振る舞いをスイムレーンやシーケンス図で整理し、それぞれのユースケースにおいてどのようなデータの参照・変更がされるか確認しました。また、事前にいくつかユーザーペルソナを定義し、各ペルソナが操作に迷うケースや業務を継続できなくなるケースがないかを、エージェントに検証させました。

さらに、共同でテックリードをしている @_manji0 が開発している manji-0/rdra-ish-dsl というツールを用いて、RDRAという要求分析の手法によってユースケース・データ・状態といった要件を明らかにし、それをDSLによる定義へ変換し、さらにDSLに対してTLA+による検証を実行できたことで、仕様バグや設計バグを検出できました。

しかし、それでも検出できなかった不具合があります。詳細は省略しますが、複数の端末で実施する作業において、あるユーザーが1台の端末で作業を開始していると、別の端末でもその作業を再開する、という振る舞いが実装に含まれていました。この振る舞いはPRDやサービスブループリントなどに記述されていませんでした。ユーザーが複数の端末で並行してセットアップを進めると、この振る舞いによって不整合が発生します。

端末Bによる作業の再開と不整合
PRD の想定のシーケンス図 ユーザー、端末A、端末B、作業の記録の4つのライフラインのシーケンス図です。ユーザーが端末Aで作業を開始し、端末Aが作業を作成します。ユーザーが端末Bでセットアップを開始し、端末Bも作業を作成します。その後、端末Aと端末Bが、それぞれ自分の作業を更新します。作業は端末ごとに独立しています。 ユーザー 端末A 端末B 作業の記録 作業を開始 作業を作成 セットアップを開始 作業を作成 作業 A を更新 作業 B を更新 端末ごとに独立した作業
PRD では、端末ごとに独立した作業を作成することを想定しています。
← 戻る
1 / 6
実際の実装のシーケンス図 ステップ 1 ユーザーが端末Aで作業を開始し、端末Aが作業の記録に作業を作成します。 ユーザー 端末A 端末B 作業の記録 作業を開始 作業を作成
ユーザーが端末Aで作業を開始し、端末Aは作業の記録を作成します。ここまでは PRD の想定と同じです。
2 / 6
実際の実装のシーケンス図 ステップ 2 同じユーザーが端末Bでセットアップを開始します。 ユーザー 端末A 端末B 作業の記録 作業を開始 作業を作成 セットアップを開始
同じユーザーが、端末Bでもセットアップを開始します。ユーザーが複数の端末を並行して準備する場面です。
3 / 6
実際の実装のシーケンス図 ステップ 3 端末Bが、進行中の作業を作業の記録から取得します。作業の記録は、端末Aの作業を端末Bに返します。 ユーザー 端末A 端末B 作業の記録 作業を開始 作業を作成 セットアップを開始 進行中の作業を取得 端末Aの作業
端末Bは、新しい作業を作成せずに、進行中の作業を取得します。端末Bが取得する作業は、端末Aで開始した作業です。
4 / 6
実際の実装のシーケンス図 ステップ 4 端末Bが、端末Aの作業を再開します。この振る舞いは PRD に記述がありません。 ユーザー 端末A 端末B 作業の記録 作業を開始 作業を作成 セットアップを開始 進行中の作業を取得 端末Aの作業 作業を再開 PRD に記述の ない振る舞い
端末Bは、端末Aの作業をそのまま再開します。この振る舞いは PRD に記述されていません。
5 / 6
実際の実装のシーケンス図 ステップ 5 端末Aと端末Bが、同じ作業の記録を更新します。 ユーザー 端末A 端末B 作業の記録 作業を開始 作業を作成 セットアップを開始 進行中の作業を取得 端末Aの作業 作業を再開 作業を更新 端末Aの作業を更新 PRD に記述の ない振る舞い
端末Aと端末Bが、同じ作業の記録を更新します。
6 / 6
実際の実装のシーケンス図 ステップ 6 2台の更新が衝突し、作業の記録に不整合が発生します。 ユーザー 端末A 端末B 作業の記録 作業を開始 作業を作成 セットアップを開始 進行中の作業を取得 端末Aの作業 作業を再開 作業を更新 端末Aの作業を更新 PRD に記述の ない振る舞い 不整合:同じ作業を2台が更新
2台の更新が衝突し、作業の記録に不整合が発生します。PRD を起点にした検証は、この振る舞いを対象にしていません。
PRD では端末ごとに独立した作業を想定していましたが、実装では端末Bが端末Aの作業を再開し、不整合が発生します。

そして、この不具合は、私たちが実際のコードをたまたま読んでいた際に、想定外の分岐に気づいたことで判明しました。

それまで要求を適切にモデリングした気分でいた私たちは、ちょっと落ち込みました。私が要求を要件へ落とし込むためにブラッシュアップし、さらに様々な視点で検証されたモデルは、そもそも実際の実装と乖離していたのです。

実は、そのプロジェクトではかなりレガシーなシステムを対象に開発をしていました。あらゆるデータの変更はミュータブルで手続き的で、コントローラからリポジトリまで、至るところにビジネスロジックが分散していました。ビジネスロジックが複数のファイルに分散しているようなコード設計では、そうした要求・要件の各項目に対応する箇所を探すために、すべてのファイルを読む必要があります。別の端末で作業を再開するロジックはいわゆるリポジトリと呼ばれるデータの取得・保存を担う箇所に記述されており、茫漠としたコンテキストの中に埋もれてしまいました。

ビジネスロジックの分散と照合の漏れ
← 戻る
1 / 3
コードの構造 ステップ 1 左にPRDの3つの業務ルール、右にコードの4つのファイル(画面、ハンドラ、バッチ、リポジトリ)を並べた図です。各ファイルには、コードの行を表す横棒があり、ビジネスロジックを表す横棒は複数のファイルにあります。リポジトリの1本の横棒は灰色で、取得条件というラベルが付いています。 PRD 作業を開始する 作業を完了する 中断した作業を同じ 端末で再開する 画面 ハンドラ バッチ リポジトリ 取得条件 ビジネスロジック ほかのコード
ビジネスロジックが、画面、ハンドラ、リポジトリなどの複数のファイルに分散しています。
2 / 3
コードの構造 ステップ 2 PRDの3つの業務ルールそれぞれから、コード側のビジネスロジックを表す横棒へ線を引いた図です。線は、画面、ハンドラ、バッチ、リポジトリの複数のファイルにまたがります。 PRD 作業を開始する 作業を完了する 中断した作業を同じ 端末で再開する 画面 ハンドラ バッチ リポジトリ 取得条件 ビジネスロジック ほかのコード
PRD の各項目に対応する箇所を見つけるには、すべてのファイルを読む必要があります。
3 / 3
コードの構造 ステップ 3 リポジトリの取得条件の横棒を、破線の枠で囲んだ図です。吹き出しに、別の端末での再開に関するロジックが、データの取得条件として記述されている、と書かれています。この横棒とPRDの間には、線がありません。 PRD 作業を開始する 作業を完了する 中断した作業を同じ 端末で再開する 画面 ハンドラ バッチ リポジトリ 取得条件 別の端末での再開に関するロジックが、 データの取得条件として記述されている
別の端末で作業を再開するロジックは、データの取得条件として記述されています。業務の用語で記述されていないため、照合の対象から漏れます。
ビジネスロジックが分散していると、データの取得条件として記述されたロジックが PRD との照合から漏れます。

ビジネスと実装の構造が乖離していると、この問題は大きくなります。検証したPRDやモデルと実際のコードが対応しなくなり、検証結果が実装の品質を保証しなくなります。

ここで、「型検査、テスト、CIがあれば、設計を気にしなくても検証基盤で品質を担保できる」という反論もありそうですね。確かに検証基盤は重要ですが、そうした検証すらも茫漠としたコンテキストの中に埋もれたコードの一部なわけです。実装から要求・要件への逆方向の確認には、複雑怪奇な実装に埋もれてしまったビジネスロジックを、要求・要件と照合できる形で抽出できる必要があります。

ビジネスロジックの配置

ビジネスロジックがデータ構造、検索条件、技術的な分岐の中に埋もれていると、人もエージェントもそのロジックを認識しにくくなります。

「何でこのコントローラーだけ複雑な認可処理をしてるんだよ、見つけられねえよ」と思ったことはありませんか?人間に認知能力の限界があるように、エージェントのコンテキストウィンドウには上限があります。あちこちのファイルへ無秩序に書かれた分岐を精一杯読み解くことにコンテキストを消費すると、その分だけビジネスロジックに割り当てられるコンテキストは減ります。

PRDに記述されたビジネスの関心と、コードに実装されたビジネスロジックの構造が一致しているほど、変更容易性は高くなり、PRDと実装の乖離も防ぎやすくなります。このため、エージェントがビジネスロジックに集中でき、エージェントにとって認知負荷の低い設計が必要です。

ビジネスロジックが業務の用語で一か所に集約されていれば、人もエージェントも、コードからPRDへの逆方向の確認を偶然に依存せず、定常的に実施できます。今回の不具合は、私が偶然コードを読んだことで検出されました。設計によって、この確認を定常的な工程にできると考えています。

コード設計とビジネス

どのような設計を採用すべきかについて、私は特定のスタイルに固執することは危険であると考えます。いくつか手札を持っておいて、それぞれの状況でどの手札を切るか、考え続けることが重要です。

たとえば、RailsでActiveRecordを使いながらクリーンアーキテクチャを無理に適用しても、うまく機能しません。フレームワークの前提に反する設計を採用すると、むしろ認知負荷が増大するだけです。自分たちがどんなビジネスを扱っているのか、そのためにどんな品質特性が要求されるのか、そのためにどんな設計が必要とされるのか、きちんと結びつけて考えることが重要です。

高効率なCRUDを生やしまくればどうにかなる仕事なのか、慎重に監査記録を残しながら状態遷移を厳しく制御する必要がある仕事なのか、そうした前提を置かずに⚪︎⚪︎⚪︎不要論などを唱えても意味がないわけですね。

ところで、現職ではTypeScriptによる関数型ドメインモデリングを採用しています。ものすごく乱暴に言えば、この手法では業務の状態と、状態間の遷移を一か所に集約して記述できます。画面、APIのハンドラ、データベースへのアクセスのようなI/Oはシステムの端に寄せ、ビジネスロジックはI/Oを持たない同期的な処理として記述します。少なくとも、状態が複雑な医療向けビジネスの場ではこの設計がかなりハマりました。

ビジネスロジックの集約と PRD との照合
← 戻る
1 / 3
コードの構造 ステップ 1 左上にPRDを薄い帯で示し、その下に入力、業務の状態と遷移、出力の3つの列を並べた図です。左の入力の列に画面とハンドラの札、中央に業務の状態と遷移の札、右の出力の列にリポジトリの札とデータベースの円柱があります。中央の札には、作業を開始する、作業を完了する、中断した作業を同じ端末で再開する、の3つの遷移が並び、札の下に入出力を持たないと書かれています。入力から中央へコマンドの矢印、中央からリポジトリへ新しい状態を保存する矢印、リポジトリから中央へ現在の状態を読み込む矢印があります。 PRD 入力 出力 画面 ハンドラ 業務の状態と遷移 作業を開始する 作業を完了する 中断した作業を同じ 端末で再開する 入出力を持たない リポジトリ 記録の 読み書きだけ データベース コマンド 新しい状態 を保存 現在の状態 を読み込み
画面、ハンドラ、リポジトリのような入出力をシステムの端に寄せ、業務の状態と遷移を入出力を持たない処理として中央に置きます。リポジトリは記録の読み書きだけを担当します。
2 / 3
コードの構造 ステップ 2 ステップ1の配置のまま、リポジトリの札の中の取得条件の横棒が、問題色の破線の枠に囲まれ、取り消し線で薄く表示されています。そこから中央の札の4行目へ、ビジネスロジックを移す矢印が引かれています。中央の札には、別の端末で作業を再開する、の遷移が4行目に加わり、問題色の枠で強調されています。 PRD 入力 出力 画面 ハンドラ 業務の状態と遷移 作業を開始する 作業を完了する 中断した作業を同じ 端末で再開する 別の端末で作業を 再開する 入出力を持たない リポジトリ 記録の 読み書きだけ データベース コマンド 新しい状態 を保存 現在の状態 を読み込み 取得条件 ビジネス ロジックを 移す
データの取得条件に埋もれていた『別の端末で作業を再開する』ロジックを、業務の遷移として中央に移します。ビジネスロジックが、入出力を持たない一覧に集約されます。
3 / 3
コードの構造 ステップ 3 PRDの3行とコードの4行を、横一直線の線で行ごとに結んだ図です。上の3行は対応があり、確認済みの印が付きます。4行目の「別の端末で作業を再開する」は、PRD側の「記述なし」の枠と結ばれ、PRDにない遷移として強調されます。 PRD 作業を開始する 作業を完了する 中断した作業を同じ 端末で再開する 記述なし 業務の状態と遷移 作業を開始する 作業を完了する 中断した作業を同じ端末で再開する 別の端末で作業を再開する PRD にない遷移
PRD と行単位で照合でき、PRD に記述のない遷移を差分として検出できます。
入出力を端に寄せてビジネスロジックを集約すると、PRD と行単位で照合でき、PRD にない遷移を検出できます。

この設計を採用しても、不適切なコードの記述は防げません。ただし、ビジネスロジックは特定の場所に配置されますし、状態のフローもとても明確です。それに、配置先から外れたコードをレビューで検出しやすくなります。

おわりに

開発速度では差別化しきれない時代になった今、これまで以上に品質が重要になっています。コードを読む機会が減った現在も、人とエージェントの両方がビジネスロジックの所在を把握できるコード設計が大事でしょう。

関数型ドメインモデリングの原則は、エージェント向けのスキル kamae として公開しています。動物病院の予約とカルテ管理を題材にしたハンズオン教材(リポジトリ)も公開しています。設計スタイルの一例として参考にしてください。

Markdownとして表示

関連記事

kosui
岩佐 幸翠 / kosui

テックリード @ 株式会社カケハシ

医療SaaSの共通基盤を開発。TypeScriptと関数型プログラミングで堅牢なシステム設計を実践。