AI-assisted coding did not remove the hard parts of shipping my Mac app

Thomas Ellon (Stewie) — Tue, 20 Oct 2026 08:06:17 +0000

Five lessons from building StepShot, where screen capture, OAuth, and installer behavior all need evidence beyond a successful build.

Disclosure: I’m the solo founder of StepShot. It is a self-funded side project built with AI-assisted programming. These are lessons from this project, not a benchmark of AI tools or a claim that the same approach fits every team.

Writing note: This article was drafted with AI assistance using StepShot project records and product documentation.

The earliest Git commit in StepShot is dated July 30, 2026. It scaffolds the app and capture engine. Since then, the work has expanded into editing, exports, optional cloud publishing, licensing, and release packaging.

AI assistance can produce code quickly. The more consequential question has been how to decide that a change is ready for a user’s Mac.

Here are five boundaries that have mattered in this project.

1. A successful build is not a successful installation

A desktop app can compile and still fail before its first window appears on another machine.

StepShot hit a concrete version of this problem: an older release packaged SwiftPM resource bundles in the app’s Resources directory while a generated bundle accessor expected them elsewhere. The developer machine had a build-directory fallback, so it could hide the defect. Signing and notarization did not prove that localization resources would load at launch.

The practical response was to verify the packaged app, including resource placement and a visible-window launch, rather than relying only on the executable produced by the build.

The general lesson is about the artifact boundary. Test the thing the user downloads, with the dependencies and resources it actually contains.

2. Cloud integrations need a clear job description

“Add Google Drive” sounds small until it leaves unanswered questions about identity, content, permissions, and failure.

In StepShot, Drive is an export destination. It uploads a reviewed document to the user’s account. It is not project synchronization and does not automatically make a guide public.

The desktop authorization flow uses a loopback callback, PKCE, and state validation. The product requests the drive.file scope, and credentials are kept in Keychain.

Notion has a different job. Publishing creates a new page composed of native editable blocks. Product OAuth credentials stay on the server; per-user tokens are held by the desktop app, and tutorial content goes from the app to Notion.

Those choices are more useful than describing both integrations as “cloud support.” They say what leaves the device, which identity owns the result, and what users can edit afterwards.

3. A lost response is not the same as a failed write

A network request can reach the service even when the app never receives its response. Blindly repeating the request can create duplicates.

StepShot’s Drive upload path retains a staged artifact and a pre-generated file ID for retry. If completion is uncertain, the app checks the remote result rather than assuming a new document is required.

Notion page and block writes need separate handling. Some explicitly rejected operations can be retried, but an ambiguous write must not be replayed as though nothing happened. Known partial page links remain useful because they let the user inspect the result.

This changed the interface work too. An upload needs visible state, a way to cancel, a meaningful error, and a recovery path. A spinner alone cannot tell the user whether they should wait, retry, or inspect a document that may already exist.

4. Update tools should preserve authored work

A freshly generated guide is not a substitute for a carefully maintained one.

StepShot’s tutorial comparison aligns old and new content and presents changes for review. Changes start unselected. Applying the selected changes creates an independent updated copy and preserves both source projects.

This is a useful design constraint for AI-assisted development as well: make it cheap to inspect a proposed change, and keep recovery possible when the proposal is wrong.

For a screenshot guide, the author might want a new image while preserving the old explanation. A comparison feature should help make that decision, rather than treating the newest recording as automatically authoritative.

5. Acceptance criteria should describe user outcomes

There is a difference between a repeatable test and an unnecessarily rigid one.

For a workflow recorder, application switches can be legitimate steps. An acceptance process that insists on exactly three captured events can accidentally test whether a person avoided switching windows, rather than whether the recorder captured the task correctly.

A more useful check identifies the actual outcomes: the intended actions were captured, the images match, unwanted events can be removed, the guide can be edited, and the published result makes sense.

The same principle applies to installers and OAuth. Verify a clean user environment, denied or cancelled authorization, interrupted uploads, and the signed candidate package. Keep evidence tied to the specific artifact instead of assuming a later build inherits every earlier result.

What I would keep in the workflow

Use AI assistance to accelerate implementation, but make the result concrete enough to inspect:

Give each integration a narrow, explicit data boundary.
Separate definite failures from uncertain remote results.
Keep original user content when generating an update.
Test the installed artifact and visible behavior.
Document limitations alongside the feature, not after someone discovers them.

StepShot 1.0.7 turns Mac workflows into editable screenshot guides, with optional Drive and Notion publishing. It is proprietary software for macOS 14 and later. Cloud AI is optional and uses the user’s own provider; there are no bundled model credits.

If you build desktop software with AI assistance, which failures still require the most hands-on verification in your release process?

Project information: https://stepshot.app/