Bolt Best Practices and Common Pitfalls

The Patterns That Work

Working with Bolt efficiently comes down to a set of repeatable habits. These aren't rules — they're observations about what consistently produces better outcomes.

Best Practices

1. Always Specify Your Stack Upfront

If you don't specify a tech stack, Bolt picks one. It picks reasonably — but not necessarily what you want. Never assume Bolt will match your preferences.

Tech stack for this project:
- React 18 + TypeScript (strict)
- Vite
- Tailwind CSS (no custom CSS files)
- Supabase (database + auth)
- React Router v6
- TanStack Query v5 for server state
- Lucide React for icons (no other icon library)

State this once in your steering file and reference it every session.

2. Verify After Every Significant Change

The preview pane is not just for watching. Click through affected flows after every change. A broken state discovered immediately takes 30 seconds to revert. A broken state discovered 20 prompts later takes an hour to untangle.

3. Use Revert Aggressively

Bolt's revert is not an admission of failure — it's a professional tool. When a change introduces a new problem, revert and approach it differently. Trying to fix forward from a broken state compounds complexity.

4. Ask for One Thing at a Time

This bears repeating because it's the most violated principle. Bundle 3 requests = 3x the risk of something going wrong. Scope one concern per prompt, verify it works, then move to the next.

5. Name Things Consistently

Bolt will use whatever naming convention it infers from context. If your codebase uses kebab-case file names, specify it. If you use PascalCase component names, specify it. Put this in your structure.md steering file so it applies automatically.

6. Lock Configuration Files Early

As soon as you have a working vite.config.ts, tailwind.config.js, or Supabase client setup that you're satisfied with, lock those files. Nothing is more frustrating than Bolt quietly modifying configuration during a feature build.

---

Common Pitfalls

Pitfall 1: Starting Without a Stack Spec

What happens: Bolt uses its defaults. You don't like them. Changing them mid-project requires either a large refactor or living with the inconsistency.

Prevention: Write your tech.md steering file before the first substantive build prompt.

---

Pitfall 2: Prompting Bolt to "Fix" Without Describing the Problem

What happens: "Fix the login" tells Bolt almost nothing. It guesses, makes changes, and may break working code while attempting to fix what it doesn't understand.

Prevention: Describe the specific symptom. "The login form submits but the redirect to /dashboard doesn't happen. The user object is present in the auth response. The issue appears to be in the router navigation logic."

---

Pitfall 3: Letting Context Overflow Without Clearing

What happens: After 50+ prompts, Bolt's context window fills up. It starts forgetting early decisions, generating code that contradicts its own patterns, or applying the same fix repeatedly without success.

Prevention: Use /clear at natural session boundaries. Re-establish context explicitly after clearing.

---

Pitfall 4: Accepting Unrequested Additions

What happens: Bolt adds a feature or library you didn't ask for. You don't notice. Later, it causes a conflict or makes your codebase harder to understand.

Prevention: Scan diffs after major changes. Remove anything not specified.

---

Pitfall 5: Using Bolt as a Search Engine for Architecture Decisions

What happens: You ask Bolt "should I use PostgreSQL or MongoDB?" and accept its answer. Bolt will give a confident, reasonable-sounding answer — but it doesn't know your specific constraints, team expertise, or operational context.

Prevention: Use Bolt for implementation. Use Claude or a knowledgeable human for architectural decisions that have significant long-term implications.

---

Pitfall 6: Not Reading the Generated Code

What happens: Bolt generates a Supabase RLS policy. It looks right. You don't read it. Later, users can access each other's data because the policy is wrong.

Prevention: Read security-critical code. Understand auth flows, RLS policies, and any code that handles user data before shipping.

---

Pitfall 7: Building in a Single Monolithic Session

What happens: You spend 4 hours in a single Bolt session building a large application. The context is enormous. Bolt starts making mistakes. You're too deep to easily revert. Export, version control, and clear session state have all been neglected.

Prevention: Use the sprint model. Export at milestones. Treat each session as a bounded unit of work with a clear definition of done.

The Productive Bolt Mindset

Bolt is a tool that amplifies your speed when you work with it correctly and wastes your time when you work against it. The mental model that works:

• You are the architect and product owner. Bolt is the implementer.
• You define what gets built. Bolt figures out how to build it.
• You verify every output. Bolt doesn't test its own work.
• You own the code. Review what you're shipping.

The speed Bolt provides is real. But it's the speed of removing mechanical friction — typing, boilerplate, scaffolding — not the speed of removing judgment.

Key Takeaways

• Specify your stack, conventions, and constraints before building — every time, every session
• Verify immediately, revert aggressively, and scope narrowly — these three habits prevent 80% of the most common Bolt frustrations
• Read security-critical generated code before shipping
• Bolt removes mechanical friction; your judgment is still required for architecture, security, and product decisions

---

Try It Yourself: Review your last or current Bolt project. Open the file list and pick 3 files at random. Read them fully. For each file, answer: (1) Do you understand what every part does? (2) Are there any security concerns? (3) Are there any patterns that contradict your tech stack conventions? This audit will teach you more about what Bolt actually produces than any tutorial can.