Iterating Effectively

1. Change one thing at a time

After the first build, each follow-up prompt should target one change. When you stack multiple changes, the Agent has to make tradeoffs and some changes land partially or get misinterpreted.

Focused prompt:

Change the navigation to a left sidebar. Keep the top bar for user settings only.

Stacked prompt (avoid this):

Change the navigation to a sidebar, redesign the dashboard cards, add a search bar, and switch to dark mode.

Break that into four separate prompts. You’ll get cleaner results and it’s much easier to catch and roll back something that didn’t land right.

---

2. Be precise when correcting

When something doesn’t look right, describe exactly what to change and what to keep. Vague correction prompts often produce overcorrection.

Vague:

The cards don't look right.

Precise:

The task cards feel too tight. Increase the vertical padding inside each card and add more spacing between cards in the list. Keep the card background, border, and typography exactly as they are.

Use direction words: replace, update, adjust, remove, increase, move, keep. Avoid: fix, improve, make it better. These give the Agent too much discretion.

---

3. Target the right layer

Every app has three layers you can iterate on independently. Knowing which one you want to change helps you write a more precise prompt.

Layer	What it covers	When to iterate here
Design	Colors, typography, layout, spacing, components	Visual changes that don’t affect behavior
Logic	User flows, feature behavior, data operations	Changing what the app does, not how it looks
Data	Entities, relationships, fields, storage	Adding new data types or changing data structure

Targeting design only:

Design change only, don't touch functionality. Make the sidebar narrower, switch the background to #0F0F14, and increase the font size on nav labels by 2px.

Targeting logic only:

Logic change only, don't change any design. After a user submits a booking request, send them back to the dashboard with a success toast. Currently the page just reloads.

For developers: Layer isolation is even more precise in the Manual Builder. If you want to change a calculation in a specific API route without the Agent touching any other layer, open that route directly in the Manual Builder and edit the code block. Agent chat for broad changes, Manual Builder for surgical ones.

---

4. Agent chat vs Manual Builder: which to reach for

The Mayson Agent and the Manual Builder serve different purposes. Knowing which to use saves time and prevents unintended changes.

Use the Agent chat when:

• You want to add or change a feature
• You’re making design or layout changes
• You’re modifying how the app behaves end to end
• You want to add a new user role or flow

Use the Manual Builder when:

• You need to edit a specific API route’s logic without changing anything else
• You want to add a custom code block (string manipulation, hashing, conditionals, date logic)
• You need to adjust middleware rules or add request validation
• You’re modifying WebSocket behavior, queue workers, or async jobs
• You want to inspect the generated backend line by line

The Agent changes things broadly and fast. The Manual Builder changes things precisely. Use both, they’re designed to complement each other.

For developers: The Manual Builder is a block-based visual IDE with direct access to your generated Python backend. Every API route is broken into discrete code blocks: input parsing, validation, business logic, database operations, and response formatting. You can open any block, edit the code, add middleware, and redeploy without running the Agent again. The generated code is yours and there is no lock-in. You can export the full codebase at any time.

---

5. When to rebuild vs refine

Sometimes a project has drifted far enough from your original intent that iterating forward costs more time than starting fresh. This is normal, it’s not a failure of the tool or the prompting.

Think in milestones as you build: layout locked, core flows working, edge cases handled, data model confirmed. When you know where you are, you make better decisions about whether to push forward or reset.

Signals that refinement is the right call:

• The core structure is right but specific parts need adjustment
• You’ve made 3 to 5 focused changes and things are converging
• The overall flow and data model are intact

Signals that a rebuild is the right call:

• The first build misunderstood the app’s core purpose
• You’ve tried to correct the same thing more than twice and it keeps regressing
• You’re spending more time explaining what to undo than what to do next
• A new role or entity needs to be added that should have been there from the start

If rebuilding: take what you learned from the first attempt and write a stronger first prompt. The second build is almost always significantly better.

---