アーキテクチャのルールをドキュメントに書いても、AIは過去の望ましくない実装パターンを律儀に再現してくる。ZOZOTOWNのiOSチームが選んだのは「努力目標」をやめ、コンポーネントの型・依存・命名・禁止パターンをスキーマとして定義し、そこからコードを自動生成する設計だった。
「ドキュメントのルールが守られない」問題をスキーマ化してコード生成に組み込むという解決策と、レビューの焦点を"書き方"から"プロダクト品質"へ移す設計思想を、個人開発でどう小さく再現するかまで。
ZOZOTOWNのiOSアプリ開発チームが直面していたのは、アーキテクチャのルールを文章で書いても守られないという壁だった（ZOZO TECH BLOG）。ViewModelやRepositoryの責務分割、命名規則、依存の向き——これらをドキュメントに丁寧に書いても、実装のばらつきは消えない。
そこにAIコーディングが加わると、この問題はさらに悪化する。AIは学習・参照したコードベースの中に残っている過去の望ましくない実装パターンまで、律儀に再現してしまうからだ。人間なら「ここは古いやり方だから今は使わない」と文脈で判断できるところを、AIは指示されない限り区別しない。ドキュメントという「努力目標」は、人間に対してすら弱いのに、AIに対してはほぼ無力に近い。
解決の軸は一つ。「守ってほしいルール」を人間が読む説明文ではなく、機械的に検証・生成できる構造として定義し直すことだ。
architecture-guidelines.mdが「何が正しい構造か」——ViewModelやRepositoryなど各コンポーネントの型・依存・命名・禁止パターンをスキーマとして定義する。もう一枚のarchitecture-templates.mdは「そのスキーマからどうSwiftコードを導くか」という生成ルールを持つ。ルールの定義と、ルールからコードへの変換を、はっきり別レイヤーに分けている。
運用は2段のコマンドで回る。/architectureコマンドが、Confluenceの仕様書やFigmaのデザインからYAML形式の画面設計（APIエンドポイント・ユーザーアクション・データモデルなど）を自動生成する。次に/codegenコマンドが、そのYAMLからView・ViewModel・Repository・モック・テスト雛形までのSwiftコード一式を導出する。
Swiftの型システムがコンパイル時に不正な状態を弾くのと同じ発想を、アーキテクチャのレイヤーにまで広げている——という言語化がこの記事の核心だ。文章のルールは読み飛ばせても、生成パイプラインを経由したコードは、最初からそのスキーマの形でしか出てこない。
ここが核心。ルールを守らせるのではなく、ルールから外れたコードがそもそも生成されない構造にした。人間へのお願いから、AIも人間も逃れられない仕組みへの転換。
効果として挙げられているのは「AIの書くコードがレビューを通る水準になった」という変化だ。命名・配置・レイヤー構成がプロジェクト標準に自動的に揃うため、AIコードにありがちなハルシネーション的な構造の逸脱が消えたという。
この設計が興味深いのは、副次効果としてレビュー文化そのものが変わった点にある。命名や配置、責務分割といった「コード品質」はスキーマが自動的に揃えるので、レビュアーはUX・エッジケース・ビジネスゴールとの整合性という「プロダクトとしての品質」に時間を使えるようになった。以前このブログで扱ったAIの「できました」を信じない検品文化の話と同じく、検品の対象を人間が判断すべき部分に絞り込む発想が根っこにある。
ZOZOTOWN規模のパイプラインをそのまま真似る必要はない。効いている考え方だけを抜き出すなら、次の3点になる。
本記事執筆時点のZOZO側の報告も、モデルの使い分けで費用を下げる話と同じく「劇的な数字」より「仕組みの設計思想」に価値がある内容だった。個人開発でCLAUDE.mdやrulesファイルを育てているなら、まず一つのコンポーネント種別（フォーム・API呼び出し・モデル定義など）だけをスキーマ化してみる、というのが最初の一歩になる。