# Writing Effective Prompts A **prompt** is how you tell the agent what to build. You don't write code or pick a framework; you describe the app you want in plain language, and the agent plans the work, writes the code, and runs it for you. The clearer your description, the closer the result is on the first try. ## Describe the Outcome Say what the app should do and how it should feel, not how it should work under the hood. The agent chooses the right approach for you, so you don't need to mention frameworks, libraries, or file structure. - **Good**: "A menu bar app that shows my next calendar event and counts down to it." - **Less helpful**: "A SwiftUI menu bar extra with a timer that polls EventKit every 30 seconds." The second prompt isn't wrong, but it spends your words on decisions the agent is happy to make. Lead with what you want to be true when the app runs. ## Include the Essentials A strong first prompt usually covers three things: - **Purpose**: What the app is for and the main thing it helps you do. - **The data involved**: What it reads, writes, or works with, such as files, a list you maintain, or a service it connects to. - **The look and feel**: Roughly how it should appear and behave, like a single window, a menu bar tool, a list with a detail pane, or a form. You don't need every detail up front. Cover the essentials and let the agent fill in sensible defaults; you can refine the rest in follow-up messages. > [!NOTE] > Not sure where to start? Describe the problem you're trying to solve and ask the agent to suggest an app for it. You can shape the idea together before any code is written. ## Start Simple Resist the urge to specify everything in one giant prompt. Ask for a focused first version, see it run, then add to it. Building in steps keeps each change easy to review and makes it obvious when something goes off track. A good rhythm looks like this: 1. **Describe**: Describe the core app and let the agent build it. 2. **Try it**: Open it and try the main flow. 3. **Follow up**: Send a follow-up for the next feature or fix. 4. **Repeat**: Keep going until it's what you want. See [Iterating](/prompting/iterating) for how to refine an app over multiple turns. ## Strong vs Vague The difference between a quick win and a few rounds of back-and-forth is usually detail. > [!TIP] > **Strong** > > "A habit tracker as a single-window app. I want to add habits with a name and an emoji, check them off each day, and see a grid of the last 30 days per habit." That prompt names the purpose (tracking habits), the data (habits with a name and emoji, daily check-offs), and the look and feel (single window, a 30-day grid). > [!WARNING] > **Vague** > > "Make me a productivity app." The agent can build something from a prompt like this, but it has to guess at every decision, so the result is less likely to match what you pictured. If you only have a rough idea, that's fine; say so and let the agent suggest specifics you can react to. ## What the Agent Handles Well The agent is good at turning a clear description into a working app, choosing sensible defaults, and handling the technical parts you didn't mention. It can build common app shapes (a window with a list and detail view, a form, a menu bar tool, a dashboard) and wire up native capabilities like notifications, file access, and connections to outside services. Give it more direction when: - The exact layout or wording matters to you. Spell it out. - There are rules or edge cases it can't infer, like how to handle duplicates or what happens when a list is empty. - You're matching an existing style or design. Describe it, or attach a reference image. For bigger or riskier ideas, switch on **Plan mode** so you and the agent agree on an approach before any code is written. See [Plan & Build Modes](/prompting/plan-and-build-modes). ## When the Agent Gets It Wrong Sometimes the agent makes something other than what you pictured. That's usually a sign the prompt left room to guess, not that you're stuck. Getting back on track comes down to spotting when intent was missed, restating the goal clearly, and deciding whether to correct or start fresh. ### Spotting a Mismatch The agent reads your prompt literally, so a mismatch shows up in the result. Watch for: - The app does something **adjacent** to what you wanted, but not quite it (a list where you meant a grid, a window where you meant a menu bar item). - A detail you cared about is **missing**, because the prompt didn't mention it. - The agent **guessed** at something you left open, and guessed differently than you would have. - Each follow-up fixes one thing but **breaks another**, a sign the goal isn't fully shared yet. When you see these, the fix is almost always in the next prompt rather than in starting over. ### Restating the Goal The most reliable fix is to say what you actually want in concrete terms. Describe the outcome, not the mistake. - **More effective**: "The dates should sort newest first, and the total at the bottom should update when I add a row." - **Less effective**: "That's not right, try again." Name the specific behavior, the data involved, and how it should look or act. The clearer the picture, the less the agent has to guess. This is the same "describe the outcome" habit from earlier, applied to a fix. ### Pointing at the Problem Words can be slippery when the problem is visual: "the button at the top, no, the other one" is hard to land. When something on screen is wrong, point at it directly. Use the ** Annotate** button next to the composer to pick the exact element in your running app and send it along with your message. The agent gets a precise pointer instead of a description it has to decode, which removes a whole class of misunderstanding. See [Annotate](/prompting/annotate). > [!NOTE] > Annotating works best for layout, styling, and "this specific element" issues. For behavior and logic ("after I save, clear the form"), a clear written prompt is usually enough. If one prompt asked for too much and the result is muddled, it was probably too big for one shot. Break it into smaller, ordered steps: core structure first, then behavior and look. Smaller steps are easier to get right and verify, and keep your [version history](/prompting/version-history) clean for targeted rollbacks. ### Correct or Revert? When a build goes wrong, you have two paths. Knowing which to take saves time. - **Keep correcting** when the app is mostly right and one or two things are off. A targeted follow-up is fastest, and you build on what's already working. - **Revert and re-prompt** when a change took the app somewhere you don't want, or when several follow-ups keep trading one problem for another. Roll back to the last version that worked and start that step again with a clearer prompt. > [!WARNING] > If you've sent three or four follow-ups and the app is drifting further from your goal, stop correcting. Roll back to a clean version and re-prompt. Layering fixes onto a confused build usually compounds the confusion. ### The agent keeps misunderstanding the same thing. What now? Try changing how you describe it rather than repeating the same words. Point at the element with the ** Annotate** button, give a concrete example of the behavior you want, or break the request into a single small step. ### A new prompt broke something that used to work. How do I recover? Tell the agent exactly what regressed ("the export button stopped working after the last change") so it can repair it. If that doesn't land, roll back to the version from before the change and re-prompt from there. See [Version History](/prompting/version-history).