Xcode の JSON xcproj：Xcode 27.2 の新しいプロジェクト形式

どの Xcode プロジェクトにも、わざわざ読む人はほとんどいないファイルがあります。project.pbxproj です。2 人が別々のブランチでファイルを追加したときに、マージのコンフリクトを生むのがこのファイルです。Xcode 27.2 はこれを置き換えます。Xcode の JSON xcproj 形式、つまり project.xcproj という名前のファイルは、同じプロジェクト構成を階層的な JSON として保存し、人も差分ツールもコーディングエージェントも実際に扱えるようにします。

このガイドでは、新しいファイルとは何か、Apple が変更した理由、その中身、プロジェクトの変換方法、そして切り替える前に確認すべきこと（古い Xcode のバージョン、CI、サードパーティのツール）を解説します。内容は Apple のドキュメントとリリースノート、Apple のオープンソースの形式パッケージ、@sarunw と Artem Novichkov の記事に基づいています。この形式は Xcode 27.2 で新たに追加されたもので、リリース間で詳細が変わる可能性があります。

Xcode 27.2 の新しい JSON .xcproj 形式とは？

.xcodeproj はフォルダです。その中に、共有スキームなどのほかのファイルとともに、プロジェクト構成ファイルがあります。Apple の記事「Updating your Xcode project configuration file format」は変更点をこう説明しています。以前のリリースではこのファイルは .pbxproj 拡張子のプロパティリストでしたが、Xcode 27.2 以降のデフォルトは「.xcproj 拡張子を持つ、より小さく、階層的で、自己記述的な JSON ファイル」です。

ほかのすべての前提となる事実が 3 つあります。

• 新規プロジェクトはデフォルトで JSON になります。 Xcode 27.2 以降で作成したプロジェクトは project.xcproj を使います。
• 既存のプロジェクトは勝手には変わりません。 Xcode 27 以降は両方の形式をサポートしており、切り替えるタイミングは自分で選べます。
• 形式はオープンソースです。 Apple はこれを、ファイルを型付きの値としてモデル化する Swift パッケージ xcode-project-format として公開しています。

Xcode 27.2 のリリースノートは、これを 1 行でまとめています。JSON ベースの形式は「より読みやすく、マージしやすく、コーディングエージェントが編集しやすい」ものです。27.2 が登場したとき @sarunw が述べたように、Xcode 27.2 は .pbxproj を新しい JSON の .xcproj 形式に置き換えます。

Apple が project.pbxproj を置き換えるのはなぜ？

従来の形式は、プロジェクトをオブジェクトのフラットな一覧として保存し、それぞれに意味のない 24 文字の 16 進数の ID をキーとして付けています。オブジェクト同士はその ID で参照し合います。ターゲットに Swift ファイルを 1 つ追加すると、たいていは複数のセクションが同時に変わります。ファイル参照、グループ内での位置、ビルドファイルのエントリ、ターゲットの Sources ビルドフェーズです。@sarunw は、おなじみのこの結果を、1 つの変更が「project.pbxproj の 3 つのセクションにわたって書き換えられる」と表現しています。2 つのブランチがそれぞれファイルを追加すると、こうした散らばった編集が衝突し、手作業で解決するにはセクションをまたいで ID を照合する必要があります。

ビルド設定にも似た問題がありました。Debug や Release などの構成ごとに設定のブロックが丸ごとあったため、1 つの設定が異なる値で何か所にも現れることがありました。

Apple のドキュメントは、新しい形式の理由を 3 つ挙げています。

1. レビューしやすい差分。 比較ビューの変更が、Xcode での操作と対応します。
2. マージのコンフリクトの減少。 JSON 形式は構成の変更を分離するので、関係のない編集が同じ行に触れる可能性が低くなります。
3. エージェントにやさしい。 コーディングインテリジェンスのエージェントが、代わりにファイルを編集しやすくなります。

Xcode 16 の同期フォルダでは、そのフォルダ内のファイルについてはすでにファイルごとのエントリがなくなっていました。@sarunw の記事によると、プロパティリストではターゲット、ビルドフェーズ、構成、パッケージ参照には引き続き ID が使われていたため、JSON 形式はさらに踏み込んだものになっています。

project.xcproj ファイルの中身は？

Apple はドキュメントで完全なサンプルファイルを公開していませんが、オープンソースのパッケージでトップレベルのキーを定義しています。default-configuration、configurations、localizations、files、targets、packages、build-settings などです。以下は、それらのキーを使い、@sarunw のデモプロジェクトの値を入れて切り詰めた抜粋で、完全なファイルではありません。

{
  "default-configuration": "Debug",
  "build-settings": {
    "DEBUG_INFORMATION_FORMAT[config=Debug]": "dwarf",
    "DEBUG_INFORMATION_FORMAT[config=Release]": "dwarf-with-dsym"
  }
}

ビルド設定は 1 回だけ書きます。構成ごとに異なる値が必要な場合は、上の [config=Debug] のように、条件をキーに含めます。ファイルは files ツリーのエントリで、別のビルドフェーズの一覧から参照されるのではなく、それぞれが自身のターゲットメンバーシップを持ちます。@sarunw のサンプルでは、ファイルは 1 行です。

{ "path": "CatalogView.swift", "target-membership": [ "ToolbarPlacements/compile-sources" ] }

サイズの差ははっきりしています。@sarunw のデモプロジェクトでは、300 行のプロパティリストが 123 行の JSON になりました。Artem Novichkov の比較では、同じ Swift パッケージを追加すると、project.pbxproj では 5 か所で 24 行、project.xcproj では 2 か所で 12 行でした。結果はプロジェクトによって異なりますが、傾向は一貫しています。

Xcode プロジェクトを JSON の xcproj に変換するには？

まず作業内容をコミットして、変換をきれいな独立した変更にしておきます。そのうえで、Xcode 27.2 で次の操作を行います。

1. プロジェクトナビゲータのいちばん上にあるプロジェクトを選択します。
2. ファイルインスペクタを開きます。
3. Project Document の Project Format ポップアップメニューで JSON を選びます。
4. ダイアログが表示されたら、Continue をクリックします。

.xcodeproj フォルダ内では、project.pbxproj が削除され、project.xcproj が追加されます。Apple によると、ソース管理を使っている場合は、その 2 つのファイルの変更を破棄すれば切り替えを元に戻せます。スキームやバンドル内のほかのファイルは変更の対象外です。

スクリプトや大規模なリポジトリ向けには、Xcode 27.2 の xcodebuild で双方向に変換できると Artem Novichkov が報告しています。また、変換したファイルが元のファイルを置き換えることも確認しており、これも先にコミットしておくべき理由の 1 つです。Apple の記事には記載がないので、自分のマシンで xcodebuild -help を確認してください。

xcodebuild -project Weather.xcodeproj -convert-project xcproj
xcodebuild -project Weather.xcodeproj -convert-project pbxproj

.xcproj を読める Xcode のバージョンとツールは？

Apple のドキュメントによると、.xcproj 形式は Xcode 27 以降と互換性があり、リリースノートでは、この形式を使うプロジェクトは Xcode 27 の以前のバージョンでも開けるとされています。つまり、Xcode 27.0 や 27.1 のチームでも変換済みのプロジェクトを開けますが、変換のオプション自体は 27.2 にあります。Xcode 26 以前を使う人がいる場合はプロパティリストの形式が必要で、@sarunw の記事でも、従来の Xcode のバージョンにはこちらを選ぶとされています。

サードパーティの対応はまだ進行中です。多くのツールの土台になっている Tuist の XcodeProj ライブラリは、9.17.0 のリリースで「[Experimental] support Xcode 27.2's JSON project format (project.xcproj)」を追加しました。XcodeGen と CocoaPods の xcodeproj gem での対応は確認できなかったため、project.pbxproj を編集するツールは、そのリリースノートで対応が明記されるまでは未対応として扱ってください。プロジェクトを仕様ファイルから生成していてコミットしていない場合は、ジェネレータが動き続ける限り、形式はそれほど重要ではありません。

独自のツールには、Apple のパッケージを使うほうがよいでしょう。Swift 6.1 以降が必要で、macOS 14 以降やほかのプラットフォームでビルドでき、Apache 2.0（Runtime Library Exception 付き）でライセンスされています。README では、XCSchema.Project でプロジェクトを読み込む方法が示されています。

import XcodeProjectFormat

func listTargets(in projectURL: URL) throws {
    let projectData = try Data(contentsOf: projectURL)
    let project = try XCSchema.Project(jsonRepresentation: projectData)
    for target in project.targets {
        print(target.name)
    }
}

xcproj はコーディングエージェントと CI にどう役立つ？

@sarunw はこの変更を、JSON 形式は人が読みやすく、コーディングインテリジェンスのエージェントが編集しやすいとまとめており、Apple 自身の表現とも一致しています。プロパティリストにファイルやパッケージを追加するエージェントは、有効な ID を作り出し、それを参照するすべてのセクションを更新しなければなりません。JSON なら、編集はプルリクエストでレビューできる小さな局所的な変更で済みます。

Apple のパッケージには、ライブラリをもとにしたコマンドラインツール xcprojformatter も含まれています。Artem Novichkov によると、xcrun xcprojformatter で実行するとファイルを正規の形式で出力し、--update を付けるとその場で書き換えます。正規の形式になっていない手作業やエージェントによる編集はフォーマッタの差分に現れるので、CI のチェックとして役立ちます。使っているバージョンが受け付ける正確な引数は、xcrun xcprojformatter --help で確認してください。

xcrun xcprojformatter --update MyApp.xcodeproj/project.xcproj
git diff --exit-code -- MyApp.xcodeproj/project.xcproj

また、フォーマッタはスペルミスのキーなど、認識できないキーを黙って削除することも確認しています。すべてを検証してくれると思い込まず、変更内容を確認してください。マージのコンフリクトの後も同じです。JSON を解決し、フォーマッタを実行し、ターゲットとパッケージが Xcode で正しく見えることを確認しましょう。

JSON のプロジェクト形式は iPhone Duo アプリに関係がある？

アプリの動作には関係ありません。プロジェクト形式が変えるのは Xcode が構成を保存する方法だけで、iPhone や iPhone Duo 向けにビルドするアプリは同じです。関係するのは、その周辺の作業です。アプリを iPhone Duo に対応させるには、iOS 27.1 SDK でリビルドし、多くの場合ブランチをまたいでプロジェクトの設定を変更します。それはまさに、project.pbxproj でマージのコンフリクトが起きるタイミングです。

また、最新のベストプラクティスと新しい API を扱う Xcode 27 の組み込みのエージェントスキルとも相性がよい形式です。@sarunw が指摘しているように、以前の uikit-app-modernization スキルは app-resizability になり、iPhone Duo に対応しました。その作業にエージェントの手を借りる場合、JSON のプロジェクトファイルなら変更がレビューできる程度に小さく収まります。その面については Xcode 27 のエージェントスキルのエクスポートのガイドで、アプリ自体の変更については iPhone Duo 対応チェックリストで解説しています。

まとめ

• Xcode 27.2 では、新規プロジェクトのデフォルトとして、project.pbxproj が、より小さく階層的な JSON ファイル project.xcproj に置き換わります。
• JSON 形式では差分が操作と一致し、変更が分離されてマージのコンフリクトが減り、コーディングエージェントも編集しやすくなります。
• 既存のプロジェクトは、ファイルインスペクタの Project Document で変換します。元に戻せるよう、先にコミットしておきましょう。
• .xcproj は Xcode 27 以降で開けます。Xcode 26 を使う人や CI マシンがある場合は、プロパティリストのままにしましょう。
• 切り替える前に、project.pbxproj を解析するジェネレータ、スクリプト、依存関係マネージャを確認しましょう。独自のツールには、Apple のオープンソースのパッケージと xcprojformatter が役立ちます。

プロジェクトが整ったら、デバイスで活かしましょう。まずは iPhone Duo 対応チェックリストから始め、ほかのデベロッパが公開したアプリを Built for the fold でご覧ください。