スキーマでアーキテクチャを縛る ── 人間とAIを同じルールで動かす
はじめに こんにちは、ZOZOTOWN開発1部iOSブロックの@kitasukeです。 前回の記事「ZOZOTOWN iOS のアーキテクチャとチームの進化」では、MVCからMVVM、そしてMVVM + Repositoryへのアーキテクチャ進化を取り上げました。あわせて、レビュー文化をチームに根づかせてきた3年間も振り返っています。 ただ、アーキテクチャを文章で定義しても、書き手によって命名や責務分割はぶれが生じますし、AIに任せると過去の望ましくない実装パターンまで律儀に再現されます。ドキュメントによる「努力目標」では、アーキテクチャは守りきれません。 そこで発想を逆にしました。アーキテクチャを「守るべきルール」ではなく、構造化されたスキーマとして定義し、人間とAIの双方がそれに従うしかない形にします。Swiftの型システムがコンパイル時に不正を弾くのと同じ発想を、アーキテクチャのレイヤーにスキーマという形で持ち込みます。それが本記事で紹介する「スキーマでアーキテクチャを縛る」アプローチです。副産物として、設計からコードを自動生成するパイプラインも動いています。 目次 はじめに 目次 どんなスキーマを定義したのか architecture-guidelines.md — コンポーネントをスキーマで縛る architecture-templates.md — スキーマから Swift を導出するルール どうやって縛っているのか 画面ごとの設計を YAML で表現する /architectureと/codegen — 実際の運用 /architecture: 仕様書やデザインから YAML を起こす /codegen: YAMLからSwiftのコードを生成する 何が変わったのか AIの書くコードがレビューを通る水準になった レビューで「プロダクト品質」の話ができるようになった まとめ どんなスキーマを定義したのか 全体像はこうなっています。 仕様書 (Confluence) / デザイン (Figma) / 既存コード │ ▼ /architecture ┌─────────────────────┐ │ 設計 YAML │ ←── AI / Codegen 向け │ Human Doc (Markdown) │ ←── 人間向けレビュー資料 └─────────────────────┘ │ ▼（人間がレビュー・編集） │ ▼ /codegen Swift コード一式 ↑ 全工程でガイドラインとテンプレートが参照される 土台となっているのが、チームで整備した 2つのドキュメント です。 architecture-guidelines.md — 各コンポーネントのスキーマ（何が正しいか） architecture-templates.md — スキーマからSwiftを導出するテンプレート（どう書くか） architecture-guidelines.md — コンポーネントをスキーマで縛る 各コンポーネント（ViewModel、Repository、Translatorなど）を、型・依存・命名・必須ルール・禁止パターンなどのフィールドで厳密に定義しています。たとえばViewModelのスキーマは次のとおりです。 ### ViewModel - type: `@MainActor final class` - imports: [Foundation, Combine] - imports_forbidden: [APIModule] - depends_on: [RepositoryProtocol, UIModelTranslator, DataModel, UIModel] - nested_types: [ViewState, Router] - naming: {Feature}ViewModel - required: - ViewState enum で画面状態を管理（複数 Bool 禁止） - @Published private(set) で外部からの直接変更を防止 - 1 ユーザーアクション = 1 input メソッド（did{Verb}{Noun}） - forbidden: - キャッシュロジック（Repository の責務） - ログ送信の直接呼び出し（UseCase/別 Repository に分離） 自由に書ける余地を意図的に潰しているのがポイントです。ViewModelがAPIモジュールをimportした時点でアウトです。@Published を private(set) にしなかった場合もアウトです。自己流のMVVM解釈を許さない設計になっています。 architecture-templates.md — スキーマから Swift を導出するルール スキーマだけではSwiftコードの具体的な書き方までは決まりません。命名規則、ファイルの生成順序、各レイヤーのSwiftコードテンプレートなどを、もう一段別のドキュメントで固めています。ガイドラインがスキーマで、テンプレートが導出規則です。この2つが揃うことで、アーキテクチャのスキーマから具体的なSwiftコードが一意で決まる状態になりました。 どうやって縛っているのか 人間・AI・ツールの全員が、同じスキーマで動くようになっています。順に見ていきます。 画面ごとの設計を YAML で表現する コンポーネントのスキーマが決まっても、画面ごとの実装は別物です。そこで、画面ごとの設計を1枚のYAMLで記述します。 feature: ProductList domain: Product api: - id: fetchProducts method: GET path: /products response: items: [Product] actions: - trigger: didAppear api: fetchProducts - trigger: didTapRetry api: fetchProducts condition: "state == .error" models: data: - name: Product fields: id: String name: String brandName: String price: Int imageURL: URL ui: - name: ProductListUIModel fields: nameText: String brandText: String priceText: String このYAMLは、ガイドラインが定めたスキーマの「値」にあたります。画面のAPI、アクション、データモデルが構造化されて並んでいるだけで、曖昧さの入り込む余地はありません。 /architectureと/codegen — 実際の運用 この縛りを日々の開発で実行しているのが2つのスラッシュコマンドです。 /architecture: 仕様書やデザインから YAML を起こす 重要なのは、このYAMLを人間がゼロから書いているわけではないという点です。Confluenceの仕様書やFigmaのデザインを入力にすると、/architectureコマンドが設計YAMLと人間向けMarkdownの大部分を自動生成します。 人間の作業は「書く」ではなく「判断する」に寄っています。生成されたYAMLを読み、責務分割やエッジケースの扱いなど設計判断が必要な箇所だけに手を入れます。スキーマが縛ってくれているので、AIが起こしたYAMLも標準から外れた形にはなりません。 /codegen: YAMLからSwiftのコードを生成する レビューが終わったYAMLを /codegen に渡すと、Swiftコード一式が出力されます。具体的には、View / ViewModel / Repository / プロトコル / モック / ユニットテストの雛形 / 依存注入のコードです。 たとえば先ほどの ProductList.yaml のうち、以下の部分に注目します。 actions: - trigger: didAppear api: fetchProducts - trigger: didTapRetry api</
- Swift
- AI
- 自動化
- 設計