---
title: "ソフトウェアファクトリーとコード設計と顧客価値"
date: "2026-11-15T00:30:00+09:00"
slug: "posts/2026/11/15/code-design-after-agents"
description: "業務でコードを読むことがほとんどなくなった現在も、コード設計を重視している理由を説明します。開発速度は顧客の認知負荷で律速されるため、差別化要因は機能適合性という品質になります。品質を維持するには、人とエージェントがビジネスロジックを把握しやすい設計が必要です。"
themes: ["typescript", "architecture"]
ogIcon: typescript
private: false
---

## 背景

### 私の近況

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

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

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

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

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

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

<Figure name="factory-structure" />

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

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

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

## 結論

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

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

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

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

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

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

> 🤖 Claude Code より
> 
> DORA の [AI Capabilities Model](https://cloud.google.com/blog/products/ai-machine-learning/introducing-doras-inaugural-ai-capabilities-model) も、ユーザー中心の視点を欠いたまま AI を導入すると、誤った方向に速く進むだけになりうると指摘しています。

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

<Figure name="scenario-matrix" />

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

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

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

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

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

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

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

<Figure name="conflict-sequence" />

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

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

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

<Figure name="logic-scattered" />

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

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

## ビジネスロジックの配置

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

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

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

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

## コード設計とビジネス

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

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

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

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

<Figure name="logic-centralized" />

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

## おわりに

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

関数型ドメインモデリングの原則は、エージェント向けのスキル [kamae](https://kosui.me/posts/2026/04/08/functional-ts-principles) として公開しています。動物病院の予約とカルテ管理を題材にした[ハンズオン教材](https://fp-with-ts-hands-on.kosui.workers.dev/)（[リポジトリ](https://github.com/iwasa-kosui/fp-with-ts-hands-on)）も公開しています。設計スタイルの一例として参考にしてください。
