Debugging & fixing errors
Strategies for diagnosing and fixing issues when things go wrong.
Advanced Prompting Strategies
These strategies help you build more complex apps efficiently while keeping token usage under control.
Build in phases
Section titled “Build in phases”Don’t try to describe your entire app in one message. Build it up in phases, using the right model for each stage.
Phase 1 — Foundation
Section titled “Phase 1 — Foundation”Set up the core structure: screens, navigation, and data models. Use Opus or Auto for this — a strong foundation saves rework later.
Create a recipe app with 4 screens: Home (recipe grid), Recipe Detail, Add Recipe form, and Favorites. Use bottom navigation. Dark theme with orange accents.
Phase 2 — Features
Section titled “Phase 2 — Features”Add features one at a time. Each message builds on the previous result. Verify each feature works before adding the next.
Add search functionality to the Home screen with a search bar at the top that filters recipes by name.
Add the ability to save recipes to favorites with a heart icon on each recipe card.
Add a pull-to-refresh gesture on the Home screen that reloads the recipe list.
Phase 3 — Polish
Section titled “Phase 3 — Polish”Switch to Sonnet for quick, cost-effective refinements:
Add a loading spinner when the recipe list is being loaded.
Show an empty state illustration when no recipes match the search.
Make the recipe card corners more rounded and add a subtle shadow.
Phase 4 — Publish
Section titled “Phase 4 — Publish”Set your app icon, test on your device, and publish. See Publishing Overview for all platform options.
Use @file references strategically
Section titled “Use @file references strategically”As your app grows, @file: references become essential for directing the AI to the right place.
- Targeted changes: “In
@file:lib/screens/home_screen.dart, add a pull-to-refresh gesture” - Bug fixes: “The list in
@file:lib/widgets/recipe_list.dartdoesn’t scroll when there are more than 10 items” - Cross-file consistency: “Make
@file:lib/screens/settings.dartmatch the style of@file:lib/screens/profile.dart”
Without file references, the AI might modify unrelated files or create new files when it should be editing existing ones. This matters more as your project grows beyond a few screens.
See Attaching Context for details on the @file: syntax.
Clean up regularly
Section titled “Clean up regularly”After the AI has made many changes, your codebase can accumulate redundancy — duplicate functions, unused imports, overly nested logic. Use the Prompt Library’s Review & Simplify Code template periodically to clean up.
A good rule of thumb: run it after every 5-10 feature additions, or whenever you feel the AI’s responses are getting slower or less accurate (a sign that the codebase complexity is working against it).
Switch models based on task
Section titled “Switch models based on task”Different tasks have different complexity. Match the model to the work:
| Task | Model | Why |
|---|---|---|
| App foundation and navigation | Opus | Complex structure needs deep reasoning |
| Multi-screen features | Opus or Sonnet | Moderate-to-high complexity |
| Simple text or color change | Sonnet | Fast and efficient for straightforward edits |
| Adding a single button or field | Sonnet | Straightforward edit |
| Design-heavy work | Opus | Best visual output |
| Quick bug fix | Sonnet | Clear fix, low complexity |
| Not sure | Auto | Let the system choose |
A color change on Sonnet costs less than what Opus would charge. Over the course of building an app, strategic model switching can save significant tokens.
See Model Selection for full details on each model.
Avoid token-wasting patterns
Section titled “Avoid token-wasting patterns”Don’t ask the AI to “fix everything”
Section titled “Don’t ask the AI to “fix everything””Vague debugging requests can cause the AI to enter loops — making changes, finding new things to adjust, and consuming tokens without meaningful progress.
Instead: Describe the specific issue: “The login button doesn’t navigate to the home screen after successful authentication.”
Don’t request too many changes at once
Section titled “Don’t request too many changes at once”The AI may complete 80% of a multi-part request and miss the rest. You’ll then spend additional tokens on follow-ups to catch the gaps.
Instead: One feature per message. Verify each before moving on.
Don’t fight the AI’s direction endlessly
Section titled “Don’t fight the AI’s direction endlessly”If the AI keeps getting something wrong after 2-3 attempts with different phrasings, stop iterating. You’re spending tokens on diminishing returns.
Instead: Rollback to a clean state and try a completely different approach. See Rollback for how.
Handle incomplete responses
Section titled “Handle incomplete responses”Sometimes the AI delivers partial results — it adds three of four screens, or implements a feature but forgets the navigation to it. When this happens:
- Follow up directly: “You didn’t finish adding the settings page — please complete it”
- Continue explicitly: “Continue where you left off”
- Break it down: If the request was too large, split it into smaller pieces for the next attempt
- Use @file references: Focus the AI’s attention on the specific file that needs work
Manage multi-screen navigation
Section titled “Manage multi-screen navigation”Apps with many screens need careful navigation management. Establish the structure early and be consistent in how you reference screens.
- Define navigation in Phase 1. “Create a bottom navigation bar with 5 tabs: Home, Search, Add, Activity, Profile.”
- Name screens consistently. Use the same names in every prompt. If you called it “Recipe Detail” in your first message, don’t switch to “Recipe Page” later.
- Describe navigation paths. When adding a new screen, explain how to get there: “Add a Settings screen accessible from the Profile tab. Add a gear icon in the top-right corner of the Profile screen that navigates to Settings.”
- Test navigation after each addition. Use the Live Preview to verify that all navigation paths work before adding more screens.
When to rollback vs. iterate
Section titled “When to rollback vs. iterate”Knowing when to rollback saves both time and tokens.
Rollback when:
- The AI changed your UI layout in a way you didn’t ask for
- The app is broken and the AI can’t fix it after 2 attempts
- You want to try a completely different approach to a feature
- A “Review & Simplify Code” pass went too far and removed something important
Iterate when:
- The result is close but needs tweaks (colors, spacing, text)
- You want to build on what the AI just created
- Small adjustments are needed and the core structure is right
See Rollback for step-by-step instructions.
Summary: prompting workflow
Section titled “Summary: prompting workflow”For a typical app build, the workflow looks like this:
- Foundation — Describe all screens and navigation (Opus/Auto)
- Core features — Add one feature per message, verify each (Opus/Sonnet)
- Integrations — Use Prompt Library templates for Firebase, AdMob, etc.
- Polish — Refine design, add loading states, empty states (Sonnet)
- Cleanup — Run “Review & Simplify Code” to reduce complexity
- Publish — Set icon, build, and submit to app stores
Next steps
Section titled “Next steps”Building a complete app
End-to-end walkthrough of building a full app from idea to publish.