Most teams build features in the order PRD → product code → test code. That order looks at product code quality (maintainability, security, performance) first, and leaves whether the feature does what the PRD promised for later.

Product code has two things to ensure: behaviour and code quality. Behaviour has fewer dependencies, so it can be ensured first.

This post makes two points:

• Test the PRD, not the code.
• Test behaviour without waiting for code quality.

Why

Tests written after the code read the code and assert what it does. If the implementation and the PRD disagree, the test judges the misreading as a pass.

Contradictions and gaps in the PRD can get filled by an engineer’s guess mid-implementation, which leads to rework later. When tests are generated from the PRD, they show up as expected outcomes you can’t write, and they become questions for the PRD owner.

What

By behaviour tests I mean integration and E2E tests, which check behaviour observable from outside. Integration tests cover every scenario against fake dependencies, and E2E tests cover the critical paths in a real environment.

PRD → test code → product code describes dependency, not time.

                    PRD
                     │
                     ▼
             executable spec
             │             │
             ▼             ▼
         test code    product code ◀── code quality

• Executable spec: the behaviour the PRD promises (states, events, expected outcomes), written so tests can be generated from it.
• Test code takes its expected outcomes only from the executable spec, never from the implementation.
• Product code depends on both behaviour and code quality.

Product code has to satisfy both behaviour and code quality, but test code needs only behaviour. That’s why behaviour tests can be written and run without the final product code.

The final test code runs against the actual product code. But what a test expects is decided by the spec alone, never by reading the product code.

How

In the AI era code is easy to generate, so even if you write the tests first, you can also generate the product-side implementation that runs them. Generate throwaway code together with the tests from the executable spec, and run them. The throwaway code can go; the tests stay and run as they are against the actual product code, because they encode the PRD, not the throwaway code.

In practice:

• If the PRD doesn’t give an expected outcome, ask the PRD owner instead of guessing one.
• Assert only observable outcomes, and don’t depend on implementation details.
• Code quality can be ensured at the same time, as long as behaviour tests don’t wait for it.

BDD’s Given/When/Then and specification by example share the same idea. ESDD, which I’ve been building (The Executable Spec Pipeline), is one way to automate it. It turns the PRD into a checkable UseCase IR, sends contradictions and gaps back to the PRD owner as questions, and generates tests from the approved IR.

Summary

• Test the PRD, not the code. Tests built from the PRD find misread requirements; tests built from the code miss them.
• Test behaviour without waiting for code quality. What tests expect is decided by behaviour alone, so they can run against throwaway code first. Quality is improved from there.

Now that code is easy to generate, there’s no reason to wait for finished code before checking behaviour. There are two things to ensure, behaviour and code quality, and behaviour has fewer dependencies, so ensure it first.

多くのチームは「PRD → プロダクトコード → テストコード」の順に機能を作ります。 この順序では、プロダクトコードの品質（保守性、セキュリティ、パフォーマンス）が先に見られ、PRD どおりに動くかは後回しになります。

プロダクトコードで担保すべきことは、振る舞いとコード品質の二つです。 振る舞いのほうが依存が少ないので、先に担保できます。

この記事の主張は二つです。

• コードではなく PRD をテストする
• コード品質を待たずに振る舞いをテストする

なぜコードではなく PRD をテストするのか

コードの後に書くテストは、コードを読んで、コードがしていることを assert します。 実装と PRD に読み違いがあっても、テストはその読み違いを成功として判定します。

PRD の矛盾や定義漏れも、実装中のエンジニアが推測で埋めて後から手戻りが起きることがあります。 PRD からテストを生成すれば、期待結果が書けないところで矛盾や定義漏れが見つかり、PRD オーナーに質問できます。

なぜコード品質を待たずに振る舞いをテストできるのか

この記事でいう振る舞いテストは、外から観測できる振る舞いを確かめる Integration テストと E2E テストです。 Integration テストは fake の外部依存に対してすべてのシナリオを、E2E テストは実際の環境でクリティカルパスを確かめます。

PRD → テストコード → プロダクトコードという並びは、時間の順序ではなく依存関係です。

                    PRD
                     │
                     ▼
              実行可能な仕様
             │             │
             ▼             ▼
       テストコード   プロダクトコード ◀── コード品質

• 実行可能な仕様：PRD が約束する振る舞い（状態、イベント、期待結果）を、テストを生成できる形で書いたものです。
• テストコードの期待結果は「実行可能な仕様」だけに依存し、実装からは取りません。
• プロダクトコードは振る舞いとコード品質の両方に依存します。

プロダクトコードは振る舞いとコード品質の両方を満たす必要がありますが、テストコードが必要とするのは振る舞いだけです。 そのため、最終的なプロダクトコードがなくても、振る舞いのテストは書いて実行できます。

最終的なテストコードは、実際のプロダクトコードに対して実行します。 ただし、テストが何を期待するかは仕様だけで決まり、プロダクトコードを読んで決めることはしません。

どうやって実現するのか

AI の時代にはコードの生成が容易なので、先にテストを書いたとしてもそれを実行するプロダクト側の実装も生成できます。 「実行可能な仕様」からテストと一緒に使い捨てのコードを生成し、テストを動かします。 使い捨てのコードは捨てても、テストは残り、そのまま実際のプロダクトコードに対して実行します。 テストが表しているのは、使い捨てのコードではなく PRD だからです。

実践では次の点を守ります。

• PRD に期待結果が書かれていなければ、値を推測せず PRD オーナーに質問する。
• 観測できる結果だけを assert し、実装の詳細に依存しない。
• コード品質の担保は振る舞いテストと同時に進めてよいが、振る舞いテストはその完了を待たない。

BDD の Given/When/Then や Specification by Example も同じ考え方です。 私が作っている ESDD（仕様を実行可能にする Executable Spec パイプライン）は、これを自動化する方法の一つです。 PRD を検査できる UseCase IR に変え、矛盾や定義漏れを PRD オーナーへの質問として返し、承認された IR からテストを生成します。

まとめ

• コードではなく PRD をテストする：PRD から作ったテストは要件の読み違いを見つけ、コードから作ったテストは読み違いを見逃します。
• コード品質を待たずに振る舞いをテストする：テストの期待結果は振る舞いだけで決まるので、使い捨てのコードに対して先に動かせます。品質はそこから向上させます。

コードの生成が容易になった今、振る舞いを確かめるために完成したコードを待つ理由はありません。 担保すべきことは振る舞いとコード品質の二つで、依存が少ない振る舞いを先に担保します。

Overview

Executable Spec converts natural-language specifications (PRDs and similar documents) into an inspectable intermediate representation (IR), machine-checks the IR, has a human approve it, and then generates test code from the approved IR.

Specification (PRD / PDD / Figma)
  ↓  AI transforms
UseCase IR (the spec written as a state machine)
  ↓  Machine checks (exhaustiveness, determinism, reachability, coverage, ...)
Check results = a list of questions about the spec (undefined combinations, ...)
  ↓  A human answers; the IR is revised
A human approves the IR once every check passes  ← the single human approval point
  ↓  AI transforms
Scenario definitions → test code → execution

The scope is the UI behavior of web and mobile apps: states, transitions, displayed text, input validation. It does not cover UX quality such as layout or visual sensibility. Keeping the appearance and type of input fields out of the IR is a deliberate design decision: that information belongs to the design-tool and component layers.

Background

With AI writing the code, the cost of generation has dropped rapidly. The bottleneck that remains is review. As long as a human ultimately reads every generated spec and every generated test to judge its correctness, verification doesn’t scale no matter how fast generation gets.

The other problem was that nothing kept specifications and tests in sync. E2E tests have been in place for a long time, but “which behavior in the spec does this test verify?” lived in human judgment. Whether tests kept up with a spec change was something you found out only when they broke.

The approach of converting natural-language specs into an inspectable structure, instead of prompting harder with them as-is, is an extension of the ideas in Don’t Prompt Harder, Structure Better.

Why build it

At the root of Executable Spec is one idea: in AI-based development, quality assurance should concentrate on the upstream and downstream ends of the pipeline.

Upstream, quality assurance means approving the spec. Once the spec is lowered into an IR, machine checks return undefined state transitions and missing definitions for concurrent operations as a list of questions about the spec. The human’s job narrows to answering those questions and approving an IR that passes every check. There is exactly one approval point in the whole pipeline.

Downstream, quality assurance means test results. The pass / fail verdict comes from a machine.

The transformations in between carry no semantic checks. Going from IR to scenario definitions, and from scenario definitions to test code, all that’s needed is to check that nothing from upstream was lost and nothing that isn’t upstream was added. Concentrating semantic checking at the single upstream point is what makes the intermediate artifacts machine-reviewable.

Human review doesn’t disappear. It changes character: from exhaustively reading artifacts end to end, to answering machine-generated questions and deciding, when a test fails, whether to fix the spec or the implementation. Replacing most of spec and test review with machine checks is the point of this pipeline.

What it can do

It turns spec holes into questions

The IR is a state machine, and the checker demands that every state × event combination be defined. “Cannot happen” must also be declared explicitly, with a reason, so that undefined is distinguished from “considered and impossible” — and every undeclared combination surfaces as a hole in the spec.

Piloting this on the PRD of one feature, the checker found 11 undefined combinations in a 13-state × 19-event table, and every one of them was a real question worth asking the PRD owner. The kind of hole humans struggle to spot in review (what happens on this input in this particular state is written nowhere) gets enumerated mechanically, without omissions.

The same mechanism works for form inputs. It checks exhaustiveness over input fields × {empty, boundary value} and returns the combinations the spec doesn’t answer as questions.

It verifies the app works as expected, with or without an implementation

The pipeline is used in two phases, and what a generated test passing or failing means changes with the phase.

Phase 1 (the implementation already exists): generated tests are expected to pass. A failure is the detection of a gap between spec and implementation, and a human decides which side to fix. In fact, the very first test generated by this pipeline failed on its first run. The cause was a product-side change to displayed text that the test’s expectations hadn’t followed. The spec in the IR was judged correct, the test was fixed, and it passed. It became the first working example of “failure = drift detected, and a human decides which side to fix.”

Phase 2 (the implementation doesn’t exist yet): frontend code and integration tests are generated together from the spec. The acceptance criterion is that the tests fail on the old build, which lacks the feature, and pass on the generated build — proof that the tests actually verify the feature. Not using E2E as the verification layer in Phase 2 is deliberate. E2E presupposes that every implementation detail — environment, test data, the full journey between screens — already exists, which is far too costly in a phase that generates the implementation itself. Integration tests against a fake server have no environment-induced flakiness, and because frontend and tests are generated together, the mapping to screen elements is closed inside the generation step.

In both phases the upstream, IR checking and approval, is the same. With or without an implementation, the same entry point verifies that the app behaves as the approved spec says.

It can be edited by diff

Each element in the IR keeps a stable ID, and ordering follows fixed rules. A behavior change is therefore written as a meaningful diff — this combination’s outcome changed, this transition was added — rather than by regenerating the whole IR.

This matters operationally. Updating the IR diff in the same PR as the feature change is the only mechanism that keeps spec and tests from drifting apart. If full regeneration were the only tool, every small behavior change would put the entire approved IR back under review, and that practice wouldn’t survive.

How it works

What goes into the IR

A UseCase IR is a state machine written in YAML. Alongside states, events, and transitions, it carries cross-cutting rules (tables of validation conditions and results), declared input axes, and representative scenarios (critical paths). Here is a minimal skeleton:

usecase: UC-EXAMPLE-001
name: Order and shipping
initial: IDLE

states:
  - id: IDLE
  - id: ORDERED
    label: Ordered
  - id: SHIPPED
    label: Shipped
  - id: CANCELED
    label: Canceled
    terminal: true

events:
  - id: place_order
    label: Place an order
    actor: customer
  - id: ship
    label: Ship
    actor: staff
  - id: cancel
    label: Cancel
    actor: customer

transitions:
  - from: IDLE
    on: place_order
    to: ORDERED
    outcome:
      - surface: WEB
        ui: Order history shows a new row with status "Ordered"

  - from: ORDERED
    on: ship
    to: SHIPPED
    outcome:
      - surface: WEB
        ui: The order's status changes to "Shipped"

  - from: ORDERED
    on: cancel
    to: CANCELED
    outcome:
      - surface: WEB
        ui: The order's status changes to "Canceled"

  # "cannot happen" must also be declared, with a reason
  - from: IDLE
    on: [ship, cancel]
    impossible: true
    reason: no order exists to act on

Of the 9 combinations across the 3 non-terminal states × 3 events, only 5 are declared here. The checker returns the remaining 4 as questions: should a shipped order be cancelable? what happens if you place another order while one is already placed? Combinations declared impossible are excluded as “considered and ruled out.”

Two principles govern how the IR is written. First, tests know nothing about the implementation: transition outcomes are written only in terms of what a user can observe, such as displayed text and states. Second, semantic checking happens exactly once, on the UseCase IR; downstream artifacts never restate behavior and hold only references to which upstream behavior they target.

Machine checks produce the questions

The checker verifies exhaustiveness (is every state × event combination defined?), determinism (is the result unique for a given state and input?), reachability (is every state reachable?), concurrency declarations (where multiple events can occur at once, is the consequence defined?), and scenario validity and coverage (do scenarios follow real transitions, and do they cover them?). A check error has the shape “what should happen on this input in this state?”, which is exactly a checklist of questions for the PRD owner.

The PRD owner answers the questions, not the implementation. Filling holes by reading the code silently promotes whatever the code currently does into the spec, destroying the ability to detect drift. Only when onboarding an existing feature for the first time do the implementation and its tests serve as a source, and even then every code-derived fact is recorded as a delta and surfaced as material for updating the spec.

Generating a per-target IR

The definition of behavior lives in exactly one place, the UseCase IR. Each deliverable (integration test code, E2E test code, and so on) gets its own IR layered on top of it. A target IR never restates behavior; it holds only the decisions that belong to that target. For E2E tests, it looks like this:

# target IR for E2E tests (excerpt)
suite: E2E-EXAMPLE-001
usecase: UC-EXAMPLE-001    # behavior is only a reference to the UseCase IR
cases:
  - id: TC-1
    scenario: SC-001       # points at a scenario in the UseCase IR
    priority: high         # a decision specific to this target
    environment: staging   # choice of execution environment

Test steps are not written here. Scenarios in the UseCase IR are defined as paths through the transitions, so steps are derived mechanically by walking the path. What remains in the target IR are only the decisions that can be made nowhere else: which scenarios to include (all of them for integration tests, critical paths only for E2E), priority, and environment. Because behavior lives in one place, a spec change has exactly one place to fix.

Generating tests from an approved IR

An approved IR is lowered into the existing scenario-definition and test-helper machinery and becomes E2E test code. Running the generated tests is how consistency with the implementation is verified: not by reading the code, but by whether the tests fail.

Day to day, the flow is one-directional and always starts from the spec. Behavior changes travel as IR diffs in the same PR as the feature change. If rewriting the IR from the implementation ever becomes routine, that is a sign the loop is no longer a loop.

Summary

Executable Spec is a pipeline that decomposes specification verification into test execution by machines and approval by humans.

• Quality assurance concentrates on the upstream (IR approval) and downstream (test results) ends of the pipeline; the transformations in between need only content-preservation checks
• Human review remains, but shifts from reading artifacts line by line to answering machine-enumerated questions and deciding, on failure, whether to fix the spec or the implementation
• With an implementation it detects spec-implementation drift; without one it is the entry point for co-generating code and tests — with or without an implementation, the same spec verifies that the app works as expected
• Stable IDs and ordering make the IR editable by diff instead of full regeneration, which is what makes updating the spec in the same PR as the feature change sustainable

概要

Executable Spec は、PRD などの自然言語の仕様を検査可能な 中間表現 （IR: Intermediate Representation）に変換し、IR を機械検査したうえで人間が承認し、承認された IR からテストコードを生成するパイプラインです。

仕様（PRD / PDD / Figma）
  ↓  AI が変換
UseCase IR（ステートマシンとして記述された仕様）
  ↓  機械検査（網羅性、決定性、到達性、カバレッジなど）
検査結果 = 仕様への質問リスト（未定義の組み合わせなど）
  ↓  人間が回答し、IR を修正
検査をすべて通った IR を人間が承認  ← 人間の承認ポイントはここ一箇所
  ↓  AI が変換
シナリオ定義 → テストコード → 実行

対象は Web とモバイルアプリの UI の振る舞い（状態、遷移、表示文言、入力検証）です。 レイアウトや感性に関わる UX の品質は扱いません。 入力フィールドの見た目や種類を IR に持たせないのは意図的な設計で、それらはデザインツールとコンポーネントの層に属する情報だからです。

背景

AI にコードを書かせる開発では、生成のコストは急速に下がりました。 残ったボトルネックはレビューです。 生成された仕様書もテストコードも、最終的に人間が全て読んで正しさを判断している限り、生成をいくら速くしても検証がスケールしません。

もうひとつの問題は、仕様とテストの対応を保つ仕組みがないことでした。 E2E テストは以前から運用していますが、「このテストは仕様のどの振る舞いを検証しているのか」は人間の判断に依存していました。 仕様が変わったときにテストが追従しているかどうかは、壊れて初めてわかります。

自然言語の仕様をそのままプロンプトとして強化するのではなく、検査可能な構造に変換してから扱うという方針は、 Don’t Prompt Harder, Structure Better で話した考え方の延長にあります。

なぜ作るのか

Executable Spec の根底には、「AI ベースの開発では、パイプラインの上流工程と下流工程の品質保証に最も注力すればよい」という考え方があります。

上流工程の品質保証は、仕様の承認です。 仕様を IR に落とすと、機械検査が、未定義の状態遷移や、複数の操作が同時に起きた場合の挙動の定義漏れを、仕様への質問リストとして返します。 人間の仕事は、質問に答えることと、検査をすべて通った IR を承認することに絞られます。 承認ポイントはパイプライン全体で一箇所だけです。

下流工程の品質保証は、テストの実行結果です。 成功 / 失敗の判定は機械が行います。

中間の変換には意味の検査を持ち込みません。 IR からシナリオ定義、シナリオ定義からテストコードへの変換で必要なのは、上流の情報が失われていないこと、上流にない振る舞いが勝手に追加されていないことの検査だけです。 意味の検査を上流の一箇所に集めることで、中間成果物のレビューを機械化できます。

人間のレビューがなくなるわけではありません。 性質が変わります。 成果物を逐一読む網羅的なレビューから、機械が生成した質問への回答と、テストが失敗したときに仕様と実装のどちらを直すかの判断へ。 仕様とテストのレビューの大部分を機械検査に置き換えることが、このパイプラインの目的です。

何ができるのか

仕様の穴を質問として返す

IR はステートマシンとして書かれ、検査器は状態×イベントの組み合わせすべてが定義されていることを要求します。 「起こり得ない」も理由つきで明示的に宣言させるため、未定義と「検討済みで不可能」が区別され、定義されていない組み合わせはそのまま仕様の穴として浮かび上がります。

ある機能の PRD をパイロットとして変換したときは、13 状態 × 19 イベントの表から 11 個の未定義の組み合わせが検出され、そのすべてが PRD オーナーに聞くべき実際の質問でした。 人間がレビューで見つけるのが難しい種類の穴（特定の状態で特定の入力が来たときの挙動が、どこにも書かれていない）を、機械が漏れなく列挙します。

フォーム入力についても同じ仕組みが働きます。 入力フィールド × {未入力、境界値} という軸の組み合わせに対して網羅性を検査し、仕様が答えていない組み合わせを質問として返します。

実装の有無を問わず「期待どおり動くこと」を確かめる

パイプラインは 2 つのモードで使い、生成テストの成功 / 失敗の意味がモードで変わります。

モードA（実装が先に存在する） ：生成テストは成功が期待値です。 失敗は仕様と実装の乖離の検出であり、どちらを直すかは人間が判断します。 実際、このパイプラインで最初に生成したテストの初回実行は失敗でした。 原因は、プロダクト側の表示文言の変更にテストの期待値が追従していなかったことです。 IR に書かれた仕様が正しいと判断し、テスト側を直して成功になりました。 「失敗 = 乖離の検出、どちらを直すかは人間が決める」という意味づけが機能した最初の例になりました。

モードB（実装がまだ存在しない） ：仕様からフロントエンドコードと Integration テストを同時生成します。 対象機能を含まない旧ビルドで失敗し、生成後のビルドで成功することが、テストが本当に対象機能を検証していることの合格条件になります。 モードB の検証層を E2E にしないのは意図的です。 E2E は環境、テストデータ、画面遷移の全体といった実装の詳細がすべて揃っていることを前提とするため、実装と同時に生成するフェーズではコストが大きすぎます。 fake サーバーを使った Integration テストであれば環境に起因する不安定さがなく、フロントエンドとテストを同時に生成するため、画面要素との対応づけも生成の中で完結します。

どちらのフェーズでも、上流（IR の検査と承認）は共通です。 実装があってもなくても、承認済みの仕様に対してアプリが期待どおり動くことを、同じ入り口から確かめられます。

差分で編集できる

IR は各要素の ID を変えず、並び順も一定のルールで揃えています。 このため振る舞いの変更は、IR 全体を作り直すのではなく、意味のある差分（この組み合わせの結果が変わった、この遷移が増えた）として書けます。

これは運用上の大事なポイントです。 機能 PR と同一の PR で IR の差分を更新する運用が、仕様とテストの乖離を防ぐ唯一の仕組みになります。 全て再生成する手段しかないと、小さな振る舞い変更のたびに承認済みの IR 全体が再レビュー対象になり、この運用は維持できません。

どう動くのか

IR に何を書くか

UseCase IR は YAML で書かれたステートマシンです。 状態、イベント、遷移に加えて、横断的なルール（バリデーションの条件と結果の表）、入力軸の宣言、代表シナリオ（クリティカルパス）を持ちます。 骨格だけの小さな例を示します。

usecase: UC-EXAMPLE-001
name: 注文と発送
initial: IDLE

states:
  - id: IDLE
  - id: ORDERED
    label: 注文済み
  - id: SHIPPED
    label: 発送済み
  - id: CANCELED
    label: キャンセル
    terminal: true

events:
  - id: place_order
    label: 注文する
    actor: customer
  - id: ship
    label: 発送する
    actor: staff
  - id: cancel
    label: キャンセルする
    actor: customer

transitions:
  - from: IDLE
    on: place_order
    to: ORDERED
    outcome:
      - surface: WEB
        ui: 注文履歴にステータス「注文済み」の行が表示される

  - from: ORDERED
    on: ship
    to: SHIPPED
    outcome:
      - surface: WEB
        ui: 該当注文のステータスが「発送済み」になる

  - from: ORDERED
    on: cancel
    to: CANCELED
    outcome:
      - surface: WEB
        ui: 該当注文のステータスが「キャンセル」になる

  # 「起こり得ない」も理由つきで態度表明する
  - from: IDLE
    on: [ship, cancel]
    impossible: true
    reason: 注文が存在しないため対象がない

この例では、終端状態を除く 3 状態 × 3 イベント = 9 個の組み合わせのうち、5 個しか宣言されていません。 検査器は残りの 4 個を「発送済みの注文はキャンセルできるべきか」「注文済みの状態で再度注文したらどうなるのか」という形の質問として返します。 impossible と宣言した組み合わせは「検討済みで不可能」として質問から除外されます。

書き方には 2 つの原則があります。 第一に、 テストは実装について何も知りません 。 遷移の結果は、表示テキストや状態など、ユーザーから観測できるものだけで書きます。 第二に、意味の検査は UseCase IR に一度だけ行い、下流の成果物は振る舞いを再記述せず、上流のどの振る舞いを対象にするかの参照だけを持ちます。

機械検査が質問を作る

検査器は、網羅性（すべての状態×イベントの組み合わせが定義済みか）、決定性（同じ状態と入力に対して結果が一意か）、到達性（到達できない状態がないか）、同時発生の宣言（複数のイベントが同時に起こりうる箇所で、その帰結が定義されているか）、シナリオの妥当性とカバレッジ（シナリオが実在する遷移をたどり、遷移を網羅しているか）を検査します。 検査エラーは「この状態でこの入力が来たらどうなるべきか」という形の質問であり、そのまま PRD オーナーへの確認リストになります。

質問に答えるのは PRD オーナーであって、実装コードではありません。 実装を読んで穴を埋めると、実装の現状が無言で仕様に昇格してしまい、乖離を検出する能力が失われます。 既存機能をこのパイプラインに載せる初回だけは実装とテストをソースに使いますが、その場合もコード由来の事実はすべて差分として記録し、仕様更新の材料として出します。

ターゲットごとの IR を生成する

振る舞いの定義は UseCase IR の一箇所だけに置き、成果物ごと（Integration テストコード、E2E テストコードなど）には、それぞれ専用の IR を UseCase IR の上に重ねます。 ターゲットの IR は振る舞いを再記述せず、そのターゲットでしか決められないことだけを持ちます。 E2E テストの IR なら、次のような形です。

# E2E テストのターゲット IR（抜粋）
suite: E2E-EXAMPLE-001
usecase: UC-EXAMPLE-001    # 振る舞いは UseCase IR への参照だけ
cases:
  - id: TC-1
    scenario: SC-001       # UseCase IR 側のシナリオを指す
    priority: high         # このターゲット固有の決定
    environment: staging   # 実行環境の選択

テスト手順はここには書きません。 UseCase IR のシナリオは遷移のパスとして定義されているため、手順はパスをたどることで機械的に得られます。 ターゲットの IR に残るのは、対象シナリオの選択（Integration テストは全シナリオ、E2E はクリティカルパスだけ、といった絞り込み）や優先度、実行環境のような、そのターゲットでしか決められないことだけです。 振る舞いが一箇所にしかないので、仕様が変わったとき直す場所も一箇所で済みます。

承認済み IR からテストを生成する

承認された IR は、既存のシナリオ定義とテストヘルパーの仕組みに落とし込まれ、E2E テストコードになります。 生成されたテストの実行が、実装との整合の検証手段です。 コードを読んで整合を確認するのではなく、テストを実行して失敗するかどうかで判定します。

日々の運用では、常に仕様を起点とした一方向の流れを保ちます。 振る舞いの変更は、機能 PR と同一 PR での IR の差分更新として行います。 実装を読んで IR を書き直すことが日常的に必要になったら、それは仕様起点のループになっていないサインとして扱います。

まとめ

Executable Spec は、仕様の検証を機械によるテストの実行と人間による承認に分解するパイプラインです。

• 品質保証はパイプラインの上流工程（IR の承認）と下流工程（テストの実行結果）に最も注力し、中間の変換は内容が保たれていることの検査だけで済ませる
• 人間のレビューは残るが、成果物を逐一読む作業から、機械が列挙した質問への回答と、失敗時に仕様と実装のどちらを直すかの判断に変わる
• 実装があれば仕様と実装の乖離の検出として、実装がなければコードとテストの同時生成の入り口として、実装の有無を問わず同じ仕様から「期待どおり動くこと」を確かめられる
• ID と並び順を安定させることで、全て再生成するのではなく差分で IR を編集でき、機能変更と同一 PR での仕様更新という運用が成立する

When we work with AI on code generation, we tend to think “if I just write a better prompt, the result will get better.” But in practice, what actually moves output quality the most is how much of the inference gap we can shrink before the model starts working.

1. AI’s Real Strength Is Inference, Not Code Generation

When AI generates code, it isn’t just reusing existing code as-is — it’s filling in missing information through inference.

A prompt like “build a user list screen” leaves an enormous amount unspecified. The model has to make decisions on every one of them:

• Which layer owns the database query?
• How are errors propagated — exceptions, result types, something else?
• Does the API response flow straight to the UI, or through a translation layer?

None of these were in the prompt. The model inferred the answers.

So the essence of AI code generation is the work of closing the gap between what you said and what code needs to exist. The quality of the output depends on three things: how accurately the AI interprets the input, how wide that gap is, and how well the model fills it in.

If we restate the problem cleanly:

The quality of AI-generated code = how small you can make the gap the model has to infer across.

So the real question isn’t “should we shrink the gap?” but rather “how do we shrink it, and where does that knowledge live?”

2. Two Approaches to Closing the Gap — Bare Prompts vs. Shared Rules

There are roughly two directions for shrinking the gap, and how much weight you put on each ends up determining the long-term quality of your output.

Approach A: Pure Inference (no shared definitions)

You hand the model the PRD and the codebase, and that’s it. Architecture, style, error handling, naming, layering — all of it gets inferred from whatever hints the model can pick up from existing files, plus whatever the engineer happens to type into the prompt.

“You only need a PRD” sounds lightweight, but that lightness is a surface impression. The knowledge that makes the output good has to come from somewhere — and in Pure Inference, the only place it exists is inside the individual engineer’s prompt.

In reality, Pure Inference is a prompt-tuning workflow disguised as an automation workflow:

• Know-how accumulates in individual chat histories, not in the org
• “What worked last time” can’t be reused by a teammate
• Reviewers have no objective standard to evaluate the result against

Approach B: Rules-Augmented Inference (with shared definitions)

In addition to the PRD and the codebase, you hand the model explicit organizational definitions. The model still infers, but it does so within the boundaries of pre-defined rules — and the know-how lives in versioned files in the repo, not inside someone’s head.

These rules split into two sides: code-side and PRD-side.

Code-side rules — definitions for how the implementation should be shaped:

• Architecture guidelines (Clean Architecture boundaries, hexagonal layers, etc.)
• Design system / UI style guide (tokens, components, spacing, typography)
• Concurrency and threading policy
• Layering and dependency rules (no API types in the View, translation layers, etc.)
• Error-handling conventions (where to throw, where to recover, how to log)
• Testing conventions (what to mock, where unit vs. integration boundaries sit)
• Naming, file structure, and module-boundary rules

PRD-side rules — definitions for how the spec should be shaped so AI can actually read it:

• A domain glossary that defines what your org-specific terms mean — what counts as an “active” user, when an order is “complete,” what “verified” means in your domain — so the model isn’t guessing
• A requirement template like EARS, so the model can mechanically detect missing trigger/condition/response clauses
• User personas and journey definitions, so acceptance criteria can be evaluated against a known cast of actors
• Analytics/event naming conventions, so the model can fill in the events a feature should emit without inventing names
• Error, empty-state, and loading-state UX standards, so the model auto-completes the unhappy paths PRDs always forget

PRD-side investment is the part most teams skip, and it’s also the part that hurts most when it’s missing.

A PRD is fundamentally a “natural-language document full of gaps,” and AI will fill those gaps with inference whether you’ve told it how to or not. Without PRD-side rules, the AI invents a plausible-but-subtly-wrong interpretation of your domain, and the PM ends up correcting it through prompts on every single feature.

Comparing the two approaches

3. Why Rules Compound and Prompts Don’t

1. Rules accumulate as assets; prompts vanish after use. A prompt you wrote disappears when the session ends. A rule you wrote will improve the next session — for you, and for everyone on the team.

2. One fix lifts every future generation. When Pure Inference produces a bad output, someone tweaks a prompt, and the next engineer hits the same problem from scratch. When a rule is wrong, you fix it once — and the model will never make that mistake again, for anyone.

3. The act of writing rules surfaces implicit disagreement. Putting a convention into words forces the team to make decisions it had been quietly deferring. Resolving those raises the baseline quality for both humans and AI. Pure Inference, by contrast, just papers over the disagreement.

4. Onboarding compounds. New members — human engineers or new AI agents — can read the rules and immediately produce output consistent with the team. In Pure Inference, every newcomer has to re-discover the team’s preferences through trial and error.

4. When Pure Inference Is Genuinely the Right Choice

Rules-augmented isn’t always the right answer. Pure Inference is the better choice in cases like:

• PoCs — code you’re going to throw away doesn’t need rules
• One-shot scripts and data migrations — code that runs once doesn’t need consistency
• Exploring new territory — sometimes you have to write code first to discover what the rules should be
• Early-stage teams without an existing framework — it can be faster to extract rules from the code after the fact

A rough guideline: long-lived, multi-author, pattern-repeating code → push toward rules-augmented. Everything else → pure inference is fine.

5. The Pattern in the Wild

Rules-augmented inference has already been adopted at multiple layers of the stack. A few public writeups:

Architecture-driven code generation

スキーマでアーキテクチャを縛る ── 人間とAIを同じルールで動かす (Japanese) — “Constraining architecture with schemas: running humans and AI on the same rules.”

The team treats their architecture guidelines (layer responsibilities, dependency rules, naming conventions) as direct AI inputs, not just human-facing docs. The result: generated code lands in the right files, in the right layers, with the right names — because the rules told the model “where things go” before it started writing.

Test code generation

Don’t prompt harder, structure better

The same thesis applied to test code. Rather than tuning prompts to “write better tests,” the team defines a structural template (what to mock, what to assert, naming patterns for test cases) and feeds that as a rule set. Test variance collapses; review becomes nearly mechanical.

Test plan generation

Generating test plans with AI (Japanese)

Pushes rules-augmented inference upstream into the spec layer. Combining the PRD with test-planning rules (coverage axes, edge-case categories, output format) produces a usable test plan instead of a generic checklist. This is the PRD-side half of the frame applied concretely.

The thread tying these three together: none of them invented a smarter prompt. Each team wrote down what they had been holding implicitly and fed it to the model as an input. That’s the entire pattern.

6. The Takeaway — Don’t Tune Prompts, Build the Rule Foundation

• Inference is the key. Rules are how you shrink the gap it has to cross.
• Rules have two sides — code-side and PRD-side. You only get the full effect when both are in place.

If there’s one thing to take from this post: stop trying harder on prompts. Build the foundation of rules — on both the spec side and the code side — that AI can infer against, and let the rules themselves do the work.

1. AIの本当の武器はコード生成ではなく「推論」

AIがコードを生成するとき、すでにあるコードをそのまま再利用しているわけではなく、足りない情報を 推論で埋めて います。

たとえば「ユーザー一覧画面を作って」という指示には書かれていないことが山のようにあり、モデルはそれぞれについて自分で判断しなければなりません。

• DBクエリはどの層が持つのか
• エラーはどう伝搬させるのか ― 例外か、Result型か、それ以外か
• APIレスポンスはそのままUIに流すのか、変換層を挟むのか

これらはプロンプトに書かれていなかった部分であり、モデルが推論で埋めた箇所です。

つまりAIによるコード生成の本質は、「あなたが言ったこと」と「存在すべきコード」のあいだに開いた ギャップを埋める 作業にあるといえます。出力の品質は、AIが入力をどれだけ正確に解釈できるか、ギャップがどれだけ広いか、そしてその埋め方がどれだけ的確かによって決まります。

問題の見え方を整理すると、こうなります。

AI生成コードの品質 ＝ モデルが推論で埋めなければならないギャップをどこまで小さくできるか

したがって本当に考えるべき問いは「ギャップを縮めるべきか」ではなく、「どう縮めるか、そしてその知識をどこに置くか」 であるはずです。

2. ギャップを埋める2つのアプローチ ― プロンプト vs. 共有ルール

ギャップを縮めるアプローチには大きく2つの方向性があり、どちらにどれだけ比重を置くかが長期的な品質を決めることになります。

アプローチA：純粋な推論（共有された定義なし）

PRDとコードベースだけをモデルに渡すアプローチです。アーキテクチャ、スタイル、エラーハンドリング、命名、レイヤリングといった事柄はすべて、既存ファイルから読み取れるヒントと、エンジニアがその場で書いたプロンプト次第で、モデルがゼロから推論することになります。

「PRDだけで済む」ので軽量に見えますが、これはあくまで見かけの話で、良い出力を生む知識は結局どこかから来ているはずです。純粋な推論の場合、それは個々のエンジニアのプロンプトの中にしか存在しません。

実態としては、純粋な推論は 自動化ワークフローを装ったプロンプトチューニングの作業 だといえます。

• ノウハウは個人のチャット履歴に溜まり、組織には残らない
• 「前回うまくいった書き方」を同僚が再利用できない
• レビュアーには結果を評価するための客観的な基準がない

アプローチB：ルール付き推論（共有された定義つき）

PRDとコードベースに加えて、組織として明示された定義 をAIに渡すアプローチです。モデルは推論を続けますが、その推論はあらかじめ定義されたルールの範囲内で行われるようになり、ノウハウは誰かの頭の中ではなく、リポジトリにバージョン管理されたファイルとして残っていきます。

このルールは、コード側とPRD側の2つの側面に分けて整理できます。

コード側のルール ― 実装をどう形作るかの定義：

• アーキテクチャガイドライン（Clean Architectureの境界、ヘキサゴナル構造など）
• デザインシステム / UIスタイルガイド（トークン、コンポーネント、間隔、タイポグラフィ）
• 並行性・スレッドポリシー
• レイヤリングと依存ルール（APIの型をViewに漏らさない、Translator層を介する、など）
• エラーハンドリング規約（どこで throw し、どこで recover し、どうログに残すか）
• テスト規約（何をモックするか、unit と integration の境界をどこに置くか）
• 命名、ファイル構成、モジュール境界のルール

PRD側のルール ― AIが読めるように仕様をどう形作るかの定義：

• ドメイン用語集 ― 「アクティブな」ユーザーとは何か、注文が「完了」と見なされるのはいつか、「認証済み」が自社の文脈で何を指すかといった、社内固有の用語をAIに推測させないための定義
• 要件テンプレート（EARS記法など）― トリガー・条件・レスポンスの抜け漏れをモデルが機械的に検出できるようにするためのフォーマット
• ユーザーペルソナ・ジャーニーの定義 ― 受け入れ条件を「既知の登場人物」に対して評価できるようにするためのもの
• 計測イベント命名規則 ― 機能ごとに飛ばすべきイベントを、AIが命名を発明することなく埋められるようにするためのルール
• エラー / 空状態 / ローディング状態のUX標準 ― PRDが書き忘れがちな異常系を、モデルが自動補完できるようにするためのガイドライン

このPRD側の整備は、多くのチームがスキップしている部分であり、同時にいちばん致命的な部分でもあります。

PRDはそもそも「ギャップだらけの自然言語文書」であり、AIはあなたが指示するかどうかに関係なく、そのギャップを推論で埋めにいきます。 PRD側のルールがない状態では、AIは「もっともらしいけれど組織の実態とは微妙にズレた」解釈を発明してしまい、PMはそれを毎回プロンプトで補正し続けることになります。

2つのアプローチの比較

3. なぜルールは積み上がり、プロンプトは積み上がらないのか

1. ルールは資産として残り、プロンプトはその場限りで消える。 あなたが書いたプロンプトはセッションが終われば消えてしまいますが、あなたが書いたルールは、次回の自分とチーム全員の次回を必ず改善します。

2. ひとつの修正が、すべての将来の生成に効く。 純粋な推論で何かがうまくいかなかった場合、誰かがプロンプトを少し直すだけになりがちで、次のエンジニアは同じ問題にゼロからぶつかります。ルールが間違っていたなら一度直すだけでよく、モデルはその間違いを誰に対しても二度と犯しません。

3. ルールを書くこと自体が、暗黙の不一致をあぶり出す。 規約を言語化するという行為そのものが、チームが先延ばしにしていた意思決定を強制します。それを解決することで、人間とAIの双方の出力水準が底上げされていきます。一方で純粋な推論は、その不一致を見えなくしているだけです。

4. オンボーディングが積み上がる。 新メンバー（人間も新しいAIエージェントも）はルールを読めば即座にチームと整合した出力を出せるようになります。純粋な推論の場合、新しく入った人がチームの好みを試行錯誤で再発見し直す必要が出てきます。

4. 純粋な推論で十分な場面

ルール付きが常に正解、というわけではありません。次のような場面では、むしろ純粋な推論のほうが適しています。

• PoC ― 捨てる前提のコードにルールは不要です
• 単発スクリプト・データ移行 ― 一度しか走らないコードに一貫性は求められません
• 新しい領域での試行 ― ルールを決める前に、まず手を動かして「ルールが何であるべきか」を見つけ出す必要があるフェーズです
• 未整備のアーリーステージなチーム ― コードから後付けでルールを抽出するほうが速い場合があります

線引きの目安としては、長く保守する／複数人で触る／同じパターンが繰り返し出てくる コードはルール付き推論に寄せ、それ以外は純粋な推論でよい、というあたりになります。

5. 実例 ― 現場での適用パターン

すでに各レイヤーでルール付き推論を適用した事例がいくつか公開されているので、ここで紹介します。

アーキテクチャ駆動のコード生成

スキーマでアーキテクチャを縛る ── 人間とAIを同じルールで動かす - ZOZO TECH BLOG

チームのアーキテクチャガイドライン（層の責務、依存ルール、命名規則）を「人間向けのドキュメント」ではなく AIへの直接の入力 として扱う取り組みです。結果として、生成されたコードは「正しいファイルに、正しい層で、正しい命名で」着地するようになります。モデルが書き始める前に「ものはどこに置くか」がルールで伝わっているからです。

テストコード生成

同じ思想をテストに適用した事例です。「もっと良いテストを書いて」とプロンプトを工夫するのではなく、構造テンプレート（何をモックするか、何をアサートするか、テストケースの命名パターン）をルールセットとしてモデルに与えます。テストのブレが消え、レビューがほぼ機械的に進むようになります。

テストプラン生成

生成AIの入出力品質は「フォーマット」で決まる ― 中間表現とテンプレートの組み合わせ - newmo 技術ブログ

ルール付き推論を 仕様側の上流 にまで押し上げた事例です。PRDとテストプラン生成ルール（カバレッジ軸、エッジケースのカテゴリ、出力フォーマット）を組み合わせることで、汎用的なチェックリストではなく実用的なテストプランが得られます。これはまさに、PRD側のルールを具体的に適用した例だといえます。

3つの事例に共通しているのは、いずれも「より賢いプロンプト」を発明しているわけではない という点です。それぞれのチームが、これまで暗黙のうちに知っていたことを書き起こし、ルールとしてモデルへの入力にした結果が、これらの取り組みになっています。

6. まとめ ― プロンプトをチューニングするのではなく、ルールの土台を整える

• 推論こそが鍵であり、ルールはそのギャップを縮めるための手段です
• ルールにはコード側とPRD側の2つの側面があり、両方を揃えて初めて効果が出ます

この記事から1つだけ持ち帰るとしたら、プロンプトを頑張ってチューニングするのをやめ、AIが推論するためのルールという土台を仕様側とコード側の両方で整え、そのルール自体に仕事をさせる ということに尽きるのではないかと思います。

今回は必要な情報をドキュメント化することで、チームをスケールする方法を紹介します。

目的

暗黙値を形式知にして不要な属人化を解消することやチーム力を上げることです。

前提

不要な属人化とは暗黙な知識を持ってる人だけしか出来ない状態です。権限が必要な属人化は問題ないのでスコープ外です。

課題

ドキュメントを書く文化が無いと下記のような課題があります

依存度が高い

作業が完了する時間や条件が特定の知識を持った人に依存していることが多いです。作業や人が増えるにつれてその人への負荷が高くなる一方で持続可能な状態ではないです。

知識が失われる

特定の知識を持った人が居なくなるとその知識も失われることが多いです。チームが育つにつれて役割の変化やチーム移動などもあり得るので、チームとして知識をストックしていないと効率が悪いです。

必要な情報

上記のような課題が発生する知識の内容は下記の通りです

• 見たい情報がどこにあるか分からない
• ソースコードを読んでも背景が分からない・理解に時間がかかる
• 簡単な作業なのにただやり方が分からない

不要な情報

下記の内容はドキュメントとしては不要であったり他のツールで管理したいです

• ソースコードと同等の内容
• タスクや進捗管理に関するもの

解決策

それらの内容をドキュメントに書きましょう。ドキュメント化が進めば依存も減りますし知識も貯まります。主に下記の3つの情報をドキュメント化したいです。

どこに何があるか

どこを見れば知りたい内容があるか分かると効率が良いです。アーキテクチャ概要やモジュール構成の概要などがそれに該当します。

なぜそうなっているか

ドメイン知識やTipsなどがあると良いです。特定の知識や手法の選定理由などがそれに該当します。

どうやっているか

知識がなくてもできることは手順としてまとまってると誰でもできて良いです。また自動化で代用できると更に良いです。

こんにちは。ソフトウェアエンジニアの@kitasuke です。

今回はなるべく早いタイミングで小分けにレビューをすることで、コードレビューによるコードの手戻りを可能な限り減らす方法を紹介します。

概要

コードレビューにおける一般的なボトルネックのひとつは、コードに対するフィードバックと修正のサイクルを回す回数が多いことです。その中でも特にコードの手戻りが発生する場合は何回もコードを大幅に書き直すこともあるので、レビューの時間もかかりますし負荷も上がります。その主な原因は、コードを書く上で必要な機能仕様の理解度が低い、コードをどう書けば良いか設計が詰められていない、良いとされるコードの状態を言語化できていないことのどれかに当てはまることが多いです。 それらの詳細なコードがなくてもレビュー可能な内容はコードレビューよりもっと早い段階でレビューしたり、レビュー対象ごとに小分けにレビューしたり、作業のスコープを小さくすることでボトルネックの解消を図ります。

前提

課題設定の内容から最適な手法が決まるので、今回のやり方は同じような課題を抱えているチーム以外や課題は同じでもチーム構成などの環境が違う状況でも効果があるかは不明です。

レビュー目的

レビューの主な目的は、下記の2つの内容が問題なく実装されているかを確認することです。

• コードが仕様通りに実装されているか
• 良いコードで実装されているか

それぞれの詳細は下記のとおりです。

仕様通りのコード

実装されたコードが仕様通りの挙動になるかは最も重要な観点です。フロントエンドは表示に関わる内容がほとんどです。またサービスとして全体の統一感を保てるように他の仕様と矛盾点がないかであったり、仕様の実現可能性を確認するのも大事です。

良いコード

良いコードとは一般的にメンテナンス性が高いコードと言い換えられます。それは具体的には拡張性が高かったり、バグを生みにくかったり、可読性が高いコードなどに該当します。フロントエンドは表示に関する値のデータフローやデータモデリングの内容がほとんどです。そしてそれらをどうやって読みやすいコードで実装するかもポイントです。

課題

コードレビューにおける課題は色々あります。その中でもコードレビュー中にコードの手戻りが多く発生して、その過程で無駄になるコードの量が多くなることが一番の課題だと感じてます。そして手戻りは想定以上の時間を費やすことにも繋がります。

手戻りが多くなるのは、コードを書く時に何をどう実装すれば良いかあやふやな状態のまま詳細実装に進むことが主な原因です。またコードレビュー時にそれらも含めてレビュー対象が多すぎることも関連しています。

解決策

上記の課題を解決するための方針として、可能な限り早い段階でレビューすること、レビュー対象を小分けにしてレビューすること、作業のスコープを小さくすることを目指しましょう。

早めのレビュー

詳細なコードがなくてもレビューできる内容はコードレビュー時より早い段階でレビューすべきです。具体的には仕様の妥当性やヌケモレは大体の場合はコードが不要です。またデータモデリングやデータフローはインターフェイスがあれば十分です。これらは詳細なコードの実装の元となる非常に重要な内容なので、詳細なコードを書く前にレビューした方が手戻りが減り効率が良いです。

またコードを書く際やレビューする時はペアでリアルタイムにフィードバックを得ながら進めると効率が良いです。詳細なコードの実装はペアプロを行い、コードレビューはペアレビューを行うのが良いです。

小分けのレビュー

コードレビューだけで全ての内容をレビューするのは難易度も属人性も高くなります。上記のように詳細なコードがなくてもレビューできる内容は対象ごとにレビューしましょう。具体的には機能仕様レビューやアーキテクチャレビューというように、段階的に行うのが良いです。それらを抽象的にカバーできる手法の Design Docs を導入するのも良いです。

またコードレビューの中でも、内容ごとにレビューできる仕組みがあれば小分けにレビューできます。例えば文法チェックなどのコーディング規約はツールやCIに任せたり、アーキテクチャなどのプラクティスはドキュメントを用意したり、動作確認などのテストはユニットテスト・UIテストを実行すると良いです。

小さいスコープ

早めに小分けにレビューするにはひとつの作業のスコープを小さくすることも大事です。なるべく必要最低限の粒度に収まるように気をつけましょう。

効果検証

上記の解決策の効果を検証するには、定性的・定量的なデータの両方を見ます。定量的には Findy Team+ のサイクルタイム分析にあるレビューからアプルーブまでの平均時間が減少しているかを確認するのが手軽な方法だと思います。自社で計測ツールを作成する場合も同じような指標を見れば良いと思います。導入直後は定性的なデータに頼ることが多いと思いますが、長期的には定量的なデータを重視するのが理想です。

まとめ

今回はコードの手戻りを減らす手法を紹介しました。この方法は開発やレビューの生産性を上げるだけではなく、スケールする上でも大事な観点です。チームメンバー数が増えたりコードベースが古くなってくると上記のような課題が生まれることが多いので、環境の変化に適応してより良い開発環境を作りましょう。

こんにちは。ソフトウェアエンジニアの@kitasukeです。

今回は何かしらの事情でUIKitが必要なケースでも、SwiftUIを積極的に使う方法とその運用について説明します。

概要

開発効率やメンテナンスコストを考慮して、可能な限りSwiftUIでViewを実装するのが良いと考えます。ただSwiftUIの標準APIではまだ実現できないことがあるので、特別な事情でUIKitが必要となるケースがあります。UIKitとSwiftUIを組み合わせる場合は、 UIViewController や UICollectionViewCell などや画面遷移はUIKitで実装して、 UIView はSwiftUIで実装するのがバランス良いと思います。

おさらい

SwiftUIをUIKitで使うには、 UIViewRepresentable や UIViewControllerRepresentable が用意されていて一通りの機能が揃っています。今回の記事ではこれの逆バージョンを説明します。

• UIViewRepresentable | Apple Developer Documentation
• UIViewControllerRepresentable | Apple Developer Documentation

必要なこと

UIKitでSwiftUIを使うのに必要なことは下記の2点です。

• SwiftUIのViewの表示
• SwiftUIのViewの更新

基本的にはSwiftUIをUIKitで使う際に必要な UIViewRepresentable の func makeUIView(context: Self.Context) -> Self.UIViewType と func updateUIView(Self.UIViewType, context: Self.Context) と同等のインターフェイスがあればよいです。

Viewの表示

SwiftUIには UIHostingController が用意されてるので、これを利用してSwiftUIのViewをUIKitにセットして表示します。

UIHostingController | Apple Developer Documentation

具体的には2つのケースがあるので下記で説明します。どちらもやることはほぼ同じです。

UIViewControllerへの対応

UIViewController の一部にSwiftUIのViewを表示するケースです。 UIViewController に UIViewController を追加してレイアウトの指定をします。

let viewController = UIHostingController(rootView: SwiftUIView())
viewController.view.translatesAutoresizingMaskIntoConstraints = false
addChild(viewController)
view.addSubview(viewController.view)
viewController.didMove(toParent: self)

// configure constraints for AutoLayout
...

UIViewへの対応

UICollectionViewCell の一部にSwiftUIのViewを表示するケースです。 UIView に UIView を追加してレイアウトの指定をします。

let viewController = UIHostingController(rootView: SwiftUIView())
viewController.view.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(viewController.view)

// configure constraints for AutoLayout
...

Viewの更新

UIKit側で値を更新する場合は、その更新をトリガーにしてSwiftUI側で再描画する必要があります。手軽な方法として下記のように @Published を利用して実現できます。UIKit側で text の値が変わるとそれが @Published 経由でSwiftUIのViewが再描画が実行されます。

// UIKit

final class HostingViewState: ObservableObject {
    @Published var text: String = ""
}

final class ViewController: UIViewController {
    private let hostingViewState = HostingViewState()

    private func updateSwiftUIView() {
        hostingViewState.text = "text"
    }
}

// SwiftUI
struct HostingView: View {
    @ObservedObject var viewState: HostingViewState

    var body: some View {
        Text(viewState.text)
    }
}

Viewの再利用性

上記のインターフェイスだと、Viewのイニシャライザーの引数に HostingViewState が必要となりますが、これはUIKitのみに必要な無駄な依存です。このViewをSwiftUIだけで利用したい場合は不要なので、下記のようにラップして定義するのが良いと思います。

// for SwiftUI
struct SwiftUIView: View {
    var text: String

    var body: some View {
        Text(text)
    }
}

// for UIKit
struct HostingSwiftUIView: View {
    @ObservedObject var state: HostingViewState

    var body: some View {
        SwiftUIView(text: state.text)
    }
}

#if DEBUG
struct SwiftUIView_Previews: PreviewProvider {
    static var previews: some View {
        SwiftUIView(text: "text")
    }
}
#endif

運用方法

SwiftUIとUIKitの使い分け方として、必要最低限の機能のみUIKitで実装するのが良いと思います。例えば古いOSをサポートしているためにSwiftUIの refreshable を使わずににPull to Refreshを実現する場合、 UIScrollView にある refreshControl のみUIKitで実装して、そこで表示するViewはSwiftUIのViewで実装するというのが分かりやすいかと思います。 refreshable のようにいずれは必要としていた機能がSwiftUIに追加されることは多いはずので、このような使い分けにすればUIKitの実装を消す際も楽です。

refreshable(action:) | Apple Developer Documentation

また画面遷移に関してもUIKitの方が仕組みを導入しやすいので、こちらも同様にUIKitで実装するのが無難です。

まとめ

SwiftUIは宣言的な記述やデバッグや表示仕様の確認など色々な観点でUIKitと比較して開発効率が良いです。SwiftUIとUIKitを組み合わせると多少コード量が増えたりして面倒ですが、それでもSwiftUIを使うほうが良いと考えます。また将来的にSwiftUIに書き換える時の作業も減るのも地味に良い点だと思います。

今回はSwiftUIに適したView用のModelについて説明します。まだ色々試行錯誤している途中なので改善点があるかもしれませんが、現時点でまとめた内容を紹介します。

概要

ViewModelでView用の値を一元管理するケースにおいて、ビジネスロジック用とは別にView用のModelを定義してそれをSwiftUIのViewに渡すのが良いと考えます。そうすることでViewに向けたデータ整形のロジックの分散を防げたり、Viewの再利用性を高めたり、SwiftUI Previewsの書きやすさを上げられます。

前提

MVVMのアーキテクチャで説明しますが、データフローが分かりやすいReduxやFluxなど他のアーキテクチャにも適用可能です。また一部SwiftUIに特化した定義がありますが、基本的な概念はUIKitにも使えます。

Modelの名前衝突を防ぐためにAppとAppEntityの2つのモジュールで構成していますが、名前空間さえ分けられれば別の方法でも構いません。

アプローチ

まず全体像を図を見ながら説明して、その後に実装の詳細をコードを見ながら説明します。

全体像

全体の処理の流れを下の図で示します。ViewModelがViewに必要な値をModelとして生成して、それをViewにバインディングするというデータフローです。

次にそれぞれの役割を下記で説明します。

各Modelの役割

ビジネスロジックとViewの表示では扱う値の性質が異なります。両者で無理に同じModelを使い回すと不要な依存が増えたり処理が煩雑になったりするので、役割ごとに型を分けて使うのが良いと思います。下記で2つのModelの役割を説明します。

ビジネスロジック用のModel

ビジネスロジック用のModelは、全般的なビジネスロジックの対応に利用します。必要な情報ソース（サーバーやアプリ内DB等）から取得した値をSwiftの型に変換します。

// Product.swift in AppEntity module
public struct Product {
    public let id: String
    public let title: String
    public let price: Decimal
    public let isSoldOut: Bool
    public let isFavorite: Bool
}

View用のModel

View用のModelは、色々なViewを表示したり制御するために利用します。基本的に表示に使う値は String 型の値に整形されます。またUIのイベント（タップ等）により表示内容を更新したい値は、 @Published を利用してViewを再描画します。そのためView用のModelは ObservableObject を継承しています。

// Product.swift in App module
final class Product: ObservableObject {
    var id = ""
    var title = ""
    var price = ""
    var isSoldOut = false
    @Published var isFavorite = false
}

ViewModelの役割

ViewModelの役割は、ビジネスロジックから取得した値をView用への変換、Viewの表示内容の更新、UIのイベント処理の対応です。ビジネスロジックとは例えば値をサーバーから取得したりサーバーへ送信する処理を指しますが、具体実装については本題と関係ないので解説を省きます。

下記がViewModelの実装例です。それぞれの役割ごとにコードを抜粋して説明します。

import Combine
import AppEntity

final class ProductViewModel: ObservableObject {
    // state: loading|loaded
    @Published var isLoading = true
    @Published var product = Product()

    // internal use only for UI event or business logic
    private var _product: AppEntity.Product?

    private var businessLogicClient = BusinessLogicClient()
    private var cancellables: [AnyCancellable] = []

    // UI event handler
    lazy var favoriteButtonTapHandler: () -> Void = { [weak self] in

        // update with latest value for further internal use
        self?._product.isFavorite.toggle()

        // rebuild favorite view with isFavorite once it's changed
        self?.product.isFavorite.toggle()
    }

    private func getProduct() {
        isLoading = true

        businessLogicClient.getProduct()
            .sink(receiveCompletion: { [weak self] completion in
                self?.isLoading = false
            }, receiveValue: { [weak self] product in

                // get AppEntity product from business logic
                self?._product = product

                // transform AppEntity product to App product
                self?.product = Product(product: product)
            }
            .store(in: &cancellables)
    }
}

Modelの変換

ビジネスロジック用のModelからView用のModelへの変換は、下記のようなインターフェイスを用意します。大体の場合は対となるModelを引数に取れば十分ですが、Viewによっては複数のModelが必要なケースもあります。 String 型への整形などView用の値の生成は全てここで処理します。

import AppEntity

final class Product: ObservableObject {
    ...

    private static let priceFormatter = PriceFormatter()

    convenience init(product: AppEntity.Product) {
        self.init(
            id: product.id,
            title: product.title,
            price: priceFormatter.string(from: product.price) ?? "",
            isSoldOut: product.isSoldOut,
            isFavorite: product.isFavorite
        )
    }
}

Viewへのバインディング

ViewModelは状態をStateで管理します。一般的にはStateは Enum を使うのが良いですが、 サンプルコードなので手を抜いているのと @Published を使うことを想定して bool で表現しています。ViewModelはこのStateによって表示する値をViewに渡します。

今回は isLoading の値でデータ読み込み中もしくはデータ読み込み完了のStateと見なします。データ読み込み完了後には App.Product をViewに渡して表示したいので、 isLoading と product の両方を @Published でViewにバインディングして、その値が変わる度に描画を行うようにしています。

final class ProductViewModel: ObservableObject {
    ...
    private func getProduct() {
        isLoading = true

        businessLogicClient.getProduct()
            .sink(receiveCompletion: { [weak self] completion in
                self?.isLoading = false
            }, receiveValue: { [weak self] product in

                // get AppEntity product from business logic
                self?._product = product

                // transform AppEntity product to App product
                self?.product = Product(product: product)
            }
            .store(in: &cancellables)
    }
}

UIイベントの対応

Viewの表示内容を更新するタイミングはデータ読み込み後だけでなく、UIからのイベント後にも一部表示更新が必要なケースがあります。今回はボタンを押したら表示を変えるケースについて対応します。ボタン用のイベントハンドラーの favoriteButtonTapHandler 内で @Published の isFavorite の値を変えているので、その更新された値がViewに通知され適切な表示になるよう再描画されます。

final class ProductViewModel: ObservableObject {
    ...
    lazy var favoriteButtonTapHandler: () -> Void = { [weak self] in

        // update with latest value for further internal use
        self?._product.isFavorite.toggle()

        // rebuild favorite view with isFavorite once it's changed
        self?.product.isFavorite.toggle()
    }
    ...
}

Viewの役割

Viewの役割は、ViewModelの各Stateで表示するViewの制御と、Viewに必要な値をセットして表示することです。

それぞれの役割ごとにコードを抜粋して説明します。

Viewの制御

ViewはViewModelのStateごとに適切なViewを表示します。今回は isLoading がViewModelのStateです。それが true の時はデータ読み込み中なので LoadingView を表示して、逆に false の時はデータ読み込み完了と見なすので Product 情報を表示する ProductContentView を表示します。

struct ProductView: View {
    @StateObject var viewModel = ProductViewModel()

    var body: some View {
        if viewModel.isLoading {
            LoadingView()
        } else {
            ProductContentView(
                product: viewModel.product,
                favoriteButtonTapHandler: viewModel.favoriteButtonTapHandler
            )
        }
    }
}

Viewの表示

ViewはViewModelからStateごとに表示する値を渡してもらい、それを表示します。Product に関連した値はこのModelに全て内包されているので、Viewに対してはModelを渡します。それと追加でUIからのイベントハンドラーも必要なケースがあります。

struct ProductContentView: View {
    @ObservedObject var product: Product
    var favoriteButtonTapHandler: (() -> Void)?

    var body: some View {
        ZStack {
            if product.isSoldOut {
                SoldOutImageView()
            }
            VStack {
                HStack {
                    TitleView(title: product.title)
                    FavoriteIconView(
                        isFavorite: product.isFavorite,
                        tapHandler: favoriteButtonTapHandler
                    )
                }
                PriceView(price: product.price)
            }    
        }
    }
}

特徴

このアプローチの特徴は、Viewに向けたデータ整形のロジックの分散を防げたり、Viewの再利用性を高めたり、SwiftUI Previewsの書きやすさを上げられることです。下記でそれぞれの詳細を説明します。

データ整形

数値や日付は表示用に String 型へ整形する必要があります。また複数の状態を組み合わせて文字列を生成するケースもあります。そのような整形や生成をViewやViewModelで行うと、同じような処理が分散されるのでコードの見通しが少し悪くなります。代わりにView用のModel内で行うことで一元管理できて分かりやすいです。

Viewの再利用

上記の ProductView はStateによって適切なViewを表示するのでViewModelに依存していますが、 ProductContentView は表示する値とイベントハンドラーのみあれば十分です。このViewでもViewModelを引数にしてしまうと不要な依存となり、 ProductContentView を違うViewModel経由からも表示したい場合に再利用し難いです。Viewの引数には可能な限り最小限の粒度の値にすることで、Viewの再利用性が上がります。

SwiftUI Previews

SwiftUI Previewsで達成したいことは、表示用の値をViewに渡せば期待通りに表示されることの確認だと考えます。したがって、正しくStateを管理出来ているか、またビジネスロジック用のModelがView用のModelに正しく変換されているかは、ViewModelのUnit testで担保すればSwiftUI Previewsで確認する必要はないです。

また共通化されたView（LoadingView やErrorView等）は定義元以外では確認する必要ないので、基本的には正常系のStateの共通化されてないViewのみ確認できれば良いと考えます。

View用のModelのインターフェイス

下記のように Product は初期値を持つ init を定義して、SwiftUI Previewsで確認したい表示に必要な値だけセットできるインターフェイスを用意します。

final class Product: ObservableObject {
    ...
    init(id: String = "", title: String = "", price: String = "", isSoldOut: Bool = false, isFavorite: Bool = false) {
        self.id = id
        self.title = title
        self.price = price
        self.isSoldOut = isSoldOut
        self.isFavorite = isFavorite
    }
    ...
}

SwiftUI Previewsの実装例

今回は Product に関して、通常時、売り切れ時、お気に入り済みの状態の3つのパターンの表示を確認します。可読性やメンテナンス性を上げるために、これらの用途でそれぞれの状態ごとにモック用のメソッドを定義するのが良いです。ただし今回はサンプルコードなので全て init で代用します。

下記のように表示用の値をセットするだけで書けます。これがビジネスロジック用のModelであったりViewModelを引数に取るViewだと、整形前のデータやSwiftUI Previewsには関係ない不要な依存となるインスタンス生成などが必要で値のセットだけでも大変です。

#if DEBUG
struct ProductView_Previews: PreviewProvider {
    static var previews: some View {
        Group {

            // normal
            ProductContentView(
                product:
                    .init(
                        title: "title1",
                        price: "¥1,000"
                    ),
                favoriteButtonTapHandler: {}
            ),

            // sold out
            ProductContentView(
                product:
                    .init(
                        title: "title2",
                        price: "¥2,000",
                        isSoldOut: true
                    ),
                favoriteButtonTapHandler: {}
            ),

            // favorite
            ProductContentView(
                product:
                    .init(
                        title: "title3",
                        price: "¥3,000",
                        isFavorite: true
                    ),
                favoriteButtonTapHandler: {}
            )
        }
    }
}
#endif

注意点

いくつか注意する点があるので下記で説明します。

値の管理

ViewModelでビジネスロジック用とView用の2つのModelを管理する必要があるので、片方だけ更新して片方は忘れるというミスが発生する可能性があります。それを防ぐためにModelの変換についてもUnit testで担保する必要があります。

値の比較

View用のModelは ObservableObject を継承するためにclassで定義しています。したがって、インスタンスの比較ではなく値の比較をする際に非常に面倒です。ただ個別の値でなくModel自体の比較にはstructで定義しているビジネスロジック用のModel同士を比較すれば良いので、大きな問題ではないと考えます。

まとめ

一般的にデータフローやアーキテクチャ全般にも共通する考え方として、役割は可能な限り小さく持たせるのが良いです（今回の例では肝心のViewModelが役割を持ちすぎてますが、本題とずれるので無視してください）。今回はその考え方をModelに適用してSwift UIに最適化してみました。またSwiftUI Previewsで書きやすいViewは結果的にViewの再利用性が高くなる気がするので、その点でも今回のアプローチは良いのではないかと考えます。