「この変更が何に波及するのか」に答えるために、何を書き留めておくべきか

「この改修で、明日の予約受付は止まりませんか」と聞かれて、コードを見ても答えが出せないケースは多くあります。
コードを走査すればシステム構造は分かりますが、それが業務で何をしているかは、コードの外の資料や開発者の記憶に埋もれているからです。

本記事では、それを改善するために、何を資料として書き留めておくべきかを示します。なお開発を外部委託している場合には、後半の「開発を委託している場合」の節も、あわせてご参照ください。

結論から言えば、書き留めておくべきはユースケースです。誰が何のために叩き、その要求がどのリソースを順に通り、どの情報がどこに残るのかを、できるだけ業務の言葉で記述します。この単位で溜めておくと、改修するリソースを含むユースケースを探すだけで、波及先の候補が並びます。

既存のコードを読んで分かるのは構造までで、システムが業務で何をしているかは書かれていません#

コードを走査して機械的に取り出せるのは、どの関数がどの関数を呼び、どのテーブルを参照しているかまでです。取り出せないのは、その呼び出しが業務の何を実現しているかです。

例えば、診療予約システムで予約のテーブルを1行更新する処理があったとします。それが受付スタッフの予約管理の一部なのか、患者のオンライン予約の一部なのかは、コードのどこにも書いてありません。実際には両方から呼ばれていることもあります。
「この改修で明日の予約受付は止まりませんか」と聞かれているのに、コールグラフが返せるのは「この関数は3箇所から呼ばれています」までです。だから、業務の言葉で書かれた記録が、コードの外側に必要です。

波及に答えられる単位は、ユースケースです#

ここで増やすのは記録の量ではなく、記録の単位です。ユースケースとは、誰かが何かをした瞬間から、要求がリソースを順に通って、どこかに情報が残るまでの、一続きの筋書きです。

この単位で書き留めるための形式は、すでにOSSで公開されています。ADL（Architecture Description Language）という、構成図をJSONのテキストとして書くための仕様です。Reindeer Technology Pte. Ltd. が Apache License 2.0 で公開していて、特定の製品の契約を必要としません（<https://github.com/reindeer-project/ArchitectureDescriptionLanguage>）。仕様が公開されているので、この形で書いたファイルは、それを利用する他システムとの契約が終わっても、内容を読むことができます。

ADLのルートオブジェクトは6項目を必須にしていて、その1つが useCases です。ユースケース1本の必須項目は4つです。名称と説明、開始イベントである trigger、経路である traffics から成ります。

trigger には、誰が何をした瞬間に始まるのかを書きます。種別は利用者のWebアクセスと時限アクションの2つです。traffics はそこから先の経路を1区間ずつ並べたもので、各区間の始点は前段のトリガーか、1つ前の区間を指します。CloudFrontからAPI Gatewayを経てLambdaに届くなら、区間を3つ作って直列に繋ぎます。この例はスキーマの説明文にそのまま書かれています。

この形にしておくと、照会を2方向へ辿れます。改修対象のリソースを終点に持つ区間を探せば、そのリソースを使っているユースケースが出ます。そこから鎖を先頭まで遡れば、止まったときに困る相手と業務が出ます。変更した1行から業務まで、参照を辿ってつながります。

各区間には情報種別への参照も必須で、情報種別は機密フラグと個人情報フラグを持ちます。個人情報を運ぶ区間がどこまで伸びているかは、このフラグを追うだけで分かります。外部波及を聞かれたとき、最初に見るのはここです。

書きすぎは禁物です#

ADLの resources が持つのは、外部ファイルへの参照だけです。項目は種別と参照先の2つで、種別としてCloudFormationやTerraformなど7種類が選べます。参照先には .json .yaml .yml .tf のいずれかを指定します。インスタンスの大きさも環境変数もIAMの設定も、ここには入りません。

参照構造であるがゆえに、すでにCloudFormationやTerraformの定義ファイルに書かれている内容の転写が必要ありません。それは記載内容のメンテナンスや齟齬の解決コストが抑えられることを意味します。

ADLスキーマに文字数の上限があることも意味があります。ユースケースの名称は70文字まで、説明は500文字までです。500文字あれば、その業務が何のために存在して、止まると誰が困るのかは書き切れます。上限は、書きすぎを機械的に止める手段です。

また、ADLの入力必須項目は少なくありません。Webアクセスのトリガーは17項目、経路の各区間は12項目が必須です。その大半は日間アクティブ率やページサイズといった、性能とコストを見積もるための数値で、人が決める項目は5つほどです。波及の問いに答えるだけなら、初回は概算を置いて先へ進んで構いません。

AI時代にうまく適合します#

AIエージェント主導開発が一般化する中、ADLの下書きはAIに任せて、人は疑わしい箇所だけを直すべきです。ADLの各ノードには _meta という任意の項目があって、作成者と最終更新時刻、確信度の3つを持ちます。作成者は ai（AIエージェントによる記述） か、h:に利用者IDを続けた形（人が書くヒューマンノート） のどちらかです。確信度は0から1の数値で、AIが生成した値にだけ意味を持ちます。_meta を省略したノードは、AIが確信度1.0で作ったものとみなされます。

この設計が効くのは、人の手が入った箇所を後から見分けられる点です。人が直した区間は、作成者が h: の形に変わります。次にこの構成図を読むAIも、どこが推定でどこが人の判断かを区別して扱えます。半年後に自分で読み返すときにも、同じ印が効きます。

分担の線は、冒頭の事実がそのまま決めてくれます。コードから推定できるものはAIが埋めます。リソースの接続関係、ポート番号、インターネットを経由するかどうかは、定義ファイルを読めば根拠が出るからです。AIが埋め切れないのは、ユースケースとトリガーと区間の説明文、そして情報種別の2つのフラグです。この経路に個人情報が乗るかどうかを、AIはコードから確信を持って言えません。そこだけは人が決めます。

なおAIに任せた時、つまずいた点を2つ書いておきます。どちらもバリデータが教えてくれました。

1. info.version は整数です。1から始まる改訂番号で、あなたが決める欄ではありません。保存のたびにツールが1ずつ増やします。
2. info.authors は配列ではなくオブジェクトです。キーが作者の識別子で、各作者は roles と joinedAt が必須になります。

開発を委託している場合#

ここまでの手順は、定義ファイルに手が届くことを前提にしています。開発を外に出していると、その前提が成り立ちません。この場合にやることは3つで、どれも手を動かすのは委託先です。

1. ADLを成果物の一覧に足します。言語仕様は公開されていて、特定の製品の契約を必要としません。納品されたファイルは、契約が終わっても読めます。
2. 下書きは委託先のAIに書かせます。構造の大半は定義ファイルから引けます。
3. 受け取ったら、5つの欄だけを自分で読みます。ユースケースとトリガーと区間の説明文、そして機密フラグ・個人情報フラグです。ここは委託先が決めてよい欄ではありません。

3つ目が要点です。この5つは、業務を持っている側にしか決められません。逆に言えば、委託先から上がってきた記録のうち発注側が目を通す箇所は、最初から5つに絞られています。全部を読んで理解し直す必要はありません。

読むときの問いは1つで足ります。「止まると誰が困るか」がその説明文に書かれているか。書かれていなければ、それはまだ構造の写しです。

AIが下書きし、人が直すと、AIの理解も変わります#

最後に、この記録が誰のためのものかを書いておきます。

IceShore（アイスショア）は、この形でのユースケースの整理をお使いのAIに促し、その結果をお使いのAIに渡す構成管理プラットフォームです。ユースケースを中心に据えた形式なので、AIの下書きは業務の側から始まります。人が直すのも同じ視点の上です。直した箇所には作成者の印が残ります。回を追って、AIが参照できる業務側の情報が増えます。

波及の問いに答えるのは、お使いのAIです。IceShoreが渡すのは、その材料です。

1本目をお使いのAIに下書きさせるところまでの手順は「登録なしで、お使いのAIが最初の答えを返すまで。繋いで、確かめて、聞く」に書きました。登録は要りません。（claude.aiサイトでのコネクタ追加など、一部のご利用経路では登録が必要です）繋いだら、まず「このユースケースの説明文に、止まると誰が困るかは書いてありますか」と聞いてみてください。