複雑なシステムへ降りていく五つの段階

すべての段階の文脈が混ざっているとき

細部がすべて同時に手に入るとき、全体像を見るのを妨げているものは何か。

ふつうのリポジトリは、情報を尺度で分けてくれない。業務領域も、操作も、データモデルも、呼び出しの順序も、基盤も、具体的なコード行も、すべてが同時に並んでいる。作業記憶は違う層の事実を抱え、そのあいだの関係を自力で組み直さねばならない。注意はシステムの造りと目の前の細部のあいだを行き来し続け、だから理解は中断のあとすぐ崩れる。

まずは責任の地図

責任はどこに住んでいるか。

最初の足がかりになるのが責任の地図だ。コントローラも、サービスも、データモデルも、基盤のアダプタも、呼び出しの連なりも、システムの大きな領域のまわりに集める — のちに操作とデータとコードを結びつけていける骨組みへ。

Domain はシステムを技術的な層でではなく、変わりにくい責任の領域で分ける。注文、決済、コミュニケーション、分析。等しく重要に見える何百ものファイルの代わりに、初めて見渡せる地形が現れる。

地図が可能性の一覧へ変わる

システムには何ができるか。

Domain の地図は責任がどこにあるかを示すが、システムに何ができるかはまだ語らない。そのために、それぞれの Domain が行為の一覧として開かれる — その Domain がシステムの他の部分へ差し出す、名前のついた可能性だ。

Action とは Domain の名前のついた公開された可能性である。一覧が見せるのは内部の関数ではなく、Domain が他の部分へ差し出す操作と、そのあいだの向きのあるつながりだ。どの行為も単一の入口になる。呼ぶ側は必要な可能性を意味で選び、ばらばらのメソッドから操作を組み立てずに済む。

操作の境界を確定する

その操作は何を求め、何を約束するか。

可能性にはもう名前とシステム内の居場所がある。それを「中身の見えない箱」として使うには、どんなデータを受け取り、どんな結果を返す義務があるのかを正確に知る必要がある。

Contract は Action の境界を、型のついた曖昧さのないものにする。Params は操作が受け取るすべてを、Result は返す義務のあるすべてを言い表す。呼ぶ側のコードが頼るのはこの約束であって、Action の内側の造りではない。入口と出口と外から見える振る舞いに互換性が保たれているかぎり、実装は変えてよい。

操作を筋書きへ展開する

筋書きはどう運ばれるか。

契約は操作の始まりと終わりを確定するが、一方がどうやってもう一方になるのかは見せない。そのために、業務上の筋書きの内側の運びを開く。

Pipeline は主たる業務の筋書きを一本道にして見えるようにする。入力を確かめ、商品を確保し、支払いを通し、結果を組み立てる。現実に誤りも分岐も補償もないという意味ではない。それらが主線に対してはっきりした居場所を得るということだ。どの手順も自分の局所的な契約を持ち、Params と State と Context から何を読むか、次の段階のために State へ何を足すかを宣言する。

ここでようやく、具体的な振る舞い

その具体的な振る舞いはどこにあるか。

Pipeline は必要な振る舞いの正確な居場所を示し、探す範囲を一気に狭める。もはやリポジトリ全体でも Action 全体でもなく、目的も入口も出口も分かっている一つの手順の実装を開けばいい。

Code が五番目の段階になるのは、細部が重要でないからではない。いまやそれが意味に囲まれているからだ。この振る舞いがどの Domain のものか、Action がどんな可能性を実現するか、Contract が何を約束するか、reserve_inventory が Pipeline のどこに座るかは、すでに分かっている。実装は具体的な課題への局所的な答えとして読める。リポジトリという終わりのない捜査への入口としてではなく。

@regular_aspect("Reserve inventory")@result_string("reservation_id", required=True)@context_requires("user.tenant_id", "env.inventory_region")async def reserve_inventory_aspect(    self, params, state, box, connections, ctx):    inventory = box.resolve(InventoryResource)    reservation_id = await inventory.reserve(        tenant_id=ctx.get("user.tenant_id"),        region=ctx.get("env.inventory_region"),        items=state["validated_items"],    )    return {"reservation_id": reservation_id}

五つの段階はコードを隠しもしないし、システムを図に単純化もしない。全体のモデルから細部までの道すじを保つ。新人は文脈を少しずつ組み立て、アーキテクトは一つ一つのファイルではなく文法と境界を扱い、AI エージェントは定められた規則の内側で局所的な仕事をする。人がシステムの言語を設計し、機械がその言語で振る舞う。