Why Small Separate SwiftUI Utility Packages Beat Monorepos with AI Agents

If you have a collection of SwiftUI utilities - a flow layout, a custom toolbar, a preference key helper - your instinct might be to put them all in one package. A tidy monorepo of reusable components. Clean, organized, professional.

Then you let an AI agent loose on your codebase and it immediately tries to refactor your entire utility library.

The Monorepo Refactor Problem

AI coding agents see connected code as an invitation to improve it. When your utilities live in a single package, the agent sees all of them in its context window. It notices that FlowLayout and GridLayout share some logic. It decides to extract a common LayoutEngine protocol. It refactors three utilities to use the new abstraction. It breaks two of them in the process.

You asked it to add a button to your app. It refactored your layout library.

Separate Packages as Agent Guardrails

When each utility is its own Swift package, the agent naturally treats it as a boundary. It sees FlowLayout as an external dependency, not as code it should modify. It uses the public API. It does not reach into the internals.

This is not a technical limitation - it is a cognitive one. The package boundary signals "this is settled code, use it as-is" in a way that a folder within a monorepo does not.

Practical Benefits

Beyond preventing unwanted refactors, separate packages provide:

• Smaller context windows: The agent only loads the package it needs, not your entire utility collection
• Clearer dependency graphs: Each package declares its own dependencies explicitly
• Independent versioning: You can pin a specific version of one utility without freezing everything
• Easier sharing: Other projects can depend on just the utilities they need
• Faster builds: Only recompile what changed

The Right Granularity

Not every file needs to be its own package. The sweet spot is one package per conceptually independent utility. A flow layout is independent. A custom color scheme is independent. A set of closely related text formatting helpers can stay together.

The test is simple: would you ever want to use this utility without the others? If yes, it should be its own package.

Working with AI Agents in Mind

Code organization decisions used to be purely about human readability and maintenance. Now there is a new factor: how will an AI agent interpret these boundaries? Separate packages create clear boundaries that both humans and AI agents respect.

More on This Topic

• Modular Swift Framework for macOS Agent
• SwiftUI Floating Toolbar on macOS
• AI Coding - Mass Produce Bad Code

Fazm is an open source macOS AI agent. Open source on GitHub.