#16 巨大な仕様書を"読ませたら"負けーーSSoTから生成する「読む人専用ビュー」

SSoTと「読む人専用ビュー」の概念

今回は、仕様を作るときとか、運用するときのことなんですかね。

そのときの SSoT、シングルソースオブトゥルース、信頼できる唯一の情報源について話を聞いてみたいなと思うんですけど、

これは、仕様文書を単一の信頼できるドキュメントにすべき、みたいな話なんですかね。

これはちょっと違っていて、ちょっと説明しながらやっていきます。

まず前提として、ちゃんとした仕様っていうのを考えてあげる。

この仕様って言ってるのは、この実装は合ってるよ、この実装は間違ってるよっていうのを、

振り分けることができるようなものを、私はちゃんとした仕様って呼んでいるんですけど、

こういうふうにちゃんとした仕様、人によって例えば、これはこっちかなとかっていうふうに、

プロダクトマネージャーに見てもらわなきゃいけないみたいな、あんまり良くない仕様ですよね。

そういうのなしに、みんな、これはこっちだよ、これはこっちだよって、ちゃんと分類できるのがちゃんとした仕様です。

ここではシーケンス図とか状態線図と一旦するんですけど、

これってちゃんと書くととっても規模が大きくなるんですね。

そうすると全てのメンバーに、はいじゃあこれ読んで理解してってやると、すごい負担が大きくなる。

例えば具体的には、あるウェブシステムがあって、

アドミン画面とユーザー画面がありますって時に、

例えばCSの人とかはアドミン画面使いますよね。

ユーザーの人っていうのはユーザー画面使うわけですけど、

この両方一度に全部理解しておかないといけないのっていうのは、

テックリードとかエンジニアのリードクラスだけで、

実際はCSの人だったらCSのアドミン画面のことだけ知っていればいいし、

ユーザーのことだったらユーザーだけの画面を知っていればいいっていう風になってるわけですよね。

ってことはこのシーケンス図とかにいらないところがたくさんあるってことなんですよ。

シーケンス図とか状態線図でここの状態別に見れなくていいなとかっていうのが結構あって、

そういう風にシーケンス図とか状態線図をうまく畳んであげることができると、

例えばCSの人はこのCSのアドミン画面周りだけを集中的にレビューしてくださいっていうときに、

ちょうどいい仕様、その人に最適化された仕様っていうのを見せることができるわけですね。

で、従来はそういう風に仕様を自動で畳んであげるとかっていうことを、

普通はみんなあんまり考えていなかったので、頑張って読んでくださいってなるか、

あるいは誰かが仕様のコピーみたいなの、解説書みたいなのを書いてあげて、

っていうようなことをやっていたわけですね。

だけどこれはツールによって解決することができて、

例えばシーケンス図だったら、この棒とこの棒を畳んで一つの棒にしちゃうとかってやると、

シーケンス図はぐっと簡単になるわけですよね。

そういう風にしてあげることで、

この人はここの部分だけフォーカスしてレビューしてほしいっていうニーズに応えられるようになると。

それが一つの大きな巨大な仕様から生まれる。

これがシングルソースオブツールです。仕様の美容をたくさん作ろうって話ですね。

なるほど。

読む人のために情報を削ぎ落としてあげましょう。

で、その上でちゃんと読みやすく、

その人の仕事がしやすいような形で見やすいようにしましょうねっていうような話ですね。

もう一つ、戦略的に話があって、

パートナー企業にここまでしか見せちゃいけないんだよなみたいなのってあると思うんですよ。

ドミニの知識、ここはちょっと秘密なんだよなみたいな時に、

やっぱり自動で切り張りしてきた方がいいわけですよね。

ここの部分だけ抜粋するみたいなことができると。

そうすると全体を知ってるのは私たちだけ、あなたは個別のところだけ知っていればいい。

こういうふうに戦略的な使用の運用もできるので、そういうふうなニーズもあります。

ドキュメントの腐敗を防ぐ自動生成とAIの活用

なるほど。

ここは社外秘だから隠しておきたいっていうところがあって、

そこだけは削ぎ落とした状態で外部に提供する。

もしかしたら技術のドキュメントとかもそうかもしれないですよね、一部は。

そういったもののソースとなるものは、

全て単一のドキュメントから生成されるべきだよねっていう。

そうですね。

逆に言えば単一の信頼できるドキュメントからじゃなかったら大変なことになってくるんですね。

大変なことになりますね。

大抵ドキュメントが腐るわけで、

さっき言った例、よく解説文章みたいなのがコンフルエンスとかWikipediaに転がっていて、

大抵腐っているっていうのはどんな現場でもよく見かけるんじゃないかなと思っていて、

なので自動生成をコミットすることにしてあげるとかができると、

必ず常に最新のフレッシュなものが手に入るっていうのができますね。

逆に言えばですよ、

その巨大な単一の信頼できるドキュメントに手を入れないと、

アップデートをしないと、

末端の核ビューが更新できないっていう意味でもあるんじゃないかなって、

若干思っちゃった気がする。

その通りなんですよ。

いいところに気がつきましたね。

ただ実はそれ自体は悪いことばっかりじゃなくて、

一ついいことがあるんです。

なぜかというと、ビューってある側面をバラバラに見たものになってるわけなんですけど、

それがちゃんとうまくくっつくのかっていうのがわからないんですよ、バラバラに作っちゃうと。

個別に作ってしまうと、

そうそう、シーケンス図とこことここがくっつくはずなんだけど、

あれ、こっちだと足りてないぞとか、こっちで人多いぞとかっていうのがあったりすると。

論理というかロジックが噛み合ってないドキュメントがそれぞれできてしまうフールってことですよね。

なので一つのドキュメントにあって、

そこにいろんなテストとかビューを作成する機能を入れてあげると、

必ず整合する状態が強制されるんですね。

今時このシーケンス図とかは AIに書かせてあげることができるわけですよ。

つまり、私ここのビューのここ変更したいんだけどっていうと、

AIはちゃんとそれを理解して、その部分だけちゃんと変更してくれて、

しかも周りにテストがいっぱいくっついてるんで、

整合性とかどのっとるんとかっていうのは全部ちゃんとチェックした上でできるっていう意味で、

精々AIがうまくできるようになったから、

この道が現実的になったっていうことですね。

そうですよね。だから3年前とかにやろうとしても絶対無理ですね。

CSの人が現場で仕事をしていく中で、

絶対アップデートしたいドキュメントがあるわけで、

そのためだけに本体の方の巨大なところの、

じゃあここをいじってとか、

ここの部分はちょっと違うから、

わかんないけどいじらないでおいて、

みたいな感じになってしまうとすごく辛そうだなと思ったんですけど、

そこは全て今AIでカバーできるようになってるから、

今は問題ないよねっていうようなことなんですね。

昔でも仕様を専属する技術の人、

最近私はこれをマニピュレーターって呼ぶようにしてるんですけど、

このマニピュレーター、よくDTMとかの文脈で、

音楽とかを作るわけじゃないんだけど、

譜面とかに落としたりするっていう記述者、初期みたいな人のことを

マニピュレーターと呼ぶそうなんです。

だからドメイン知識がないんだけど、

その仕様をどう書けばいいのかっていう知識をすごく持っている。

こういうふうにあなたの言ってることはこういうこと、

仕様で言うとこういうことですよって示せる人がマニピュレーターですね。

そのマニピュレーターがシリーズの人とかにヒアリングしながら、

ミーティング1時間でここをウォークスリルしてみましょうって言って、

それで実際にウォークスリルしてみて、

こことこことここ違いますねってなったら、

その場で即座に本体を直すっていうふうな運用をしていれば、

できなくはなかった。

確かに。

その単一の信頼できるドキュメントの管理者ですよね。

そうです。

管理チームというか。

そういった、逆に言えばそういうチームがないと、

理想的なシステムっていうかドキュメントっていうのは

運用できないよねっていうところが、

AIによってチームがAIに置き換わるみたいなイメージなんですかね。

そうですね。

AIに置き換えて何ならスキルとかにしてあげると、

それぞれの人のパワー、エンバワーできるんで、

すごくいいですね。

C4モデルとツールによる整合性検証

ここでさっき言ってたシーケンス図とか状態遷移図の話で言うと、

前回の検証のツールみたいなところのやつも

ここでは使われてるっていうことですかね。

ここでは使われてます。

テストの一環として使われていますね。

これ実際にぐりあげさんの仕事でやってたりするんですかね。

やってますやってます。

例えばC4ダイアグラムっていう図があって、

C4ダイアグラムっていうのはこのシステムがあります。

周りにステークホルダーとしてAさんBさんCさんがいますとかっていうのがあって、

それぞれがどんな関係で結ばれてるかっていうのをやるコンテキストダイアグラムっていうのがレベル1ってところにあるんですね。

このコンテキストダイアグラムとシーケンス図って多様するはずなんですよ。

なぜかというとシーケンス図にもAさんBさんシステムみたいなのがあって、

その間が矢印でシーケンスが繋がれていて、

AさんからBさんに矢印が繋がっているってことは、

C4ダイアグラムでもAさんからBさんに矢印が繋がってないとおかしいですよね。

っていうことで、あれここに矢印あるはずなのにシーケンス図だと矢印ないぞって気づくとおかしいぞ、不整合だってことが分かると。

こういうふうなのはツールで確かめることができて、

実際そういうツールを社内で運用していますね。

ではこのSSOTのドキュメントで運用しているドキュメントというものは存在するんですかね。

巨大のシーケンス図があって、本当に巨大なんで、

あれ理解できる人はなかなか大変なんじゃないかなって感じですね。

そこから切り取った折りたたまれたシーケンス図だったりとか状態遷移図、

あとはもしかしたら安易な言葉で書かれたドキュメント、日本語文章だったりとか、

そういったものが各CSの人向けとかそういった形で保存されていたりするんですかね。

そういうことです。

あとは自動英訳されたりとかもしますね。

確かに。英訳とかかなり相性良さそうですね、そういったところは。

しかも絶対翻訳漏れあるんで、AIとかでやらないと。

今はGitHub Actionsで日本語ブランチが更新が入ると、

英語ブランチにトランスレートしてプッシュされるというパイプラインが動いています。

実際それを今までだったら絶対これはい読んでって巨大なドキュメント全てを渡して読み解いて、

SSoT運用の課題とAIによる解決

多分それを読んだことによってドメイン知識が育まれていくみたいな感じかなと思うんですけど、

実際これ運用してみてどうです、他の人たち。

めっちゃやりやすくなったところってあったりするんですか。

これは使用の知識がある人っていうのがこの仕組みを整えきらないとまずワークしないっていうのが今の弱点で。

そもそもそうですよね。

今私が整備してるんでいいんですけど、私が例えばトラックに引かれていなくなったみたいな時があった時に、

この仕組みがちゃんと回り続けるのかってことについては課題があると思っていますね。

なるほど。とりあえず組み上げさんがいれば運用は回ってるけども、

いなくなったらちょっとどうなんだろう。

単一障害点ですね。

そうなんですよ。

そここそAIに任せたいですけどね。

ただAIに任せるためにはスキルとか書く必要あるじゃないですか。

あのスキルはある程度理論に基づいて書いた方が良くて、

その理論とかを知ってる方がその分かれ道になるんですよね。

なるほど。

ちなみにこういう仕様のドキュメント、

まあ仕様に限らないかもしれないですけどね、これもしかしたら。

あまねくドキュメント全部こうなんじゃねと思ったんですけど、

でもそれも全部仕様に基づくものから生成される何らかのドキュメントって考えると、

まあ一緒なのかなっていうところにおいては、

なんかこの形は割と今後あり得るというか、

まあ全部の会社やるべきかなと思ったんですけど、

どのぐらいに考えてます?

いやーこれはなかなか難しくて、

大きな仕様を見た時に人間ってどう反応するかっていうと、

まずウッってなって拒否するんですよ。

理解を拒否するんですよね。

すごい長文を見たらウワッてなって。

みんなSSAIのやつが情緒で嫌いみたいなこと言うじゃないですか。

みんな読まないんですよね結局。

読まないね。

だからこの大きな巨大の仕様をメンテするっていう考え方に、

この谷を乗り越えてたどり着くっていうのはなかなか難しくて、

実はツールの問題だって気づくのはだいぶ熟練した人だけなんですよ。

なるほど。

そういうふうなビューアーがあったりだとか、

ビューの生成パイプラインがあったりだとかすれば、

実はこの巨大なものをみんながみんな見なくて済むっていうのは気づくんですけど、

そもそもそれを気づくためには、

仕様がそういうふうな機械化読って言うんですかね、

SequencesとかPlantMLとかで書かれているっていうのが前提になるわけです。

だけど多くの人のところを見ていると、

SequencesがFigmaで書かれていたり、

状態先生がFigmaで書かれていたり、

Drawer用で書かれていたりとかって多いじゃないですか。

全然読めないんですよね。

バイナリで書かれているってことですね。

そうなっちゃうんで、

大きな仕様をメンテするってことはできないと思われている。

できないと思われて、

日本語でまあまあなんとかそれっぽくしていくのが限界なんだよってみんな思っているんだと思います。

諦め?

諦め。AIも同じですね。

AIも何も支持しないと人間の諦めに乗ってくるんですよね。

耐えろみたいなことをだからか言わなきゃいけない。

寄り添ってきますからね。

AIはね、褒めて欲しいから。

なるほど。

結構、だから高速にわきさんみたいに社内とか、

そういうチームでちゃんと推進していくような人が必要だよね、

現時点においてはっていうようなところなんですかね。

なんかやっぱりSAIとかの付き合い方とか見てると、

何もこう開発のことについてとか仕様のことについてとか知らずに開発すると、

やっぱりしっぺ返しを食らってるっていうのはよく見るんですよね。

例えば最近聞いた話だと、

バグが出たらそのバグのテキストを食わせて直させてっていうふうなボグラ叩きみたいなことをしてるみたいな話を聞いて、

あれあれだと思いますけどね。

それはまあまずいだろうと思うわけですよ。

だってそれ仕様がないってわけだからボコッて叩いたらその仕様がないままふわっと変更されて、

結局どう動いてるのが正しいのかってわからなくなっちゃうわけですよね。

でもAIは別にやれって言われたら、はい、うっすってやっちゃう。

直しますってね。

直しちゃって、また変って叩いたところの反対側がパッてみたいなことになってるってわけなんで。

しかもそれが気づかないですよね。

そう、気づかない。

だからそれはちゃんと仕様とかの段階で作り込んで状態整理とかあれば、

ボコッてやったときに裏側がボコッて出たらすぐ気づけるよっていうのをしてあげないと、

やっぱりAIも直しきれないし、人間もわかんないしってなっちゃうっていう意味で、

どういうものを作っていくとちゃんと自分の思った通りのものが正しくできるかっていう、

その流れについて知識がないとやっぱりまだ厳しい時代だと思っていますね。

今の聞いてちょっと思ったのが、

仕様記述の理論的背景：契約による設計（DbC）

言語化をすべきだっていうところは、

たぶんかなりの人、納得感ある言葉かなと思うんですよ。

ちゃんと言語化して何がやりたいのかを言語化してプロンプトとしてAIに渡しましょうみたいなのは

割とあり得るかなと思うんですけど、

その一歩先が、一歩二歩先が、

その言語化をするフォーマットをちゃんと整えましょうなんですかね。

そうですね。ただ実は一歩後ろに下がることもできるんですよ。

なるほど。

イエス・ノーで答えられる質問をAIにしてもらうっていう方法ですね。

そうするとこっちは何も言語化しなくていいわけですよ。

向こうから勝手に言語化して、これがいいですか、これがいいですか、あれがいいですかって聞いてくれたら

うん、違う、違う、オッケーですかっていうふうに言うとできる、言語化しなくても。

ただものすごく遠回りですね。

だから直接言語化できて、それをちゃんとしたフォーマット、

適するような、そのプロジェクトに適するような仕様のフォーマットに落とし込めれば一番早いというか、

一番いいんだけども、それができない場合は聞いてくれと。

AIにこういうことをしたいんだけど何か足りない情報がないかみたいに言うと。

イエス・ノーで答えられるやつ聞いてくれみたいなことをすると、ある程度はいけるし、

その先でその得られた情報を基に仕様のフォーマットに乗っ取って成形してくださいねみたいなことをすれば、

まだマシになるんじゃないかっていう。

そうですね、あとは本当に全くわからなかった時も、

せいせいにこのままいくと未来どうなってますかみたいな質問をすると、

割と予測してくれて、例えば仕様がないんでこうなりますみたいな、

多分さっきのモグラ叩きみたいなことも多分予見してくれるんじゃないかなと思うんで、

結局この今あなたのやってる作業はどれぐらい長生きするんですかっていう情報が与えられないと、

やっぱりどうしてもAIとしては手抜くとか平均的なものに寄せるみたいなことをしちゃうわけなので、

やっぱり思った通りのものはできないと思うんですよね。

そういうのはやっぱり、未来のことが気になるんだったら未来はどうなりますかって聞かないといけないし、

それぐらいの工夫っていうんですかね、必要な情報なんだよっていうのがわかってないと、

まだ使いこなすのは難しいなって感じます。

質問力っていうのかどうなのかわかんないですけど。

質問力っていうのか何なんでしょうね、シミュレーション力だとは思うんですよ。

シミュレーション力か。

このままいくとどうなるかってシミュレーションして、この未来になった、あ、ダメだな、破棄みたいな感じで、

この未来になる、あ、こいつの方がまだマシだなみたいな、そんなのをアーキテクトの頭の中でずっと考えてるわけですよ。

いや、なんとなくそれができるっていうのは経験値があるんですよね、きっと。

経験測からこっちのコードのスメルがちゃんと匂うみたいな感じと多分似てて、

どういうことが起こりそうだから、じゃあ先に質問しとくかだったりとか、先に言語化しとくかみたいないうことですよね、きっと。

そういったところがかなり重要になってくるかなってところと、あとちょっと質問があって、

さっきから仕様のフォーマットだったりとか、あとシーケース図が過読性があるような形で必要であるとか、

そういったところをちょっと聞きたいんですけど、ここら辺の仕様の理論的なところのベースとかってあったりするんですか?

はい、仕様をどういうふうに書けるかっていうのはすごくいっぱい研究されている分野で、

実は一つに絞ることがなかなかできないんですね、本当にいろんな流派がある。

どれもが派遣を取れたわけではないっていう感じ。

なるほど、宗教戦争をしてるんですね。

宗教戦争をずっとしていますね。

比較的派遣を取れたものの一つが、契約による設計っていうやつ、DBCと言われてるやつなんですけど、契約による設計、バートランド・メディアだったかな?が提唱したやつで、

オブジェクト思考入門っていう水色と紫のドンキーがあるんですよ、本当に分厚い本があって、

オブジェクト思考入門なのにこれが?みたいな感じだったんですよね。

この本に契約による設計っていうのが書かれてるんですけど、ただ実はあの契約による設計をバートランド・メディアの本で読んでもなかなか理解できないんですね。

なんか難しそう。

難しいんですよ、難しいというよりかは考え方一つではあるんだけど、今までの考えてたものをさっぱりリフレッシュしないとそれが入ってこないみたいな感じだった感覚で、ちょっと難しいですね。

アンラーニングしないといけないってことですね。

アンラーニングしないとなかなか入ってこないっていうのがあって、

一般にすごく契約による設計が誤解されていますね。

例えばアサート書けばいいんでしょうみたいな。

なるほど。

そういうふうに誤解されちゃいがちなんですけど、実際はちゃんとした理論に基づいたもので、あれはもともとはアントニー・フォア先生っていう人がいて、最近なくなっちゃったんですけど、

フォア先生っていうのはフォア論理っていうプログラムをどう書いたら今度はもうバグがないってことを証明できるかってことを考えた人で、

そのうちの一つがフォア論理っていうので事前条件と事後条件っていうのを書いてあげるとこういうふうな証明ができるようになるんだよっていうふうな仕様のある意味その形式的なパターンを一つ編み出した人なんですね。

なるほど。

フォア論理っていうのから段々とそこにいくつかのアレンジを加えたものっていうのがさっき言った契約による設計っていうもの。すごくアカデミックなバックグラウンドを持っているものなんですね。

なのでこのフォア論理に問題をいくつか解いたことある人は、ああこれね、分かる分かる、こういうふうに解答したらいいじゃんいいじゃんみたいな感じで分かるんですけど、これがないと何を言ってるんだこれは、分からんって言ってる感じになっちゃう。

なんかちょっと多分具体例あった方が分かりやすいかなと思ったんですけど、何かあったりします?

ありますね。例えば契約による設計だとフィズバズ関数がすごくいいから、私フィズバズ大好きなんでフィズバズ関数出すと。

フィズバズ関数って一般にその0以下の数値に対しては特に振る舞いが規定されていないんですよね。

だから0以下の数値が来た時には基本来ないんでどう振る舞ってもいいってしちゃう。

これが事前条件と呼ばれているもので、なのでこの事前条件っていうのを調べるために、0以下の呼び出しが来たら速攻切れるぞっていう行動を防御的に入れておく、これがアサートの考え方なんですね。

早期リターンみたいな感じですね。

アサートインプットが0より大きいみたいなことを書いておくと、0以下の数値が来た瞬間にクラッシュするじゃないですか。

なので私はこの仕様を守れなかったってことが分かる。だからアサートを入れてるってのがここに出てくるんですね。

一方でアサートがOKってなった後はちゃんと契約を果たさなきゃいけないっていうのがこの契約による設計の考え方で、

ちゃんと1以上の数値が来たら、1の場合は1が返るし、3の場合はフィーズが返るし、5の場合はバズが返るしっていう風にそれを守んなきゃいけないんですね。

こっちに関してはアサートが入るとかっていうのは特になくて、約束を守れとしか言われないので何のこっちゃってなっちゃうわけです。

でも要するにこれはテストしろって言ってるのと同じで、1の時は1が返るよね、3の時はフィーズが返るよねっていうテストをする。

そうするとOKだよって。テストはアサートを踏むようなものはしないっていう風に。

これが基本的な契約による設計のすごく一番根っこの部分ですね。

これのアサートを入れるって部分だけが1人歩きして、想像しやすいじゃないですか。

だからアサートを入れれば契約による設計なんでしょっていう風に誤解されちゃったっていう悲しい歴史があります。

表層的な理解だけ進んでるっていうようなところですね。

だからチャットGPTとかみたいな生成AIも契約による設計は最初は間違えて覚えています。

ウェブの文献に当たらせないと間違った答えを返してきますね。

契約による設計を学びたかったら何見たらいいんですか?

基本的にはThinkingモードを有効にするか、ウェブの文献の出典を確認してから言ってくださいみたいなことを言わないとすごく間違った答えを返されてきます。

例えばさっきのアサートの話から連想してその間違いが生まれるんですけど、

防御的にアーリーリターンでエラー返せばいいじゃんみたいなのがアサートの代わりに使われることがあるんですね。

これが例えばどういうことに使われるかっていうとRESTful APIでないリソースに来たときに404を返すかっていう風になったときに

それを防御的にリターンするわけじゃないですか、オブジェクトがなかったら404返すみたいな。

っていう風なのを契約による設計のアサートだと見出すっていうのが間違った解釈としてすごく有名で。

これは一斉に同じ間違いを踏んでいきます。

エラーに返すものが全部事前条件違反なんでしょって思っちゃうんですけど。

たださっき言った通り事前条件っていうのはそれを守らない方では基本的に来ないから

どんな風に振る舞ってもいいですよっていうものなんですよ。

例えばないオブジェクトにやったらそのままサーバーがクラッシュして死にましたっていうのを許せますかって言ったら

普通は許せないですよね。

正しい挙動が期待されているわけで、それは事前条件ではなくて自己条件っていうので

こういう時はこういうエラーが返るよっていう風に指定しなきゃいけない。

これを先生は間違って覚えている。

なるほど。

さっきの404ノットファウンドの例だったら

リソースがない場合の404ノットファウンドは

ちゃんと404が返ることを自己条件としてテストしないといけないってことですか?

そういうことです。

事前条件ではないってことですね。

事前条件ではないってことなんですよ。

テストされないってことですかね。事前条件違反ってことは。

だからもうちょっと実は緩く書くこともできて

なんかこう存在しなかったりとか

しなかった時とかは40系が返るよみたいな

どれでもいいよ40系だったらみたいなこととか

っていう風に緩めてあげることもできて

要するに答えは一つじゃないってことなんですね。

404だけを返すかそのメッセージはどうかっていうこととかは

全部決め切らなくてよくて

大雑把に言えば400系の何かが返るよねっていうのだけでも

自己条件はOKなんです。

なるほど。

だからそういう風にしてエラーは

ざっくり言うとここら辺のが返るよ

それうちどれが返るかは知らないけどね

実装依存だよね母みたいなことをしとくと

契約による設計に従っているってことになりますね。

そこからさらに踏み込んで

DbCの誤解とRESTful APIにおける適用

じゃあこれの場合は404

この場合は400とか

そういうステータスコードを返していくっていう

仕様にまで落とし込む話は

より深いというか実際の具体的な仕様の

フォーマットの話になっていくんですかね。

よくAPI仕様書とかで

何が来ると404を返せますよとか

よくRESTfulAPIとかのドキュメントに書いてあると思うんですけど

あれはこの契約による設計の考え方を

かなり下敷きにしていますね。

ただ本当は契約による設計って

これを返した後どういう状態になる

次はそのリクエストが送ったら

同じ結果になるとは限らないってことまで表明できるんですけど

そこまではなかなか

ドキュメント上は表現されてないことが多いなって思いますね。

難しいですよね。404でNot Foundで

で、もう一回やった時に404であるかどうかっていうところは

確実ではないですもんね。

本当はその404

裏側に実はデータベースみたいな状態があって

そのデータベースになければ404が返るよって書き方をするんですよ。

そのリクエスト直前にデータベースになければ

で、PUTコマンドとかPOSTコマンドとかで

その内部状態を変えるよっていうのがあったりすると

これでPUTとかPOSTとかがあった後は

404じゃなくて20系のものが返るんだとか

っていうのが分かるようになるっていうのがあって

そこまで書いてあげると契約による設計としてはバッチリって

なるほど。ただAPIドキュメントでそれは書かないよねっていうことですね。

そうなんですよ。

なので我々は苦しんで

テストとかでなんでこいつでこれが返るんやみたいなことが分からなくて

サポートに問い合わせて仕様ですみたいなことを答えられる

約束仕様だったら書けよみたいな話なんですけど

変なAPIの副作用としてリソース作られますみたいな

そういうことがあり得るってことですよね。

ドキュメントの通りにやってるんだけどなーって思ったら

スコープが足りませんでしたみたいなことがよくあって

そのスコープってどこに書いてあるんじゃって書いてないんですよね。

それどうやったら防げるっていうか

むずいだろうなーと思っちゃったんですけど

普通のAPIドキュメント

一般的なAPIドキュメントだとこのステータスみたいな感じで

全部網羅性の方が重要視されていて

ステータスコードとかの網羅性があって

その依存関係みたいなのって書きづらいわけじゃないですか。

書きづらいですね。

なので一応でも頑張って書こうとしてる流派がいました。

BDDと仕様の非決定性

それはBDDって呼ばれてる流派

Behaviour Driven Developmentの人たちで

BDDの人たちはITって何とかとかディスクライブ何とかって書きますよね。

なんであんなわけのわかんない書き方をしてるかっていうと

テストレポートが使用書になるんですよ。

ITって何ちゃら何ちゃらって書いてあると

ホゲホゲクラスは何々をされた時

Xが変わるみたいなことが書いてあるわけですね。

それのテストレポートをそのままHTMLとかにやってあげると

それ実は使用書として機能するんですね。

ちゃんとしたことが書いてあれば。

ちゃんと確認されてる。

なので実はそこまでBDDとかを使ってあげると繋がるんですけど

なかなかそういう風に繋がってる例を見ないっていうのが現実的なところですね。

まあそうですよね。

そのテストで書くことの観点と

外部にドキュメントとして公開していい観点って若干違いますよね。

そうそうそう。

さっきの冒頭の方でもあったように

社外に出していいデータかどうかっていうところも観点としてありますしね。

この裏の仕様としてあるけども

これは外に出すとあれだなみたいなのは絶対あると思うので

そこが結構ネックになってるんだろうなっていうのは考えるに。

ただ隠しておくことはできるんですよ。

それは非決定性って言い方をして

例えば200が帰る時もあるし

何らかの事情によって500系が帰ることもあるよって書いておくことはできるわけですね。

何の事情なのかは説明しない。

何かわかんないけど帰ってくる時あるんだなっていうのはわかるわけですよ。

それは仕様なんだなっていうのがわかる。

例えばそれだったらリトライとかを組んだりとかっていうふうなことを

考えたりもできるかもしれないしっていうのがあるんで

その理由を説明しなければ

外側としてはどう観測できるってことは

基本的に言及しても問題ないことが多いので

理由がそのテストのレポートに入ってなければ

大体は問題ないことが多いですね。

最近毎日XのAPIを叩いてるんですけど

所持状によって

XのAPIが時々失敗するんですよ。

時々500系のエラーを返してくると

リトライをしないといけないわけなんですけど

その500系のエラーが返ってくるっていうのは

テンポラリーなエラーだから

リトライしてねみたいなことが

ドキュメントに書いてあればいいってことですよね。

本当はもちろんそんなのがないよって言いたいでしょうけど

現実としてあるんだったら

それはあるって書いてるのがいいでしょうね。

500系のエラーの場合は

仕様マクロとビュー生成ツールの連携

おそらくサーバーのリソースが足りないだったりとか

普通にリクエスト詰まってるんだったりとか

全てのAPIに

APIエンドポイントに全て

その仕様が入りそうな気も若干しますけどね。

すごく序章な気が若干しますけど

私がよく仕様作る時には

仕様枕って考え方をよく入れていて

これ書いてないけど全部にこれが当てはまるよ

みたいな書き方をするんですよ。

例えばシーケンス図でこういう風に

このXマークが書いてある時は

非同期でこういう風な順番とかで

来ることがあるかもしれないよみたいな

そういうマークの意味なんだよみたいなのをつけて

うまくそのマクロ的な解釈をさせるってことを

よくやりますね。

それ重要ですよねきっと。

じゃないとコピペコピペコピペみたいな感じになっちゃいますよね。

ちなみにさっきのXマークが付いてたら

何々みたいなこととする

全部を何々とする

みたいなことを書いた時に

仕様として書いた時に

一番最初に言ってたビューごとに生成する

ツールではちゃんとコピペというか

展開されるような感じになってるんですか?

するようにも書けますし

あるいはリントとか書けた時に

これはこういう事情だから見なくていいよみたいな

そういう風にSSAIの結果に

トランプとして食わせるっていうこともできて

そういうのがより簡単ですね

ここ繋がってないのはRマークがあるからか

Xマークがあるからか

そういうのがあって

なるほどねっていう風になると

仕様マクロに書いてあるからこれはOKでした

みたいなところでちゃんとわかってくれるので

っていう感じですね

確かに

そこで大丈夫って

そうなんですね

最後に1個聞きたいのが

一番最初はビューを分けるって話だったんですけど

見る人によってビューを分けた方が見やすいよね

読みやすいよねっていうのは

それ確かにそうだなと思うんですけど

LLMによる巨大ドキュメントの読解 vs 専用ビュー

違う考え方で

どでかいドキュメントをボカンと

SSOTのドキュメント

シングルソースオブテリアスの

ドキュメントが1個ありますと

すごいでかいものが

重厚なものがありますと

それを各自のLLMで読まして

質問してもらえたらいいんじゃない

っていうのと

対決させるとしたらどうなんですかね

おそらく

最初の質問が思い浮かばないと思いますね

なるほど

だからやっぱり

最初からガイダンスとして

この人は見ればいいよみたいな

リードミーカーなんかに書いておくと

あなたはどれを見るべきですか

みたいな質問形式で

わかるようになるんですけどやっぱり最初に

オープンクエスチョンしちゃうと

わかんないけど何も質問できないんですよね

だから最初は選択肢を狭めたほうが

よくてある程度のプリセットを

使用技術のマニプレーターの人が

考えておいて

それの選択肢から選ばせるみたいなことをしたほうが

いいですね

確かに絶対

全ての人が

LLMに精通しているわけではないという

観点プラスいろんな

修飾度の人が

いるというユーザーの人がね

ユーザーがそのドキュメントを読む

ユーザーの修飾度がいるんだったら

まあ確かに

取っ掛かりがないと

いきづらいですよねいきづらいというか

わかんないですよね

急に例えば漁師コンピューターの

使用指紋でくださいみたいなこと言われたら

ははーってなるじゃないですか

何が起こるのそうそう何ができるの

みたいな感じになって

しかもあれですよね

冒頭初めにとかしょうがない感じですよね

そうそうそうそう

ナイスナイス

そういうなんか

こういう感じで進んでいきますよとか

インデックスとかもない感じでいきなり

ドドンと本題から入っている

重厚な使用書

そうそうそうそうなっちゃうので

やっぱりある程度

絞り込んであげて

っていうのは大事ですね

だからこそ

合わせたビュー

っていうのが重要になってくるよね

そうですね

テスト駆動開発とドキュメントの入口

なんとなくやっぱ

これ聞く限り

そういう仕組みっていうのは

なんか

大きい企業になればなるほど

欲しくなりそうな気がしますね

そうですねそう思いますね

どこの会社もやっぱり使用って苦しんでて

わかんないですもんね

部門でこう分かれてたらしたら

隣の例えばプロダクトのやつで

ちょっと関連するから

調べないといけないんだけど

どうやって調べるのか

わかんないみたいな

っていう時に

ここだけ見ててくださいねみたいな

ちゃんとアップデートされて腐らないドキュメントがあったら

それは

すごくない?ってなりますよね

私はでも他の人のコード読むときは

真っ先にやっぱテスト読むんで

これはこの人たちは

どんな振る舞いを保証したいのかっていうのを見て

これはこういうことやるものなのね

っていうのを理解していく

そしてそれはCIが動いてれば腐っていないので

なので下手にドキュメント読めるか

テスト見た方が早いっていうのは

本当に往々にしてよくあるって感じですね

だから今の例だと

国明さんにとっての

ドキュメントの入り口っていうのはテスト

だからそこの

SSOTを信頼して

しかもCIで

ぶっ壊れてないフェイルしてない

毎日ちゃんと動いてる

みたいなところの信頼性からそこを読んで

いきつつ

仕様を読み解いていくっていう

ビューとしての

テストってことですよね

はい

ただやっぱり使用マクロみたいなものも

テストにも作ることができて

RSPECとかだとスペックヘルパーって書くじゃないですか

あそこにさまざまなマジカルなことを書けちゃって

テストに急に変なの入ってるんだけど

何これ

わかんないみたいな

スペックヘルパー見に行くとそういうことかみたいになる

あれは良し悪しあるなって思うんですよ

使用マクロと同じなんですけどね

すごいことになって

多分GoToと一緒だと思うんですけど

飛びまくるんでね

そう

何のプラギンですかこれみたいなのが

よくあるっていう

スペックヘルパーの

1ファイルだけだったらいいけども

ファイル分割するんですからね

そうそうそうそう

この時だけこれぐらい漏れるんですよ

やめてくれーみたいになるっていう

大変なことになりますね

そういうテストの書き方の

技法的にもちょっと良し悪しは

あるよねっていう感じですね

だから使用マクロも良し悪しがあるんですよ

書く方を楽にするんだけど

読む方は楽にならないんですよね

使用マクロも同じ

読み解き方が複雑になるよね

やりすぎると

AI時代のコメントと開発フロー

そうやりすぎると

で、なんだけど

最近のAIはやっぱりなかなか間違いないんで

いろいろなことが

楽になりましたね本当に

唯一の大事なのは

AIは近くに置いたものしか読まないんで

近くに置いておく

グレップした時に引っかかるようにしておく

みたいなのがすごく大事ですね

遠かったら読みに行かないし

そもそもコンテキストに漏れたりとか

入らなかったりするんでね

できる限り

圧縮しつつ手元にある

情報で

LLMに読んでもらうみたいな

良いってことですね

それにちょっと

総スター数

エピソードをシェアする

Instagram シェア画像

埋め込みプレイヤーのカスタマイズ

プレビュー

カラーテーマ

メッセージを送信

henteko

感想

サマリー

目次

総スター数

コメント

感想を書く

こちらもおすすめ