Codex で Swift 開発を進める手順と設定のコツ
Codex は Web やバックエンド開発で広く使われてきたが、v0.142 系の安定版が普及して長時間の自律実行が実用段階に入ったことで、iOS・macOS アプリの主要言語である Swift の開発に持ち込む例も増えている。Xcode 中心だった Swift 開発に、ターミナルから動く Codex をどう組み合わせるかは多くの開発者の関心事だ。本記事ではプロジェクトの始め方から AGENTS.md による文脈共有、SwiftPM でのビルドとテスト、そしてつまずきやすい点までを実践的に解説する。
Codex を Swift 開発に使う最大の利点は、ターミナルから動くエージェントが Xcode の外でコードの読解・修正・テスト実行までを担える点だ。Swift Package Manager（SwiftPM）を使うプロジェクトであれば swift build や swift test をそのまま実行でき、Codex は出力を読んでエラーを直すループを自律的に回せる。Xcode の GUI が必須だった作業の一部を、コマンドラインの開発フローに移せるのが大きい（出典: https://openai.com/codex/ ）。
一方で、iOS シミュレータの GUI 操作や実機ビルド・署名のように Xcode と macOS の環境に強く依存する作業は Codex 単独では完結しない。Codex が得意とするのはコードの生成・リファクタリング・テストコード作成・ビルドエラーの解消であり、UI の目視確認や App Store への提出は人間と Xcode が担う。Codex を「コードを書いてテストを通すところまでの担当」と位置づけるのが現実的な分担だ。
本記事では、SwiftPM プロジェクトでの Codex の始め方、AGENTS.md に Swift の文脈を書く方法、ビルドとテストを Codex に任せる流れ、そして注意点までを順に解説する。Swift は型が厳格でコンパイラの警告も多い言語であり、テストとビルドという機械的に検証できる足場を Codex に与えることが、Swift 開発で Codex を活かす鍵になる。Apple の公式ドキュメント（出典: https://www.swift.org/ ）が示す言語仕様やパッケージ構成を前提に、実務的な手引きとしてまとめた。
目次 (9)
Codex は Swift 開発でどこまで使えるか
Codex を Swift 開発に導入するとき、最初に押さえるべきは「どこまでが Codex の守備範囲か」という線引きだ。Codex はターミナルで動くコーディングエージェントであり、リポジトリ内のファイルを読み、編集し、シェルコマンドを実行できる。Swift の場合、この能力がそのまま活きる領域と、Xcode と macOS の GUI 環境に依存して活きにくい領域がはっきり分かれる。
活きる領域は、コードの読解とリファクタリング、新規型や関数の実装、テストコードの作成、そしてビルドエラーやコンパイラ警告の解消だ。Swift はオプショナルや並行性（async/await、actor）など型システムが厳格で、コンパイラが出すエラーメッセージが具体的に原因を指す。Codex は swift build の出力を読んで「どの行のどの型不一致が問題か」を理解し、修正を当ててもう一度ビルドする、というループを自律的に回せる。型エラーという明確なシグナルがあるぶん、Codex の自己修正が効きやすい言語だと言える（出典: https://www.swift.org/documentation/ ）。
一方、活きにくい領域は GUI と環境依存の作業だ。iOS シミュレータでアプリを起動して画面を目視確認する、Storyboard や SwiftUI プレビューの見た目を調整する、実機ビルドのために証明書とプロビジョニングプロファイルを扱う、App Store Connect に提出する——こうした作業は Xcode と macOS のグラフィカルな環境が前提であり、ターミナルのエージェントだけでは完結しない。Codex に画面の見た目を判断させることはできないため、UI の最終確認は人間が Xcode で行う前提で分担を組む必要がある。
つまり Codex は、Swift 開発の「コードを書いてテストを通すまで」を担うパートナーと考えるのが適切だ。ロジック層の実装、データモデルの定義、ネットワーク処理、ユニットテストの整備といった、コマンドラインで検証可能な部分に Codex を集中させ、画面確認やリリース作業は人間が引き取る。この役割分担を最初に決めておくと、Codex に何を任せ何を任せないかの判断で迷わなくなる。
Codex で Swift プロジェクトを始める手順
ここからは、SwiftPM をベースにした Swift プロジェクトで Codex を使い始める流れを 4 ステップで整理する。Xcode プロジェクト（.xcodeproj）中心の構成でも考え方は同じだが、コマンドラインでビルド・テストが回せる SwiftPM 構成のほうが Codex との相性は明確に良い。
Step 1: SwiftPM でビルド・テストできる状態にする
最初にやるべきは、ターミナルから swift build と swift test が通る状態を作ることだ。新規であれば swift package init --type executable（あるいは --type library）でパッケージの雛形を生成し、Package.swift に依存関係とターゲットを定義する。既存の Xcode プロジェクトでロジックを SwiftPM のローカルパッケージに切り出しておくと、その部分は Codex がコマンドラインだけで扱えるようになる。Codex はビルドとテストの成否を判断材料にするため、この足場がないと自己修正のループが回らない。まずは人間が手元で swift test が緑になることを確認してから Codex に渡すのが鉄則だ。
Step 2: Codex を起動してプロジェクトを把握させる
ビルド環境が整ったら、プロジェクトのルートで Codex を起動する。最初のタスクはコード生成ではなく「現状把握」にするとよい。「このパッケージの構成と主要な型の役割を要約して」と依頼すると、Codex は Package.swift やソースを読み、ターゲット構成・依存関係・公開 API の概要を返す。ここで Codex の理解にずれがあれば、その時点で補足説明を加える。いきなり大きな実装を頼むより、Codex がリポジトリの地図を正しく持っているかを先に確認するほうが、後続のタスクの精度が上がる。
Step 3: 小さく区切ったタスクを渡す
把握ができたら、実装タスクを小さく区切って渡す。Swift の場合、「新しいモデル型 User を Codable 準拠で定義し、対応するユニットテストを追加して swift test が通ることを確認して」のように、完了条件をテストで表現すると Codex が動きやすい。Codex は実装→swift test 実行→失敗箇所の修正→再実行というループを自分で回し、テストが緑になった状態を成果物として提示する。一度に複数機能を頼むより、テストで検証できる単位に分けて渡すほうが、レビューも修正も容易になる。
Step 4: 差分をレビューして Xcode で最終確認する
Codex が変更を終えたら、人間が差分をレビューする。Swift では特に、オプショナルの強制アンラップ（!）の乱用、@MainActor の付け忘れによる並行性の警告、リテイン循環につながるクロージャのキャプチャといった、テストだけでは拾いきれない品質面を確認する。ロジックの妥当性とテストの網羅性を見たうえで、UI に関わる変更があれば Xcode を開いてシミュレータで挙動を目視する。コマンドラインで完結する部分は Codex、画面の最終確認は人間と Xcode、という分担をこのステップで締める。
AGENTS.md で Swift プロジェクトの文脈を渡す
Codex はタスクを受け取るたびに、リポジトリ直下の AGENTS.md を読んでプロジェクトの前提を把握する。Swift 開発では、この AGENTS.md に言語固有のルールを書いておくことで、Codex の出力をプロジェクトの慣習に揃えられる（出典: https://openai.com/codex/ ）。何も書かないと、Codex は一般的な Swift の書き方で実装してしまい、チームの規約とずれることがある。
AGENTS.md に書いておくと効果が高い項目は、次のようなものだ。
- ビルドとテストのコマンド:
swift build/swift test、あるいはxcodebuildを使う場合の正確なスキーム名と引数 - 対応バージョン: サポートする Swift のツールチェーンと iOS のデプロイメントターゲット
- コーディング規約: 命名規則、
SwiftLintなどの静的解析ツールを使っているかどうかとその設定の場所 - アーキテクチャ方針: MVVM や TCA などの採用パターン、ディレクトリ構成のルール
- 依存管理の方針: SwiftPM を正とするか、追加してよいライブラリの範囲
特に重要なのが、検証コマンドを明示することだ。「変更後は必ず swift test を実行し、すべて成功した状態で完了とすること」と書いておけば、Codex はタスクの締めくくりに自分でテストを回し、失敗していれば修正してから報告する。Swift はコンパイルが通っても実行時の挙動で差が出る言語だけに、テスト実行を完了条件として AGENTS.md に固定しておく価値は大きい。
なお AGENTS.md には文字数の上限（既定で 32 KiB）があるため、規約の全文をそのまま貼るのではなく、要点を箇条書きで載せ、詳細は別ファイル（例: CONTRIBUTING.md や lint 設定ファイル）への参照で示すのが現実的だ。Codex は必要に応じて参照先のファイルも読みに行くため、AGENTS.md は「どこを見ればよいかの地図」として簡潔に保つのがよい。
Codex で Swift 開発するときの注意点
Codex を Swift 開発に取り入れるうえで、つまずきやすい点を三つ挙げる。
ビルド環境の前提を Codex に押し付けないこと。 iOS アプリのビルドは macOS と Xcode のツールチェーンに依存する。Codex が動く実行環境に Xcode の iOS SDK が入っていなければ、xcodebuild でのシミュレータ向けビルドは失敗する。ロジック層を SwiftPM のクロスプラットフォームなターゲットに切り出し、そこは swift test で検証できるようにしておくと、Codex が確実に回せる範囲が広がる。環境が許す作業と許さない作業を見極めて渡すことが、無駄なリトライを防ぐ。
並行性と型安全の警告を見落とさないこと。 Swift の async/await や actor を使う並行コードは、コンパイルが通っても @Sendable 関連の警告やデータ競合の潜在リスクが残ることがある。Codex は警告を消すために安易に @unchecked Sendable を付けたり、@MainActor の境界を雑に広げたりすることがあるため、並行性に関わる差分は人間が意図を確認する必要がある。テストが緑であることと、並行性設計が正しいことは別の問題だと意識しておきたい。
生成コードをそのままマージしないこと。 Codex の出力は確率的な補完であり、Swift らしいイディオム（値型の活用、プロトコル指向、オプショナルの安全な扱い）から外れることもある。強制アンラップの多用やエラーの握りつぶしは、テストを通っていても保守性を下げる。差分は必ずレビューし、必要なら「強制アンラップを使わず guard let で書き直して」のように追加指示で修正させる。Apple が公開する Swift の API デザインガイドライン（出典: https://www.swift.org/documentation/api-design-guidelines/ ）を AGENTS.md から参照させておくと、出力がイディオムに近づきやすい。
まとめ
Codex は Swift 開発において、コードを書いてテストを通すまでの工程を担う有力なパートナーになる。SwiftPM でビルドとテストが回る足場を用意し、AGENTS.md に言語固有の規約と検証コマンドを書いておけば、Codex は型エラーやテスト失敗を手がかりに自律的に修正のループを回せる。一方で、iOS シミュレータでの目視確認や実機ビルド・署名・提出といった Xcode と macOS に依存する作業は人間が引き取る、という分担を最初に決めておくことが重要だ。Codex を意思決定者ではなく実装のパートナーと位置づけ、テストという機械的な足場を与えること——これが Swift という型に厳格な言語で Codex を最大限に活かす近道になる。
