Codex Swift: How to Make Codex Check Its Own iOS Changes with the CFA Change Gate

Oct 23

6 min read

The short answer

To get Codex to write Swift that still fits your iOS app after the tenth change, give it a checklist to run before and after every edit. The free, open-source CFA AI Toolkit for iOS includes one, called the CFA change gate. It asks the AI to map the screens it's about to touch and say what each new type owns before it writes code, then to review the finished change as one feature slice before it hands it back. Seven of the toolkit's eight skills tell the AI to read it, so once the Codex plugin is installed, an ordinary request is enough:

Using CFA, add a new feature to the tab bar but keep it locked under an IAP.

💡 What this article covers

What the change gate is, what Codex writes down before it edits your Swift, which rules it protects, what it checks before it delivers, and how you can check the result yourself.

Why does AI-written Swift drift over time?

An AI coding agent usually answers each request on its own. One change adds a helper that duplicates something an existing type already does. Another passes a model into a screen's initializer because that was quickest. A third skips the tests because the build passed. None of these looks serious alone, but after a few weeks the app no longer has one clear owner for each job.

CFA (Cooperative Feature Architecture) is a blueprint that gives every kind of code a clear home in an Xcode project. The change gate is how the toolkit keeps an AI agent inside that blueprint on every change, not just on the first one.

What is the CFA change gate?

It's a short Markdown file in the toolkit, architecture/cfa-change-gate.md, and a copy sits in the references folder of the skills that use it. The file describes itself as "a short design pass and a final structural review, not a line-by-line ceremony."

The App Creation, Feature Work, Architecture Adoption, Architecture Review, Codebase Tidy, Unit Tests and Legacy GCD migration skills all point the AI to it. The eighth skill, Swift Code Quality, focuses on Swift standards instead.

What does Codex write down before it changes your code?

First, the affected route for every screen in scope. In CFA that route always has the same shape:

Screen View → Screen ViewModel → AppModel.shared feature → provider / storage

Second, a one-line ownership statement for every new or changed type, in the form "This type owns …", plus a check that an existing type doesn't already own that job. This is the step that stops duplicate managers and competing copies of the same data before they're written.

Third, the gate lists the CFA invariants the change must preserve, unless you explicitly ask to change the architecture. If any invariant fails, the instruction is to correct the plan before expanding the implementation.

Which rules does the change gate protect?

The gate lists more than twenty invariants. Here are a few that show the idea:

Every screen-level View has one adjacent, dedicated ViewModel, created by the View with @State.
Screen View initializers don't receive AppModel, features, repositories or ViewModels.
Features own feature state and behaviour; ViewModels own screen presentation state and route user intent to their feature.
Every concrete feature type ends in Feature, such as SettingsFeature, and there's no matching FeatureAPI protocol. Tests inject a fake repository or provider instead.
Database availability never gates the interface. If storage fails to open, the affected feature screen shows its own error and the rest of the app stays usable.
ViewModel methods name the work they do, such as refresh(), save() or retry(), never refreshTapped() or screenAppeared().

This is what a ViewModel looks like when it follows those rules. It's from the toolkit's CFA App Xcode template, trimmed slightly:

import Foundation
import Observation

@MainActor
@Observable
final class GitReposViewModel {
    private let gitReposFeature: GitReposFeature

    init(gitReposFeature: GitReposFeature = AppModel.shared.gitReposFeature) {
        self.gitReposFeature = gitReposFeature
    }

    var repos: [Repo] {
        gitReposFeature.repos
    }

    func refresh() async {
        await gitReposFeature.refresh()
    }
}

The ViewModel takes only its one feature, defaulted from AppModel.shared so a test can pass in an isolated replacement. The data comes from the feature, and the method is named after the work it does.

What does Codex check before it delivers the change?

The second half of the gate is a review of the changed source as one feature slice, not as isolated files. Among other checks, it asks the AI to:

Trace every affected screen to its ViewModel and its default AppModel feature.
Confirm no screen initializer gained dependency plumbing.
Confirm every new screen and feature has a named test file under View Model Tests and Feature Tests.
Check that repeated button presses and overlapping refreshes share one piece of work instead of starting duplicates.
Search for AppModel.shared stored elsewhere, direct URLSession calls and ModelContainer outside the storage boundary.
Check every new or moved Swift file has the imports its own declarations need.
Remove abandoned files, duplicate state owners, placeholder names and speculative abstractions created during the change.

Finally, it asks the AI to build and run focused tests when they're available, and to report an unavailable runtime or toolchain honestly: "do not turn missing verification into a pass." That last line matters. It means a good report from Codex tells you what it couldn't check, too.

Step 1: Install the CFA AI Toolkit plugin for Codex

Download and extract the plugin release from the CFA AI Toolkit for iOS repository, then double-click Install.command. In Terminal, the equivalent is:

node scripts/install.mjs

Open a new Codex conversation and paste the confirmation message from the README:

I have installed CFA AI Toolkit for iOS from
https://github.com/3DaysOfSwift/CFA-AI-Toolkit-for-iOS.
Do you have access to create and maintain iOS projects with CFA?

Codex should confirm that it can see the CFA skills. If you use Claude Code or another tool that reads plain skill folders, the README explains how to copy the eight skill folders instead. The cfa command used in Step 3 comes with the Codex plugin install, so it may be missing if you only copied the skills folder.

Step 2: Ask for a change as you normally would

You don't need to mention the gate. Ask for the work, and start with "Using CFA" so your intention is clear. These prompts come from the toolkit's README:

Using CFA, add a new feature to the tab bar but keep it locked under an IAP.
Using CFA, now that we added a new feature, tidy up the code.
Using CFA, remove the new feature and all IAP code too.

Each request runs through a skill that reads the change gate, so the route mapping and the delivery review are part of the work rather than something you have to remember to ask for.

Step 3: Check the result yourself

Read Codex's summary for the route it changed, the ownership of any new types, and which builds and tests actually ran. Then, from your project folder, run the toolkit's read-only inspector:

cfa inspect /path/to/your-xcode-project

It maps each screen to its adjacent ViewModel, its visible AppModel.shared feature route and its named tests, and flags missing links without changing anything. The README is clear that it's a lexical source check, not a compiler, a test run or automatic CFA certification, so treat it as a quick map, not a verdict.

What to Remember

The CFA change gate is a short checklist the AI runs before and after a change: map the route and owners first, then review the finished slice.
Seven of the eight CFA AI Toolkit skills read it, so ordinary "Using CFA" requests in Codex follow it.
It protects rules like one ViewModel per screen, Features owning state, and no dependency plumbing in screen initializers.
It asks the AI to report checks it couldn't run instead of treating them as passed.
cfa inspect gives you a quick, read-only map to check the result yourself.

Does the change gate slow Codex down?

It adds a short planning step and a review at the end. The file itself says it's "a short design pass and a final structural review, not a line-by-line ceremony." In exchange, problems are caught while the plan is still cheap to change.

Can I ask Codex to break one of the rules?

Yes. The invariants apply "unless the developer explicitly asks to change the architecture," so you stay in charge. Say clearly what you want changed and why.

Is the CFA AI Toolkit free?

Yes. It's open source under the MIT licence, so you can use, change and share it, including in commercial apps.

About Us

3 Days of Swift Concurrency is created by Matthew Thomas, an iOS developer building in public since 2022. He publishes the free, MIT-licensed CFA AI Toolkit for iOS and reference apps on GitHub. Visit 3DaysOfSwiftConcurrency.com to follow along. The paid training programme is still being built: a soft launch is targeted for 1 December 2026, but that date depends on deadlines being met and isn't guaranteed.